Northbeam Orders API
The Orders API from Northbeam — 2 operation(s) for orders.
Operations 4
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
The Orders API from Northbeam — 2 operation(s) for orders.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/northbeam:northbeam-orders-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: V2 Orders API
description: API for syncing data from ecommerce shops to the Northbeam app.
termsOfService: https://www.northbeam.io/terms
contact:
name: Northbeam customer success
email: success@northbeam.io
version: 1.1.0
servers:
- url: https://api.northbeam.io/v2
description: Production server (uses live data)
- url: https://api-uat.northbeam.io/v2
description: User Acceptance Testing (UAT), Production Equivalent (provided for Customer Testing ONLY, orders submitted here do not get used in attribution)
security:
- api_key: []
client_id: []
tags:
- name: Orders
paths:
/orders:
post:
summary: Upsert a list of orders to Northbeam
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
description: Orders list
required: true
responses:
'200':
description: Orders succesfully upserted
'400':
description: Invalid input
'401':
description: Unauthenticated
'500':
description: Server error
tags:
- Orders
operationId: postOrders
x-operation-id-source: derived
patch:
summary: Partially update existing orders
operationId: patchOrders
description: 'Update specific fields of existing orders. Only fields present in the
request payload will be modified. Omitted fields retain their existing values.
Use explicit null to clear optional field values.
**Note:** The `products` and `refunds` fields currently cannot be patched. To modify
products or refunds, re-submit the full order via POST.
Array fields (order_tags, discount_codes) are replaced entirely when
present - no per-item merging is performed.
The entire batch fails if any order_id does not exist or any entry fails validation.'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OrderPatch'
minItems: 1
maxItems: 2500
required: true
responses:
'200':
description: Orders successfully queued for update
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Orders received
'400':
description: Invalid input - validation error or order not found
'401':
description: Unauthenticated
'413':
description: Payload too large
'500':
description: Server error
tags:
- Orders
get:
summary: Fetch a list of orders
description: ''
parameters:
- in: query
name: start_date
description: Start date of the form %Y-%m-%d
required: true
schema:
type: string
default: '2001-01-01'
- in: query
name: end_date
description: End date of the form %Y-%m-%d
required: true
schema:
type: string
default: '9999-01-01'
responses:
'200':
description: Orders fetched
'401':
description: Unauthenticated
'500':
description: Could not fetch
tags:
- Orders
operationId: getOrders
x-operation-id-source: derived
/orders/aliases:
post:
summary: Add aliases to existing orders
description: 'Additively attach alternate order IDs to existing orders. Aliases that already
exist are silently ignored. Orders must already exist.'
operationId: addOrderAliases
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- aliases
properties:
aliases:
type: array
maxItems: 2500
items:
type: object
additionalProperties: false
required:
- order_id
- type
- id
properties:
order_id:
type: string
minLength: 1
description: The order_id to attach this alias to
type:
type: string
minLength: 1
description: Alias type identifier
examples:
- shopify_checkout_token
- custom:legacy_system
id:
type: string
minLength: 1
description: The alternate order ID value
examples:
- abc-xyz-123
responses:
'200':
description: Aliases accepted
'400':
description: Validation error
'404':
description: One or more order_ids not found
tags:
- Orders
components:
schemas:
OrderPatch:
type: object
additionalProperties: false
description: Partial order update. Only order_id and customer_id are required.
required:
- order_id
- customer_id
properties:
order_id:
type: string
minLength: 1
description: This must be a universal id that must be unique across all of your existing orders. It should exactly match the ID that you send using `firePurchaseEvent` if that is a part of your workflow. For documentation on `firePurchaseEvent` please review our Northbeam Pixel API. This must not be the customer ID.
examples:
- abc-123
customer_id:
type: string
minLength: 1
description: This must be a universal id that must be unique across all of your existing customers. The internal customer ID. This must not be the order ID. This should not be an email.
examples:
- def-456
time_of_purchase:
type: string
format: date-time
description: The time the order was placed by the customer. ISO-8601 timestamp.
examples:
- '2022-03-08T01:23:45-08:00'
customer_email:
type: string
format: email
description: The email associated with the customer. Cannot be provided if hashed_customer_email is present.
examples:
- example@gmail.com
nullable: true
hashed_customer_email:
type: string
description: 'Pre-hashed (SHA-256) email associated with the customer. Cannot be provided if customer_email is present.
**Important:** Email must be normalized before hashing. See the [Hashing Customer Data](https://docs.northbeam.io/reference/hashing-customer-data) guide for normalization rules and implementation examples.
'
examples:
- 5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5
nullable: true
customer_phone_number:
type: string
description: The phone number associated with the customer. Cannot be provided if hashed_customer_phone_number is present.
examples:
- '1112223333'
nullable: true
hashed_customer_phone_number:
type: string
description: 'Pre-hashed (SHA-256) phone number associated with the customer. Cannot be provided if customer_phone_number is present.
**Important:** Phone number must be normalized to E.164 format before hashing. See the [Hashing Customer Data](https://docs.northbeam.io/reference/hashing-customer-data) guide for normalization rules and implementation examples.
'
examples:
- 8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92
nullable: true
customer_name:
type: string
description: The name associated with the customer.
examples:
- Jane Doe
nullable: true
customer_ip_address:
type: string
format: ip
description: The IP address associated with the customer.
examples:
- 127.0.0.1
nullable: true
discount_codes:
type: array
uniqueItems: true
description: A list of discount codes used in the order.
items:
type: string
examples:
- Discount
nullable: true
discount_amount:
type: number
maximum: '100_000_000_000_000'
description: The amount of money discounted due to discount codes in the currency of the order.
examples:
- 10
nullable: true
order_tags:
type: array
description: A list of internal tags describing the order.
uniqueItems: true
items:
type: string
examples:
- Special order
nullable: true
tax:
type: number
maximum: '100_000_000_000_000'
description: The tax amount in the currency of the order.
examples:
- 1
nullable: true
is_recurring_order:
type: boolean
description: Whether or not this order is part of a recurring purchase.
examples:
- false
nullable: true
currency:
type: string
minLength: 3
description: The currency of the order. Note, all subsequent fields will assume that the currency is the one passed in this field. Please use standard ISO-4217 currency codes.
pattern: ^AED|AFN|ALL|AMD|ANG|AOA|ARS|AUD|AWG|AZN|BAM|BBD|BDT|BGN|BHD|BIF|BMD|BND|BOB|BRL|BSD|BTN|BWP|BYR|BZD|CAD|CDF|CHF|CLP|CNY|COP|CRC|CUC|CUP|CVE|CZK|DJF|DKK|DOP|DZD|EGP|ERN|ETB|EUR|FJD|FKP|GBP|GEL|GGP|GHS|GIP|GMD|GNF|GTQ|GYD|HKD|HNL|HRK|HTG|HUF|IDR|ILS|IMP|INR|IQD|IRR|ISK|JEP|JMD|JOD|JPY|KES|KGS|KHR|KMF|KPW|KRW|KWD|KYD|KZT|LAK|LBP|LKR|LRD|LSL|LYD|MAD|MDL|MGA|MKD|MMK|MNT|MOP|MRO|MUR|MVR|MWK|MXN|MYR|MZN|NAD|NGN|NIO|NOK|NPR|NZD|OMR|PAB|PEN|PGK|PHP|PKR|PLN|PYG|QAR|RON|RSD|RUB|RWF|SAR|SBD|SCR|SDG|SEK|SGD|SHP|SLL|SOS|SPL|SRD|STD|SVC|SYP|SZL|THB|TJS|TMT|TND|TOP|TRY|TTD|TVD|TWD|TZS|UAH|UGX|USD|UYU|UZS|VEF|VND|VUV|WST|XAF|XCD|XDR|XOF|XPF|YER|ZAR|ZMW|ZWD$
message:
pattern: Currency does not match any known currencies
examples:
- USD
nullable: true
purchase_total:
type: number
maximum: '100_000_000_000_000'
description: The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order.
examples:
- 10000
nullable: true
customer_shipping_address:
type: object
additionalProperties: false
required:
- zip
- country_code
properties:
address1:
type: string
minLength: 1
description: The street address of the customer's shipping address.
examples:
- 123 Main St.
address2:
type: string
description: An optional additional field for the street address.
examples:
- Apt. 1A
city:
type: string
minLength: 1
description: The city or locality of the customer's shipping address.
examples:
- Small town
state:
type: string
description: The state or region of the customer's shipping address.
examples:
- CO
zip:
type: string
description: The postal code (e.g. zip, postcode) of the customer's shipping address.
examples:
- '11111'
country_code:
type: string
minLength: 1
description: The three-letter ISO 3166 country code of the customer's shipping address.
examples:
- USA
pattern: ^A(BW|FG|GO|IA|L[AB]|ND|R[EGM]|SM|T[AFG]|U[ST]|ZE)|B(DI|E[LNS]|FA|G[DR]|H[RS]|IH|L[MRZ]|MU|OL|R[ABN]|TN|VT|WA)|C(A[FN]|CK|H[ELN]|IV|MR|O[DGKLM]|PV|RI|U[BW]|XR|Y[MP]|ZE)|D(EU|JI|MA|NK|OM|ZA)|E(CU|GY|RI|S[HPT]|TH)|F(IN|JI|LK|R[AO]|SM)|G(AB|BR|EO|GY|HA|I[BN]|LP|MB|N[BQ]|R[CDL]|TM|U[FMY])|H(KG|MD|ND|RV|TI|UN)|I(DN|MN|ND|OT|R[LNQ]|S[LR]|TA)|J(AM|EY|OR|PN)|K(AZ|EN|GZ|HM|IR|NA|OR|WT)|L(AO|B[NRY]|CA|IE|KA|SO|TU|UX|VA)|M(A[CFR]|CO|D[AGV]|EX|HL|KD|L[IT]|MR|N[EGP]|OZ|RT|SR|TQ|US|WI|Y[ST])|N(AM|CL|ER|FK|GA|I[CU]|LD|OR|PL|RU|ZL)|OMN|P(A[KN]|CN|ER|HL|LW|NG|OL|R[IKTY]|SE|YF)|QAT|R(EU|OU|US|WA)|S(AU|DN|EN|G[PS]|HN|JM|L[BEV]|MR|OM|PM|RB|SD|TP|UR|V[KN]|W[EZ]|XM|Y[CR])|T(C[AD]|GO|HA|JK|K[LM]|LS|ON|TO|U[NRV]|WN|ZA)|U(GA|KR|MI|RY|SA|ZB)|V(AT|CT|EN|GB|IR|NM|UT)|W(LF|SM)|YEM|Z(AF|MB|WE)$
message:
pattern: Country code should use three-letter ISO 3166 country codes
nullable: true
shipping_cost:
type: number
maximum: '100_000_000_000_000'
description: The amount that was paid for shipping for this order
examples:
- 10.99
nullable: true
alternate_order_ids:
type: array
items:
type: object
additionalProperties: false
required:
- type
- id
properties:
type:
type: string
minLength: 1
description: Alias type identifier
examples:
- shopify_checkout_token
- custom:legacy_system
id:
type: string
minLength: 1
description: The alternate order ID value
examples:
- abc-xyz-123
description: Alternate identifiers for this order
nullable: true
Order:
xml:
name: Order
type: array
uniqueItems: true
minItems: 1
items:
type: object
additionalProperties: false
required:
- order_id
- customer_id
- time_of_purchase
- currency
- purchase_total
- tax
- products
- shipping_cost
properties:
order_id:
type: string
minLength: 1
description: This must be a universal id that must be unique across all of your existing orders. It should exactly match the ID that you send using `firePurchaseEvent` if that is a part of your workflow. For documentation on `firePurchaseEvent` please review our Northbeam Pixel API. This must not be the customer ID.
examples:
- abc-123
customer_id:
type: string
minLength: 1
description: This must be a universal id that must be unique across all of your existing customers. The internal customer ID. This must not be the order ID. This should not be an email.
examples:
- def-456
time_of_purchase:
type: string
format: date-time
description: The time the order was placed by the customer. ISO-8601 timestamp.
examples:
- '2022-03-08T01:23:45-08:00'
customer_email:
type: string
format: email
description: The email associated with the customer. Cannot be provided if hashed_customer_email is present.
examples:
- example@gmail.com
customer_phone_number:
type: string
description: The phone number associated with the customer. Cannot be provided if hashed_customer_phone_number is present.
examples:
- '1112223333'
hashed_customer_email:
type: string
description: 'Pre-hashed (SHA-256) email associated with the customer. Cannot be provided if customer_email is present.
**Important:** Email must be normalized before hashing. See the [Hashing Customer Data](https://docs.northbeam.io/reference/hashing-customer-data) guide for normalization rules and implementation examples.
'
examples:
- 5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5
hashed_customer_phone_number:
type: string
description: 'Pre-hashed (SHA-256) phone number associated with the customer. Cannot be provided if customer_phone_number is present.
**Important:** Phone number must be normalized to E.164 format before hashing. See the [Hashing Customer Data](https://docs.northbeam.io/reference/hashing-customer-data) guide for normalization rules and implementation examples.
'
examples:
- 8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92
customer_name:
type: string
description: The name associated with the customer.
examples:
- Jane Doe
customer_ip_address:
type: string
format: ip
description: The IP address associated with the customer.
examples:
- 127.0.0.1
discount_codes:
type: array
uniqueItems: true
description: A list of discount codes used in the order.
items:
type: string
examples:
- Discount
discount_amount:
type: number
maximum: '100_000_000_000_000'
description: The amount of money discounted due to discount codes in the currency of the order.
examples:
- 10
order_tags:
type: array
description: A list of internal tags describing the order.
uniqueItems: true
items:
type: string
examples:
- Special order
tax:
type: number
maximum: '100_000_000_000_000'
description: The tax amount in the currency of the order.
examples:
- 1
is_recurring_order:
type: boolean
description: Whether or not this order is part of a recurring purchase.
examples:
- false
currency:
type: string
minLength: 3
description: The currency of the order. Note, all subsequent fields will assume that the currency is the one passed in this field. Please use standard ISO-4217 currency codes.
pattern: ^AED|AFN|ALL|AMD|ANG|AOA|ARS|AUD|AWG|AZN|BAM|BBD|BDT|BGN|BHD|BIF|BMD|BND|BOB|BRL|BSD|BTN|BWP|BYR|BZD|CAD|CDF|CHF|CLP|CNY|COP|CRC|CUC|CUP|CVE|CZK|DJF|DKK|DOP|DZD|EGP|ERN|ETB|EUR|FJD|FKP|GBP|GEL|GGP|GHS|GIP|GMD|GNF|GTQ|GYD|HKD|HNL|HRK|HTG|HUF|IDR|ILS|IMP|INR|IQD|IRR|ISK|JEP|JMD|JOD|JPY|KES|KGS|KHR|KMF|KPW|KRW|KWD|KYD|KZT|LAK|LBP|LKR|LRD|LSL|LYD|MAD|MDL|MGA|MKD|MMK|MNT|MOP|MRO|MUR|MVR|MWK|MXN|MYR|MZN|NAD|NGN|NIO|NOK|NPR|NZD|OMR|PAB|PEN|PGK|PHP|PKR|PLN|PYG|QAR|RON|RSD|RUB|RWF|SAR|SBD|SCR|SDG|SEK|SGD|SHP|SLL|SOS|SPL|SRD|STD|SVC|SYP|SZL|THB|TJS|TMT|TND|TOP|TRY|TTD|TVD|TWD|TZS|UAH|UGX|USD|UYU|UZS|VEF|VND|VUV|WST|XAF|XCD|XDR|XOF|XPF|YER|ZAR|ZMW|ZWD$
message:
pattern: Currency does not match any known currencies
examples:
- USD
purchase_total:
type: number
maximum: '100_000_000_000_000'
description: The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order.
examples:
- 10000
products:
type: array
minItems: 1
description: A list of objects describing the products in the order.
message:
uniqueItems: Cannot include duplicate product IDs
minItems: Must have at least one product
items:
type: object
additionalProperties: false
required:
- id
- name
- quantity
- price
properties:
id:
type: string
minLength: 1
description: A unique identifier describing the product in the order.
examples:
- prod-1
name:
type: string
minLength: 1
description: The name of the product.
examples:
- Our product
quantity:
type: number
maximum: '100_000_000_000_000'
description: How many of this product was sold in the order
examples:
- 1
price:
type: number
maximum: '100_000_000_000_000'
description: The (per unit) price of the product in the currency of the order.
examples:
- 10011
variant_id:
type: string
minLength: 1
description: A unique identifier describing the product variant in the order.
examples:
- prod-variant-1
variant_name:
type: string
description: The name of the product variant. Cannot be empty when specified.
examples:
- Our product variant
refunds:
type: array
description: A list of objects describing the refunded products.
uniqueItems: true
message:
uniqueItems: Cannot include duplicate product IDs
items:
type: object
additionalProperties: false
required:
- product_id
- quantity
- refund_amount
- refund_cost
- refund_made_at
properties:
product_id:
type: string
minLength: 1
description: A unique identifier describing the product in the refund (should also be included in the products list).
quantity:
type: number
maximum: '100_000_000_000_000'
description: The number of products refunded (should be less than or equal to the corresponding quantity in the products list).
refund_amount:
type: number
maximum: '100_000_000_000_000'
description: The total amount refunded to the customer in the currency of the order.
refund_cost:
type: number
maximum: '100_000_000_000_000'
description: 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:
type: string
format: date-time
description: The time the refund was fulfilled by your brand. ISO-8601 timestamp.
variant_id:
type: string
minLength: 1
description: A unique identifier describing the variant of the product in the refund (should also be included in the products list).
customer_shipping_address:
type: object
additionalProperties: false
required:
- zip
- country_code
properties:
address1:
type: string
minLength: 1
description: The street address of the customer's shipping address.
examples:
- 123 Main St.
address2:
type: string
description: An optional additional field for the street address.
examples:
- Apt. 1A
city:
type: string
minLength: 1
description: The city or locality of the customer's shipping address.
examples:
- Small town
state:
type: string
description: The state or region of the customer's shipping address.
examples:
- CO
zip:
type: string
description: The postal code (e.g. zip, postcode) of the customer's shipping address.
examples:
- '11111'
country_code:
type: string
minLength: 1
description: The three-letter ISO 3166 country code of the customer's shipping address.
examples:
- USA
pattern: ^A(BW|FG|GO|IA|L[AB]|ND|R[EGM]|SM|T[AFG]|U[ST]|ZE)|B(DI|E[LNS]|FA|G[DR]|H[RS]|IH|L[MRZ]|MU|OL|R[ABN]|TN|VT|WA)|C(A[FN]|CK|H[ELN]|IV|MR|O[DGKLM]|PV|RI|U[BW]|XR|Y[MP]|ZE)|D(EU|JI|MA|NK|OM|ZA)|E(CU|GY|RI|S[HPT]|TH)|F(IN|JI|LK|R[AO]|SM)|G(AB|BR|EO|GY|HA|I[BN]|LP|MB|N[BQ]|R[CDL]|TM|U[FMY])|H(KG|MD|ND|RV|TI|UN)|I(DN|MN|ND|OT|R[LNQ]|S[LR]|TA)|J(AM|EY|OR|PN)|K(AZ|EN|GZ|HM|IR|NA|OR|WT)|L(AO|B[NRY]|CA|IE|KA|SO|TU|UX|VA)|M(A[CFR]|CO|D[AGV]|EX|HL|KD|L[IT]|MR|N[EGP]|OZ|RT|SR|TQ|US|WI|Y[ST])|N(AM|CL|ER|FK|GA|I[CU]|LD|OR|PL|RU|ZL)|OMN|P(A[KN]|CN|ER|HL|LW|NG|OL|R[IKTY]|SE|YF)|QAT|R(EU|OU|US|WA)|S(AU|DN|EN|G[PS]|HN|JM|L[BEV]|MR|OM|PM|RB|SD|TP|UR|V[KN]|W[EZ]|XM|Y[CR])|T(C[AD]|GO|HA|JK|K[LM]|LS|ON|TO|U[NRV]|WN|ZA)|U(GA|KR|MI|RY|SA|ZB)|V(AT|CT|EN|GB|IR|NM|UT)|W(LF|SM)|YEM|Z(AF|MB|WE)$
message:
pattern: Country code should use three-letter ISO 3166 country codes
shipping_cost:
type: number
maximum: '100_000_000_000_000'
description: The amount that was paid for shipping for this order
examples:
- 10.99
alternate_order_ids:
type: array
items:
type: object
additionalProperties: false
required:
- type
- id
properties:
type:
type: string
minLength: 1
description: Alias type identifier
examples:
- shopify_checkout_token
- custom:legacy_system
id:
type: string
minLength: 1
description: The alternate order ID value
examples:
- abc-xyz-123
description: Alternate identifiers for this order
securitySchemes:
api_key:
type: apiKey
name: Authorization
in: header
client_id:
type: apiKey
name: Data-Client-ID
in: header
x-alias-properties:
type:
type: string
minLength: 1
description: Alias type identifier
examples:
- shopify_checkout_token
- custom:legacy_system
id:
type: string
minLength: 1
description: The alternate order ID value
examples:
- abc-xyz-123