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

# Send cart and product view events from your storefront

> Tell the Privy code about the visitor's cart, and on headless Shopify and WooCommerce the products they view, from a headless or custom storefront.

On Shopify Online Store themes, 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 or Shopify store, the cart's items also power abandoned cart flows, and on WooCommerce abandoned checkout flows too. On a headless Shopify or WooCommerce store, product views power Browse Abandonment flows.

> [!NOTE]
>
> These events run in the visitor's browser. They update the Privy code on the page. On a WooCommerce or Shopify store they also save the cart for abandoned cart flows, and on headless Shopify and WooCommerce the shopper's product views for Browse Abandonment. To send orders to Privy, use the [Orders API](https://help.privy.com/docs/api-reference/order-placed.md) from your server.

## Quick start

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

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

> [!TIP]
>
> Using an AI coding assistant? Give it the Markdown version of this page: [help.privy.com/docs/api-reference/browser-events.md](https://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.

```js theme={null}
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. On Shopify it only updates the cart. |
| `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.

> [!TIP]
>
> 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.

> [!NOTE]
>
> Cart items are supported for WooCommerce stores, and for Shopify stores (see [Cart items (Shopify)](#cart-items-shopify)). Abandoned carts from Custom Integration storefronts aren't currently supported, but those storefronts can still send cart totals for **Cart Value** targeting.

```js theme={null}
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. If every item is invalid, the event leaves the saved cart as it was. 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.

> [!NOTE]
>
> 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.

### Cart items (Shopify)

On a headless Shopify store (Hydrogen or a custom storefront on the Storefront API), Shopify doesn't send Privy its cart events, so your storefront sends the cart's items and id instead. Privy saves the cart for abandoned cart flows.

```js theme={null}
// cart: the Storefront API cart, with its lines
window.privyEvents.push({
  event: 'cart_updated',
  cart_id: cart.id, // "gid://shopify/Cart/...", as the Storefront API returns it
  total: Math.round(Number(cart.cost.subtotalAmount.amount) * 100), // cents, for a 2-decimal currency
  currency: cart.cost.subtotalAmount.currencyCode,
  items: cart.lines.nodes.map(line => ({
    product_id: line.merchandise.product.id, // "gid://shopify/Product/..."
    variant_id: line.merchandise.id,         // "gid://shopify/ProductVariant/..."
    quantity: line.quantity
  }))
});
```

| Field | Required | Description |
| - | - | - |
| `cart_id` | For items | The Storefront API cart's `id`, as returned, starting `gid://shopify/Cart/`. Privy keeps only the cart's token, never the `key` after it. An id without that prefix is taken as a WooCommerce cart. |
| `items` | No | The cart's lines, up to 50. Send `[]` when the cart is emptied. |
| `items[].product_id` | Yes | The product's id, as a Shopify GID (`gid://shopify/Product/123`) or the number alone. |
| `items[].variant_id` | Yes | The variant's id, as a GID (`gid://shopify/ProductVariant/456`) or the number alone. |
| `items[].quantity` | Yes | A whole number, 1 or more. |
| `discount` | No | Not needed: `total` before cart-level discount codes is what Privy expects. |

Items without both ids, or with an invalid quantity, are skipped. If every item is invalid, the event leaves the saved cart as it was. Privy reads product names and images from Shopify, so don't send them.

For `total`, send the Storefront API's `cost.subtotalAmount` in minor units (`1899.90` USD is `189990`). It's before tax and shipping, and before discount codes applied to the whole cart.

When the shopper checks out, send them to the cart's `checkoutUrl` exactly as the Storefront API returns it. Without its `key`, Shopify starts the checkout from a new cart, without the shopper's email. The cart link in abandoned cart emails opens Shopify's checkout with the cart's items. It goes through your store's Online Store address, so while that is password protected, shoppers see the password page first.

> [!NOTE]
>
> 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 Shopify.

### Product views

Send a `product_viewed` event on each product page so Privy can use the shopper's product views for Browse Abandonment flows. Product views are supported on headless Shopify and WooCommerce stores (see below for the id format).

```js theme={null}
window.privyEvents.push({
  event: 'product_viewed',
  product_id: product.id, // the product's id, in your platform's format
  price: variant.price    // optional: { amount, currencyCode }
});
```

| Field | Required | Description |
| - | - | - |
| `event` | Yes | `product_viewed` |
| `product_id` | Yes | The viewed product's id, in the format for your platform below. Other ids are ignored. |
| `price` | No | Shopify only. The viewed variant's price, with both `amount`, a plain decimal like `"749.95"`, and `currencyCode`, a three-letter ISO code like `USD`. A price missing either is ignored. |

Push once per product page view, when the product page opens, not on every render or variant change.

On Shopify, send the price if your Browse Abandonment flows use the **Min Price of Products Viewed** filter. Views sent without a price don't count toward that filter.

**Shopify:** send the Storefront API product's `id`, starting `gid://shopify/Product/`, as it's returned; the number alone isn't recorded for Shopify. Send the variant's `price` in your store's currency. Privy doesn't convert prices, so a price fetched with `@inContext` for another country can make the **Min Price of Products Viewed** filter match the wrong products. It uses only the prices in the currency of the shopper's latest priced view. On a store's Online Store pages, Shopify sends Privy the product views itself.

**WooCommerce:** send the product's numeric `id`, as a number or a string of digits, such as the `id` WooCommerce's Store API returns. For a variable product, send the parent product's id, not the variation's. Leave out `price`: Privy reads prices from your WooCommerce catalog. On a WordPress-rendered store, the Privy code records product views by itself.

> [!NOTE]
>
> If Privy already knows the shopper, for example from an earlier signup, each view is sent as it happens. Otherwise Privy sends the session's views once `identify` or a signup on a Privy display tells it who the shopper is. After a full page load that isn't a product page, they're sent with the next product view.

### Identify

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

```js theme={null}
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 and product view events are ignored on platforms Privy already reads.** On the platforms listed at the top of this page, including a Shopify store's own Online Store pages, the Privy code reads the cart itself and ignores cart and `product_viewed` events from `privyEvents`. Of those, only Shopify Online Store pages and WordPress-rendered WooCommerce pages record product views by themselves. `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](#cart-items-woocommerce)), 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.

```js Quick start theme={null}
// 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'
});
```
