1. Use the ‘Data-client-ID’ and ‘API Key’ to upload your orders to Northbeam

You can access your client ID and API key right in the Onboarding Flow during this step. If you don’t see an ID and Key, just click on “GENERATE NEW API KEY” to create one.

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.

To sync order data with Northbeam, please 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

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 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 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 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 - (optional) A list of product objects describing the refunded products
  • product_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 a variant_id was provided in the products field.
• customer_shipping_address - (optional) an object that captures the shipping address for the order
  • address1 - (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.

2. Testing the Orders API

You don’t need to be a full-fledged developer—just plug in your API keys and fill out an example payload with some sample data (you can use our example values if you’re unsure) to make an API call to our development or production endpoints. The Reference page also has example code for Shell, Ruby, PHP, Python, and other languages to help you out!

When you’re testing, feel free to use the following values without needing production keys. In the testing environment, no orders are saved, and we only return validation results. You can also test with your user keys, but keep in mind that the development database is periodically cleared to manage storage, so it’s best to treat it as a temporary testing environment rather than a stable one.

Endpoint URLs