Configuration

8 min

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.

*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.

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:

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:

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

const chord = new ChordAnalytics<ObjectTypes>(options)

Individual formatter types are also available:

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

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