---
title: Shopify Theme API Reference
slug: analytics-developer-docs/shopify-theme-api-reference
docTags:
createdAt: 2024-03-14T19:06:54.382Z
---
### trackCartViewed
The “Cart Viewed” event is sent automatically from a page with `/cart` in the URL.
If you’re using a cart overlay on other pages, here’s an example of how you can add the event:
```tsx
chord.trackCartViewed()
```
If an object with a `cart` property is not provided as an argument, Chord fetches data about the cart from [Shopify’s Ajax API](https://shopify.dev/docs/api/ajax/reference/cart#get-locale-cart-js).
### trackCheckoutStarted
The “Checkout Started” event is sent automatically when the `submit` [event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event) fires on a form with CSS selector `form[action="/cart" i][method="post"]`. This selector works with Shopify’s `{% form 'cart', cart %}` tag ([see docs](https://shopify.dev/docs/api/liquid/tags/form#form-cart)).
If the site is using custom “Check out” buttons or forms, you can either adjust the CSS selector or add the event in Javascript. If the CSS selector is a `form` element, the event will be sent when the form’s `submit` event fires. Otherwise, the event will be sent when the `click` event fires.
```jsx
const chord = new ChordAnalytics({
autoInstrumentSelectors: {
'Checkout Started': 'form#checkout'
},
...rest
});
```
If the element is added after `ChordAnalytics` is initialized, call `chord.autoInstrument()` to rescan the page and re-attach event handlers.
Here’s how you can add the event in Javascript:
```tsx
chord.trackCheckoutStarted()
```
### trackCouponApplied
The “Coupon Applied” event is not sent automatically. Here’s an example of how you can add the event:
```tsx
chord.trackCouponApplied({ couponName: '50off' })
```
### trackCouponDenied
The “Coupon Denied” event is not sent automatically. Here’s an example of how you can add the event:
```tsx
chord.trackCouponDenied({ couponName: '50off', reason: 'expired' })
```
### trackCouponEntered
The “Coupon Entered” event is not sent automatically. Here’s an example of how you can add the event:
```tsx
chord.trackCouponEntered({ couponName: '50off' })
```
### trackCouponRemoved
The “Coupon Removed” event is not sent automatically. Here’s an example of how you can add the event:
```tsx
chord.trackCouponRemoved({ couponName: '50off' })
```
### trackEmailCaptured
The “Email Captured” event is sent automatically when the `submit` [event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event) fires on a form with CSS selector `form[action="/contact#contact_form" i][method="post"], form[action="/contact#contactform" i][method="post"]`. The email address is read from the `contact[email]` input element in the form. This selector works with Shopify’s `{% form 'contact' %}` and `{% form 'customer' %}` tags ([see docs](https://shopify.dev/docs/api/liquid/tags/form#form-contact)).
If the site is using other methods to capture email addresses, you can either adjust the CSS selector or add the event in Javascript.
If you adjust the CSS selector, keep it mind it has to be a selector of a `form` element, because the listener is listening for a `submit` event. Here’s how you can adjust the CSS selector:
```jsx
const chord = new ChordAnalytics({
autoInstrumentSelectors: {
'Email Captured': 'form#newsletter'
},
...rest
});
```
If the element is added after `ChordAnalytics` is initialized, call `chord.autoInstrument()` to rescan the page and re-attach event handlers.
Here’s how you can add the event in Javascript:
```tsx
chord.trackEmailCaptured({
email: 'test@chord.co',
placementComponent: 'footer'
})
```
### trackProductAdded
The “Product Added” event is not sent automatically. Here’s an example of how you can add the event:
```text
chord.trackProductAdded({
product: {
handle: formData.get("handle"),
quantity: formData.get("quantity"),
variantId: formData.get("id"),
}
})
```
We recommend sending the event after the product has been successfully added to the cart, not before.
### trackProductClicked
The “Product Clicked” event is sent automatically when an HTML element matching the CSS selector `a[href*="/products/" i]` is clicked. The product handle is read from the `href` element and used to fetch product details from [Shopify’s Ajax API](https://shopify.dev/docs/api/ajax/reference/cart#get-locale-cart-js).
You can customize the CSS selector. If you adjust the CSS selector, keep it mind it has to be a selector of an element with an `href` to the product page that will be the target of a `click` event. Here’s how you can adjust the CSS selector:
```jsx
const chord = new ChordAnalytics({
autoInstrumentSelectors: {
'Product Clicked': 'a.product[href*="/products/" i]'
},
...rest
});
```
If the element is added after `ChordAnalytics` is initialized, call `chord.autoInstrument()` to rescan the page and re-attach event handlers.
Here’s how you can add the event in Javascript:
```text
chord.trackProductClicked({
listName: 'Related Products',
product: {
handle: 'product-1',
},
})
```
### trackProductViewed
The “Product Viewed” event is sent automatically from a page with `/product` in the URL. Here’s an example of how you can add the event elsewhere:
```jsx
chord.trackProductViewed({
product: {
handle: 'product-1',
},
})
```
### trackProductListViewed
The “Product List Viewed” event is not sent automatically. Here’s an example of how you can add the event:
```text
{% assign selectedCollection = block.settings.collection %}
```
`products` can be either an array of product handles, in which case Chord will fetch the product details from [Shopify’s Ajax API](https://shopify.dev/docs/api/ajax/reference/cart#get-locale-cart-js), or an array of product objects, like this:
```tsx
```
`products` represents the products that were actually viewed, not every product in the collection.
### trackProductsSearched
Sends a “Products Searched” event.
```tsx
chord.trackProductsSearched({ query: 'pizza' })
```
### trackSignedIn
This event should be sent after the user successfully signs in. Here’s how you can add the event in Javascript:
```tsx
chord.trackSignedIn({ email: 'test@chord.co' })
```
### trackSignedOut
This event should be sent after the user successfully signs out. Here’s how you can add the event in Javascript:
```tsx
chord.trackSignedOut({ email: 'test@chord.co' })
```
### trackSignedUp
This event should be sent after the user successfully signs up. Here’s how you can add the event in Javascript:
```tsx
chord.trackSignedUp({ email: 'test@chord.co' })
```
### Identify
Your website should send an `identify` event to the CDP every time identifying information is captured about the current user. This library automatically sends an `identify` event in these scenarios:
- On every page load by an authenticated user. This code is in `chord.liquid` and can be modified if desired.
- When the `Email Captured` event is sent automatically. `identify` is not sent when you call `chord.trackEmailCaptured` manually.
If you're capturing identifying information like an email address in a situation that's not covered above, we recommend you add the `identify` event in Javascript to send this information to the CDP. For example, you might have a newsletter sign up form or a form where users can change their default shipping address.
Here’s how you can add the `identify` event in Javascript:
```jsx
chord.identify(userId, {
name: "Chord Commerce",
email: "test@chord.co"
});
```
`userId` in the above example is the stringified [Shopify customer id](https://shopify.dev/docs/api/liquid/objects/customer#customer-id). The second argument is an object representing user traits. If the `userId` is not available, omit this argument and send the object of user traits as the first argument. *Never* send an email address or other value as the user ID. For example, if you are adding an `identify` event to a newsletter signup form, it should look like this:
```jsx
chord.identify({
email: "test@chord.co"
});
```
If you’re sending a `track` event at the same time as an `identify` event, we recommend sending `identify` first and the `track` event second. Some integrations require an `identify` event before they can process `track` events.
### reset
The `reset` method sends a `reset` event to the CDP tracking library. This does not result in an event appearing in the CDP. It resets the user’s session in the browser, which means the user will receive a new anonymous identifier and any previous user data will be cleared.
We recommend calling the `reset` method after a user has successfully logged out of their account.
### track
The `track` method sends a `track` event to the CDP:
```typescript
chord.track('Navigation Clicked', {
label: 'Home',
location: 'main nav',
url: '/'
})
```
`track` can be used to send any event to the CDP, including events in the Chord tracking plan. However, we recommend using an event-specific method like `trackProductViewed` instead if one is available, so that Chord's library can construct the event body to match the tracking plan. See the individual event tracking methods above. `track` simply sends the second argument directly to the CDP as the event body.
`track` does not transform property names from camel case to snake case; event properties will be sent to the CDP exactly as written. We recommend using snake case for all event properties. `null` values will be stripped by default unless `stripNull` is set to `false` in the library options.