> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtual.fit/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce events

> Track cart, checkout, and purchase outcomes for Custom JavaScript storefront analytics.

Custom storefronts must send normalized commerce events so virtual.fit can connect fitting-room usage to cart and purchase outcomes. Try-on views, opens, uploads, starts, completions, and failures are recorded automatically.

## Event reference

| Event                        | Send when                               | Product fields                    | Amount                            |
| ---------------------------- | --------------------------------------- | --------------------------------- | --------------------------------- |
| `product_added_to_cart`      | A product is successfully added to cart | Required                          | Line total for the added quantity |
| `checkout_started_line_item` | Checkout starts                         | One event per line item           | Line total                        |
| `checkout_completed`         | The order or checkout completes         | Not required                      | Full order total                  |
| `purchase_line_item`         | The order completes                     | One event per purchased line item | Line total                        |

<Warning>
  Do not send one aggregate product event for a multi-item checkout. Send one line-item event per product, then one checkout-level completion event.
</Warning>

## Set shopper identity

Attach customer context before sending commerce events:

```javascript theme={null}
bitstudio('setCustomer', {
  id: currentCustomer?.id || '',
  email: currentCustomer?.email || ''
});
```

For logged-out shoppers, omit the fields or pass empty strings. virtual.fit maintains anonymous journey context according to the active consent mode.

## Add to cart

Send after your cart API confirms success, not when the shopper merely clicks the button.

```javascript theme={null}
bitstudio('track', 'product_added_to_cart', {
  cartId: 'cart-123',
  quantity: 2,
  totalAmount: 158,
  currency: 'USD',
  productId: 'sku-10042',
  productHandle: 'linen-midi-dress',
  productTitle: 'Linen Midi Dress'
});
```

Before adding manual tracking, check whether a successful add-to-cart already appears in virtual.fit. Do not send a duplicate event.

## Checkout started

Send one event for each checkout line item.

```javascript theme={null}
checkout.lineItems.forEach((lineItem) => {
  bitstudio('track', 'checkout_started_line_item', {
    cartId: checkout.cartId,
    checkoutId: checkout.id,
    quantity: lineItem.quantity,
    totalAmount: lineItem.lineTotal,
    currency: checkout.currency,
    productId: lineItem.productId,
    productHandle: lineItem.productHandle,
    productTitle: lineItem.productTitle
  });
});
```

## Purchase completed

Send one checkout-level completion, followed by one event per purchased line item.

```javascript theme={null}
bitstudio('track', 'checkout_completed', {
  cartId: order.cartId,
  checkoutId: order.checkoutId,
  orderId: order.id,
  currency: order.currency,
  totalAmount: order.total
});

order.lineItems.forEach((lineItem) => {
  bitstudio('track', 'purchase_line_item', {
    cartId: order.cartId,
    checkoutId: order.checkoutId,
    orderId: order.id,
    quantity: lineItem.quantity,
    totalAmount: lineItem.lineTotal,
    currency: order.currency,
    productId: lineItem.productId,
    productHandle: lineItem.productHandle,
    productTitle: lineItem.productTitle
  });
});
```

## Payload fields

| Field           | Type     | Description                                                    |
| --------------- | -------- | -------------------------------------------------------------- |
| `cartId`        | `string` | Stable cart identifier shared across cart and checkout events. |
| `checkoutId`    | `string` | Stable checkout identifier.                                    |
| `orderId`       | `string` | Completed order identifier.                                    |
| `quantity`      | `number` | Quantity represented by this line-item event.                  |
| `totalAmount`   | `number` | Numeric line or order total, without a currency symbol.        |
| `currency`      | `string` | Uppercase ISO 4217 code such as `USD` or `EUR`.                |
| `productId`     | `string` | Same external product ID synced to virtual.fit.                |
| `productHandle` | `string` | Same handle synced to virtual.fit.                             |
| `productTitle`  | `string` | Display title at the time of the event.                        |

## Correctness rules

* Send events only after the business action succeeds.
* Use stable IDs across the whole journey.
* Use line totals for line-item events and order totals for `checkout_completed`.
* Keep amounts in the stated currency; do not send formatted strings.
* Avoid duplicate events from click handlers, cart callbacks, and tag managers.
* Call `setCustomer` after identity changes.
* Respect analytics consent before including identity.

## Verify events

1. Use a unique test product and cart.
2. Complete one try-on.
3. Add the product to cart.
4. Start checkout.
5. Complete a test order if your environment supports it.
6. Open **Virtual Fitting Room → Analytics** and confirm each funnel stage increments once.

<Tip>
  If a stage is missing, verify that the event is sent only after the corresponding cart, checkout, or order action succeeds and that its product ID matches the synced catalog record.
</Tip>