Customer events reference
Customer events represent and describe the behavior of your customers, including key events during the customer journey, such as page views, product views, cart updates, searches, and purchases.
Event structure
Anchor link to section titled "Event structure"| Name | Type | Description |
|---|---|---|
| id | string | The ID of the customer event. |
| clientId | string | The client-side ID of the customer, provided by Shopify. |
| name | string | The name of the customer event. |
| timestamp | string | The timestamp of when the customer event occurred, in ISO 8601 format. |
| context | Context | A snapshot of various read-only properties of the browser at the time of event. |
| data | Object | A free-form JSON object representing data specific to this event provided by Shopify. Refer to standard events for details on the payload available to each event. |
| customData | Object | A free-form JSON object representing data specific to a custom event provided by the custom event publisher. |
Standard events
Anchor link to section titled "Standard events"Shopify publishes a limited set of standard events that are available on the online store, checkout, and order status pages. Shopify might share specific data for each event as part of the data attribute. The following standard events are available:
- checkout_completed
- checkout_started
- collection_viewed
- page_viewed
- payment_info_submitted
- product_added_to_cart
- product_viewed
- search_submitted
checkout_completed
Anchor link to section titled "checkout_completed"The checkout_completed event logs when a visitor completes a purchase. This event is available on the order status and checkout pages.
| Name | Type | Description |
|---|---|---|
| checkout | Checkout | A container for all the information required to checkout items and pay. |
Example:
checkout_started
Anchor link to section titled "checkout_started"The checkout_started event logs an instance of a buyer starting the checkout process. This event is available on the checkout page.
| Name | Type | Description |
|---|---|---|
| checkout | Checkout | A container for all the information required to checkout items and pay. |
Example:
collection_viewed
Anchor link to section titled "collection_viewed"The collection_viewed event logs an instance where a buyer visited a product collection index page. This event is available on the online store page.
| Name | Type | Description |
|---|---|---|
| collection | Collection | A collection is a group of products that a shop owner can create to organize them or make their shops easier to browse. |
Example:
page_viewed
Anchor link to section titled "page_viewed"The page_viewed event logs an instance where a buyer visited a page. This event is available on the online store, checkout, and order status pages.
Example:
payment_info_submitted
Anchor link to section titled "payment_info_submitted"The payment_info_submitted event logs an instance of a buyer submitting their payment information. This event is available on the checkout page.
| Name | Type | Description |
|---|---|---|
| checkout | Checkout | A container for all the information required to checkout items and pay. |
Example:
product_added_to_cart
Anchor link to section titled "product_added_to_cart"The product_added_to_cart event logs an instance where a buyer adds a product to their cart. This event is available on the online store page.
| Name | Type | Description |
|---|---|---|
| cartLine | CartLine | Information about the merchandise in the cart. |
Example:
product_viewed
Anchor link to section titled "product_viewed"The product_viewed event logs an instance where a buyer visited a product details page. This event is available on the product page.
| Name | Type | Description |
|---|---|---|
| productVariant | ProductVariant | A product variant represents a different version of a product, such as differing sizes or differing colors. |
Example:
search_submitted
Anchor link to section titled "search_submitted"The search_submitted event logs an instance where a buyer performed a search on the storefront. This event is available on the online store page.
| Name | Type | Description |
|---|---|---|
| searchResult | SearchResult | An object that contains the metadata of when a search has been performed. |
Example:
Standard objects
Anchor link to section titled "Standard objects"Some events reference object types that have their own schema. The following stand object are available:
- Attribute
- Cart
- CartCost
- CartLine
- CartLineCost
- Checkout
- CheckoutLineItem
- Collection
- Context
- Customer
- Image
- Location
- MailingAddress
- Money
- Order
- Product
- ProductVariant
- SearchResult
- ShippingRate
- WebPixelsDocument
- WebPixelsNavigator
- WebPixelsWindow
Custom attributes left by the customer to the merchant, either in their cart or during checkout.
| Name | Type | Description |
|---|---|---|
| key | string | The key for the attribute. |
| value | string | The value for the attribute. |
A cart represents the merchandise that a customer intends to purchase, and the estimated cost associated with the cart.
| Name | Type | Description |
|---|---|---|
| cost | CartCost | The estimated costs that the buyer will pay at checkout. |
| id | string | A globally unique identifier. |
| lines | CartLine[] | A list of lines containing information about the items the customer intends to purchase. |
| totalQuantity | number | The total number of items in the cart. |
The costs that the customer will pay at checkout. It uses CartBuyerIdentity to determine international pricing.
| Name | Type | Description |
|---|---|---|
| totalAmount | Money | The total amount for the customer to pay. |
Information about the merchandise in the cart.
| Name | Type | Description |
|---|---|---|
| cost | CartLineCost | The cost of the merchandise that the buyer will pay for at checkout. The costs are subject to change and changes will be reflected at checkout. |
| merchandise | ProductVariant | The merchandise that the buyer intends to purchase. |
| quantity | number | The quantity of the merchandise that the customer intends to purchase. |
CartLineCost
Anchor link to section titled "CartLineCost"The cost of the merchandise line that the customer will pay at checkout.
| Name | Type | Description |
|---|---|---|
| totalAmount | Money | The total cost of the merchandise line. |
A container for all the information required to checkout items and pay.
| Name | Type | Description |
|---|---|---|
| attributes | Attribute[] | A list of attributes accumulated throughout the checkout process. |
| currencyCode | string | The three-letter code that represents the currency, for example, USD. Supported codes include standard ISO 4217 codes, legacy codes, and non-standard codes. |
| string | The email attached to this checkout. | |
| lineItems | CheckoutLineItem[] | A list of line item objects, each one containing information about an item in the checkout. |
| order | Order | The resulting order from a paid checkout. |
| phone | string | A unique phone number for the customer. Formatted using E.164 standard. For example, +16135551111. |
| shippingAddress | MailingAddress | The shipping address to where the line items will be shipped. |
| shippingLine | ShippingRate | Once a shipping rate is selected by the customer it is transitioned to a shipping_line object. |
| subtotalPrice | Money | The price at checkout before duties, shipping, and taxes. |
| token | string | A unique identifier for a particular checkout. |
| totalPrice | Money | The sum of all the prices of all the items in the checkout, including duties, taxes, and discounts. |
| totalTax | Money | The sum of all the taxes applied to the line items and shipping lines in the checkout. |
CheckoutLineItem
Anchor link to section titled "CheckoutLineItem"A single line item in the checkout, grouped by variant and attributes.
| Name | Type | Description |
|---|---|---|
| id | string | A globally unique identifier. |
| quantity | number | The quantity of the line item. |
| title | string | The title of the line item. Defaults to the product's title. |
| variant | ProductVariant | Product variant of the line item. |
A collection is a group of products that a shop owner can create to organize them or make their shops easier to browse.
| Name | Type | Description |
|---|---|---|
| id | string | A globally unique identifier. |
| title | string | The collection’s name. Maximum length: 255 characters. |
A snapshot of various read-only properties of the browser at the time of event.
| Name | Type | Description |
|---|---|---|
| window | WebPixelsWindow | Snapshot of a subset of properties of the window object in the top frame of the browser. |
| document | WebPixelsDocument | Snapshot of a subset of properties of the document object in the top frame of the browser. |
| navigator | WebPixelsNavigator | Snapshot of a subset of properties of the navigator object in the top frame of the browser. |
A customer represents a customer account with the shop. Customer accounts store contact information for the customer, saving logged-in customers the trouble of having to provide it at every checkout.
| Name | Type | Description |
|---|---|---|
| string | The customer’s email address. | |
| id | string | The ID of the customer. |
| phone | string | The customer’s phone number. |
An image resource.
| Name | Type | Description |
|---|---|---|
| src | string | The location of the image as a URL. |
A snapshot of a subset of properties of the location object in the top frame of the browser.
| Name | Type | Description |
|---|---|---|
| href | string | Per MDN, a string containing the entire URL. |
| protocol | string | Per MDN, a string containing the protocol scheme of the URL, including the final ':'. |
| host | string | Per MDN, a string containing the host, that is the hostname, a ':', and the port of the URL. |
| hostname | string | Per MDN, a string containing the domain of the URL. |
| port | string | Per MDN, a string containing the port number of the URL. |
| pathname | string | Per MDN, a string containing an initial '/' followed by the path of the URL, not including the query string or fragment. |
| search | string | Per MDN, a string containing a '?' followed by the parameters or "querystring" of the URL. |
| hash | string | Per MDN, a string containing a '#' followed by the fragment identifier of the URL. |
| origin | string | Per MDN, a string containing the canonical form of the origin of the specific location. |
MailingAddress
Anchor link to section titled "MailingAddress"A mailing address for customers and shipping.
| Name | Type | Description |
|---|---|---|
| city | string | The name of the city, district, village, or town. |
| country | string | The name of the country. |
| countryCode | string | The two-letter code that represents the country, for example, US. The country codes generally follows ISO 3166-1 alpha-2 guidelines. |
| phone | string | The phone number for this mailing address as entered by the customer. |
| province | string | The region of the address, such as the province, state, or district. |
| provinceCode | string | The two-letter code for the region. For example, ON. |
A monetary value with currency.
| Name | Type | Description |
|---|---|---|
| amount | number | The decimal money amount. |
| currencyCode | string | The three-letter code that represents the currency, for example, USD. Supported codes include standard ISO 4217 codes, legacy codes, and non-standard codes. |
An order is a customer’s completed request to purchase one or more products from a shop. An order is created when a customer completes the checkout process.
| Name | Type | Description |
|---|---|---|
| id | string | The ID of the order. |
A product is an individual item for sale in a Shopify store.
| Name | Type | Description |
|---|---|---|
| id | string | The ID of the product. |
| title | string | The product’s title. |
| vendor | string | The product’s vendor name. |
ProductVariant
Anchor link to section titled "ProductVariant"A product variant represents a different version of a product, such as differing sizes or differing colors.
| Name | Type | Description |
|---|---|---|
| id | string | A globally unique identifier. |
| image | Image | Image associated with the product variant. This field falls back to the product image if no image is available. |
| price | Money | The product variant’s price. |
| product | Product | The product object that the product variant belongs to. |
| sku | string | The SKU (stock keeping unit) associated with the variant. |
| title | string | The product variant’s title. |
SearchResult
Anchor link to section titled "SearchResult"An object that contains the metadata of when a search has been performed.
| Name | Type | Description |
|---|---|---|
| query | string | The search query that was executed. |
| productVariants | ProductVariant[] | A list of product variants returned by the search query. |
ShippingRate
Anchor link to section titled "ShippingRate"A shipping rate to be applied to a checkout.
| Name | Type | Description |
|---|---|---|
| price | Money | Price of this shipping rate. |
WebPixelsDocument
Anchor link to section titled "WebPixelsDocument"A snapshot of a subset of properties of the document object in the top frame of the browser.
| Name | Type | Description |
|---|---|---|
| characterSet | string | Per MDN, returns the character set being used by the document. |
| location | Location | Per MDN, returns the URI of the current document. |
| referrer | string | Per MDN, returns the URI of the page that linked to this page. |
| title | string | Per MDN, returns the title of the current document. |
WebPixelsNavigator
Anchor link to section titled "WebPixelsNavigator"A snapshot of a subset of properties of the navigator object in the top frame of the browser.
| Name | Type | Description |
|---|---|---|
| cookieEnabled | boolean | Per MDN, returns false if setting a cookie will be ignored and true otherwise. |
| language | string | Per MDN, returns a string representing the preferred language of the user, usually the language of the browser UI. The null value is returned when this is unknown. |
| languages | string[] | Per MDN, returns an array of strings representing the languages known to the user, by order of preference. |
| userAgent | string | Per MDN, returns the user agent string for the current browser. |
WebPixelsWindow
Anchor link to section titled "WebPixelsWindow"A snapshot of a subset of properties of the window object in the top frame of the browser.
| Name | Type | Description |
|---|---|---|
| innerHeight | number | Per MDN, gets the height of the content area of the browser window including, if rendered, the horizontal scrollbar. |
| innerWidth | number | Per MDN, gets the width of the content area of the browser window including, if rendered, the vertical scrollbar. |
| outerHeight | number | Per MDN, gets the height of the outside of the browser window. |
| outerWidth | number | Per MDN, gets the width of the outside of the browser window. |
| pageXOffset | number | Per MDN, an alias for window.scrollX. |
| pageYOffset | number | Per MDN, an alias for window.scrollY. |
| screenX | number | Per MDN, the horizontal distance from the left border of the user's browser viewport to the left side of the screen. |
| screenY | number | Per MDN, the vertical distance from the top border of the user's browser viewport to the top side of the screen. |
| scrollX | number | Per MDN, the number of pixels that the document has already been scrolled horizontally. |
| scrollY | number | Per MDN, the number of pixels that the document has already been scrolled vertically. |
| origin | string | Per MDN, the global object's origin, serialized as a string. |
| location | Location | Per MDN, the location, or current URL, of the window object. |
Custom events
Anchor link to section titled "Custom events"Merchants and app developers can publish custom customer events from online store theme liquid files, theme app extensions and checkout extensions. When custom customer events are published they can be accessed by all custom pixels and app pixels.
Publishing custom events
Anchor link to section titled "Publishing custom events"The analytics.publish method is available in different contexts for publishing custom events. The analytics.publish method takes an event_name and some event_data as parameters.
| Parameter | Type | Description |
|---|---|---|
| event_name | String | The name of a single event or a group of events. |
| event_data | Object | An object that contains metadata about the event. |
In the online store you can access the analytics.publish method on the Shopify object.
On checkout, you can publish custom events from your checkout extensions. For more information, review the analytics checkout extension point.
The object passed into the event_data field is shared with subscribers to the event using the customData field. If you haven't set up a way for merchants to define custom transformation of payloads, then your app pixels might not be able to parse these custom fields. Custom pixels, though, can be changed by the merchant to translate custom fields to a service’s required format.
Subscribing to custom events
Anchor link to section titled "Subscribing to custom events"You can subscribe to custom events like you would standard events. Anything published to the custom event is passed to the customData field.
Example: