SDK API reference

41 min

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

Page Views

chord.page()

Sends a page view event to Chord.

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.

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

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.

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.

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

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.

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

Important: This method does not use formatters or transform property names. Use snake_case for all property names. Prefer event-specific methods when available.