8. Add Orders
In addition to tracking client-side purchases, it's important to sync your source of truth for order data with Northbeam for accurate and up-to-date reporting.
For customers that use Shopify of Amazon as their ground truth for Orders, we support Shopify and Amazon native integrations.
To sync order data with Northbeam, you can use our Orders API.
The Orders API can be used both to:
- continuously sync orders with Northbeam on an ongoing basis, and
- backfill historical orders to Northbeam
Background
For Northbeam's Multi-Touch Attribution (MTA) and Mixed Media Modeling (MMM) offerings we use our customer's Orders as the ground truth for Revenue. This enables Northbeam to perform Ad Attribution on Purchases that took place (MTA) and to assist in predicting what will take place (MMM).
For customers that use Shopify of Amazon as their ground truth for Orders, we support a Shopify and Amazon native integrations. These integrations sync a customer's Shopify/Amazon store to get information about orders that is subsequently used for attribution (MTA) or for predictive analytics (MMM)
It is sometimes the case that Shopify or Amazon are not the customer's go-to for the most up-to-date Order information.
- In some cases, customers employ a collection of Shopify/Amazon stores from which they internally pull data into their own data pipelines for centralization, or downstream data transformation (i.e. currency conversion, time-zone manipulation, filtering of incomplete orders, or for tagging purposes)
- In other cases customers do not use either Shopify or Amazon and use an Order Management System that does not have native support in Northbeam
In either of these above cases (or others), we support the Orders API so that Northbeam can obtain the order information needed to support operations for MMM and MTA. The Orders API is a standard solution that that accepts HTTP API calls where the payload contains a list of orders and associated metadata for the orders.
Northbeam's Definition of an Order
Different Order Management Systems(OMS) consider the notion of an order differently. For best results, we recommend submitting orders that have been shipped, where the costs associated with the order (and/or other metadata subject to alteration after initial creation) is considered more or less settled.
Because an unfavorable amount of time usually passes between when the order is placed and lands in a customer's OMS also support an initial order submission with 'estimated' costs (i.e. shipping that is quoted at the time of order submission, but may be subject to change) to support timely order attribution (MTA). At the time of shipment, a customer can make an API call to update the order. An call made that includes an order with an order_id that matches a previously submitted order_id is updated with the most recent call's attributes.
Order Attributes
Each order has a set of required attributesal attributes that can be submitted for each order.
Required Attributes (Relevant for Orders API Integration)
Certain metadata is required for an order to be submitted. Without these fields, an API call will return an error as part of our validation check to make sure the Orders contained in an API call pass muster. The following order attributes are required:
order_id
- This is the canonical identity of an order for a customer in Northbeam's Order database. This number is typically the same as the id that is used in a customers OMS and must be the same as the id that is submitted using Northbeam's Fire Purchase Event method from the website. It is important that these two match so that we can pair the website event with the corresponding order.customer_id
- This is the canonical identity of a customer's customer in Northbeam's Order Database. This number is also typically the same as the id that denotes a customer in a customer's OMS and must be the same as the customer_id that is submitted using Northbeam's Fire Purchase Event method from the website. It is important that these two match so that we can pair the website event with the corresponding order.time_of_purchase
- This field denotes the time at which the order is created/placed. This is also used when aggregating revenue in the platform over time.tax
- the amount in a given currency that was paid as tax for an ordercurrency
- The currency of the order. Note, all monetary fields will assume that the currency is the one passed in this field. Please use standard ISO-4217 currency codes.purchase_total
- The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order.products
- a list of product objects describing the products in the order - the list could have only one line item but have at least one member. Similar to lineItems in Northbeam's Fire Purchase Eventid
- A unique identifier describing the product in the ordername
- Name of the productquantity
- How many of the product were sold in the orderprice
- The price of the product in the currency of the ordervariant_id
- (optional) A unique identifier describing the product variant in the order.variant_name
- (optional) The name of the product variant. Cannot be empty when specified.
shipping_cost
- The amount that was paid for shipping for this order
Optional Attributes
The following order attributes are optional:
customer_email
- the email associated with a customer - not necessary if using Northbeam's Fire Purchase Event method - absolutely necessary if not using Northbeam's Fire Purchase Event method and using Northbeam's Identify method insteadcustomer_phone_number
- The phone number associated with a customercustomer_name
- The name associated with a customercustomer_ip_address
- The IP address associated with a customerdiscount_codes
- a list of strings that resemble Coupons or discount codes used in the order - similar to coupons in Northbeam's Fire Purchase Eventdiscount_amount
- The amount of money discounted due to discount codes in the currency of the orderorder_tags
- A list of internal tags describing the order - these tags may also be used to denote the subscription stage or customer stage of the order, as well as for exclusions to exclude orders that you do not seek to have attributed - to learn more read on in Subscriptions, Customer Stage, and Exclusions.is_recurring_order
- a boolean value that denotes whether or not this order is part of a recurring purchase (subscription)refunds
- (optional) A list of product objects describing the refunded productsproduct_id
- (required) A unique identifier describing the product in the refund (should also be included in the products list).quantity
- (required) The number of products refunded (should be less than or equal to the corresponding quantity in the products list).refund_amount
- (required) The total amount refunded to the customer in the currency of the order.refund_cost
- (required) The estimated total cost of the refund, including the refund amount to the customer and any other overhead costs (i.e. shipping, fees).refund_made_at
(required) - The time the refund was fulfilled by your brand. ISO-8601 timestamp.variant_id
- (optional) A unique identifier describing the variant of the product in the refund (should also be included in the products list). This field is entirely optional but should be included if the refund is for a product and avariant_id
was provided in the products field.
customer_shipping_address
- (optional) an object that captures the shipping address for the orderaddress1
- (required)The street address of a customer's shipping address.address2
- (required) An optional additional field for the street address.city
- (required) The city or locality of a customer's shipping address.state
- (required) The state or region of the customer's shipping address.zip
- (required) The postal code or region-code (in outside US) of the customer's shipping address.country code
- (required) A three-letter ISO 3166 country code of a customer's shipping address.
Roles of order_tags
of an order
order_tags
of an orderOrder tags play a wide variety of roles when it comes to an how ads that may have driven the order are attributed. Order tags are used in determining
- if the order is part of a subscription, and if it is a first-time or a recurring order
- if the order is from a first time or returning customer
- whether the order is to be excluded from attribution altogether
Subscriptions
Northbeam's customers often want to be ad attribution or revenue as a function of whether the orders are part of a subscription initiation or part of a recurring order. Order tags are used here so that we may identify order that are part of a first time subscription order or if they are a recurring order.
Using the Subscription Order Tags
page in the Settings
Section of your Northbeam Dashboard, a customer can choose which order tags are associated with which stage of a subscription - thus enabling them to delineate between first time or recurring subscription order and revenue. A category Other
is also included to capture orders that could be either.
Customer Stage
Order tags can also play a role in determining if the order is from a first time or returning customer. By default, the logic we apply to determine if an order is form a first-time or returning customer is by taking all orders from a particular customer_id
and looking at the orders as a function of time. The first order in the sequence is a first-time customer, and all subsequent orders are labeled returning customer.
If this logic is insufficient for your use case, please contact [email protected] and consult us on how we can leverage your order tags to capture the logic you seek to leverage!
This delineation can be used to analyze orders (and revenue) as a function of both of these customer stages.
Order Exclusions
There are certain cases where it is desire-able to exclude certain orders altogether. This may be the case if you are looking to do ad attribution or analyze revenue as a function of web store orders but your OMS also includes orders that came from a brick and mortar store. If these undesirable orders are tagged with a specific tag, these can be added to the Exclude Orders by Tag
section in the Settings
page of your Northbeam dashboard.
Updated 2 months ago