Ecommerce Integration

Integrating Mimeeq with your ecommerce platform means connecting the configurator's "Add to Cart" action to your own shopping cart. This guide covers the full flow: enabling basket mode, listening for the mimeeq-add-to-cart event, understanding the payload, and mapping it to your cart system.

note

If you want Mimeeq to manage the entire cart experience — collecting items, checkout form, order submission — set the Integration to Mimeeq and see the Basket Embed guide instead. This guide covers the HTML integration type, where your platform owns the cart.

Choosing Your Integration Type

Mimeeq supports two basket integration types, configured in your embed template under E-commerce → Integration:

HTML (this guide) — The configurator dispatches a mimeeq-add-to-cart event with the full product payload. Your code catches it and creates a line item in your own cart (WooCommerce, Magento, BigCommerce, custom, etc.). Mimeeq has no knowledge of cart state after the event fires.

Mimeeq — Mimeeq provides a built-in B2B cart with item management, checkout forms, PDF generation, and order submission. See the Basket Embed guide for this approach.

The basketImplementationType field in the event payload reflects this setting — 'html' or 'mimeeq'. When set to Mimeeq, items are routed to Mimeeq's internal basket. When set to HTML, the mimeeq-add-to-cart event fires for your external system to handle.

Setup

Step 1: Configure Your Embed Template

In the admin panel, create or edit an embed template:

1. Go to Templates and select your template
2. In the E-commerce section, enable Basket Support
3. Under Integration, select HTML
4. Choose your Add to Cart Placement — whether the button replaces the Finish button or appears on the summary screen
5. Save the template

Step 2: Embed the Configurator

<mmq-embed
  short-code="YOUR_PRODUCT_CODE"
  template="your_ecommerce_template"
></mmq-embed>

<script src="https://cdn.mimeeq.com/read_models/embed/app-embed.js" async></script>

Step 3: Listen for the Event

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

  // Create a line item in your cart
  yourCart.addItem({
    id: payload.productId,
    name: payload.productName,
    sku: payload.sku,
    price: payload.unitPrice,
    quantity: payload.qty,
    image: payload.image,
    variant: payload.variantCode,
    options: payload.selectedOptions,
    configurationCode: payload.configurationCode,
    shortCode: payload.shortCode,
  });
});

Event Payload Reference

The mimeeq-add-to-cart event carries a FinishEventPayload in event.detail. The table below describes every field with practical context.

Core Identification

Field	Type	Description
productId	string	Internal Mimeeq product ID. Use this as the primary identifier when storing cart items.
productName	string	Product display name in the current language. Use as the line item label in your cart.
code	string	Product prefix code — the base product identifier before configuration. For example, CHAIR in a variant code like CHAIR=Color-b2&Size-a3.
sku	string | undefined	Generated SKU based on the product's code structure and selected options. Only present for standard products — modular products don't have a single SKU.
configurationCode	string | undefined	The encoded configuration string representing all selected options, without the prefix. For example, Color-a1&Size-a2. Not present for modular products.
variantCode	string	Full variant identifier: {prefix}={configurationCode}. This is the complete reference to reconstruct the exact configuration. For example, CHAIR=Color-a1&Size-a2.
shortCode	string	A short code that can be used to reload this exact configuration later. For standard products this is the configuration short code; for modular products it's the scene short code.
embedShortCode	string	The short code used in the mmq-embed element's short-code attribute. Use this to re-embed the same product.

Pricing

These fields are only populated when the configurator has pricing enabled (i.e., the product has prices configured or custom pricing is active).

Field	Type	Description
price	number | undefined	Total price for the configured product at the selected quantity (unitPrice × qty).
unitPrice	number | undefined	Price per single unit of the configured product.
currency	string | undefined	Currency code (e.g., USD, EUR, GBP).

note

If you're using custom pricing, these values reflect whatever you set via mimeeqApp.utils.setPrice(). If custom pricing is enabled but you haven't set a price, these fields may be 0 or undefined.

Quantity

Field	Type	Description
qty	number	Quantity selected by the customer. Respects the product's minimum order quantity (MOQ) and incremental quantity settings.
mqq	number	Minimum order quantity configured for this product. Your cart should enforce this as a floor value.
incrementalQty	number	Quantity increment step. For example, if set to 5, valid quantities are 5, 10, 15, etc. Your cart's quantity selector should respect this step.

Selected Options

Field	Type	Description
selectedOptions	Record<string, string> | undefined	Map of block names to selected option display names in the current language. Hidden and PDF-excluded options are filtered out. Example: { "Color": "Ocean Blue", "Size": "Large", "Fabric": "Premium Linen" }. Use this for displaying option summaries in your cart.
selectedOptionsList	SelectedOptionSimple[] | undefined	Full list of all selected options with detailed metadata including block IDs, option codes, images, and group information. Use this when you need structured data rather than display strings.

Product Image

Field	Type	Description
image	string | undefined	Base64-encoded product image (JPEG, 1000px wide for basket variant). For 3D products, this is a rendered screenshot of the current configuration. For 2D products, the composed image layers. Only generated for basket and selector variants.

