Installing the WooCommerce and WordPress Plugin

With the WordPress plugin you bring your configento.app configurators onto any page of your WordPress website – with a block or a shortcode. If WooCommerce is installed, the configurator also appears on the product page: your customers put the product together, see the total price instantly and add the finished configuration to the normal cart. configento.app checks the price on the server. You edit your components in the embedded admin without leaving wp-admin.

Requirements

• WordPress 6.6 or later and PHP 8.1 or later. For the shop also WooCommerce 9 or later.
• Pretty permalinks: under Settings → Permalinks any setting other than Plain. Only then can the plugin connect to configento.app – see Troubleshooting.
• A WordPress user allowed to install plugins and change settings (administrator).
• A login to the Service Portal for the service you want to connect the website to.
• At least one published component.

Which frontend engine runs

The plugin always loads the V3 engine. The Frontend engine setting of the component plays no role here. Features that only exist in Legacy – such as accordion, autocomplete or quantity predefinition – are therefore not available in WordPress. You will find the overview under Frontend Engine: Legacy or V3.

Download the plugin

You get the plugin in configento.app under Settings → Integrations, card WordPress / WooCommerce, button Download plugin. You receive a ZIP file – do not unpack it.

If the tab is locked, first accept the data processing agreement under Settings → Data processing.

Installing the plugin

1. In wp-admin, open Plugins → Add New Plugin and click Upload Plugin at the top.
2. Choose the ZIP file and click Install Now.
3. Click Activate Plugin.

The plugin adds the menu item configento to wp-admin. From the command line: wp plugin install configento-wordpress-*.zip --activate.

You install a new version the same way: WordPress asks whether to replace the installed plugin. The connection and the links are kept.

Connecting to configento.app

You set up the connection once from wp-admin. You don't have to copy a key.

1. Open the menu item configento.
2. You see the card Connect your configento.app account. Click Connect to configento.app.
3. You are forwarded to the Service Portal. Log in and confirm the connection.
4. You then return to wp-admin, and the configento.app admin opens right in the page.

If the permalinks are set to Plain, the card shows a notice on where to change that instead of the button.

While connecting, the plugin also sets up everything your pages need: it fetches the credentials for your website and reports its domain to configento.app (see Allow your domain). If your service is a dedicated Enterprise instance, the Service Portal names it when you connect, and the plugin works with that instance.

Every WordPress user connects individually. The connection applies to the user account that made it. If a colleague works with their own login, they see the card to connect again the first time they open configento. The configurator on your pages keeps running as long as at least one user is connected.

Above the embedded admin you see the email address of your portal login and the button Disconnect.

Editing components in wp-admin

Once connected, configento opens the configento.app admin right inside wp-admin. There you create components, maintain characteristics, values, prices and rules and publish them – exactly as under admin.configento.app. The basics are in Create Your First Component.

If the page stays open for a long time, the session of the embedded admin eventually expires. The plugin then renews it in the background; you don't have to reload the page.

Allow your domain

The configurator only loads on domains that are allowed for your service. The plugin reports your website's domain, but does not allow it itself. Until it is allowed, the configento page shows a notice.

1. In the embedded admin, open Settings → Domains.
2. The section Reported by connected shops lists your website's domain with the note WooCommerce.
3. Choose the type, for example Production or Staging, and click Add to licence.

The domain is reported when you connect and every time you change the site address under Settings → General – for example when moving from a test environment to the live domain. The new domain then only needs to be added to the licence. More on this: Global Settings.

Showing a configurator on a page

On any page and in any post – also without WooCommerce, for example for enquiry configurators with the action button.

With the block

1. In the block editor, insert the block configento Configurator (category Embeds).
2. Under Configurator, choose the component from the list. The list shows the components of your connected service. If it cannot be loaded, enter the Configurator ID instead, as shown on the tile in the component overview.
3. Optionally, in the sidebar under Settings:
   • Minimum height, for example 600px. Keeps the page from jumping while the configurator loads.
   • Language selection: visitors can switch between the languages of the configurator.

In the editor the block only shows which configurator appears. You see the configurator itself in the preview and on the page.

With the shortcode

For the classic editor and page builders:

[configento id="10722"]

What happens

• The configurator appears in the page's language. Multilingual websites (for example with WPML or Polylang) thus show it in the right language automatically; if a translation is missing, it takes another available one.
• The configurator script only loads on pages with a configurator.
• The page source contains neither an access key nor a token: the configurator fetches a short-lived token through your website. Caching plugins may therefore cache pages with a configurator.
• If the website is not connected, only logged-in editors see a notice; visitors see nothing.

WooCommerce: linking a product to a component

1. Open the product under Products.
2. The Product data box has the tab configento.
3. Under Configurator, choose the component from the list. If it cannot be loaded, the field Configurator ID appears instead.
4. Update the product.

