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 attributes as well as optional attributes that can be submitted for each order. These fields are also documented in the API Reference albeit in much more detail here.

Required Attributes

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 recipe 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 recipe 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 order
• currency- 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 Event
  • id - A unique identifier describing the product in the order
  • name - Name of the product
  • quantity - How many of the product were sold in the order
  • price - The price of the product in the currency of the order
  • variant_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 optionalL

• customer_email- the email associated with a customer - not necessary if using Northbeam's Fire Purchase Event - absolutely necessary if not using Northbeam's Fire Purchase Event and using Northbeam's Identify recipe instead
• customer_phone_number- The phone number associated with a customer
• customer_name- The name associated with a customer
• customer_ip_address - The IP address associated with a customer
• discount_codes- a list of strings that resemble Coupons or discount codes used in the order - similar to coupons in Northbeam's Fire Purchase Event
• discount_amount- The amount of money discounted due to discount codes in the currency of the order
• order_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 - A list of product objects describing the refunded products
  • product_id - A unique identifier describing the product in the refund (should also be included in the products list). If an entry is made in the optional refunds object, this field is required.
  • quantity- The number of products refunded (should be less than or equal to the corresponding quantity in the products list). If an entry is made in the optional refunds object, this field is required.
  • refund_amount - The total amount refunded to the customer in the currency of the order. If an entry is made in the optional refunds object, this field is required.
  • refund_cost - The estimated total cost of the refund, including the refund amount to the customer and any other overhead costs (i.e. shipping, fees). If an entry is made in the optional refunds object, this field is required.
  • refund_made_at - The time the refund was fulfilled by your brand. ISO-8601 timestamp. If an entry is made in the optional refunds object, this field is required.
  • variant_id - 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 a variant_id was provided in the products field.
• customer_shipping_address - an object that captures the shipping address for the order
  • address1- The street address of a customer's shipping address. If an entry is made in the optional customer_shipping_address object, this field is required.
  • address2 - An optional additional field for the street address. If an entry is made in the optional customer_shipping_address object, this field is required.
  • city - The city or locality of a customer's shipping address. If an entry is made in the optional customer_shipping_address object, this field is required.
  • state - The state or region of the customer's shipping address. If an entry is made in the optional customer_shipping_address object, this field is required.
  • zip - The postal code or region-code (in outside US) of the customer's shipping address. If an entry is made in the optional customer_shipping_address object, this field is required.
  • country code - A three-letter ISO 3166 country code of a customer's shipping address. If an entry is made in the optional customer_shipping_address object, this field is required.

When to call the Orders API

To enable the most realtime data for orders within Northbeam, if possible, we recommend triggering an API call for an order as soon as it lands in the Order Management System (OMS) (in a world absent of any logistical constraints).

If this is not often feasible, we generally advise you to sync as many orders as possible with a cadence of at least 2x faster than the number of times a day your pipeline runs per you services agreement.

• For example, if you are on the 4x plan, we recommend pushing updates 8x per day.

📘

Batching orders

Our API currently accepts orders in batches of up to 1000 per API call. If your volume of orders exceeds this batch size, it is best to breakup the calls to not exceed this limit.

Order updates

In addition to posting updates when an order is created, we recommend sending updates when an order is modified in such a way that would impact attribution analysis. If an order is fully or partially refunded, and your net revenue definition includes refunds, we recommend upserting updated orders data.

Roles of order_tags of an Order

Order 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.
• 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 undesire-able 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.

Meta and Tiktok Shops

While Northbeam is capable of planting a pixel on your web store, the same cannot be said of our ability to do so on your Meta or Tiktok Shop. To attribute these orders, which have no corresponding web events that we receive, there is a special treatment to ensure that you are able to optimize your ad spend for your maximize your revenue from these channels. For users of the Orders API, letting us know which orders are Tiktok or Meta shops orders by providing Northbeam with the appropriate tag, will enable a richer experience and allow for attribution of these orders.

Backfilling past Orders

Northbeam recommends that customers backfill their Orders data to around 5 years prior. This can be done via the Orders API, and is recommended to be done in batches.

It is important to note that backfilled Order data can only be Attributed if the orders have had relevant Pixel events recorded by the Northbeam Pixel.