---
title: SDK API reference
slug: sdk-api-reference
createdAt: 2026-03-09T21:01:44.434Z
---

Complete reference for all tracking methods available in the `@chordcommerce/analytics` library.

## Page Views

### `chord.page()`

Sends a page view event to Chord.

```typescript
chord.page()
```

***

## User Identity

### `chord.identify(userId, traits)`

Sends an identify event to associate a user with their traits. Call this after account creation, login, or when a user submits identifying information.

```typescript
chord.identify(userId, { email, phone, firstName, lastName })
// or without userId:
chord.identify({ email, phone })
```

| Property | Type     | Required | Description                            |
| -------- | -------- | -------- | -------------------------------------- |
| `userId` | `string` | No       | The user's unique identifier           |
| `traits` | `object` | No       | User traits (email, phone, name, etc.) |

:::BlockQuote
**Best practice:** Send `identify` before `track` events when both occur at the same time. Some downstream integrations require identity to be established before processing track events.
:::

### `chord.reset()`

Resets the user session. The user receives a new anonymous identifier and previous user data is cleared. Call this after logout.

```typescript
chord.reset()
```

***

## Product Events

### `chord.trackProductViewed({ cart, product })`

Sends a "Product Viewed" event. Call this whenever a product page is viewed.

| Property            | Type     | Required | Description                 |
| ------------------- | -------- | -------- | --------------------------- |
| `cart`              | `any`    | Yes      | The current cart            |
| `product.product`   | `any`    | Yes      | Product and variant details |
| `product.position`  | `number` | No       | Position in a list          |
| `product.quantity`  | `number` | No       | Quantity                    |
| `product.variantId` | `any`    | No       | Product variant identifier  |

### `chord.trackProductAdded({ cart, product })`

Sends a "Product Added" event when a product is first added to cart (not for quantity changes).

Same parameters as `trackProductViewed`.

### `chord.trackProductRemoved({ cart, lineitem })`

Sends a "Product Removed" event when a product is removed from cart.

| Property   | Type  | Required | Description            |
| ---------- | ----- | -------- | ---------------------- |
| `cart`     | `any` | Yes      | The cart after removal |
| `lineitem` | `any` | Yes      | The removed line item  |

### `chord.trackProductClicked({ cart, product, listId, listName })`

Sends a "Product Clicked" event when a product link is clicked.

| Property           | Type     | Required | Description          |
| ------------------ | -------- | -------- | -------------------- |
| `cart`             | `any`    | Yes      | The current cart     |
| `product.product`  | `any`    | Yes      | Product details      |
| `product.position` | `number` | No       | Position in the list |
| `listId`           | `any`    | No       | List identifier      |
| `listName`         | `string` | No       | List name            |

### `chord.trackProductListViewed({ category, listId, listName, products })`

Sends a "Product List Viewed" event.

| Property   | Type     | Required | Description          |
| ---------- | -------- | -------- | -------------------- |
| `category` | `string` | No       | Product category     |
| `listId`   | `string` | No       | List identifier      |
| `listName` | `string` | No       | List name            |
| `products` | `array`  | Yes      | Products in the list |

### `chord.trackProductListFiltered({ category, listId, listName, filters, sorts })`

Sends a "Product List Filtered" event when filters are applied.

| Property   | Type     | Required | Description                           |
| ---------- | -------- | -------- | ------------------------------------- |
| `category` | `string` | No       | Product category                      |
| `listId`   | `string` | No       | List identifier                       |
| `listName` | `string` | No       | List name                             |
| `filters`  | `array`  | No       | Applied filters (`[{ type, value }]`) |
| `sorts`    | `array`  | No       | Applied sorts (`[{ type, value }]`)   |

### `chord.trackProductsSearched({ query })`

Sends a "Products Searched" event.

