Choose a version:

Cart analytics

The cart analytics functions publish analytics events when the customer's cart changes. Use these functions to send cart updated, product added to cart, and product removed from cart events to your analytics destinations through the analytics bus.

In React and Vue apps, call useCartAnalytics inside the CartProvider from createCartComponents. In other frameworks, pass a cart store to trackCartAnalytics. In Vue, useCartAnalytics starts tracking when the component mounts and stops when the component unmounts.

Import trackCartAnalytics from @shopify/hydrogen, or import useCartAnalytics from @shopify/hydrogen/react or @shopify/hydrogen/vue.

Render ShopifyScripts before tracking starts. Tracking needs the analytics bus that ShopifyScripts creates.

Anchor to Cart store trackingCart store tracking

Anchor to trackCartAnalytics
trackCartAnalytics(
store
)

Publishes cart analytics events when the server confirms a change to the customer's cart. In React, call useCartAnalytics.

The function publishes cart_updated when the cart's update time changes, plus product_added_to_cart or product_removed_from_cart for each added line, removed line, and quantity change. The function waits until no cart change or reload is in flight. Analytics payloads leave out cart lines without merchandise.

The function stores the last published cart update in local storage under cartLastUpdatedAt to avoid repeat events across page loads and tabs. A store that you fill from your own cart query must select updatedAt. Without the update time, the function publishes on every confirmed cart state. The function also sets window.Shopify.currency.active to the cart's currency.

The function throws when the Shopify analytics bus isn't available, including during server rendering. Render ShopifyScripts, then start tracking in a client-only effect, such as useEffect or onMounted.

Anchor to trackCartAnalytics-parametersParameters

Anchor to store store required: The cart store to track.

Anchor to trackCartAnalytics-returnsReturns

() => void

A function that stops tracking.

CartAnalyticsStore

A cart store, or any object with the cart store's `getState()` and `subscribe()` methods.

getState
Returns the current cart state, including changes that the server hasn't confirmed yet.
```
() => CartState<CartData>
```
subscribe
Calls the listener on every state change and returns a function that removes the listener. The method works with React's `useSyncExternalStore`.
```
(listener: (state: CartState<CartData>) => void) => () => void
```

CartState

The cart, plus what's loading, pending, and failed. The cart hooks return values from this state. The data type matches the cart fragment in your cart server handlers.

data
The cart, including changes that the server hasn't confirmed yet.
```
TData
```
errors
Errors and warnings, grouped by the part of the cart that they affect.
```
CartErrorState
```
loading
`true` while the store loads the full cart: the first load, a load after `reset()`, or before `connect()` when the store has no initial data.
```
boolean
```
pending
The parts of the cart with changes in flight.
```
CartPending
```
readyPromise
Present while a full cart load runs. The promise resolves, and never rejects, when the load finishes or the store drops the load.
```
PromiseLike<void>
```
revalidating
`true` while the store reloads the cart in the background after overlapping cart changes or a `refresh()` call.
```
boolean
```

CartErrorState

The cart's errors, grouped by the part of the cart that they affect: lines, the note, attributes, discount codes, or the cart as a whole. Each group has a timestamp in milliseconds since the epoch. Use the timestamps to flag stale errors or dismiss errors after a timeout. Failed requests go in a network list, apart from Storefront API user errors.

attributes
Errors keyed by attribute name.
```
Map<string, CartErrorGroup>
```
attributesUpdatedAt
Time in milliseconds since the epoch when the store last recorded attribute errors, or `0` before any.
```
number
```
cart
Errors that don't belong to a line, the note, an attribute, or a discount code.
```
CartErrorGroup
```
cartUpdatedAt
Time in milliseconds since the epoch of the last line, discount code, or attribute error, or `0` before any.
```
number
```
discountCodes
Errors keyed by discount code.
```
Map<string, CartErrorGroup>
```
discountCodesUpdatedAt
Time in milliseconds since the epoch when the store last recorded discount code errors, or `0` before any.
```
number
```
lastUpdatedAt
Time in milliseconds since the epoch when the store last recorded any error, or `0` before the first.
```
number
```
lines
Errors keyed by cart line ID.
```
Map<string, CartErrorGroup>
```
linesUpdatedAt
Time in milliseconds since the epoch when the store last recorded line errors, or `0` before any.
```
number
```
network
Failed cart requests. A failed cart change adds an entry, with an HTTP status when the endpoint returned a non-2xx response. A failed refresh adds an entry with a generic message and no status. A failed first load or a failed load after a reset adds no entry.
```
CartNetworkEntry[]
```
networkUpdatedAt
Time in milliseconds since the epoch when the store last recorded a network error, or `0` before any.
```
number
```
note
Errors for the cart note.
```
CartErrorGroup
```
noteUpdatedAt
Time in milliseconds since the epoch when the store last recorded note errors, or `0` before any.
```
number
```

CartErrorGroup

Errors and warnings from one cart change.

userErrors
Validation errors that the mutation returned.
```
CartUserError[]
```
warnings
Non-blocking warnings that the mutation returned.
```
CartWarning[]
```

CartUserError

A validation error returned by a Storefront API cart mutation.

code
Machine-readable error code, or `null` for unclassified errors.
```
CartErrorCode | null
```
field
The path to the input field that caused the error, such as `["lines", "0", "quantity"]`.
```
string[]
```
message
Human-readable error text from the Storefront API.
```
string
```

CartErrorCode

Error codes that the cart POST handler returns. The handler returns `invalid_cart_request` when it can't parse a JSON request, and `missing_cart` when a JSON request changes the cart but has no cart ID. With `customerSession`, the handler returns `cart_mutation_failed` when a mutation fails after the handler refreshes the customer's access token.

"invalid_cart_request" | "missing_cart" | "cart_mutation_failed"

CartWarning

A non-blocking warning returned by a Storefront API cart mutation.

code
The warning code from the Storefront API.
```
CartWarningCode
```
message
Human-readable warning text from the Storefront API.
```
string
```

CartNetworkEntry

A failed cart request, such as a non-2xx response or a timeout. Canceled requests add no entry.

message
The error message, or a generic message when the failure has no message of its own.
```
string
```
status
The HTTP status code, when the endpoint returned a non-2xx response.
```
number
```

CartPending

Shows which parts of the cart have changes in flight. Check a line ID or a discount code to show a pending indicator on that item. Check `cost` to show pending UI on prices, which update only when the server responds.

attributes
`true` while an attribute update is in flight.
```
boolean
```
cost
`true` while a change that can affect cart prices is in flight.
```
boolean
```
discountCodes
Discount codes with an apply or remove in flight.
```
Set<string>
```
lines
Line IDs with an add, quantity change, or removal in flight. A new line has an ID that starts with `optimistic:` until the server confirms the line.
```
Set<string>
```
note
`true` while a note update is in flight.
```
boolean
```

CartData

The customer's cart, in the shape that the Storefront API returns. Cart costs come only from the server. Extra fields from your custom cart fragment appear unchanged.

[key: string]
```
unknown
```
attributes
Cart-level custom attributes.
```
Attribute[]
```
checkoutUrl
The Shopify checkout URL. The URL can change when the customer logs in or out, or changes tracking consent.
```
string | null
```
cost
The cart's subtotal, total, and checkout charge.
```
CartCost
```
discountCodes
Discount codes applied to the cart, with their applicability.
```
DiscountCode[]
```
id
The cart's Storefront API GID, or `null` when no cart exists yet.
```
string | null
```
lines
The cart's line items.
```
CartLineConnection
```
note
Customer-supplied cart note, or `null` or empty when unset.
```
string | null
```
totalQuantity
Sum of all line quantities.
```
number
```
updatedAt
The cart's last update time in ISO 8601 format. Absent until the first server response.
```
string
```

Attribute

A key-value pair attached to the cart or to an individual cart line.

key
The attribute name. Look up the attribute's errors with this name.
```
string
```
value
The attribute value.
```
string | null
```

CartCost

The cart's costs from the Storefront API.

checkoutChargeAmount
Estimated amount due at checkout, excluding deferred payments. Equals the subtotal when no deferred payments exist.
```
Money
```
subtotalAmount
The amount, before taxes and cart-level discounts, for the customer to pay.
```
Money
```
totalAmount
Final amount the customer pays at checkout.
```
Money
```

Money

A monetary value from the Storefront API.

amount
The decimal amount as a string, such as `29.99`.
```
string
```
currencyCode
The ISO 4217 currency code, such as `USD`.
```
string
```

DiscountCode

A discount code applied to the cart.

applicable
Whether the code applies to the cart's current contents. A new code reads `false` until the server responds.
```
boolean
```
code
The discount code text. Look up the code's pending state and errors with this value.
```
string
```

CartLineConnection

The cart's line items in the Storefront API connection shape.

[key: string]
```
unknown
```
nodes
The cart lines that the cart query returns.
```
CartLine[]
```

CartLine

A single line item in the cart. Each line holds a product variant at a quantity. A line can carry custom attributes, a selling plan allocation for a subscription, or line components for a bundle.

attributes
Custom key-value attributes attached to the line.
```
Attribute[]
```
cost
Per-line cost breakdown from the Storefront API.
```
CartLineCost
```
id
The cart line's Storefront API GID. Look up the line's pending state and errors with this ID.
```
string
```
lineComponents
Nested child lines when this line is a bundle parent.
```
CartLine[]
```
merchandise
The product variant on the line.
```
CartLineMerchandise
```
parentRelationship
The parent line's ID when this line is a bundle component.
```
{ parent: { id: string } } | null
```
quantity
Number of units of this merchandise in the cart.
```
number
```
sellingPlanAllocation
Subscription selling plan allocation, or `null` for one-time purchases.
```
{ sellingPlan: { id: string } } | null
```

CartLineCost

A cart line's costs from the Storefront API.

amountPerQuantity
Unit price for a single quantity of this line.
```
Money
```
compareAtAmountPerQuantity
Original compare-at unit price, or `null` when no comparison exists.
```
Money | null
```
subtotalAmount
Line subtotal before line-level discounts.
```
Money
```
totalAmount
Line total after all applicable discounts.
```
Money
```

CartLineMerchandise

The product variant on a cart line.

[key: string]
```
unknown
```
id
Storefront API GID of the product variant.
```
string
```

image

The variant image that the cart query selects.

{
    id?: string | null;
    url: string;
    altText?: string | null;
    width?: number | null;
    height?: number | null;
    [key: string]: unknown;
  } | null

product

The product that the variant belongs to.

{ [key: string]: unknown; title: string; handle?: string; }

quantityAvailable
Units available for sale. When your cart fragment selects the field, the store caps the quantity of a `set` submission at this number.
```
number | null
```
selectedOptions
The variant's selected options as name and value pairs.
```
Array<{ name: string; value: string }>
```
title
The variant title, such as `"Small / Black"`.
```
string
```

Examples

TypeScript

import { configureCartEndpoint, createCartStore, trackCartAnalytics } from "@shopify/hydrogen";

const store = createCartStore();

export function startCart() {

configureCartEndpoint("/api/cart");

store.connect();

const stopTracking = trackCartAnalytics(store);

return () => {

stopTracking();

store.destroy();

};

}

Examples

Description

Start tracking after the store connects in the browser, and stop tracking before you destroy the store.

TypeScript

import { configureCartEndpoint, createCartStore, trackCartAnalytics } from "@shopify/hydrogen";

const store = createCartStore();

export function startCart() {
  configureCartEndpoint("/api/cart");
  store.connect();

  const stopTracking = trackCartAnalytics(store);

  return () => {
    stopTracking();
    store.destroy();
  };
}

Anchor to React and Vue hookReact and Vue hook

Anchor to useCartAnalytics
useCartAnalytics()

Publishes cart analytics events when the customer's cart changes.

Call the hook once near the root of your app, inside CartProvider. The hook starts tracking on mount and stops on unmount. The hook publishes cart_updated, product_added_to_cart, and product_removed_from_cart events.

The hook throws outside CartProvider, and when the Shopify analytics bus isn't available. Render ShopifyScripts before the hook runs.

Anchor to useCartAnalytics-returnsReturns
void

Nothing. The hook tracks cart analytics for the lifetime of the calling component.

Examples

React

import { createCartComponents, useCartAnalytics } from "@shopify/hydrogen/react";

import type { ReactNode } from "react";

const { CartProvider } = createCartComponents();

function CartAnalyticsTracker() {

useCartAnalytics();

return null;

}

export function Providers({ children }: { children: ReactNode }) {

return (

{children}

</CartProvider>

);

}

Examples

Description

Render a tracker component inside the cart provider.

React

import { createCartComponents, useCartAnalytics } from "@shopify/hydrogen/react";
import type { ReactNode } from "react";

const { CartProvider } = createCartComponents();

function CartAnalyticsTracker() {
  useCartAnalytics();
  return null;
}

export function Providers({ children }: { children: ReactNode }) {
  return (
    <CartProvider>
      <CartAnalyticsTracker />
      {children}
    </CartProvider>
  );
}

Description

Call the composable in a component that renders inside the cart provider.

Vue

<script setup lang="ts">
import { useCartAnalytics } from "@shopify/hydrogen/vue";

// Render this component inside CartProvider. useCartAnalytics throws outside it.
useCartAnalytics();
</script>

<template>
  <slot />
</template>

Was this page helpful?

Anchor to Cart store trackingCart store tracking

Anchor to trackCartAnalyticstrackCartAnalytics(storestore)

Anchor to trackCartAnalytics-parametersParameters

Anchor to trackCartAnalytics-returnsReturns

CartAnalyticsStore

CartState

CartErrorState

CartErrorGroup

CartUserError

CartErrorCode

CartWarning

CartNetworkEntry

CartPending

CartData

Attribute

CartCost

Money

DiscountCode

CartLineConnection

CartLine

CartLineCost

CartLineMerchandise

Examples

Description

TypeScript

Anchor to React and Vue hookReact and Vue hook

Anchor to useCartAnalyticsuseCartAnalytics()

Anchor to useCartAnalytics-returnsReturnsvoidvoid

Examples

Description

React

Description

Vue

Anchor to trackCartAnalytics
trackCartAnalytics(
store
)

Anchor to useCartAnalytics
useCartAnalytics()

Anchor to useCartAnalytics-returnsReturns
void