checkout_started

The checkout_started event logs an instance of a customer starting the checkout process. This event is available on the checkout page. For Checkout Extensibility, this event is triggered every time a customer enters checkout. For non-checkout extensible shops, this event is only triggered the first time a customer enters checkout.

Anchor to propertiesProperties

Anchor to clientId clientId string: The client-side ID of the customer, provided by Shopify
Anchor to context context
Anchor to data data
Anchor to id id string: The ID of the customer event
Anchor to name name string: The name of the customer event
Anchor to seq seq number: The sequence index number of the event.
Anchor to timestamp timestamp string: The timestamp of when the customer event occurred, in ISO 8601 format
Anchor to type type .Standard

Context

A snapshot of various read-only properties of the browser at the time of event

document
Snapshot of a subset of properties of the `document` object in the top frame of the browser
```
WebPixelsDocument
```
navigator
Snapshot of a subset of properties of the `navigator` object in the top frame of the browser
```
WebPixelsNavigator
```
window
Snapshot of a subset of properties of the `window` object in the top frame of the browser
```
WebPixelsWindow
```

WebPixelsDocument

A snapshot of a subset of properties of the `document` object in the top frame of the browser

characterSet
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document), returns the character set being used by the document
```
string
```
location
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document), returns the URI of the current document
```
Location
```
referrer
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document), returns the URI of the page that linked to this page
```
string
```
title
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document), returns the title of the current document
```
string
```

Location

A snapshot of a subset of properties of the `location` object in the top frame of the browser

hash
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location), a string containing a `'#'` followed by the fragment identifier of the URL
```
string
```
host
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location), a string containing the host, that is the hostname, a `':'`, and the port of the URL
```
string
```
hostname
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location), a string containing the domain of the URL
```
string
```
href
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location), a string containing the entire URL
```
string
```
origin
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location), a string containing the canonical form of the origin of the specific location
```
string
```
pathname
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location), a string containing an initial `'/'` followed by the path of the URL, not including the query string or fragment
```
string
```
port
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location), a string containing the port number of the URL
```
string
```
protocol
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location), a string containing the protocol scheme of the URL, including the final `':'`
```
string
```
search
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location), a string containing a `'?'` followed by the parameters or "querystring" of the URL
```
string
```

WebPixelsNavigator

A snapshot of a subset of properties of the `navigator` object in the top frame of the browser

cookieEnabled
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator), returns `false` if setting a cookie will be ignored and true otherwise
```
boolean
```
language
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator), 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
```
string
```
languages
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator), returns an array of strings representing the languages known to the user, by order of preference
```
ReadonlyArray<string>
```
userAgent
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator), returns the user agent string for the current browser
```
string
```

WebPixelsWindow

A snapshot of a subset of properties of the `window` object in the top frame of the browser

innerHeight
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), gets the height of the content area of the browser window including, if rendered, the horizontal scrollbar
```
number
```
innerWidth
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), gets the width of the content area of the browser window including, if rendered, the vertical scrollbar
```
number
```
location
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), the location, or current URL, of the window object
```
Location
```
origin
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), the global object's origin, serialized as a string
```
string
```
outerHeight
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), gets the height of the outside of the browser window
```
number
```
outerWidth
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), gets the width of the outside of the browser window
```
number
```
pageXOffset
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), an alias for window.scrollX
```
number
```
pageYOffset
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), an alias for window.scrollY
```
number
```
screen
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Screen), the interface representing a screen, usually the one on which the current window is being rendered
```
Screen
```
screenX
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), the horizontal distance from the left border of the user's browser viewport to the left side of the screen
```
number
```
screenY
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), the vertical distance from the top border of the user's browser viewport to the top side of the screen
```
number
```
scrollX
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), the number of pixels that the document has already been scrolled horizontally
```
number
```
scrollY
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window), the number of pixels that the document has already been scrolled vertically
```
number
```

Screen

The interface representing a screen, usually the one on which the current window is being rendered

height
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Screen/height), the height of the screen
```
number
```
width
Per [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Screen/width), the width of the screen
```
number
```

PixelEventsCheckoutStartedData

checkout
```
Checkout
```

Checkout

A container for all the information required to add items to checkout and pay.

