Docs  /  Integrations  /  JavaScript API reference (V3)

JavaScript API reference (V3)

Last updated: 20. October 2026

This reference describes every method, event and setting that the V3 frontend engine provides on window.Configento – with signature, return value, error cases and a short example. It is aimed at developers of shop themes, plugins and custom integrations. How to solve typical tasks and switch from Legacy code is shown in the guide JavaScript API (V3).

The signatures are written in TypeScript notation. Everything works in plain JavaScript as well.

Lifecycle

  1. The page loads https://cloud.configento.app/configento-v3/configento.js (with defer).
  2. The script creates window.Configento, searches once for all elements with data-configento and registers an instance for each. Its id is the element's id, otherwise configento-anon-<n>.
  3. For each instance, loading the component starts immediately (or the embedded one is used, see component).
  4. As soon as a component has loaded, its instance gets the methods below. Before that they throw Configento instance not ready — await Configento.ready first.
  5. Configento.ready resolves when all instances on the page have loaded.

Elements that only enter the page after step 2 are not picked up. An instance reference stays valid across loading: if you hold Configento.instances.get(id) before ready, the same object gets the real methods afterwards.

Global: window.Configento

Property / method Type Description
version string Version of the engine, e.g. 3.0.0-alpha.0
frontendVersionTag 'v3' Identifier of the engine generation. Check this, not version, if your code only works with one generation.
ready Promise<void> Resolves when all instances have loaded
instances ReadonlyMap<string, ConfiguratorInstance> All instances, keyed by the instance id
first() ConfiguratorInstance or null The first instance on the page
forElement(el) (el) => ConfiguratorInstance (or null); el is an HTMLElement or a string The instance for an element or CSS selector; also searches outward (closest('[data-configento]'))
loadAsset(id, opts?) (id: string, opts?: { instance?: ConfiguratorInstance }) => Promise<AssetPayload> Reads a saved configuration, see Saving and loading
setModalAdapter(adapter?) (adapter?: ModalAdapter) => void Your own window for large image views, see Modal adapter
CloudError Class Error class of storeAsset() and loadAsset(), see CloudError 
window.addEventListener('DOMContentLoaded', async () => {
  await Configento.ready;
  const k = Configento.forElement('#product-form');
});

Instance: ConfiguratorInstance

Properties (read-only):

Property Type Description
id string Instance id
componentId string or null ID of the component
element HTMLElement The element with data-configento
config WebshopConfig or null The settings at load time, frozen – see Embedding

You specify characteristics as an internal name (string) or numeric ID (CharacteristicRef), values as the Value field (string) or numeric ID (ValueRef). An unknown name, an unknown value or an unsuitable data type throws an Error.

Reading

getValue(characteristic): unknown

Value of a characteristic in the form that formulas see as well:

Characteristic Result Empty
Select, radio buttons, list with images Value field of the selected entry (without a value: its ID) null
Multi-selection, checkbox List of values []
Input fields Text, without surrounding spaces ''
Multi-selection with quantities { [value ID]: quantity } {}
Formula, price list, combination, product attribute, webservice Result of the calculation null

A characteristic that a rule hides always returns "empty".

k.getValue('width');        // → '120'
k.getValue('accessories');  // → ['crank', 'remote_control']

getSelections(): SelectionsMap

The current selection of all characteristics as { [characteristic ID]: selection } – see Selection. Characteristics that a rule hides are missing; blocked values are removed.

getState(): ConfiguratorSnapshot

{
  selections: SelectionsMap;                     // like getSelections()
  evaluated: Record<number, number | string | null>;  // results of all calculations by characteristic ID
  hiddenCharacteristics: number[];               // characteristics hidden by rules
  blacklistedValues: number[];                   // values blocked by rules
  price: PriceSnapshot;                          // like getPriceBreakdown()
}

A pure query – you can call it as often as you like.

getPriceBreakdown(): PriceSnapshot

{ total: number; currency: string; priceIncludesTax: boolean }

total is already converted to the shop's tax rate and currency (data-configento-tax-rate, data-configento-currency).

getSummary(opts?): string

Option Default Effect
format 'text' 'html' returns <dl><dt>Characteristic</dt><dd>Value</dd>…</dl>
includePrices false Surcharge after the value
separator '; ' Separator in text format

Contains only visible characteristics. If the component shows the combined article number in the summary, it comes at the end.

k.getSummary({ format: 'html', includePrices: true });

getCombinedSku(): string

Article number of the configured product from the article numbers of the selected values, joined with -, e.g. CL-W-GR-TXT. Per characteristic in the component's order: the article number of the selected value (for multi-selection the first one present), otherwise that of the characteristic. Empty parts are dropped, hidden characteristics don't count. '' if nothing carries an article number. If it isn't empty, it's also in every order payload as _combined_sku.

getAssetPayload(): AssetPayload | null

