openapi: 3.1.0
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
info:
  title: API - Orders - V1 (Deprecated)
  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.0.1
security:
- api_key: []
  client_id: []
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
    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
servers:
- url: https://api.northbeam.io/v1
  description: Production server (uses live data)
- url: https://api-uat.northbeam.io/v1
  description: User Acceptance Testing (UAT), Production Equivalent (provided for Customer Testing ONLY, orders submitted here do not get used in attribution)
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    client_id:
      type: apiKey
      name: Data-Client-ID
      in: header
  schemas:
    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
        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: 1
            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
          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.
          customer_shipping_address:
            type: object
            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: 3
                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