Partially update existing orders

curl --request PATCH \
  --url https://api.northbeam.io/v2/orders \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Data-Client-ID: <api-key>' \
  --data '
[
  {
    "order_id": "abc-123",
    "customer_id": "def-456",
    "time_of_purchase": "2022-03-08T01:23:45-08:00",
    "customer_email": "example@gmail.com",
    "hashed_customer_email": "5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5",
    "customer_phone_number": "1112223333",
    "hashed_customer_phone_number": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92",
    "customer_name": "Jane Doe",
    "customer_ip_address": "127.0.0.1",
    "discount_codes": "Discount",
    "discount_amount": 10,
    "order_tags": "Special order",
    "tax": 1,
    "is_recurring_order": false,
    "currency": "USD",
    "purchase_total": 10000,
    "customer_shipping_address": {
      "zip": "11111",
      "country_code": "USA",
      "address1": "123 Main St.",
      "address2": "Apt. 1A",
      "city": "Small town",
      "state": "CO"
    },
    "shipping_cost": 10.99,
    "alternate_order_ids": [
      {
        "type": "shopify_checkout_token",
        "id": "abc-xyz-123"
      }
    ]
  }
]
'

const options = {
  method: 'PATCH',
  headers: {
    Authorization: '<api-key>',
    'Data-Client-ID': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      order_id: 'abc-123',
      customer_id: 'def-456',
      time_of_purchase: '2022-03-08T01:23:45-08:00',
      customer_email: 'example@gmail.com',
      hashed_customer_email: '5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5',
      customer_phone_number: '1112223333',
      hashed_customer_phone_number: '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92',
      customer_name: 'Jane Doe',
      customer_ip_address: '127.0.0.1',
      discount_codes: 'Discount',
      discount_amount: 10,
      order_tags: 'Special order',
      tax: 1,
      is_recurring_order: false,
      currency: 'USD',
      purchase_total: 10000,
      customer_shipping_address: {
        zip: '11111',
        country_code: 'USA',
        address1: '123 Main St.',
        address2: 'Apt. 1A',
        city: 'Small town',
        state: 'CO'
      },
      shipping_cost: 10.99,
      alternate_order_ids: [{type: 'shopify_checkout_token', id: 'abc-xyz-123'}]
    }
  ])
};