The configuration as JSON, keyed by internal names – the same form as finalize().payload, but without validation. null as long as nothing is selected. Besides the characteristics it contains _component_title, _locale, _combined_sku where applicable and – for components with a Captcha – altcha.

getHeaderValue(opts?): string | null

The same configuration Base64-encoded (UTF-8-safe) – the form that shop plugins pass to the cart and that Legacy had in the configurator1-header field. With opts.assets (result of storeCombinedImage() as { type: 'imgData', id, url, file }), the image list is added, from which the Magento plugin, for example, reads the cart image.

Changing

Method Signature For
selectValue (characteristic, value) => void; value may be null Select, radio buttons, list with images. null clears.
toggleValue (characteristic, value) => void Checkbox, multi-selection, list with images with multi-selection
setText (characteristic, text: string) => void Input fields
setQuantity (characteristic, value, quantity: number) => void Multi-selection with quantities; negative quantities become 0
resetSelection (characteristic) => void All data types; rules may preselect the characteristic again afterwards
setProductAttributes (attributes: Record<string, string>) => void Replaces the values of the product attributes, e.g. after a variant change. Can also be called before ready.
showLanguageSelect () => void Shows the language selection again (only with languageSelect and several languages); the selection is kept

Every change works like an input by the customer: rules, formulas and price are recalculated, then change follows and – if the price changes – price.

Completing

finalize(): Promise<FinalizeResult>

Validates the whole configuration like a click on the action button and shows errors on the characteristic.

{
  ok: boolean;
  validationErrors: ValidationError[];
  payload?: AssetPayload;        // only when ok
  priceTotal: number;
  summary: string;               // text, at most 1024 characters
  combinedImage?: string;        // PNG as data URL if the component has a combined image
}

finalize() doesn't send anything and fires the finalize event afterwards.

Saving and loading

Method Signature Description
storeAsset () => Promise<{ id: string; url: string }> Saves the configuration. id is the key for the deep link, url the address of the saved JSON file.
Configento.loadAsset (id, { instance? }) => Promise<AssetPayload> Reads a saved configuration. Without instance, the first one applies.
restoreFromAssetJson (payload) => void Transfers a configuration that has been read into the instance
storeCombinedImage () => Promise<{ id: string; url: string }> (or null) Saves the combined product image for cart or order; null if the component has none

When someone opens the product page with ?dl=<id> (or ?configento_asset=<id>), V3 restores the configuration in the first configurator by itself. For other parameters or a different configurator, call loadAsset() and restoreFromAssetJson() yourself.

const { id } = await k.storeAsset();
const link = new URL(location.href);
link.searchParams.set('dl', id);

storeAsset() and loadAsset() need the shop settings (customer ID, token). In the admin preview they therefore throw CONFIG_MISSING. The configurator doesn't retry failed uploads by itself – otherwise duplicate entries would be created.

Groups and wizard

Method Signature Description
getGroups () => GroupInfo[] Groups shown, in order; those hidden by rules are missing
getActiveGroup () => ActiveGroup (or null) Group shown; null with No groups or a single group
setActiveGroup (ref, opts?: { validate?: boolean }) => Promise<boolean>; ref is number or string Switches by ID or internal name. Going forward, it checks every step on the way (validate: false skips this) and asks the step guard. true if the step changed.
nextGroup () => Promise<boolean> Like Next
prevGroup () => Promise<boolean> Like Back – without a check
setStepGuard (guard, opts?: { backward?: boolean }) => void; guard is StepGuard or null Your own check before the change 
type GroupRef   = { id: number; key: string | null; index: number };
type GroupInfo  = GroupRef & { title: string };
type ActiveGroup = GroupRef & { total: number };

type StepGuard = (step: { from: GroupRef; to: GroupRef; direction: 'forward' | 'back' | 'jump' })
  => boolean | void | Array<{ characteristic: number | string; message: string }>
   | Promise<boolean | void | Array<{ characteristic: number | string; message: string }>>;

key is the group's internal name from the editor, index the position among the groups shown. The step guard runs after the built-in check, by default only forward. false holds the step without a message, a list holds it and shows each message on the characteristic (error code guard). As long as a promise is pending, Next and Back are locked. If the guard throws, the step changes anyway.

In addition, an error rule with "Execute when: Wizard" and Error type Error holds the step it belongs to.

Events

on(event, callback) returns a function for unsubscribing. Listeners stay subscribed even if the instance is reconnected internally (for example when webservice values arrive later).

Event When Content
change After every change of the selection { selections: SelectionsMap } – like getSelections()
price When total price, currency or tax basis change; once right after loading { total, currency, priceIncludesTax, delta } – delta relative to the previous price
finalize When finalize() has finished FinalizeResult
error When errors appear on a characteristic { errors: ValidationError[] }
group After every change of the group shown, not when it's first shown { from, to, direction }; to is a GroupRef, from a GroupRef or null

onChange(callback) is the older form of on('change', …) without content and will be removed.

Data types

Selection

SelectionsMap is { [characteristic ID]: selection }; depending on the data type, a selection is:

