Send cart events from your storefront

On Shopify, BigCommerce, Wix, Weebly and WordPress-rendered WooCommerce stores, the Privy code reads the visitor’s cart by itself. On a headless or custom storefront it can’t, so your storefront sends it with window.privyEvents. The cart value powers Cart Value display targeting and the cart value in your displays, such as a free-shipping bar. On a headless WooCommerce store, the cart’s items also power abandoned cart and abandoned checkout flows.

These events run in the visitor’s browser. They update the Privy code on the page, and on a WooCommerce store they also save the cart for abandoned cart flows. To send orders to Privy, use the Orders API from your server.

Quick start

The whole integration is three calls, shown in the Quick start example:

Set up the queue once per page.
identify when the shopper signs in or gives you their email.
cart_updated whenever the cart changes, including when it’s emptied after a purchase.

Using an AI coding assistant? Give it the Markdown version of this page: help.privy.com/docs/api-reference/browser-events.md.

The sections below cover each call in detail.

Set up the queue

Add window.privyEvents = window.privyEvents || []; before your first push, anywhere on the page. You can push events before the Privy code has loaded. They wait in the queue and run in order once it loads.

Events

Cart events

Send one whenever the cart changes: an item added, removed or updated, or the cart emptied.

window.privyEvents.push({
  event: 'cart_updated',
  total: 4599,           // $45.99, in minor units
  currency: 'USD',
  currency_minor_unit: 2 // optional, defaults to 2
});

// Cart emptied, or the shopper just bought
window.privyEvents.push({ event: 'cart_updated', total: 0 });

Field	Required	Description
`event`	Yes	`cart_updated`, `added_to_cart` or `checkout_started`. All three update the cart the same way. On WooCommerce, `checkout_started` also starts a checkout.
`total`	Yes	The cart’s merchandise total in minor units (cents for USD): the items minus discounts, without shipping or tax. A number or a numeric string.
`currency`	No	A three-letter ISO 4217 code, like `USD`.
`currency_minor_unit`	No	How many decimal places the currency has. Defaults to `2`. Use `0` for currencies like JPY.

Send total: 0 when the cart is emptied, including after a purchase.

If your storefront uses the WooCommerce Store API, its cart response has these values in totals. Send total_items minus total_discount as total, and pass currency_code and currency_minor_unit as they are. Send total_discount as discount. Don’t use total_price, which includes shipping and tax.

Cart items (WooCommerce)

On a headless WooCommerce store, add the cart’s items and id to your cart events so Privy’s abandoned cart flows can email the cart.

Cart items are currently supported for WooCommerce stores only. Abandoned carts from Custom Integration storefronts aren’t currently supported, but those storefronts can still send cart totals for Cart Value targeting.

window.privyEvents.push({
  event: 'cart_updated',
  cart_id: 't_0d5c3f9a8b7e6d5c4b3a2f1e0d9c8b', // your cart's id, the same on every push
  total: 4100,            // items minus discounts, as above
  discount: 500,          // optional: the discount already taken off total
  currency: 'USD',
  items: [
    { product_id: 101, quantity: 2 },
    { product_id: 210, variation_id: 211, quantity: 1 }
  ]
});

Field	Required	Description
`cart_id`	For items	A stable id for the cart, up to 255 characters, as a string or a whole number. With the WooCommerce Store API, use the `user_id` from the `Cart-Token` header’s payload. A guest’s cart is saved right away. A cart under any other id is saved once the shopper is a Privy contact.
`items`	No	The cart’s items, up to 50. Send `[]` when the cart is emptied.
`items[].product_id`	Yes	The WooCommerce product id. For a variation, the parent product’s id.
`items[].variation_id`	No	The variation’s id, for a variable product.
`items[].quantity`	Yes	A whole number, 1 or more.
`discount`	No	The discount in minor units. Privy adds it back to `total` to match the cart to its order.

Items with missing or invalid ids or quantities are skipped. Privy reads product names, images and links from your store’s catalog, so don’t send them. The cart link in abandoned cart emails goes to your WordPress site’s address, so redirect it to your storefront.

Privy saves the cart as soon as identify or a signup on a Privy display tells it who the shopper is, and links it to their contact on their next page. Carts are saved only for stores connected to Privy through WooCommerce.

Identify

Tell Privy who the visitor is, for example when they sign in.

window.privyEvents.push({
  event: 'identify',
  email: 'shopper@example.com'
});

Field	Required	Description
`event`	Yes	`identify`
`email`	Yes	The visitor’s email address.

Things to know

Push when the cart changes, not on every render. In a framework like React, push from your cart’s change handler, not from a component that re-renders. Repeated pushes with the same total are throttled, but each one still does work in the browser.
Cart events are ignored on platforms Privy already reads. On the platforms listed at the top of this page, the Privy code reads the cart itself and ignores cart events from privyEvents. identify works everywhere.
checkout_started starts a checkout on WooCommerce. On a headless WooCommerce store, send it when the shopper reaches checkout, with the cart’s id and items (see Cart items), so abandoned checkout flows can email them. Elsewhere it only updates the cart.
Calling the WooCommerce Store API from another domain: if your storefront and WordPress are on different domains, WordPress only answers your storefront’s requests once its domain is allowed. Add it with WordPress’s allowed_http_origins filter.

// 1. Once per page, before any push.
//    Safe to run before the Privy code loads.
window.privyEvents = window.privyEvents || [];

// 2. When the shopper signs in or gives you their email.
window.privyEvents.push({
  event: 'identify',
  email: 'shopper@example.com'
});

// 3. Whenever the cart changes, including when
//    it's emptied after a purchase.
window.privyEvents.push({
  event: 'cart_updated',
  total: 4599, // $45.99: items minus discounts, in cents
  currency: 'USD'
});

API Reference

Contacts

Orders

Events

Send cart events from your storefront

Quick start

Set up the queue

Events

Cart events

Cart items (WooCommerce)

Identify

Things to know

​Quick start

​Set up the queue

​Events

​Cart events

​Cart items (WooCommerce)

​Identify

​Things to know

Quick start

Set up the queue

Events

Cart events

Cart items (WooCommerce)

Identify

Things to know