---
title: Configuration
slug: TEmF-configuration
docTags: 
createdAt: 2026-03-09T21:00:56.054Z
---

This page documents all configuration options for the `@chordcommerce/analytics` library.

## Initialization Options

| Property                 | Required | Default   | Description                                                                                    |
| ------------------------ | -------- | --------- | ---------------------------------------------------------------------------------------------- |
| `cdpDomain`              | Yes\*    | —         | Your Chord domain (provided by the Chord team)                                                 |
| `cdpWriteKey`            | Yes\*    | —         | Your Chord write key (provided by the Chord team)                                              |
| `cdp`                    | No\*     | —         | Reference to an external analytics library. If provided, events are also sent to that library. |
| `formatters`             | Yes      | —         | Functions for transforming your platform's data into the Chord tracking plan format            |
| `metadata`               | Yes      | —         | Event metadata identifying your store and platform                                             |
| `consent`                | No       | —         | Consent adapter: `"onetrust"`, `"ketch"`, or `"shopify"`                                       |
| `awaitConsent`           | No       | `false`   | If `true`, delays sending events until consent is given (timeout: 1 minute)                    |
| `debug`                  | No       | `false`   | Validates events against the tracking plan and logs warnings. Recommended during development.  |
| `enableLogging`          | No       | `true`    | Logs errors via `console.log`                                                                  |
| `namespace`              | No       | `"chord"` | The global namespace where the Chord instance is available (e.g., `window.chord`)              |
| `stripNull`              | No       | `true`    | Removes properties with null values from events before sending                                 |
| `enableWebPixelListener` | No       | `true`    | Receives events from Chord's Shopify custom web pixel. Disable if not using the web pixel.     |

:::BlockQuote
\*At least one of `cdpDomain`/`cdpWriteKey` or `cdp` must be provided. If all three are omitted, no events are sent.
:::

## Metadata

Metadata is included with every event and identifies your store to Chord.

```typescript
metadata: {
  i18n: {
    currency: 'USD',      // ISO 4217 currency code (uppercase)
    locale: 'en-US',      // Locale string
  },
  ownership: {
    omsId: '...',          // UUID assigned by Chord
    storeId: '...',        // UUID assigned by Chord
    tenantId: '...',       // UUID assigned by Chord
  },
  platform: {
    name: 'Shopify',       // Your commerce platform name
    type: 'web',           // 'web' or 'pos'
  },
  store: {
    domain: 'my-store',    // Store slug (for Shopify: the part before .myshopify.com)
  },
}
```

### Metadata Fields

| Property                      | Required | Description                                                   |
| ----------------------------- | -------- | ------------------------------------------------------------- |
| `metadata.i18n.currency`      | Yes      | ISO 4217 currency code, uppercase (e.g., `USD`, `GBP`, `EUR`) |
| `metadata.i18n.locale`        | Yes      | Locale string (e.g., `en-US`, `fr-FR`)                        |
| `metadata.ownership.omsId`    | Yes      | UUID assigned by Chord (unique per store)                     |
| `metadata.ownership.storeId`  | Yes      | UUID assigned by Chord (unique per store)                     |
| `metadata.ownership.tenantId` | Yes      | UUID assigned by Chord (unique per organization)              |
| `metadata.platform.name`      | Yes      | Commerce platform name (e.g., `Shopify`, `Custom`)            |
| `metadata.platform.type`      | Yes      | Platform type: `web` or `pos`                                 |
| `metadata.store.domain`       | Yes      | Store domain or slug                                          |

## Formatters

Formatters are functions that transform your platform's data structures into the format expected by the Chord tracking plan. There are two types: **object formatters** (required) and **event formatters** (optional).

### Object Formatters (Required)

You must provide formatters for four core data types. Each formatter receives a props object and returns a plain object matching the Chord tracking plan schema.

| Formatter                     | Input          | Description                                           |
| ----------------------------- | -------------- | ----------------------------------------------------- |
| `formatters.objects.cart`     | `{ cart }`     | Transforms your cart object into tracking plan format |
| `formatters.objects.checkout` | `{ checkout }` | Transforms your checkout object                       |
| `formatters.objects.lineItem` | `{ lineItem }` | Transforms a single line item                         |
| `formatters.objects.product`  | `{ product }`  | Transforms a single product                           |

Example:

```typescript
formatters: {
  objects: {
    cart: ({ cart }) => ({
      cart_id: cart.id,
      products: cart.lines.map(line => ({
        product_id: line.merchandise.product.id,
        sku: line.merchandise.sku,
        name: line.merchandise.product.title,
        price: parseFloat(line.merchandise.price.amount),
        quantity: line.quantity,
        category: line.merchandise.product.productType,
      })),
    }),

    checkout: ({ checkout }) => ({
      order_id: checkout.id,
      revenue: parseFloat(checkout.subtotalPrice.amount),
      total: parseFloat(checkout.totalPrice.amount),
      tax: parseFloat(checkout.totalTax.amount),
      shipping: parseFloat(checkout.shippingLine?.price.amount || '0'),
      currency: checkout.currencyCode,
      products: checkout.lineItems.map(item => ({
        product_id: item.variant.product.id,
        sku: item.variant.sku,
        name: item.title,
        price: parseFloat(item.variant.price.amount),
        quantity: item.quantity,
      })),
    }),

    lineItem: ({ lineItem }) => ({
      product_id: lineItem.merchandise.product.id,
      sku: lineItem.merchandise.sku,
      name: lineItem.merchandise.product.title,
      price: parseFloat(lineItem.merchandise.price.amount),
      quantity: lineItem.quantity,
    }),

    product: ({ product }) => ({
      product_id: product.id,
      sku: product.variants?.[0]?.sku,
      name: product.title,
      price: parseFloat(product.priceRange.minVariantPrice.amount),
      category: product.productType,
      brand: product.vendor,
      url: `/products/${product.handle}`,
      image_url: product.featuredImage?.url,
    }),
  },
}
```

### Event Formatters (Optional)

Event formatters run after Chord constructs the event from object formatters, allowing you to transform or enrich specific events before they are sent to Chord. This is useful when you need to add custom properties or override default behavior for specific events.

## TypeScript Support

The library accepts a generic type parameter for type-safe formatter inputs:

```typescript
interface ObjectTypes {
  Cart: ShopifyCart
  Checkout: ShopifyCheckout
  LineItem: ShopifyLineItem
  Product: ShopifyProduct
}

const chord = new ChordAnalytics<ObjectTypes>(options)
```

Individual formatter types are also available:

```typescript
import type { CartFormatter, ProductFormatter } from '@chordcommerce/analytics'

const cartFormatter: CartFormatter<ShopifyCart> = ({ cart }) => {
  // `cart` is typed as ShopifyCart
  return { /* ... */ }
}
```