| Property    | Type     | Required | Description             |
| ----------- | -------- | -------- | ----------------------- |
| `query`     | `string` | No       | Search query            |
| `productId` | `any`    | No       | Product ID searched for |
| `currency`  | `string` | No       | ISO 4217 currency code  |
| `price`     | `number` | No       | Product price           |
| `quantity`  | `number` | No       | Quantity                |

***

## Cart Events

### `chord.trackCartViewed({ cart })`

Sends a "Cart Viewed" event.

| Property | Type  | Required | Description      |
| -------- | ----- | -------- | ---------------- |
| `cart`   | `any` | Yes      | The current cart |

***

## Checkout Events

### `chord.trackCheckoutStarted({ checkout })`

Sends a "Checkout Started" event.

| Property   | Type  | Required | Description          |
| ---------- | ----- | -------- | -------------------- |
| `checkout` | `any` | Yes      | The current checkout |

### `chord.trackCheckoutStepViewed({ checkoutId, step })`

Sends a "Checkout Step Viewed" event.

| Property         | Type     | Required | Description         |
| ---------------- | -------- | -------- | ------------------- |
| `checkoutId`     | `string` | Yes      | Checkout identifier |
| `step`           | `number` | Yes      | Step number         |
| `paymentMethod`  | `string` | No       | Payment method      |
| `shippingMethod` | `string` | No       | Shipping method     |

### `chord.trackCheckoutStepCompleted({ checkoutId, step })`

Sends a "Checkout Step Completed" event.

Same parameters as `trackCheckoutStepViewed`.

### `chord.trackPaymentInfoEntered({ checkoutId, step })`

Sends a "Payment Info Entered" event.

| Property         | Type     | Required | Description          |
| ---------------- | -------- | -------- | -------------------- |
| `checkoutId`     | `string` | No       | Checkout identifier  |
| `step`           | `number` | Yes      | Step number          |
| `paymentMethod`  | `string` | No       | Payment method used  |
| `shippingMethod` | `string` | No       | Shipping method      |
| `coupon`         | `string` | No       | Coupon code          |
| `currency`       | `string` | No       | Currency code        |
| `orderId`        | `string` | No       | Order identifier     |
| `value`          | `number` | No       | Total value          |
| `products`       | `array`  | No       | Products in checkout |

***

## Order Events

### `chord.trackOrderCompleted({ orderId, orderDate, currency, revenue, total, products })`

Sends an "Order Completed" event.

| Property    | Type     | Required | Description                  |
| ----------- | -------- | -------- | ---------------------------- |
| `orderId`   | `string` | Yes      | Order identifier             |
| `orderDate` | `string` | Yes      | Date of completion           |
| `currency`  | `string` | Yes      | Currency code                |
| `revenue`   | `number` | Yes      | Revenue (subtotal)           |
| `total`     | `number` | Yes      | Total with discounts/coupons |
| `products`  | `array`  | Yes      | Products in the order        |

***

## Coupon Events

### `chord.trackCouponApplied({ cartId, couponId, couponName, discount, orderId })`

Sends a "Coupon Applied" event after successful application.

| Property     | Type     | Required | Description              |
| ------------ | -------- | -------- | ------------------------ |
| `cartId`     | `string` | No       | Cart identifier          |
| `couponId`   | `string` | No       | Coupon identifier        |
| `couponName` | `string` | No       | Coupon name              |
| `discount`   | `number` | No       | Monetary discount amount |
| `orderId`    | `string` | No       | Order identifier         |

### `chord.trackCouponDenied({ cartId, couponId, couponName, orderId, reason })`

Sends a "Coupon Denied" event.

Same parameters as `trackCouponApplied`, plus `reason` (`string`, optional).

### `chord.trackCouponEntered({ cartId, couponId, couponName, discount, orderId })`

Sends a "Coupon Entered" event immediately after entry, before approval/denial.

Same parameters as `trackCouponApplied`.

### `chord.trackCouponRemoved({ cartId, couponId, couponName, discount, orderId })`

