Skip to main content

Basket Events

Basket events track the lifecycle of Mimeeq's built-in B2B cart — from creation through item management to order submission. These events only fire when using Mimeeq's own basket system (Integration = Mimeeq in the embed template). If you're using the HTML integration type and managing the cart yourself, see Finish & Cart Events for the mimeeq-add-to-cart event instead.

Basket Lifecycle Flow​

  User adds first item to cart
       │
       ▼
  mimeeq-basket-created            ← new cartId assigned
       │
       ▼
  mimeeq-basket-item-added         ← cartId + cartItemId
       │
       ▼
  mimeeq-basket-updated            ← full cart state (items, totals, currency)
       │
       ▼
  ┌─── User continues configuring ──────────────────────────────┐
  │                                                              │
  │  adds another item ──► mimeeq-basket-item-added              │
  │                              │                               │
  │                              ▼                               │
  │                        mimeeq-basket-updated                 │
  │                                                              │
  │  changes quantity ───► mimeeq-basket-updated                 │
  │                                                              │
  │  removes item ───────► mimeeq-basket-updated                 │
  │                                                              │
  │  price recalculation ► mimeeq-basket-updated                 │
  │  (company/price type                                         │
  │   change)                                                    │
  └──────────────────────────────────────────────────────────────┘
       │
       ▼
  User submits order
       │
       ▼
  mimeeq-basket-submitted          ← cartId + referenceCode

The key pattern: mimeeq-basket-item-added fires for each individual item, then mimeeq-basket-updated fires with the full cart state. Every change to the cart — adding, removing, quantity adjustment, or price recalculation — produces a mimeeq-basket-updated event with the current totals.

Events​

mimeeq-basket-created​

A new basket was created. This fires when the first item is added and no active basket exists yet. The cartId is the persistent identifier for this basket — store it if you need to reference the basket in your backend or via the Cart Operations API.

A basket is created once per session (or per user, if authentication is enabled). Subsequent items are added to the existing basket without triggering this event again.

Payload: BasketCreatedEventPayload

FieldTypeDescription
cartIdstringUnique identifier for the newly created basket (e.g., "CART-40e54c8a-...")
document.addEventListener('mimeeq-basket-created', (event) => {
  const { cartId } = event.detail;

  // Store cart ID for server-side operations
  sessionStorage.setItem('mimeeqCartId', cartId);

  // Initialize your cart tracking
  analytics.track('basket_created', { cartId });
});

mimeeq-basket-item-added​

An item was added to the basket. This fires immediately after the item is persisted — a mimeeq-basket-updated event follows with the full updated cart state. The cartItemId uniquely identifies this specific line item in the basket.

Payload: BasketItemAddedEventPayload

FieldTypeDescription
cartIdstringBasket identifier
cartItemIdstringUnique identifier for the newly added line item (e.g., "ITEM-00067907-...")
document.addEventListener('mimeeq-basket-item-added', (event) => {
  const { cartId, cartItemId } = event.detail;

  analytics.track('basket_item_added', { cartId, cartItemId });

  // Show a brief confirmation — the full cart update follows
  showToast('Item added to basket');
});

mimeeq-basket-updated​

The basket contents or totals have changed. This is the most frequently fired basket event — it follows every mutation: item added, item removed, quantity changed, or prices recalculated (e.g., after switching company or price type).

The payload includes the complete current state of the basket: all items, total price, quantity count, and currency. Use this as the single source of truth for keeping an external cart badge, summary panel, or analytics in sync.

Payload: BasketUpdatedEventPayload

FieldTypeDescription
cartIdstringBasket identifier
quantitynumberTotal number of items in the basket
itemsCartItem[]Array of all items currently in the basket
totalPricenumberSum of all item prices after quantity multiplication and pricing rules
currencystringCurrency code (e.g., "USD", "EUR", "GBP")
// Keep a cart badge in sync with basket state
document.addEventListener('mimeeq-basket-updated', (event) => {
  const { quantity, totalPrice, currency } = event.detail;

  const badge = document.getElementById('cart-badge');
  badge.textContent = quantity;
  badge.style.display = quantity > 0 ? 'flex' : 'none';

  const total = document.getElementById('cart-total');
  total.textContent = new Intl.NumberFormat(undefined, {
    style: 'currency',
    currency,
  }).format(totalPrice);
});
// Sync basket state with your backend for abandoned cart recovery
document.addEventListener('mimeeq-basket-updated', (event) => {
  const { cartId, items, totalPrice, currency } = event.detail;

  fetch('/api/sync-basket', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      cartId,
      itemCount: items.length,
      totalPrice,
      currency,
      lastUpdated: new Date().toISOString(),
    }),
  });
});

mimeeq-basket-submitted​

The basket was submitted as an order or RFQ. This is the terminal event in the basket lifecycle — after submission, the basket is closed and a new one will be created for subsequent items.

The referenceCode is a human-readable order reference (e.g., "OARTWSTS") that can be used to look up the order in the admin panel under Business Panel → Baskets → Submitted Baskets. A basket-submitted webhook also fires server-side if configured.

Payload: BasketSubmittedEventPayload

FieldTypeDescription
cartIdstringBasket identifier of the submitted basket
referenceCodestring | undefinedHuman-readable order reference code (e.g., "OARTWSTS"), if assigned
document.addEventListener('mimeeq-basket-submitted', (event) => {
  const { cartId, referenceCode } = event.detail;

  // Track conversion
  analytics.track('order_submitted', {
    cartId,
    referenceCode,
  });

  // Redirect to confirmation page
  if (referenceCode) {
    window.location.href = `/order-confirmation?ref=${referenceCode}`;
  }
});
// Notify your backend to process the order
document.addEventListener('mimeeq-basket-submitted', async (event) => {
  const { cartId, referenceCode } = event.detail;

  // Retrieve full order details via the API
  const items = await window.mimeeqApp.actions.getCartItems(cartId);

  await fetch('/api/orders', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      referenceCode,
      cartId,
      items,
    }),
  });
});
tip

If you need detailed order data (items, submitter info, custom fields, pricing rules, PDF URL), the basket-submitted webhook provides a much richer payload than the browser event. See Basket Webhook Payloads for the full structure.

Programmatic Cart Management​

Beyond listening for events, you can manage the basket programmatically through window.mimeeqApp.actions. The full API is documented in the Basket Embed guide. Key operations:

ActionDescription
createCart()Create a new empty basket
addItemToCart(item)Add an item programmatically
getCartItems(cartId)Retrieve all items in a basket
removeCartItem(cartId, itemId)Remove a specific line item
recalculateCart(cartId, ...)Recalculate prices after context change
preSubmitCart(cartId, form)Save checkout form progress
submitCart(cartId, form)Submit the order
getCartSubmissionForm(cartId)Get the checkout form field definitions

Each mutation action triggers the corresponding basket events, so your event listeners stay in sync whether the user interacts with the built-in basket UI or you drive the basket programmatically.