Finish & Cart Events

Finish events fire when the user completes their configuration and clicks the primary action button. Which event fires depends on how the embed template is configured — there are three distinct paths, and the event you receive tells you which path the user took.

The Branching Flow

The embed template's variant and basket mode settings determine which event fires:

  User clicks the primary action button
       │
       ├── Standard product: validation check
       │   └── if required fields missing ──► toast error, NO event fires
       │
       ├── Modular product: short code generation
       │   └── if short code fails ──► NO event fires (silent failure)
       │
       ▼
  ┌─── Which variant? ──────────────────────────────────────────────────┐
  │                                                                     │
  ├── "basket" ──► image + shortCode generated                          │
  │                      │                                              │
  │                      ├── Mimeeq integration (cart=true):            │
  │                      │   auto-dispatches mimeeq-show-basket-loader  │
  │                      │                                              │
  │                      └── HTML integration:                          │
  │                          loader NOT auto-dispatched                 │
  │                      │                                              │
  │                      ▼                                              │
  │                mimeeq-add-to-cart                                    │
  │                (includes unitPrice, price, currency)                 │
  │                                                                     │
  └── default ────► mimeeq-show-summary                                 │
                    (standard: NO image, shortCode, price fields)        │
                    (modular: has image, shortCode, elements — no price) │
                                                                        │
  ──────────────────────────────────────────────────────────────────────┘

All finish events carry the same payload type — FinishEventPayload — but the fields populated differ between variants and product types.

Standard vs Modular payloads

For standard products, the payload includes configurationCode, selectedOptions (a map of block names to option values), selectedOptionsList (the full array with codes and metadata), and sku. The image and shortCode fields are only populated for the basket variant — mimeeq-show-summary fires without them. unitPrice, price, and currency are only present on mimeeq-add-to-cart.

For modular products, the top-level payload has no configurationCode, selectedOptions, or sku. Instead, it includes an elements array where each element represents one product on the scene with its own configuration. The shortCode, image, and elements are generated for all variants (including default/summary).

Events

mimeeq-add-to-cart

The "Add to Cart" button was clicked. This only fires when the embed template has basket mode enabled. It's the primary integration point for connecting Mimeeq to your ecommerce platform's shopping cart.

The basketImplementationType field tells you how the item is being handled: 'html' means your code is responsible for catching this event and creating a cart line item. 'mimeeq' means Mimeeq's built-in basket is handling it (see Basket Events).

The mimeeq-show-basket-loader is only auto-dispatched when using Mimeeq's built-in cart (cart: true in the embed config). For HTML integrations, the loader does not fire automatically — if you want a loading state on the action button while your code processes the event, dispatch mimeeq-show-basket-loader and mimeeq-hide-basket-loader yourself. See Host-Triggered Events for details.

This event includes unitPrice, price, and currency fields that are not present on mimeeq-show-summary. For modular products, unitPrice is the total scene price and price is unitPrice × qty.

Events that may not fire

For standard products, the configurator validates that all required fields are filled before dispatching. If validation fails, a toast error appears and the event does not fire.

For modular products, a new scene short code must be generated before the event can fire. If short code generation fails (e.g., network issue), the function returns silently — no event, no error toast. Your integration should not assume a button click always produces an event.

The image field is a base64-encoded product image generated at the time of the event. For standard products, image generation is wrapped in a try/catch — if it fails, the event still fires but image will be undefined. For modular products, image generation runs in parallel with element data collection via Promise.all, so a failure there may prevent the event entirely.

Fires for both standard and modular products.

Payload: FinishEventPayload

Key fields for ecommerce integration:

Field	Type	Description
productId	string	Unique product identifier
productName	string	Display name of the product
variantCode	string	Full variant code (prefix=configurationCode for standard, just prefix for modular)
configurationCode	string | undefined	SKU-style code built from option selections (standard only)
shortCode	string | undefined	Shareable short code. For standard: only on basket variant (generated on the fly if not already cached). For modular: always present (new code assigned for every finish action).
code	string	Variant code prefix (short code of the product)
sku	string | undefined	SKU value if configured in admin (standard only)
qty	number	Quantity selected by the user
unitPrice	number | undefined	Price per unit. Only on mimeeq-add-to-cart — not present on select-product or show-summary. For modular, this is the total scene price.
price	number | undefined	Total price (unitPrice × qty). Only on mimeeq-add-to-cart.
currency	string | undefined	Currency code. Only on mimeeq-add-to-cart.
image	string | undefined	Base64-encoded product image. For standard: only on basket variant, and can be undefined if generation failed (wrapped in try/catch). For modular: always present (generated for all variants).
selectedOptions	Record<string, string> | undefined	Map of block names → selected option display values (standard only). Blocks with no value, no code, or marked as hidden in PDF are excluded.
selectedOptionsList	SelectedOptionSimple[] | undefined	Detailed array of selected options with codes, names, and metadata (standard only)
isModular	boolean | undefined	Whether this is a modular product
elements	FinishModularElement[] | undefined	Per-component data for modular scenes (modular only, all variants)
basketImplementationType	'html' | 'mimeeq'	Whether your code handles the cart ('html') or Mimeeq Basket does ('mimeeq')
collectionId	string | undefined	Collection ID from the embed template, for routing items into categories
mqq	number	Minimum order quantity for this product
incrementalQty	number	Quantity step size (quantity must be a multiple of this value)
action	string	'addToCart' for basket variant, 'select' for selector variant. Not set for default variant.
embedShortCode	string | undefined	Short code of the product embed
embedInstanceId	string | undefined	Unique ID of the embed instance. Useful when multiple embeds exist on a page.
embedTemplateId	string | undefined	ID of the embed template used
publicPriceListGroups	string | undefined	Public price list group from embed config, if set
customerId	string	Current customer (tenant) ID. Deprecated — avoid building logic around this field.