A product has exactly one component. To unlink it, choose No configurator. The product's price is the base price; the configuration adds its surcharge.

What happens in the shop

On the product page

• The configurator appears above the Add to cart button.
• Price: The price on the product page shows the product price plus the configuration and updates with every selection – it is the amount the cart charges. On variable products the chosen variation counts: its price plus the configuration appears where WooCommerce shows the variation's price.
• Gross or net: The configurator shows prices the way your shop does. If WooCommerce shows prices without tax or taxes are switched off, the surcharges are net as well. Otherwise it calculates with the tax rate WooCommerce applies to this product and customer.
• Currency: The component must keep its prices in your shop's currency.
• Quantity: If you lock the cart quantity in the component (see Component Settings), the product page shows no quantity field and every configuration stays at quantity 1 in the cart.

Adding to the cart

The Add to cart button adds the configuration to the cart, not the bare product. Before that, the configurator checks the required fields and marks what is missing.

configento.app calculates the price again on the server when the item is added. The description of the configuration that goes with the order is also built by configento.app from the checked selection. What is displayed in the browser therefore cannot end up manipulated in the cart. This applies to the classic cart and the cart block alike.

Product lists

In shop, category and search lists, the button of linked products is labelled Configure and leads to the product page. That way nobody adds the product to the cart without a configuration – not through a cart block or the Store API either.

Cart, checkout and order

• The line shows Configuration with the summary of the selection.
• If the component creates a combined product image, the cart, the checkout, the order view in wp-admin and order emails show this image instead of the product photo.
• The same configuration a second time gives one line with quantity 2 – with a locked quantity WooCommerce instead reports that the product is already in the cart; another configuration gets a line of its own.
• The order, order emails and the customer account show the configuration on the line.
• The plugin supports WooCommerce's order tables (HPOS).

Changing a configuration

In the classic cart every configured line has the link Change configuration; in the cart block the product name leads there. The product page then shows the saved selection. When the customer adds the changed configuration to the cart, it replaces the old line and they return to the cart.

Data for ERP and production

On every order line the plugin stores hidden fields next to the visible Configuration, which interfaces and exports can read:

Subscription status

If there is something to do about your configento.app subscription, the configento page shows a notice with the link Open the portal. If configento.app no longer serves your website, pages show the sentence This configurator is currently unavailable. instead of the configurator, and WooCommerce no longer accepts configurations into the cart. The plugin checks the status at most once an hour.

Disconnecting

Disconnect above the embedded admin disconnects your user account – in the plugin and in the Service Portal.

Important: As long as another user is still connected, the configurator keeps running. When the last connected user disconnects, the plugin also deletes the website's credentials – the configurator then disappears from all pages until someone connects again.

Deleting the plugin

When deleted under Plugins, the plugin removes the connections, the credentials and the stored subscription status. The link on the product and the configurations on past orders are kept.

Click Disconnect once before deleting. Otherwise the authorisation in the Service Portal remains in place.

Which data goes to configento.app

• When connecting: your website's address and the return address to wp-admin, to the Service Portal.
• Afterwards: your website's domain, so the configurator may load there, and requests for the subscription status.
• On pages with a configurator: your visitors' browsers load the configurator from configento.app and send it the chosen values.
• In the cart: the selection and the product's tax rate, for the price check.

Before you connect, the plugin sends no requests to the outside.

Troubleshooting

1. Instead of the "Connect to configento.app" button there is a notice about permalinks – choose any setting other than Plain under Settings → Permalinks. The Service Portal requires a return address ending in /configento/connect/callback.
2. "Component could not be loaded (HTTP 401)" – your website's domain is not allowed. See Allow your domain.
3. No configurator appears on the page – is a component chosen in the block or shortcode, and is at least one user connected? Logged-in editors see a notice in its place.
4. The list of configurators is missing, there is only a field for the ID – the website is not connected, or configento.app was not reachable at that moment. Connect under configento or enter the ID directly.
5. "Please configure the product on its page first." – the product was meant to go into the cart without a configuration, for example through a list or cart block. Linked products can only be bought through their product page.
6. "The price could not be checked right now. Please try again in a moment." – the price check was briefly unreachable, or the component keeps its prices in a currency other than your shop's. You find the reason under WooCommerce → Status → Logs in the entries of the source configento.
7. "This configuration is no longer valid. Please put it together again." – the component was changed while the customer was configuring. Reload the page and put the configuration together again.
8. "This product cannot be configured at the moment." – your configento.app subscription no longer serves the website. See Subscription status.
9. "The storefront is not set up yet: disconnect and connect again." – the credentials for your pages could not be fetched while connecting. Disconnect and connect again.
10. The configuration image is missing in the cart – the component does not create a combined product image. The cart then shows the product photo.

Next steps

• Create Your First Component
• Component Settings
• The Action Button
• Global Settings