JavaScript API reference (V3)

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.1.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
registerRenderer(name, renderer)	(name: string, renderer: CharacteristicRenderer) => () => void	Your own rendering for characteristics, see Custom rendering. Returns a function for unregistering.
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()
  characteristicPrices: Record<string, number>;  // surcharge per characteristic by internal name
}

A pure query – you can call it as often as you like. characteristicPrices gives what each characteristic contributes to price.total, in the shop's currency and tax basis. Characteristics without a price share, without an internal name or hidden by a rule are missing.

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	The characteristic's surcharge after the value, as in characteristicPrices; characteristics without a surcharge get none
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.

getCharacteristics(): CharacteristicInfo[]

Describes all characteristics of the component in their order – independent of rules and selection. Use it to read the CSS class and the custom fields of characteristics and values.

type CharacteristicInfo = {
  id: number;
  key: string | null;          // internal name, key in getAssetPayload()
  groupId: number;
  groupKey: string | null;
  title: string;
  type: string;                // e.g. 'radiobuttons', 'text'
  visibility: 'visible' | 'hidden' | 'shop' | 'backend';
  cssClass: string;            // "CSS class" field as entered, '' when empty
  customFields: { [fieldNumber]: CustomField };
  values: Array<{
    id: number;
    key: string | null;        // the value's value
    label: string;
    sku: string | null;
    customFields: { [fieldNumber]: CustomField };
  }>;                          // all values, blocked ones too; empty for input fields
};

CustomField is described under Payload entry. Finding a value by the content of a field:

const colour = k.getCharacteristics().find((c) => c.key === 'colour');
const value = colour.values.find((v) =>
  Object.values(v.customFields).some((f) => f.id === 'checkout-title' && f.value === 'Red'));

The class in the CSS class field may also serve as a control value for your own script. A custom renderer only applies when exactly this name is registered with registerRenderer().

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. It always contains all groups, not only the one shown, in the component's order. The fields per characteristic are described under Payload entry. 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; characteristics: 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. characteristics lists the internal names of the group's characteristics in display order – the keys under which they appear in getAssetPayload(). Characteristics hidden by rules stay in the list, characteristics without an internal name are missing. This lets you structure your own summary by step without maintaining the mapping in your own code:

const payload = k.getAssetPayload() ?? {};
for (const group of k.getGroups()) {
  const rows = group.characteristics
    .map((name) => payload[name])
    .filter((entry) => entry && entry.visibility !== 0);
  // group.title as heading, rows as lines
}

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
action	When an action button's request has finished – also on an error status or a network error, not when validating the input stops the click (then error) – for the action Hand over to the page (event) instead as soon as the input has been validated, before submitting	ActionEvent, see below

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

ActionEvent

Field	Meaning
ok	true for HTTP status 2xx. Always true for event
status	HTTP status of the response, 0 without a response (network error). 0 for event
body	The endpoint's response: as an object if it is JSON, otherwise as text; null for a PDF or without a response. null for event
characteristic	Internal name of the action button
action	custom_url, pdf, email or event (action Hand over to the page)
payload	Only for event: the configuration to submit, with the captcha solution as altcha
preventDefault()	The button then shows neither its success nor its error line and doesn't redirect. A PDF download still starts.
defaultPrevented	true if a listener has called preventDefault()

For event, the button waits for the promise your listener returns: { ok: true, message } shows success (with your message, if given), { ok: false, message } shows your message as an error, a rejected promise shows its error text. If the listener returns nothing, that counts as success. Since version 3.2.0.

Since version 3.1.0.

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

Payload entry

Each characteristic appears in getAssetPayload() and finalize().payload under its internal name. These fields are guaranteed:

Field	Type	Present
label	string	Always. The characteristic's title in the configurator's language.
value	see below	Always.
valueLabel	see below	Always. The value's label or the input.
visibility	number	Always. Follows the characteristic's Visibility: 1 Yes (visible), 3 Backend only, 0 No (hidden) or hidden by a rule.
valueId	number, null or number[]	For characteristics with values.
choiceSku	string or string[]	For characteristics with values. For single selection only when the selected value has an article number; in arrays '' stands for values without one.
valueQty	number or number[]	Always for multi-selection with quantities, otherwise only when a quantity is set on the characteristic.
sku	string	When the characteristic itself has an article number.
files	Array<{ id, folder, type, … }>	For file upload.
customFields	{ [field number]: CustomField }	When the characteristic has custom fields.
choiceCustomFields	{ [field number]: CustomField }	For select, radio buttons and Package, when the selected value has custom fields.

By data type:

Characteristics	value	valueLabel	valueId
Select, radio buttons, Package	string – the value's value, '' without a selection	string	number, null without a selection
Checkbox, multi-selection, list with images	string[]	string[]	number[]
Multi-selection with quantities	string[]	string[]	number[], plus valueQty: number[] at the same position
Input fields	string	string (same as value)	–
Formula, Simple combination, Product attribute, Webservice	string – the result, '' without one	string	–
File upload	string – file names separated by commas	string[]	–