// Standard ecommerce integration
document.addEventListener('mimeeq-add-to-cart', (event) => {
  const payload = event.detail;

  if (payload.isModular && payload.elements) {
    // Modular: create a bundle with individual line items
    const bundleId = payload.shortCode;

    payload.elements.forEach((element) => {
      yourCart.addItem({
        bundleId,
        id: element.productId,
        name: element.productName,
        sku: element.sku,
        quantity: element.qty,
        variant: element.variantCode,
        options: element.selectedOptions,
        image: element.image,
      });
    });

    // Set the bundle image to the full scene snapshot
    yourCart.setBundleImage(bundleId, payload.image);
  } else {
    // Standard: single line item
    yourCart.addItem({
      id: payload.productId,
      name: payload.productName,
      sku: payload.sku,
      price: payload.unitPrice,
      quantity: payload.qty,
      image: payload.image || null, // image may be undefined if generation failed
      variant: payload.variantCode,
      configurationCode: payload.configurationCode,
      shortCode: payload.shortCode,
      options: payload.selectedOptions,
    });
  }

  // Show confirmation
  showNotification(`Added ${payload.productName} to cart`);
});

// WooCommerce example — pass configuration to a custom endpoint
document.addEventListener('mimeeq-add-to-cart', async (event) => {
  const payload = event.detail;

  const response = await fetch('/wp-json/myshop/v1/add-to-cart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      product_id: payload.productId,
      quantity: payload.qty,
      configuration_code: payload.configurationCode,
      short_code: payload.shortCode,
      variant_code: payload.variantCode,
      selected_options: payload.selectedOptions,
      image_base64: payload.image,
      unit_price: payload.unitPrice,
      currency: payload.currency,
    }),
  });

  if (response.ok) {
    updateCartBadge(await response.json());
  }
});

tip

The shortCode in the payload is a permanent link to this exact configuration (or scene). Store it alongside the cart line item so customers can return to edit their configuration later by loading ?shortCode=XXXXXX on the configurator page.

---

mimeeq-select-product

Internal use

This event fires when the embed variant is set to 'selector'. This variant is currently used by Mimeeq's internal quotation tools and the upcoming AI Studio — it is not available in the standard embed. For embed integrations, your users will see either the Finish button (mimeeq-show-summary) or Add to Cart (mimeeq-add-to-cart).

Payload: FinishEventPayload

---

mimeeq-show-summary

The "Finish" button was clicked. This fires when the embed is in its default mode (no basket, no selector). In the standard Mimeeq UI, this opens the summary/finish screen where the user can review their configuration, generate a PDF, or share a link.

The behavior differs between standard and modular products:

For standard products, the image and shortCode fields are not populated — image generation and short code resolution only run for the basket variant. The payload still includes configurationCode, selectedOptions, selectedOptionsList, sku, and other configuration data. No loader is dispatched. unitPrice, price, and currency are not included.

For modular products, image, shortCode, and elements are populated — the modular path generates these for all variants. No loader is dispatched for default variant. unitPrice, price, and currency are still not included (those are only added for basket variant).

If you're building a custom UI that replaces the default finish screen, listen for this event to capture the configuration data and display your own summary.

Fires for both standard and modular products.

Payload: FinishEventPayload

// Build a custom summary screen
document.addEventListener('mimeeq-show-summary', (event) => {
  const payload = event.detail;

  const optionsHtml = Object.entries(payload.selectedOptions || {})
    .map(([block, value]) => `<dt>${block}</dt><dd>${value}</dd>`)
    .join('');

  const summaryHtml = `
    <h2>${payload.productName}</h2>
    <dl>${optionsHtml}</dl>
    <p>Configuration: ${payload.configurationCode}</p>
    <p>Variant: ${payload.variantCode}</p>
  `;

  document.getElementById('custom-summary').innerHTML = summaryHtml;
  document.getElementById('custom-summary').style.display = 'block';
});

tip

For standard products, mimeeq-show-summary does not include image or shortCode. If your custom summary needs them, use mimeeqApp.utils.takeScreenshot() for an image and mimeeqApp.utils.getShortCode() for a shareable code. For modular products, both fields are already present in the payload.

Which Event Should You Listen For?

Your use case	Event	Embed template setting	Includes price?	Auto-loader?
Ecommerce cart integration	mimeeq-add-to-cart	Variant = basket, Integration = HTML	Yes	No — dispatch loader yourself
B2B cart with Mimeeq checkout	mimeeq-add-to-cart (Mimeeq handles it)	Variant = basket, Integration = Mimeeq	Yes	Yes
Custom finish screen	mimeeq-show-summary	Default variant	No	No

Related

• Ecommerce Integration — complete setup guide for connecting to your shopping cart
• Basket Events — events from Mimeeq's built-in B2B cart
• FinishEventPayload API Reference — full TypeScript type documentation
• Capturing Configurator Data with a Third-Party Form — no-code guide using Zapier, Typeform, etc.
• Custom Ecommerce Integration — business-oriented walkthrough with platform examples