Commerce events reference
avsb.commerce.* is the browser API for sending e-commerce signals: product views, cart changes, checkout steps, searches, and more. These events power commerce audiences (groups of visitors picked out by rules, like everyone with $50 or more in their cart), revenue metrics, and product recommendations.
The install tag stubs out avsb.commerce until the full snippet loads. Calls you make before then wait in a queue. They run once the snippet is ready, and once the visitor has given consent, if you use consent mode. Wrap your calls in avsb.ready() so they always run at the right time:
avsb.ready?.(function () { avsb.commerce.productView({ sku: 'SHIRT-42', price: 29.99, currency: 'USD' })})Methods
Every method is fire-and-forget (returns void); the snippet batches and sends events in the background.
| Method | Signature | When to call |
|---|---|---|
productView | productView(product: ContractProduct) | A product detail page renders. |
productList | productList(items: ContractProduct[], meta?: { listId?: string }) | A PLP / collection / grid of products is shown (impressions). |
addToCart | addToCart(line: ContractCartLine) | An item is added to the cart. |
removeFromCart | removeFromCart(line: ContractCartLine) | An item is removed from the cart. |
cart | cart(cart: ContractCart) | Send a full cart snapshot (e.g. on cart-page load). |
checkoutStep | checkoutStep(step: { step: number | string; cart?: ContractCart }) | The visitor advances a checkout step. |
search | search(q: { query: string; resultCount?: number; skus?: string[] }) | A search is performed. |
categoryView | categoryView(c: { category: string; skus?: string[] }) | A category / collection landing page renders. |
wishlist | wishlist(w: { sku: string; action: 'add' | 'remove' }) | An item is added to or removed from a wishlist. |
The simplest thing that works: a product page
Only sku is required. Send whatever else you already have.
avsb.ready?.(function () { avsb.commerce.productView({ sku: 'SHIRT-42', title: 'Oxford Shirt', price: 29.99, currency: 'USD', })})A common example: add to cart, then check out
avsb.ready?.(function () { avsb.commerce.addToCart({ sku: 'SHIRT-42', quantity: 1, price: 29.99 }) // A full cart snapshot, e.g. when the cart page itself loads avsb.commerce.cart({ items: [{ sku: 'SHIRT-42', quantity: 1, price: 29.99 }], total: 29.99, currency: 'USD', }) avsb.commerce.checkoutStep({ step: 2 })})An awkward case: a product with sizes or colors
If the shirt comes in sizes or colors, each specific size-and-color combination is a "variant" of the product. Send the exact one the visitor picked in the variant field. The top-level price still describes the base product. Only set variant.price if that specific variant costs something different.
avsb.ready?.(function () { avsb.commerce.productView({ sku: 'SHIRT-42', title: 'Oxford Shirt', price: 29.99, variant: { variantSku: 'SHIRT-42-M-BLUE', options: { size: 'M', color: 'Blue' }, }, })})Data shapes
ContractProduct
Only sku is required; send whatever else you have.
| Field | Type | Notes |
|---|---|---|
sku | string | Required. The merchant's product id. |
productKey | string | Product-grain canonical key. Defaults to sku when absent. |
title | string | |
price | number | Major units as displayed (e.g. 29.99). |
priceMinor | number | Already-minor integer (e.g. 2999). Wins over price when both are set. |
compareAtPrice | number | Was-price / RRP, major units. |
compareAtPriceMinor | number | Was-price in minor units; wins over compareAtPrice. |
currency | string | ISO 4217 code, e.g. "USD". |
image / url | string | Product image and PDP URL. |
brand / category | string | |
categories | string[] | Multiple category paths. |
availability | 'in_stock' | 'out_of_stock' | 'preorder' | |
stock | number | |
variant | { variantSku: string; options?: Record<string, string>; price?: number; priceMinor?: number; stock?: number } | The exact version of the product in view, for example one size or color. |
customFields | Record<string, string | number | boolean> | Arbitrary extra attributes. |
createdAt | number | ms-epoch product creation time (feeds the NEW_ARRIVALS recipe). |
ContractCartLine
interface ContractCartLine { sku: string productKey?: string // defaults to sku quantity: number price?: number // major units priceMinor?: number // minor units, wins over price variantSku?: string}ContractCart
interface ContractCart { items: ContractCartLine[] total?: number // major units totalMinor?: number // minor units, wins over total currency?: string}Money and minor units
Prices you pass as price, compareAtPrice, or cart total are major units. That's the way a price tag shows them: 29.99, not 2999.
If you already store prices as whole-number minor units (cents, for most currencies), use the *Minor field instead: priceMinor, compareAtPriceMinor, or totalMinor. When both forms are present for the same value, the *Minor one wins.
The snippet converts every price to minor units before it sends the event, using your project's currency settings. Pick one form per value and stick with it, so nothing is ambiguous.