A list with images always returns arrays, even when only one value can be selected. A characteristic hidden by a rule keeps its key but is empty: value and valueLabel are '', visibility is 0, the other fields except sku and customFields are missing.

CustomField is { value: string; title: string; id: string }: value is the text entered (also ''), title the field's name from the component settings and id derived from it – without spaces and special characters, lowercase, e.g. Checkout-Titel → checkout-titel. The key is the field's number. This is the same form as in Legacy; the Magento plugin takes both fields into the order.

Not in the payload: characteristics with the visibility Shop only, characteristics without an internal name, and static fields, charts, action buttons and Captchas. Prices per characteristic are not in the payload – getState().characteristicPrices provides them.

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) card
data-configento-token-endpoint	tokenEndpoint	Address that issues short-lived tokens (shop plugins). If the address lacks the component ID (?id=), the configurator appends it itself.
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.

Requesting the token earlier: with tokenEndpoint, the configurator asks for its token only after it has loaded. It is faster if the page starts this request already in the <head> and stores the promise under window.ConfigentoTokenPrefetch, keyed by exactly the URL from tokenEndpoint. The configurator takes this result once. If the promise returns null, an error or no token, it asks by itself. That way only the URL goes into the page, never a token – which works with page caches. The Magento plugin does this on its own from version 5.0.0-beta22.

<script>
  (window.ConfigentoTokenPrefetch ||= {})['https://shop.example/configento/v3/token/id/42/'] =
    fetch('https://shop.example/configento/v3/token/id/42/', { method: 'POST', credentials: 'omit' })
      .then((r) => (r.ok ? r.json() : null))
      .catch(() => null);
</script>

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.

Custom rendering

With Configento.registerRenderer(name, renderer) your code draws a characteristic itself. If name is in a characteristic's CSS class field, the configurator renders an empty container (div.cfg-custom with data-configento-renderer="<name>") instead of the input element. The configurator never touches its content. Your code sets values via ctx – rules, price, validation, wizard, summary and order work as with an input by the customer.

interface CharacteristicRenderer {
  replace?: 'body' | 'all';     // default 'body'
  combine?: boolean;            // default false
  mount(el: HTMLElement, ctx: RendererContext): void;
  update?(ctx: RendererContext, el: HTMLElement): void;
  destroy?(el: HTMLElement): void;
}

Part	Meaning
name	Class name of lowercase letters, digits and -. One of several classes in the CSS class field is enough. A second registerRenderer with the same name replaces the first.
replace: 'body'	The configurator keeps showing title, required asterisk, info text and error messages; the container sits in .cfg-char__body.
replace: 'all'	The container is the only child of .cfg-char. You show title and errors yourself from ctx.
combine: true	All visible characteristics of the same group with this class become one widget, at the position of the first. The others show nothing but stay in rules, validation, price and order. Their errors appear collected at the widget.
mount	Once, as soon as the container is in the DOM
update	When something in ctx changes: selection, errors, allowed values, prices, language. Not on changes to other characteristics.
destroy	Before the container disappears: step change in the wizard, a rule hides it, unregistering. After that, the methods of this ctx no longer have any effect. If the characteristic comes back, a new mount follows.

ctx:

Property / method	Content
characteristic	The characteristic; with combine the first one
characteristics	All characteristics of the widget, otherwise only characteristic
locale	Language of the configurator, e.g. en_GB
instance	The instance, see above. Its methods only work after Configento.ready.
selectValue(value, characteristic?), toggleValue(value, characteristic?), setText(text, characteristic?), setQuantity(value, quantity, characteristic?), reset(characteristic?)	Like the instance methods of the same name. Without characteristic, characteristic applies; otherwise only a characteristic from characteristics.

Every characteristic in ctx has: id, key (internal name), type, title, info (HTML), required, selection (like getValue()), errors (ValidationError[]), values and, for input fields, textConstraints (minLength, maxLength, validator). values contains only the allowed values; values blocked by rules are missing. Every value has id, key (Value field), label, info, image, price (surcharge in shop currency and tax basis), priceLabel (formatted as in the configurator, empty if none is shown) and selected.

Registering before the bundle: If your script runs before configento.js, store the renderer under (window.ConfigentoRenderers ||= {})[name] = renderer. Renderers registered later work as well: characteristics already shown switch immediately.

Fallback: If no renderer is registered – for example in the admin preview – the characteristic shows the built-in rendering. If mount or update throws an error, the configurator writes it to the console and shows the built-in input element for this characteristic again. Applies to V3 only.

Styling with CSS

You adjust colours, font and corners via variables such as --configento-color-accent, individual elements via guaranteed classes such as .cfg-toggle-item__label. Both are described on the page Customising the design (CSS).

Versions and guarantees

Configento.version follows Semantic Versioning. 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 – including the fields under Payload entry – and on the variables and classes under Customising the design (CSS), not on other classes or the rest of the configurator's DOM structure. The attributes data-configento-group-id and data-configento-group-key are also stable.

Next steps

• JavaScript API (V3) – guide with examples
• HTML Snippet Integration
• Uploads & Deep Links
• Frontend Engine: Legacy or V3