kind Fields Characteristics
single valueId (number or null), qty?: number Select, radio buttons, list with images
multi valueIds: number[], qtys?: { [value ID]: number } Checkbox, multi-selection
text value: string Input fields
quantities quantities: { [value ID]: number } Multi-selection with quantities
files files: Array<{ id, folder, type, … }> File upload
captcha payload: string Captcha

ValidationError

{ characteristicId: number; altTitle: string; code: string; message: string }

message is already translated into the configurator's language. code is one of: required, pattern, range, length, numeric, integer, gt-zero, gte-zero, email, url, zip, phone, iban, bic, vat, code, alpha, alphanum, data, lowercase, uppercase, rule (error rule), guard (step guard).

CloudError

storeAsset() and loadAsset() reject with a Configento.CloudError: code, retryable, and status for HTTP errors.

code Meaning retryable
NO_SELECTIONS Nothing selected yet no
CONFIG_MISSING No shop settings (admin preview) or no instance no
HTTP_4XX Rejected, e.g. token or domain no
HTTP_5XX Server error yes
BAD_RESPONSE Unexpected response no
NETWORK No connection, CORS, certificate yes
NOT_FOUND The saved configuration doesn't exist no 
try {
  await k.storeAsset();
} catch (err) {
  if (!(err instanceof Configento.CloudError)) throw err;
  if (err.retryable) scheduleRetry();
}

Embedding: attributes and JSON

Every setting goes either as an attribute on the element with data-configento or as a key in the JSON attribute data-configento-config. If both are present, the JSON wins.

Attribute JSON key Value
data-component-id componentId ID of the component – required
data-configento-customer customer Customer ID
data-configento-token token Token from the HTML5 (V3 Beta) card
data-configento-token-endpoint tokenEndpoint Address that issues short-lived tokens (shop plugins)
data-configento-cloud-base-url cloudBaseUrl cloud.configento.app
data-configento-asset-base-url assetBaseUrl Host for saved configurations (shop plugins)
data-configento-tax-rate taxRate The shop's tax rate in percent
data-configento-currency currency Currency code, e.g. EUR
data-configento-currency-rates currencyRates Rates as JSON, e.g. {"CHF": 0.94}
data-configento-locale uiLocale Language, e.g. de_DE
data-configento-content-locale contentLocale Different language for the component's texts only
data-configento-embed-mode embedMode storefront (default with attributes) or admin-preview
data-configento-price-mount priceMount CSS selector for the total price
data-configento-summary-mount summaryMount CSS selector for the summary
data-configento-summary-open summaryOpen Summary initially expanded or collapsed
data-configento-combined-image-mount combinedImageMount CSS selector for the combined product image
data-configento-language-select languageSelect Language selection in front of the configurator
data-configento-language-select-title languageSelectTitle Text above the language selection
data-configento-languages languages Languages offered, comma-separated (JSON: list)
data-configento-min-height minHeight Height reserved while loading, e.g. 640px
data-configento-min-height-keep minHeightKeep Keep the height after loading as well
data-configento-wizard-nav wizardNav full, buttons or none
data-configento-component-json component The component itself, as GET /api/v3/components/{id} returns it
– productAttributes Values of the product attributes, e.g. {"width": "120"}

Yes/no attributes accept true/false, 1/0, yes/no or the attribute without a value for "yes". Unknown values leave the default in place and produce a warning in the console.

Display when embedding via attributes: in storefront mode the configurator shows neither the total price nor the summary – the shop has its own. With price-mount and summary-mount you place them wherever you like. If a selector finds no element, that part appears nowhere instead of twice in the configurator. summary-open only works together with summary-mount; there the summary starts expanded by default.

Modal adapter

interface ModalAdapter {
  openOverlay(args: { title: string; container: HTMLElement; onClose: () => void }): { close(): void };
}

The configurator fills container after openOverlay returns. Your adapter attaches it to a window of its own and calls onClose() when the customer closes it. The configurator calls close() when it closes the window itself (e.g. after the selection). Set the adapter as soon as window.Configento exists and before a window opens; setModalAdapter() without an argument restores the built-in window.

Compatibility script

https://cloud.configento.app/configento-v3/configento-compat.js – loaded before configento.js – maps the Legacy engine's global objects (Justselling_Configento_App_*, CONFIGENTO_PRODUCT.setPrice, the configentoUpdate…InDom… events) onto this API. What exactly it takes over and how to rewrite old code is described in the guide under Switching from Legacy.

Versions and guarantees

Configento.version follows Semantic Versioning. Until version 3.0.0, error texts and small details may still change; the methods and data types on this page stay. From 3.0.0 on: bug fixes change the last digit, new features the middle one, and only a new first digit breaks existing code – with migration instructions.

Rely on the methods, events and data types on this page, not on CSS classes or the configurator's DOM structure. Only the attributes data-configento-char-id, data-configento-group-id and data-configento-group-key are stable.

Next steps

← All articles Try free for 14 days