attributes
A list of attributes accumulated throughout the checkout process.
```
Attribute[]
```
billingAddress
The billing address to where the order will be charged.
```
MailingAddress | null
```
buyerAcceptsEmailMarketing
Indicates whether the customer has consented to be sent marketing material via email. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
boolean
```
buyerAcceptsSmsMarketing
Indicates whether the customer has consented to be sent marketing material via SMS. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
boolean
```
currencyCode
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 | null
```
delivery
Represents the selected delivery options for a checkout. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
Delivery | null
```
discountApplications
A list of discount applications.
```
DiscountApplication[]
```
discountsAmount
The total amount of the discounts applied to the price of the checkout. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
MoneyV2 | null
```
email
The email attached to this checkout. Requires the `read_customer_email` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
lineItems
A list of line item objects, each one containing information about an item in the checkout.
```
CheckoutLineItem[]
```
localization
Information about the active localized experience. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
Localization
```
order
The resulting order from a paid checkout.
```
Order | null
```
phone
A unique phone number for the customer. Formatted using E.164 standard. For example, *+16135551111*. Requires the `read_customer_phone` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
shippingAddress
The shipping address to where the line items will be shipped.
```
MailingAddress | null
```
shippingLine
Once a shipping rate is selected by the customer it is transitioned to a `shipping_line` object.
```
ShippingRate | null
```
smsMarketingPhone
The phone number provided by the buyer after opting in to SMS marketing. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-upgrade). Requires the `read_customer_phone` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
subtotalPrice
The price at checkout before duties, shipping, and taxes.
```
MoneyV2 | null
```
token
A unique identifier for a particular checkout.
```
string | null
```
totalPrice
The sum of all the prices of all the items in the checkout, including duties, taxes, and discounts.
```
MoneyV2 | null
```
totalTax
The sum of all the taxes applied to the line items and shipping lines in the checkout.
```
MoneyV2
```
transactions
A list of transactions associated with a checkout or order. Certain transactions, such as credit card transactions, may only be present in the checkout_completed event.
```
Transaction[]
```

Attribute

Custom attributes associated with the cart or checkout.

key
The key for the attribute.
```
string
```
value
The value for the attribute.
```
string
```

MailingAddress

A mailing address for customers and shipping.

address1
The first line of the address. This is usually the street address or a P.O. Box number. Requires the `read_customer_address` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
address2
The second line of the address. This is usually an apartment, suite, or unit number. Requires the `read_customer_address` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
city
The name of the city, district, village, or town. Requires the `read_customer_address` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
country
The name of the country. Requires the `read_customer_address` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
countryCode
The two-letter code that represents the country, for example, US. The country codes generally follows ISO 3166-1 alpha-2 guidelines. Requires the `read_customer_address` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
firstName
The customer’s first name. Requires the `read_customer_name` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
lastName
The customer’s last name. Requires the `read_customer_name` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
phone
The phone number for this mailing address as entered by the customer. Requires the `read_customer_phone` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
province
The region of the address, such as the province, state, or district. Requires the `read_customer_address` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
provinceCode
The two-letter code for the region. For example, ON. Requires the `read_customer_address` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```
zip
The ZIP or postal code of the address. Requires the `read_customer_address` access scope. See [Protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).
```
string | null
```

Delivery

The delivery information for the event.

selectedDeliveryOptions
The selected delivery options for the event.
```
DeliveryOption[]
```

DeliveryOption

Represents a delivery option that the customer can choose from.

cost
The cost of the delivery option.
```
MoneyV2 | null
```
costAfterDiscounts
The cost of the delivery option after discounts have been applied.
```
MoneyV2 | null
```
description
The description of the delivery option.
```
string | null
```
handle
The unique identifier of the delivery option.
```
string
```
title
The title of the delivery option.
```
string | null
```
type
The type of delivery option. - `pickup` - `pickupPoint` - `shipping` - `local`
```
string
```

MoneyV2

A monetary value with currency.

amount
The decimal money amount.
```
number
```
currencyCode
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
```

DiscountApplication

The information about the intent of the discount.

allocationMethod
The method by which the discount's value is applied to its entitled items. - `ACROSS`: The value is spread across all entitled lines. - `EACH`: The value is applied onto every entitled line.
```
string
```
targetSelection
How the discount amount is distributed on the discounted lines. - `ALL`: The discount is allocated onto all the lines. - `ENTITLED`: The discount is allocated onto only the lines that it's entitled for. - `EXPLICIT`: The discount is allocated onto explicitly chosen lines.
```
string
```
targetType
The type of line (i.e. line item or shipping line) on an order that the discount is applicable towards. - `LINE_ITEM`: The discount applies onto line items. - `SHIPPING_LINE`: The discount applies onto shipping lines.
```
string
```
title
The customer-facing name of the discount. If the type of discount is a `DISCOUNT_CODE`, this `title` attribute represents the code of the discount.
```
string
```
type
The type of the discount. - `AUTOMATIC`: A discount automatically at checkout or in the cart without the need for a code. - `DISCOUNT_CODE`: A discount applied onto checkouts through the use of a code. - `MANUAL`: A discount that is applied to an order by a merchant or store owner manually, rather than being automatically applied by the system or through a script. - `SCRIPT`: A discount applied to a customer's order using a script
```
string
```
value
The value of the discount. Fixed discounts return a `Money` Object, while Percentage discounts return a `PricingPercentageValue` object.
```
MoneyV2 | PricingPercentageValue
```

PricingPercentageValue

A value given to a customer when a discount is applied to an order. The application of a discount with this value gives the customer the specified percentage off a specified item.

percentage
The percentage value of the object.
```
number
```

CheckoutLineItem

A single line item in the checkout, grouped by variant and attributes.

discountAllocations
The discounts that have been applied to the checkout line item by a discount application.
```
DiscountAllocation[]
```
finalLinePrice
The combined price of all of the items in the line item after line-level discounts have been applied. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
MoneyV2
```
id
A globally unique identifier.
```
string | null
```
properties
The properties of the line item. A shop may add, or enable customers to add custom information to a line item. Line item properties consist of a key and value pair. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
Property[]
```
quantity
The quantity of the line item.
```
number
```
sellingPlanAllocation
The selling plan associated with the line item and the effect that each selling plan has on variants when they're purchased. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
SellingPlanAllocation | null
```
title
The title of the line item. Defaults to the product's title.
```
string | null
```
variant
Product variant of the line item.
```
ProductVariant | null
```

DiscountAllocation

The discount that has been applied to the checkout line item.

amount
The monetary value with currency allocated to the discount.
```
MoneyV2
```
discountApplication
The information about the intent of the discount.
```
DiscountApplication
```

Property

The line item additional custom properties.

key
The key for the property.
```
string
```
value
The value for the property.
```
string
```

SellingPlanAllocation

Represents an association between a variant and a selling plan.

sellingPlan
A representation of how products and variants can be sold and purchased. For example, an individual selling plan could be '6 weeks of prepaid granola, delivered weekly'.
```
SellingPlan
```

SellingPlan

Represents how products and variants can be sold and purchased.

id
A globally unique identifier.
```
string
```
name
The name of the selling plan. For example, '6 weeks of prepaid granola, delivered weekly'.
```
string
```

ProductVariant

A product variant represents a different version of a product, such as differing sizes or differing colors.

id
A globally unique identifier.
```
string | null
```
image
Image associated with the product variant. This field falls back to the product image if no image is available.
```
Image | null
```
price
The product variant’s price.
```
MoneyV2
```
product
The product object that the product variant belongs to.
```
Product
```
sku
The SKU (stock keeping unit) associated with the variant.
```
string | null
```
title
The product variant’s title.
```
string | null
```
untranslatedTitle
The product variant’s untranslated title.
```
string | null
```

Image

An image resource.

src
The location of the image as a URL.
```
string | null
```

Product

A product is an individual item for sale in a Shopify store.

id
The ID of the product.
```
string | null
```
title
The product’s title.
```
string
```
type
The [product type](https://help.shopify.com/en/manual/products/details/product-type) specified by the merchant.
```
string | null
```
untranslatedTitle
The product’s untranslated title.
```
string | null
```
url
The relative URL of the product.
```
string | null
```
vendor
The product’s vendor name.
```
string
```

Localization

Information about the active localized experience.

country
The country of the active localized experience.
```
Country
```
language
The language of the active localized experience.
```
Language
```
market
The market including the country of the active localized experience.
```
Market
```

Country

A country.

isoCode
The ISO-3166-1 code for this country, for example, "US".
```
string | null
```

Language

A language.

isoCode
The BCP-47 language tag. It may contain a dash followed by an ISO 3166-1 alpha-2 region code, for example, "en-US".
```
string
```

Market

A group of one or more regions of the world that a merchant is targeting for sales. To learn more about markets, refer to [this](https://shopify.dev/docs/apps/markets) conceptual overview.

handle
A human-readable, shop-scoped identifier.
```
string | null
```
id
A globally unique identifier.
```
string | null
```

Order

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.

customer
The customer that placed the order.
```
OrderCustomer | null
```
id
The ID of the order. ID will be null for all events except checkout_completed.
```
string | null
```

OrderCustomer

The customer that placed the order.

id
The ID of the customer.
```
string | null
```
isFirstOrder
Indicates if the order is the customer’s first order. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
boolean | null
```

ShippingRate

A shipping rate to be applied to a checkout.

price
Price of this shipping rate.
```
MoneyV2
```

Transaction

A transaction associated with a checkout or order.

amount
The monetary value with currency allocated to the transaction method.
```
MoneyV2
```
gateway
The name of the payment provider used for the transaction.
```
string
```
paymentMethod
The payment method used for the transaction. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-upgrade).
```
TransactionPaymentMethod
```

TransactionPaymentMethod

The payment method used for the transaction. This property is only available if the shop has [upgraded to Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-upgrade).

name
The name of the payment method used for the transaction. This may further specify the payment method used.
```
string
```
type
The type of payment method used for the transaction. - `creditCard`: A vaulted or manually entered credit card. - `redeemable`: A redeemable payment method, such as a gift card or store credit. - `deferred`: A [deferred payment](https://help.shopify.com/en/manual/orders/deferred-payments), such as invoicing the buyer and collecting payment later. - `local`: A [local payment method](https://help.shopify.com/en/manual/payments/shopify-payments/local-payment-methods) specific to the current region or market. - `manualPayment`: A manual payment method, such as an in-person retail transaction. - `paymentOnDelivery`: A payment that will be collected on delivery. - `wallet`: An integrated wallet, such as PayPal, Google Pay, Apple Pay, etc. - `offsite`: A payment processed outside of Shopify's checkout, excluding integrated wallets. - `customOnSite`: A custom payment method that is processed through a checkout extension with a payments app. - `other`: Another type of payment not defined here.
```
string
```

EventType

AdvancedDom
```
advanced-dom
```
Custom
```
custom
```
Dom
```
dom
```
Meta
```
meta
```
Standard
```
standard
```

Examples

import {register} from '@shopify/web-pixels-extension';

analytics.subscribe('checkout_started', (event) => {

// Example for accessing event data

const checkout = event.data.checkout;

const checkoutTotalPrice = checkout.totalPrice?.amount;

const allDiscountCodes = checkout.discountApplications.map((discount) => {

if (discount.type === 'DISCOUNT_CODE') {

return discount.title;

}

});

const firstItem = checkout.lineItems[0];

const firstItemDiscountedValue = firstItem.discountAllocations[0]?.amount;

const customItemPayload = {

quantity: firstItem.quantity,

title: firstItem.title,

discount: firstItemDiscountedValue,

};

const payload = {

event_name: event.name,

event_data: {

totalPrice: checkoutTotalPrice,

discountCodesUsed: allDiscountCodes,

firstItem: customItemPayload,

};

// Example for sending event data to third party servers

fetch('https://example.com/pixel', {

method: 'POST',

body: JSON.stringify(payload),

keepalive: true,

});

Examples

Accessing Standard Events

App Pixel

import {register} from '@shopify/web-pixels-extension';

register(({analytics}) => {
  analytics.subscribe('checkout_started', (event) => {
    // Example for accessing event data
    const checkout = event.data.checkout;

    const checkoutTotalPrice = checkout.totalPrice?.amount;

    const allDiscountCodes = checkout.discountApplications.map((discount) => {
      if (discount.type === 'DISCOUNT_CODE') {
        return discount.title;
      }
    });

    const firstItem = checkout.lineItems[0];

    const firstItemDiscountedValue = firstItem.discountAllocations[0]?.amount;

    const customItemPayload = {
      quantity: firstItem.quantity,
      title: firstItem.title,
      discount: firstItemDiscountedValue,
    };

    const payload = {
      event_name: event.name,
      event_data: {
        totalPrice: checkoutTotalPrice,
        discountCodesUsed: allDiscountCodes,
        firstItem: customItemPayload,
      },
    };

    // Example for sending event data to third party servers
    fetch('https://example.com/pixel', {
      method: 'POST',
      body: JSON.stringify(payload),
      keepalive: true,
    });
  });
});

Custom Pixel

analytics.subscribe('checkout_started', (event) => {
  // Example for accessing event data
  const checkout = event.data.checkout;

  const checkoutTotalPrice = checkout.totalPrice?.amount;

  const allDiscountCodes = checkout.discountApplications.map((discount) => {
    if (discount.type === 'DISCOUNT_CODE') {
      return discount.title;
    }
  });

  const firstItem = checkout.lineItems[0];

  const firstItemDiscountedValue = firstItem.discountAllocations[0]?.amount;

  const customItemPayload = {
    quantity: firstItem.quantity,
    title: firstItem.title,
    discount: firstItemDiscountedValue,
  };

  const payload = {
    event_name: event.name,
    event_data: {
      totalPrice: checkoutTotalPrice,
      discountCodesUsed: allDiscountCodes,
      firstItem: customItemPayload,
    },
  };

  // Example for sending event data to third party servers
  fetch('https://example.com/pixel', {
    method: 'POST',
    body: JSON.stringify(payload),
    keepalive: true,
  });
});

Was this page helpful?