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 |
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.
Set shopper identity
Attach customer context before sending commerce events:
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.
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.
Purchase completed
Send one checkout-level completion, followed by one event per purchased line item.
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
- Use a unique test product and cart.
- Complete one try-on.
- Add the product to cart.
- Start checkout.
- Complete a test order if your environment supports it.
- Open Virtual Fitting Room → Analytics and confirm each funnel stage increments once.
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.
