> ## Documentation Index
> Fetch the complete documentation index at: https://docs.northbeam.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.


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.

<div className="nb-api-tables nb-field-table">
  ## Headers

  | Header | Description |
  | :- | :- |
  | `Authorization` <span className="nb-req">required</span> | Your Northbeam API key |
  | `Data-Client-ID` <span className="nb-req">required</span> | Your Northbeam client ID |
  | `Content-Type` <span className="nb-req">required</span> | `application/json` |

  ## Body

  Required array length: `1 - 2500` elements

  Partial order update. Only order\_id and customer\_id are required.

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>order\_id</code> <span className="nb-req">required</span></td><td>string</td><td>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 <code>firePurchaseEvent</code> if that is a part of your workflow. For documentation on <code>firePurchaseEvent</code> please review our Northbeam Pixel API. This must not be the customer ID.<br />Minimum string length: <code>1</code></td><td><code className="nb-ex">"abc-123"</code></td></tr><tr><td><code>customer\_id</code> <span className="nb-req">required</span></td><td>string</td><td>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.<br />Minimum string length: <code>1</code></td><td><code className="nb-ex">"def-456"</code></td></tr><tr><td><code>time\_of\_purchase</code></td><td>string (date-time)</td><td>The time the order was placed by the customer. ISO-8601 timestamp.</td><td><code className="nb-ex">"2022-03-08T01:23:45-08:00"</code></td></tr><tr><td><code>customer\_email</code></td><td>string (email), nullable</td><td>The email associated with the customer. Cannot be provided if hashed\_customer\_email is present.</td><td><code className="nb-ex">"[example@gmail.com](mailto:example@gmail.com)"</code></td></tr><tr><td><code>hashed\_customer\_email</code></td><td>string, nullable</td><td>Pre-hashed (SHA-256) email associated with the customer. Cannot be provided if customer\_email is present.<br /><strong>Important:</strong> Email must be normalized before hashing. See the <a href="/docs/hashing-customer-data">Hashing Customer Data</a> guide for normalization rules and implementation examples.</td><td><code className="nb-ex">"5d41402abc4b2a76b9719d911017c592ae5f7d09d5c8d0e9e3e5f4a8e5c5c5c5"</code></td></tr><tr><td><code>customer\_phone\_number</code></td><td>string, nullable</td><td>The phone number associated with the customer. Cannot be provided if hashed\_customer\_phone\_number is present.</td><td><code className="nb-ex">"1112223333"</code></td></tr><tr><td><code>hashed\_customer\_phone\_number</code></td><td>string, nullable</td><td>Pre-hashed (SHA-256) phone number associated with the customer. Cannot be provided if customer\_phone\_number is present.<br /><strong>Important:</strong> Phone number must be normalized to E.164 format before hashing. See the <a href="/docs/hashing-customer-data">Hashing Customer Data</a> guide for normalization rules and implementation examples.</td><td><code className="nb-ex">"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"</code></td></tr><tr><td><code>customer\_name</code></td><td>string, nullable</td><td>The name associated with the customer.</td><td><code className="nb-ex">"Jane Doe"</code></td></tr><tr><td><code>customer\_ip\_address</code></td><td>string (ip), nullable</td><td>The IP address associated with the customer.</td><td><code className="nb-ex">"127.0.0.1"</code></td></tr><tr><td><code>discount\_codes</code></td><td>string\[], nullable</td><td>A list of discount codes used in the order.<br />Items must be unique.</td><td><code className="nb-ex">"Discount"</code></td></tr><tr><td><code>discount\_amount</code></td><td>number, nullable</td><td>The amount of money discounted due to discount codes in the currency of the order.<br />Required range: <code>x \<= 100000000000000</code></td><td><code className="nb-ex">10</code></td></tr><tr><td><code>order\_tags</code></td><td>string\[], nullable</td><td>A list of internal tags describing the order.<br />Items must be unique.</td><td><code className="nb-ex">"Special order"</code></td></tr><tr><td><code>tax</code></td><td>number, nullable</td><td>The tax amount in the currency of the order.<br />Required range: <code>x \<= 100000000000000</code></td><td><code className="nb-ex">1</code></td></tr><tr><td><code>is\_recurring\_order</code></td><td>boolean, nullable</td><td>Whether or not this order is part of a recurring purchase.</td><td><code className="nb-ex">false</code></td></tr><tr><td><code>currency</code></td><td>string, nullable</td><td>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.<br />Minimum string length: <code>3</code><br />Pattern: <div className="nb-toggle nb-long"><label><input type="checkbox" /><span>Show pattern</span></label><div className="nb-toggle-body"><code>^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\$</code></div></div></td><td><code className="nb-ex">"USD"</code></td></tr><tr><td><code>purchase\_total</code></td><td>number, nullable</td><td>The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order.<br />Required range: <code>x \<= 100000000000000</code></td><td><code className="nb-ex">10000</code></td></tr><tr className="nb-has-children"><td><code>customer\_shipping\_address</code></td><td>object, nullable</td><td /><td /></tr><tr className="nb-children-row"><td /><td /><td colSpan={2}><div className="nb-toggle nb-children"><label><input type="checkbox" /><span>Show child attributes</span></label><div className="nb-toggle-body"><div className="nb-child-table"><div className="nb-ct-head"><div>Field</div><div>Type</div><div>Description</div><div>Example</div></div><div className="nb-ct-row"><div><code>address1</code></div><div>string</div><div>The street address of the customer's shipping address.<br />Minimum string length: <code>1</code></div><div><code className="nb-ex">"123 Main St."</code></div></div><div className="nb-ct-row"><div><code>address2</code></div><div>string</div><div>An optional additional field for the street address.</div><div><code className="nb-ex">"Apt. 1A"</code></div></div><div className="nb-ct-row"><div><code>city</code></div><div>string</div><div>The city or locality of the customer's shipping address.<br />Minimum string length: <code>1</code></div><div><code className="nb-ex">"Small town"</code></div></div><div className="nb-ct-row"><div><code>state</code></div><div>string</div><div>The state or region of the customer's shipping address.</div><div><code className="nb-ex">"CO"</code></div></div><div className="nb-ct-row"><div><code>zip</code> <span className="nb-req">required</span></div><div>string</div><div>The postal code (e.g. zip, postcode) of the customer's shipping address.</div><div><code className="nb-ex">"11111"</code></div></div><div className="nb-ct-row"><div><code>country\_code</code> <span className="nb-req">required</span></div><div>string</div><div>The three-letter ISO 3166 country code of the customer's shipping address.<br />Minimum string length: <code>1</code><br />Pattern: <div className="nb-toggle nb-long"><label><input type="checkbox" /><span>Show pattern</span></label><div className="nb-toggle-body"><code>^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)\$</code></div></div></div><div><code className="nb-ex">"USA"</code></div></div></div></div></div></td></tr><tr><td><code>shipping\_cost</code></td><td>number, nullable</td><td>The amount that was paid for shipping for this order<br />Required range: <code>x \<= 100000000000000</code></td><td><code className="nb-ex">10.99</code></td></tr><tr className="nb-has-children"><td><code>alternate\_order\_ids</code></td><td>object\[], nullable</td><td>Alternate identifiers for this order</td><td /></tr><tr className="nb-children-row"><td /><td /><td colSpan={2}><div className="nb-toggle nb-children"><label><input type="checkbox" /><span>Show child attributes</span></label><div className="nb-toggle-body"><div className="nb-child-table"><div className="nb-ct-head"><div>Field</div><div>Type</div><div>Description</div><div>Example</div></div><div className="nb-ct-row"><div><code>type</code> <span className="nb-req">required</span></div><div>string</div><div>Alias type identifier<br />Minimum string length: <code>1</code></div><div><code className="nb-ex">"shopify\_checkout\_token"</code></div></div><div className="nb-ct-row"><div><code>id</code> <span className="nb-req">required</span></div><div>string</div><div>The alternate order ID value<br />Minimum string length: <code>1</code></div><div><code className="nb-ex">"abc-xyz-123"</code></div></div></div></div></div></td></tr></tbody></table></div>

  ## 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

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>message</code></td><td>string</td><td /><td><code className="nb-ex">"Orders received"</code></td></tr></tbody></table></div>
</div>


## OpenAPI

````yaml openapi/orders-v2.json PATCH /orders
openapi: 3.1.0
info:
  title: API - Orders - V2
  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: []
paths:
  /orders:
    patch:
      summary: Partially update existing orders
      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.
      operationId: patchOrders
      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
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](/docs/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](/docs/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: 100000000000000
          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: 100000000000000
          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: 100000000000000
          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: 100000000000000
          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
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    client_id:
      type: apiKey
      name: Data-Client-ID
      in: header

````