Sends a "Coupon Removed" event.

Same parameters as `trackCouponApplied`.

***

## Email & Login Events

### `chord.trackEmailCaptured({ email, placementComponent, placementPage })`

Sends an "Email Captured" event when a customer enters an email address.

| Property             | Type     | Required | Description                                         |
| -------------------- | -------- | -------- | --------------------------------------------------- |
| `email`              | `string` | No       | Email address captured                              |
| `placementComponent` | `string` | No       | UI component identifier (e.g., `footer-newsletter`) |
| `placementPage`      | `string` | No       | Page identifier (e.g., `homepage`)                  |

### `chord.trackLoginStarted({ email })`

Sends a "Login Started" event.

| Property | Type     | Required | Description          |
| -------- | -------- | -------- | -------------------- |
| `email`  | `string` | No       | Email used for login |

***

## Authentication Events

### `chord.trackSignedIn({ email, method })`

Sends a "Signed In" event after successful login.

| Property | Type     | Required | Description  |
| -------- | -------- | -------- | ------------ |
| `email`  | `string` | No       | User's email |
| `method` | `string` | No       | Login method |

### `chord.trackSignedUp({ email, method })`

Sends a "Signed Up" event after successful signup.

Same parameters as `trackSignedIn`.

### `chord.trackSignedOut({ email })`

Sends a "Signed Out" event after successful logout.

| Property | Type     | Required | Description  |
| -------- | -------- | -------- | ------------ |
| `email`  | `string` | No       | User's email |

***

## Navigation Events

### `chord.trackNavigationClicked({ category, label, navigationPlacement, navigationTitle, navigationUrl })`

Sends a "Navigation Clicked" event.

| Property              | Type     | Required | Description                          |
| --------------------- | -------- | -------- | ------------------------------------ |
| `category`            | `string` | No       | Navigation category                  |
| `label`               | `string` | No       | Navigation label                     |
| `navigationPlacement` | `string` | No       | Placement (e.g., `header`, `footer`) |
| `navigationTitle`     | `string` | No       | Navigation title                     |
| `navigationUrl`       | `string` | No       | Target URL                           |

***

## Variant Events

### `chord.trackVariantClicked({ product, cart, lineItemId, coupon })`

Sends a "Variant Clicked" event.

| Property     | Type     | Required | Description          |
| ------------ | -------- | -------- | -------------------- |
| `product`    | `any`    | Yes      | The variant clicked  |
| `cart`       | `any`    | Yes      | The current cart     |
| `lineItemId` | `string` | No       | Line item identifier |
| `coupon`     | `string` | No       | Coupon code          |

***

## Subscription Events

### `chord.trackSubscriptionCancelled({ subscriptionId, ... })`

Sends a "Subscription Cancelled" event.

| Property         | Type     | Required | Description                    |
| ---------------- | -------- | -------- | ------------------------------ |
| `subscriptionId` | `string` | No       | Subscription identifier        |
| `email`          | `string` | No       | Associated email               |
| `brand`          | `string` | No       | Associated brand               |
| `currency`       | `string` | No       | Currency code                  |
| `intervalLength` | `number` | No       | Subscription interval length   |
| `intervalUnits`  | `string` | No       | Interval units (e.g., `month`) |
| `state`          | `string` | No       | Subscription state             |
| `products`       | `array`  | No       | Products in subscription       |
| `actionableDate` | `string` | No       | Actionable date                |
| `endDate`        | `string` | No       | End date                       |
| `address`        | `object` | No       | Associated address             |

***

## Generic Track Method

### `chord.track(eventName, properties)`

Sends a custom event directly to Chord. This bypasses formatters and sends properties as-is.

```typescript
chord.track('Custom Event Name', {
  custom_property: 'value',
  another_property: 123,
})
```

:::hint{type="info"}
**Important: **This method does not use formatters or transform property names. Use snake\_case for all property names. Prefer event-specific methods when available.
:::