tip

The image is base64-encoded and ready to use as a data URL: <img src="${payload.image}" />. If you need to store it, decode the base64 and upload to your CDN or media library.

Metadata

Field	Type	Description
action	'addToCart' | 'select'	Always 'addToCart' for mimeeq-add-to-cart events. The 'select' value appears in mimeeq-select-product events (selector variant).
isModular	boolean | undefined	Whether this is a modular product. Modular products have an elements array instead of a single configuration code.
basketImplementationType	'html' | 'mimeeq'	Reflects the Integration setting from the embed template. 'html' means the event is intended for your external cart. 'mimeeq' means Mimeeq Basket is handling it (you'll typically not see this if you're listening for external integration).
embedInstanceId	string | undefined	Unique ID of the embed instance that fired the event. Useful when multiple embeds exist on a page (though this is generally discouraged).
embedTemplateId	string | undefined	ID of the embed template used.
publicPriceListGroups	string | undefined	The public price list group used for pricing, if one was configured on the embed template. Store this if you need to reference which pricing tier was applied.
customerId	string	Current customer (tenant) ID. Deprecated — avoid building logic around this field.

Modular Product Data

For modular products (isModular: true), the payload includes an elements array with per-component details:

Field	Type	Description
elements	FinishModularElement[] | undefined	Array of individual components in the modular scene. Each element includes its own productId, productName, configurationCode, variantCode, selectedOptions, image, sku, and qty.

When handling modular products, iterate over elements to create individual line items or group them as a bundle:

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

  if (payload.isModular && payload.elements) {
    // Modular: create a line item per component, grouped by the scene short code
    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,
      });
    });
  } else {
    // Standard: single line item
    yourCart.addItem({
      id: payload.productId,
      name: payload.productName,
      sku: payload.sku,
      price: payload.unitPrice,
      quantity: payload.qty,
      variant: payload.variantCode,
      options: payload.selectedOptions,
      image: payload.image,
    });
  }
});

note

Modular product pricing works differently — unitPrice on the top-level payload is the total scene price. Individual element prices are not included in the event payload. If you need per-component pricing, use the Cart Operations API or your own pricing logic.

How Embed Settings Affect the Payload

Several embed template and product settings change what you receive in the payload:

Setting	Effect on payload
Custom Pricing enabled	price, unitPrice, currency reflect values you set via setPrice(), not Mimeeq's pricing engine
Price List Group configured	publicPriceListGroups is populated; prices come from that specific price list
No pricing configured	price, unitPrice, currency are undefined
MOQ / Incremental Quantity set	mqq and incrementalQty reflect product constraints; qty will always be a valid value
Hidden options (via rules or configuration)	Excluded from selectedOptions but included in selectedOptionsList
Custom Fields configured	Included in selectedOptionsList alongside regular options

Preserving Configurations

Store the embedShortCode along with configurationCode (standard) or shortCode (modular) from the payload. This lets customers return to their exact configuration later:

<!-- Standard product: re-open with saved configuration -->
<mmq-embed
  short-code="EMBED_SHORT_CODE"
  template="your_ecommerce_template"
  configuration-code="SAVED_CONFIGURATION_CODE"
></mmq-embed>

<!-- Modular product: re-open with saved scene -->
<mmq-embed
  short-code="EMBED_SHORT_CODE"
  template="your_ecommerce_template"
  scene-short-code="SAVED_SCENE_SHORT_CODE"
></mmq-embed>

This is useful for "Edit configuration" links in your cart, order history, or confirmation pages.

Analytics Integration

The same event can drive analytics tracking alongside cart integration:

document.addEventListener('mimeeq-add-to-cart', (event) => {
  const { productId, productName, price, qty, variantCode } = event.detail;

  // Send to your analytics platform
  gtag('event', 'add_to_cart', {
    currency: event.detail.currency,
    value: price,
    items: [{
      item_id: productId,
      item_name: productName,
      item_variant: variantCode,
      quantity: qty,
      price: event.detail.unitPrice,
    }],
  });

  // Also add to your cart...
});

For more analytics patterns, see the Google Analytics integration example.

Related Events

Beyond mimeeq-add-to-cart, several other events are useful for ecommerce integrations:

Event	When it fires	Typical use
mimeeq-price-change	Before the configurator fetches a new price (standard products only)	Sync your UI if showing prices outside the configurator
mimeeq-select-company	Customer changes company in the price selector	Update pricing context in your system
mimeeq-select-price-type	Customer changes price type (retail, wholesale, etc.)	Switch price tiers in your cart
mimeeq-show-summary	Finish button clicked (non-basket variant)	Capture configuration without cart intent

See the Events reference for the complete event catalog.

Next Steps

• Basket Embed — Use Mimeeq's built-in cart instead of your own
• Custom Pricing Integration — Provide prices from your own pricing engine
• Embed Options — All available embed configuration attributes
• Events — Complete event reference
• FinishEventPayload API Reference — TypeScript type documentation

For a business-oriented walkthrough with platform-specific setup steps, see Custom Ecommerce Integration on the help site.