fetch('https://api.northbeam.io/v2/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.northbeam.io/v2/orders"

payload = [
    {
        "order_id": "abc-123",
        "customer_id": "def-456",
        "time_of_purchase": "2022-03-08T01:23:45-08:00",
        "customer_email": "example@gmail.com",
        "hashed_customer_email": "5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5",
        "customer_phone_number": "1112223333",
        "hashed_customer_phone_number": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92",
        "customer_name": "Jane Doe",
        "customer_ip_address": "127.0.0.1",
        "discount_codes": "Discount",
        "discount_amount": 10,
        "order_tags": "Special order",
        "tax": 1,
        "is_recurring_order": False,
        "currency": "USD",
        "purchase_total": 10000,
        "customer_shipping_address": {
            "zip": "11111",
            "country_code": "USA",
            "address1": "123 Main St.",
            "address2": "Apt. 1A",
            "city": "Small town",
            "state": "CO"
        },
        "shipping_cost": 10.99,
        "alternate_order_ids": [
            {
                "type": "shopify_checkout_token",
                "id": "abc-xyz-123"
            }
        ]
    }
]
headers = {
    "Authorization": "<api-key>",
    "Data-Client-ID": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.northbeam.io/v2/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'order_id' => 'abc-123',
        'customer_id' => 'def-456',
        'time_of_purchase' => '2022-03-08T01:23:45-08:00',
        'customer_email' => 'example@gmail.com',
        'hashed_customer_email' => '5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5',
        'customer_phone_number' => '1112223333',
        'hashed_customer_phone_number' => '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92',
        'customer_name' => 'Jane Doe',
        'customer_ip_address' => '127.0.0.1',
        'discount_codes' => 'Discount',
        'discount_amount' => 10,
        'order_tags' => 'Special order',
        'tax' => 1,
        'is_recurring_order' => false,
        'currency' => 'USD',
        'purchase_total' => 10000,
        'customer_shipping_address' => [
                'zip' => '11111',
                'country_code' => 'USA',
                'address1' => '123 Main St.',
                'address2' => 'Apt. 1A',
                'city' => 'Small town',
                'state' => 'CO'
        ],
        'shipping_cost' => 10.99,
        'alternate_order_ids' => [
                [
                                'type' => 'shopify_checkout_token',
                                'id' => 'abc-xyz-123'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "Data-Client-ID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.northbeam.io/v2/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Data-Client-ID"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"order_id\": \"abc-123\",\n    \"customer_id\": \"def-456\",\n    \"time_of_purchase\": \"2022-03-08T01:23:45-08:00\",\n    \"customer_email\": \"example@gmail.com\",\n    \"hashed_customer_email\": \"5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5\",\n    \"customer_phone_number\": \"1112223333\",\n    \"hashed_customer_phone_number\": \"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92\",\n    \"customer_name\": \"Jane Doe\",\n    \"customer_ip_address\": \"127.0.0.1\",\n    \"discount_codes\": \"Discount\",\n    \"discount_amount\": 10,\n    \"order_tags\": \"Special order\",\n    \"tax\": 1,\n    \"is_recurring_order\": false,\n    \"currency\": \"USD\",\n    \"purchase_total\": 10000,\n    \"customer_shipping_address\": {\n      \"zip\": \"11111\",\n      \"country_code\": \"USA\",\n      \"address1\": \"123 Main St.\",\n      \"address2\": \"Apt. 1A\",\n      \"city\": \"Small town\",\n      \"state\": \"CO\"\n    },\n    \"shipping_cost\": 10.99,\n    \"alternate_order_ids\": [\n      {\n        \"type\": \"shopify_checkout_token\",\n        \"id\": \"abc-xyz-123\"\n      }\n    ]\n  }\n]"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.northbeam.io/v2/orders"

	payload := strings.NewReader("[\n  {\n    \"order_id\": \"abc-123\",\n    \"customer_id\": \"def-456\",\n    \"time_of_purchase\": \"2022-03-08T01:23:45-08:00\",\n    \"customer_email\": \"example@gmail.com\",\n    \"hashed_customer_email\": \"5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5\",\n    \"customer_phone_number\": \"1112223333\",\n    \"hashed_customer_phone_number\": \"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92\",\n    \"customer_name\": \"Jane Doe\",\n    \"customer_ip_address\": \"127.0.0.1\",\n    \"discount_codes\": \"Discount\",\n    \"discount_amount\": 10,\n    \"order_tags\": \"Special order\",\n    \"tax\": 1,\n    \"is_recurring_order\": false,\n    \"currency\": \"USD\",\n    \"purchase_total\": 10000,\n    \"customer_shipping_address\": {\n      \"zip\": \"11111\",\n      \"country_code\": \"USA\",\n      \"address1\": \"123 Main St.\",\n      \"address2\": \"Apt. 1A\",\n      \"city\": \"Small town\",\n      \"state\": \"CO\"\n    },\n    \"shipping_cost\": 10.99,\n    \"alternate_order_ids\": [\n      {\n        \"type\": \"shopify_checkout_token\",\n        \"id\": \"abc-xyz-123\"\n      }\n    ]\n  }\n]")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Data-Client-ID", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.northbeam.io/v2/orders")
  .header("Authorization", "<api-key>")
  .header("Data-Client-ID", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"order_id\": \"abc-123\",\n    \"customer_id\": \"def-456\",\n    \"time_of_purchase\": \"2022-03-08T01:23:45-08:00\",\n    \"customer_email\": \"example@gmail.com\",\n    \"hashed_customer_email\": \"5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5\",\n    \"customer_phone_number\": \"1112223333\",\n    \"hashed_customer_phone_number\": \"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92\",\n    \"customer_name\": \"Jane Doe\",\n    \"customer_ip_address\": \"127.0.0.1\",\n    \"discount_codes\": \"Discount\",\n    \"discount_amount\": 10,\n    \"order_tags\": \"Special order\",\n    \"tax\": 1,\n    \"is_recurring_order\": false,\n    \"currency\": \"USD\",\n    \"purchase_total\": 10000,\n    \"customer_shipping_address\": {\n      \"zip\": \"11111\",\n      \"country_code\": \"USA\",\n      \"address1\": \"123 Main St.\",\n      \"address2\": \"Apt. 1A\",\n      \"city\": \"Small town\",\n      \"state\": \"CO\"\n    },\n    \"shipping_cost\": 10.99,\n    \"alternate_order_ids\": [\n      {\n        \"type\": \"shopify_checkout_token\",\n        \"id\": \"abc-xyz-123\"\n      }\n    ]\n  }\n]")
  .asString();

{
  "message": "Orders received"
}

Orders API

Partially update existing orders

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.

PATCH

orders

Partially update existing orders

curl --request PATCH \
  --url https://api.northbeam.io/v2/orders \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Data-Client-ID: <api-key>' \
  --data '
[
  {
    "order_id": "abc-123",
    "customer_id": "def-456",
    "time_of_purchase": "2022-03-08T01:23:45-08:00",
    "customer_email": "example@gmail.com",
    "hashed_customer_email": "5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5",
    "customer_phone_number": "1112223333",
    "hashed_customer_phone_number": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92",
    "customer_name": "Jane Doe",
    "customer_ip_address": "127.0.0.1",
    "discount_codes": "Discount",
    "discount_amount": 10,
    "order_tags": "Special order",
    "tax": 1,
    "is_recurring_order": false,
    "currency": "USD",
    "purchase_total": 10000,
    "customer_shipping_address": {
      "zip": "11111",
      "country_code": "USA",
      "address1": "123 Main St.",
      "address2": "Apt. 1A",
      "city": "Small town",
      "state": "CO"
    },
    "shipping_cost": 10.99,
    "alternate_order_ids": [
      {
        "type": "shopify_checkout_token",
        "id": "abc-xyz-123"
      }
    ]
  }
]
'

const options = {
  method: 'PATCH',
  headers: {
    Authorization: '<api-key>',
    'Data-Client-ID': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      order_id: 'abc-123',
      customer_id: 'def-456',
      time_of_purchase: '2022-03-08T01:23:45-08:00',
      customer_email: 'example@gmail.com',
      hashed_customer_email: '5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5',
      customer_phone_number: '1112223333',
      hashed_customer_phone_number: '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92',
      customer_name: 'Jane Doe',
      customer_ip_address: '127.0.0.1',
      discount_codes: 'Discount',
      discount_amount: 10,
      order_tags: 'Special order',
      tax: 1,
      is_recurring_order: false,
      currency: 'USD',
      purchase_total: 10000,
      customer_shipping_address: {
        zip: '11111',
        country_code: 'USA',
        address1: '123 Main St.',
        address2: 'Apt. 1A',
        city: 'Small town',
        state: 'CO'
      },
      shipping_cost: 10.99,
      alternate_order_ids: [{type: 'shopify_checkout_token', id: 'abc-xyz-123'}]
    }
  ])
};

fetch('https://api.northbeam.io/v2/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.northbeam.io/v2/orders"

payload = [
    {
        "order_id": "abc-123",
        "customer_id": "def-456",
        "time_of_purchase": "2022-03-08T01:23:45-08:00",
        "customer_email": "example@gmail.com",
        "hashed_customer_email": "5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5",
        "customer_phone_number": "1112223333",
        "hashed_customer_phone_number": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92",
        "customer_name": "Jane Doe",
        "customer_ip_address": "127.0.0.1",
        "discount_codes": "Discount",
        "discount_amount": 10,
        "order_tags": "Special order",
        "tax": 1,
        "is_recurring_order": False,
        "currency": "USD",
        "purchase_total": 10000,
        "customer_shipping_address": {
            "zip": "11111",
            "country_code": "USA",
            "address1": "123 Main St.",
            "address2": "Apt. 1A",
            "city": "Small town",
            "state": "CO"
        },
        "shipping_cost": 10.99,
        "alternate_order_ids": [
            {
                "type": "shopify_checkout_token",
                "id": "abc-xyz-123"
            }
        ]
    }
]
headers = {
    "Authorization": "<api-key>",
    "Data-Client-ID": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.northbeam.io/v2/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'order_id' => 'abc-123',
        'customer_id' => 'def-456',
        'time_of_purchase' => '2022-03-08T01:23:45-08:00',
        'customer_email' => 'example@gmail.com',
        'hashed_customer_email' => '5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5',
        'customer_phone_number' => '1112223333',
        'hashed_customer_phone_number' => '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92',
        'customer_name' => 'Jane Doe',
        'customer_ip_address' => '127.0.0.1',
        'discount_codes' => 'Discount',
        'discount_amount' => 10,
        'order_tags' => 'Special order',
        'tax' => 1,
        'is_recurring_order' => false,
        'currency' => 'USD',
        'purchase_total' => 10000,
        'customer_shipping_address' => [
                'zip' => '11111',
                'country_code' => 'USA',
                'address1' => '123 Main St.',
                'address2' => 'Apt. 1A',
                'city' => 'Small town',
                'state' => 'CO'
        ],
        'shipping_cost' => 10.99,
        'alternate_order_ids' => [
                [
                                'type' => 'shopify_checkout_token',
                                'id' => 'abc-xyz-123'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "Data-Client-ID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.northbeam.io/v2/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Data-Client-ID"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"order_id\": \"abc-123\",\n    \"customer_id\": \"def-456\",\n    \"time_of_purchase\": \"2022-03-08T01:23:45-08:00\",\n    \"customer_email\": \"example@gmail.com\",\n    \"hashed_customer_email\": \"5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5\",\n    \"customer_phone_number\": \"1112223333\",\n    \"hashed_customer_phone_number\": \"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92\",\n    \"customer_name\": \"Jane Doe\",\n    \"customer_ip_address\": \"127.0.0.1\",\n    \"discount_codes\": \"Discount\",\n    \"discount_amount\": 10,\n    \"order_tags\": \"Special order\",\n    \"tax\": 1,\n    \"is_recurring_order\": false,\n    \"currency\": \"USD\",\n    \"purchase_total\": 10000,\n    \"customer_shipping_address\": {\n      \"zip\": \"11111\",\n      \"country_code\": \"USA\",\n      \"address1\": \"123 Main St.\",\n      \"address2\": \"Apt. 1A\",\n      \"city\": \"Small town\",\n      \"state\": \"CO\"\n    },\n    \"shipping_cost\": 10.99,\n    \"alternate_order_ids\": [\n      {\n        \"type\": \"shopify_checkout_token\",\n        \"id\": \"abc-xyz-123\"\n      }\n    ]\n  }\n]"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.northbeam.io/v2/orders"

	payload := strings.NewReader("[\n  {\n    \"order_id\": \"abc-123\",\n    \"customer_id\": \"def-456\",\n    \"time_of_purchase\": \"2022-03-08T01:23:45-08:00\",\n    \"customer_email\": \"example@gmail.com\",\n    \"hashed_customer_email\": \"5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5\",\n    \"customer_phone_number\": \"1112223333\",\n    \"hashed_customer_phone_number\": \"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92\",\n    \"customer_name\": \"Jane Doe\",\n    \"customer_ip_address\": \"127.0.0.1\",\n    \"discount_codes\": \"Discount\",\n    \"discount_amount\": 10,\n    \"order_tags\": \"Special order\",\n    \"tax\": 1,\n    \"is_recurring_order\": false,\n    \"currency\": \"USD\",\n    \"purchase_total\": 10000,\n    \"customer_shipping_address\": {\n      \"zip\": \"11111\",\n      \"country_code\": \"USA\",\n      \"address1\": \"123 Main St.\",\n      \"address2\": \"Apt. 1A\",\n      \"city\": \"Small town\",\n      \"state\": \"CO\"\n    },\n    \"shipping_cost\": 10.99,\n    \"alternate_order_ids\": [\n      {\n        \"type\": \"shopify_checkout_token\",\n        \"id\": \"abc-xyz-123\"\n      }\n    ]\n  }\n]")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Data-Client-ID", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.northbeam.io/v2/orders")
  .header("Authorization", "<api-key>")
  .header("Data-Client-ID", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"order_id\": \"abc-123\",\n    \"customer_id\": \"def-456\",\n    \"time_of_purchase\": \"2022-03-08T01:23:45-08:00\",\n    \"customer_email\": \"example@gmail.com\",\n    \"hashed_customer_email\": \"5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5\",\n    \"customer_phone_number\": \"1112223333\",\n    \"hashed_customer_phone_number\": \"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92\",\n    \"customer_name\": \"Jane Doe\",\n    \"customer_ip_address\": \"127.0.0.1\",\n    \"discount_codes\": \"Discount\",\n    \"discount_amount\": 10,\n    \"order_tags\": \"Special order\",\n    \"tax\": 1,\n    \"is_recurring_order\": false,\n    \"currency\": \"USD\",\n    \"purchase_total\": 10000,\n    \"customer_shipping_address\": {\n      \"zip\": \"11111\",\n      \"country_code\": \"USA\",\n      \"address1\": \"123 Main St.\",\n      \"address2\": \"Apt. 1A\",\n      \"city\": \"Small town\",\n      \"state\": \"CO\"\n    },\n    \"shipping_cost\": 10.99,\n    \"alternate_order_ids\": [\n      {\n        \"type\": \"shopify_checkout_token\",\n        \"id\": \"abc-xyz-123\"\n      }\n    ]\n  }\n]")
  .asString();

{
  "message": "Orders received"
}

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.

Headers

Header	Description
`Authorization` required	Your Northbeam API key
`Data-Client-ID` required	Your Northbeam client ID
`Content-Type` required	`application/json`

Body

Required array length: 1 - 2500 elementsPartial order update. Only order_id and customer_id are required.

Field	Type	Description	Example
`order_id` required	string	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. Minimum string length: `1`	`”abc-123”`
`customer_id` required	string	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. Minimum string length: `1`	`”def-456”`
`time_of_purchase`	string (date-time)	The time the order was placed by the customer. ISO-8601 timestamp.	`”2022-03-08T01:23:45-08:00”`
`customer_email`	string (email), nullable	The email associated with the customer. Cannot be provided if hashed_customer_email is present.	`”example@gmail.com”`
`hashed_customer_email`	string, nullable	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 guide for normalization rules and implementation examples.	`”5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5”`
`customer_phone_number`	string, nullable	The phone number associated with the customer. Cannot be provided if hashed_customer_phone_number is present.	`”1112223333”`
`hashed_customer_phone_number`	string, nullable	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 guide for normalization rules and implementation examples.	`”8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92”`
`customer_name`	string, nullable	The name associated with the customer.	`”Jane Doe”`
`customer_ip_address`	string (ip), nullable	The IP address associated with the customer.	`”127.0.0.1”`
`discount_codes`	string[], nullable	A list of discount codes used in the order. Items must be unique.	`”Discount”`
`discount_amount`	number, nullable	The amount of money discounted due to discount codes in the currency of the order. Required range: `x <= 100000000000000`	`10`
`order_tags`	string[], nullable	A list of internal tags describing the order. Items must be unique.	`”Special order”`
`tax`	number, nullable	The tax amount in the currency of the order. Required range: `x <= 100000000000000`	`1`
`is_recurring_order`	boolean, nullable	Whether or not this order is part of a recurring purchase.	`false`
`currency`	string, nullable	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. Minimum string length: `3` Pattern: Show 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$	`“USD”`
`purchase_total`	number, nullable	The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order. Required range: `x <= 100000000000000`	`10000`
`customer_shipping_address`	object, nullable
		Show child attributes Field Type Description Example `address1` string The street address of the customer’s shipping address. Minimum string length: `1` `”123 Main St.”` `address2` string An optional additional field for the street address. `”Apt. 1A”` `city` string The city or locality of the customer’s shipping address. Minimum string length: `1` `”Small town”` `state` string The state or region of the customer’s shipping address. `”CO”` `zip` required string The postal code (e.g. zip, postcode) of the customer’s shipping address. `”11111”` `country_code` required string The three-letter ISO 3166 country code of the customer’s shipping address. Minimum string length: `1` Pattern: Show 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)$ `“USA”`
`shipping_cost`	number, nullable	The amount that was paid for shipping for this order Required range: `x <= 100000000000000`	`10.99`
`alternate_order_ids`	object[], nullable	Alternate identifiers for this order
		Show child attributes Field Type Description Example `type` required string Alias type identifier Minimum string length: `1` `”shopify_checkout_token”` `id` required string The alternate order ID value Minimum string length: `1` `”abc-xyz-123”`

Responses

Status	Description
`200`	Orders successfully queued for update
`400`	Invalid input - validation error or order not found
`401`	Unauthenticated
`413`	Payload too large
`500`	Server error

`200` response body

Field	Type	Description	Example
`message`	string		`”Orders received”`

Authorizations

Authorization

string

header

required

Data-Client-ID

string

header

required

Body

application/json

Required array length: 1 - 2500 elements

order_id

string

required

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.

Minimum string length: 1

Example:

"abc-123"

customer_id

string

required

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.

Minimum string length: 1

Example:

"def-456"

time_of_purchase

string<date-time>

The time the order was placed by the customer. ISO-8601 timestamp.

Example:

"2022-03-08T01:23:45-08:00"

customer_email

string<email> | null

The email associated with the customer. Cannot be provided if hashed_customer_email is present.

Example:

"example@gmail.com"

hashed_customer_email

string | null

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 guide for normalization rules and implementation examples.

Example:

"5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5"

customer_phone_number

string | null

The phone number associated with the customer. Cannot be provided if hashed_customer_phone_number is present.

Example:

"1112223333"

hashed_customer_phone_number

string | null

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 guide for normalization rules and implementation examples.

Example:

"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"

customer_name

string | null

The name associated with the customer.

Example:

"Jane Doe"

customer_ip_address

string<ip> | null

The IP address associated with the customer.

Example:

"127.0.0.1"

discount_codes

string[] | null

A list of discount codes used in the order.

Example:

"Discount"

discount_amount

number | null

The amount of money discounted due to discount codes in the currency of the order.

Required range: x <= 100000000000000

Example:

10

order_tags

string[] | null

A list of internal tags describing the order.

Example:

"Special order"

tax

number | null

The tax amount in the currency of the order.

Required range: x <= 100000000000000

Example:

1

is_recurring_order

boolean | null

Whether or not this order is part of a recurring purchase.

Example:

false

currency

string | null

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.

Minimum string length: 3

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$

Example:

"USD"

purchase_total

number | null

The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order.

Required range: x <= 100000000000000

Example:

10000

customer_shipping_address

object | null

Show child attributes

shipping_cost

number | null

The amount that was paid for shipping for this order

Required range: x <= 100000000000000

Example:

10.99

alternate_order_ids

object[] | null

Alternate identifiers for this order

Show child attributes

Response

Orders successfully queued for update

message

string

Example:

"Orders received"

​Headers

​Body

​Responses

​200 response body

Authorizations

Body

Response

Headers

Body

Responses

`200` response body