Northbeam

introduction northbeam is a marketing analytics and attribution platform that helps brands measure performance across channels using multi touch attribution, media mix modeling, and real time reporting connecting northbeam as a cdp destination allows chord to send eligible commerce events to northbeam, enabling more accurate attribution and downstream analytics northbeam only processes a limited set of events, and requires a customer id to be included in all payloads (email cannot be used as customer id) this document outlines how to configure the destination and how data flows from chord getting started northbeam is a device mode destination , which means chord sends events directly from the client side to northbeam’s api before connecting, ensure you have an active northbeam account your northbeam api key your northbeam data client id clarification on which customer id field your brand will use (must not be an email) northbeam offers both a production mode and a test mode test mode accepts any credentials and routes data to a northbeam sandbox environment, making it useful for integration checks before enabling production delivery connecting to the northbeam cdp destination log into the chord data platform navigate to the cdp select the destinations tab click “add” to open the destination catalog choose northbeam from the list enter a destination name (e g , “northbeam – production”) provide the required credentials api key data client id select test mode or production mode depending on your environment click create to save and activate the destination once configured, chord will begin sending eligible events based on your cdp tracking setup what data northbeam accepts northbeam strictly processes the following event types order completed order refunded chord will forward these events only when the event includes a valid customer id the customer id is not an email address required northbeam payload fields are present if customer id is missing or incorrectly formatted, northbeam will reject the event because of these constraints, ensure your chord identity configuration maps a consistent, non email customer id for all events events order completed sends an order to the northbeam orders api the event is skipped (with an error log) if validation fails api call post {url} with payload as a single element array \[orderpayload] order attributes northbeam attribute chord source (in priority order) notes order id properties order id required event is skipped if missing customer id userid > properties customer id required event is skipped if missing customer email properties email > context traits email > traits email required event is skipped if missing time of purchase timestamp falls back to current time if not present iso 8601 format purchase total properties total > properties revenue > 0 currency properties currency > "usd" (default) tax properties tax > 0 shipping cost properties shipping > 0 product attributes each product in properties products is mapped to a northbeam product item required — at least one product must be present, and each product must have an id and name northbeam attribute chord source (in priority order) notes id properties products\[] product id > properties products\[] id required name properties products\[] name required quantity properties products\[] quantity > 1 (default) price properties products\[] price > 0 variant id properties products\[] variant id > properties products\[] variant > "" variant name properties products\[] variant name > properties products\[] variant > "" order refunded sends a refund to the northbeam orders api refunds are sent as part of the order payload with a refunds array attached the event is skipped (with an error log) if validation fails api call post {url} with payload as a single element array \[orderpayload] order attributes same as order completed above, except northbeam attribute chord source (in priority order) notes time of purchase properties original timestamp > timestamp falls back to current time the original order timestamp should be provided for accurate attribution refund attributes the adapter first checks for an explicit properties refunds array if not present, it falls back to properties products and treats all products as refunded required — at least one refund item must be present from properties refunds\[] (preferred) northbeam attribute chord source (in priority order) notes product id properties refunds\[] product id > properties refunds\[] id required variant id properties refunds\[] variant id > properties refunds\[] variant > "" quantity properties refunds\[] quantity > 1 (default) refund amount properties refunds\[] refund amount > properties refunds\[] amount > properties refunds\[] price > 0 required refund cost properties refunds\[] refund cost > refund amount (default) defaults to refund amount if not provided refund made at properties refunds\[] refund made at > timestamp falls back to current time iso 8601 format from properties products\[] (fallback) when no properties refunds array is present, all products are treated as fully refunded northbeam attribute chord source (in priority order) notes product id properties products\[] product id > properties products\[] id variant id properties products\[] variant id > properties products\[] variant > "" quantity properties products\[] quantity > 1 (default) refund amount properties products\[] price x properties products\[] quantity calculated from price and quantity refund cost same as refund amount refund made at timestamp falls back to current time product attributes (on refund events) same as order completed product attributes above products are included alongside refunds in the order payload validation both order completed and order refunded events are validated before sending if validation fails, the event is skipped and errors are logged required fields order completed order id must be present customer id must be present ( userid or properties customer id ) customer email must be present products array must be non empty each product must have id and name order refunded order id must be present customer id must be present customer email must be present refunds array must be non empty each refund must have product id and refund amount error handling http status behavior 2xx success — logged at info level with order id 4xx client error — logged at error level with payload, not retried (payload issue) 5xx server error — logged at error level, retried via retryerror using test mode northbeam’s test mode accepts any api key or data client id (not validated) sends events to a sandbox server , not the production environment allows teams to confirm event structure and flow before enabling production delivery we recommend connecting first in test mode verifying that order completed and order refunded events appear as expected switching to production mode only after validation troubleshooting events not appearing in northbeam confirm customer id is being sent (and is not an email) check that only order completed and order refunded events are expected verify you are not still in test mode if reviewing production dashboards northbeam rejecting events validate customer id formatting ensure the required order fields exist in your chord implementation credentials not working test mode accepts any credentials — if test mode works and production does not, confirm your api key and data client id with northbeam chord events relevant for destination not all chord events are used downstream in your configured destinations the most relevant and important events in the chord tracking plan are mapped within the cdp destination, relayed and then ingested in the destination the chord tracking plan events used by the https //docs northbeam io/docs/orders api are chord tracking event destination event/action order completed creates order payload via api order refunded creates refund payload via api note the only specific chord track events which prompt action downstream in the northbeam api are order completed and order refunded all other track , identify and page events are ignored before connecting destinations in the chord cdp, please verify with all destination owners that all non chord cdp configured destinations are disabled running external destinations alongside configured chord cdp destinations can result in duplicate events downstream