Ometria Orders API

openapi: 3.2.0
info:
  version: 1.1.0
  title: Ometria data Orders API
  description: 'Welcome to the Ometria API reference.


    The Ometria API is organized around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors. All requests are authenticated using an API key which can be obtained from your account settings.


    ### HTTPS


    All requests to the Ometria API MUST be carried out via HTTPS. API servers do not listen on unsecured HTTP ports to avoid the possibility of insecure information exchange.


    ### Message encoding


    The V2 Ometria API uses JSON encoding for all data exchanges and assumes UTF-8 character encoding throughout.


    ### Rate limits


    The Ometria API has a default rate limit of 4 requests per second per Ometria account. The /push/ endpoint allows 8 requests per second per Ometria account. If you expect to exceed this limit, please contact us.


    In the case of your application being rate limited, the HTTP code 429 (too many requests) will be returned. In this case your application should reduce the number of requests it is trying to send.'
  contact:
    name: Ometria
    email: support@ometria.com
    url: https://ometria.com
servers:
- url: https://api.ometria.com/v2
security:
- apikey: []
tags:
- name: Orders
paths:
  /orders:
    get:
      tags:
      - Orders
      summary: List Orders
      description: List orders with optional filters
      parameters:
      - name: limit
        in: query
        description: Number of items to return. Maximum 250.
        required: false
        schema:
          type: string
          default: '10'
      - name: offset
        in: query
        description: The index of first record to return.
        required: false
        schema:
          type: string
          default: '0'
      - name: customer_id
        in: query
        description: Find all orders by customer.
        required: false
        schema:
          type: string
      - name: email
        in: query
        description: Find all orders by customer.
        required: false
        schema:
          type: string
      - name: updateBefore
        in: query
        description: Find all orders updated before a certain date.
        required: false
        schema:
          type: string
          format: date-time
          default: '1970-01-01 00:00:00.000000+00:00'
      - name: updateSince
        in: query
        description: Find all orders updated since a certain date.
        required: false
        schema:
          type: string
          format: date-time
          default: '1970-01-01 00:00:00.000000+00:00'
      - name: createBefore
        in: query
        description: Find all new orders created before a certain date.
        required: false
        schema:
          type: string
          format: date-time
          default: '1970-01-01 00:00:00.000000+00:00'
      - name: createSince
        in: query
        description: Find all new orders created since a certain date.
        required: false
        schema:
          type: string
          format: date-time
          default: '1970-01-01 00:00:00.000000+00:00'
      - name: timestampSince
        in: query
        description: Find all orders placed at a certain time.
        required: false
        schema:
          type: string
          format: date-time
          default: '1970-01-01 00:00:00.000000+00:00'
      - name: timestampBefore
        in: query
        description: Find all orders placed at a certain time.
        required: false
        schema:
          type: string
          format: date-time
          default: '1970-01-01 00:00:00.000000+00:00'
      responses:
        '200':
          description: List of Order objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '403':
          description: API key is not authorised to access this resource
      operationId: getOrders
      x-operation-id-source: derived
  /orders/{order_id}:
    get:
      tags:
      - Orders
      summary: Get Order
      description: Return a single Order item
      parameters:
      - name: order_id
        in: path
        description: The ID of the order to return.
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Number of items to return. Maximum 250.
        required: false
        schema:
          type: string
          default: '10'
      - name: offset
        in: query
        description: The index of the first record.
        required: false
        schema:
          type: string
          default: '0'
      responses:
        '200':
          description: Order object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '403':
          description: API key is not authorised to access this resource
        '404':
          description: Order with specified ID was not found
      operationId: getOrdersByOrderId
      x-operation-id-source: derived
components:
  schemas:
    ExtraIdentifier:
      title: Extra Identifier
      type: object
      description: An additional identifier for a record, used to attach non-standard customer or record IDs (e.g. loyalty programme IDs, external CRM IDs). Records may carry multiple extra identifiers.
      required:
      - type
      - value
      properties:
        type:
          type: string
          description: The identifier type label. Must contain only lowercase letters and underscores (regex `^[a-z_]+$`), 1-255 characters. Will be coerced to lowercase on ingestion.
          minLength: 1
          maxLength: 255
          pattern: ^[a-z_]+$
          example: loyalty_id
        value:
          type: string
          description: The identifier value (free-form string).
          example: LOY-7898734
      example:
        type: loyalty_id
        value: LOY-7898734
    OrderLineItem:
      type: object
      description: Describes an individual product line item added to an Order.
      required:
      - product_id
      - quantity
      - unit_price
      properties:
        product_id:
          type: string
          description: The ID of the product.
        variant_id:
          type: string
          description: 'The ID of the <a href="https://ometria-api-reference.readme.io/docs/products-product-listings-and-product-variants" target="_blank">product variant</a> (if applicable), max length: 255'
        quantity:
          type: integer
          description: The number of products in the line item (not inclusive of any refunded items).
        sku:
          type: string
          description: 'The SKU of the product in this line item, max length: 255.

            If this field is left empty it will be set to ''null''.'
        unit_price:
          type: number
          description: The unit price of the product in this line item.
          format: float
        quantity_refunded:
          type: integer
          description: The number of products refunded in the line item.
        refunded:
          type: number
          description: The total price of refunded products in this line item.
          format: float
        subtotal:
          type: number
          description: The subtotal of this line item after refunds have been taken.
          format: float
        tax:
          type: number
          description: The tax value of this line item after refunds have been taken.
          format: float
        total:
          type: number
          description: The total price of this line item after refunds amounts have been taken.
          format: float
        discount:
          type: number
          description: 'The value of any discount applied to the order.

            This value should be either a negative number, e.g. -`2.99` or `0`.'
          format: float
        is_on_sale:
          type: boolean
          description: Set to 'True' if the product was on sale when the order was placed.
        variant_options:
          type: array
          description: An array of OrderLineItemVariantOption objects.
          items:
            $ref: '#/components/schemas/OrderLineItemVariantOption'
        totals:
          $ref: '#/components/schemas/OrderExtendedLineItemTotals'
        properties:
          description: Custom key / value pairs accessible in emails using the related Order object.
          type: object
      example:
        product_id: SS14-059493
        sku: SS14-059493-S5
        quantity: 2
        unit_price: 50
        discount: -10
        subtotal: 100
        tax: 0
        total: 100
        is_on_sale: true
        properties:
          custom_key: custom value
        variant_options:
        - type: size
          id: large
          label: Large
        - type: color
          id: color-45
          label: Blue
    Order:
      title: Order
      type: object
      description: Describes an Order record.
      required:
      - '@type'
      - id
      - timestamp
      - grand_total
      - subtotal
      - currency
      properties:
        '@type':
          type: string
          description: The value must be "order". This shows that this record represents an order object.
        id:
          type: string
          description: 'The order ID, max length: 36.

            If you exceed the character limit this field will pass validation but will appear truncated in Ometria.'
        timestamp:
          type: string
          description: 'The date and time the order was placed on the site or in store.

            Follow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.'
          format: date-time
        grand_total:
          type: number
          description: The grand total of the order.
          format: float
        subtotal:
          type: number
          description: The subtotal of this order after refunds have been taken.
          format: float
        discount:
          type: number
          description: This value should be negative or 0. Not positive.
          format: float
        shipping:
          type: number
          description: The shipping cost of this order.
          format: float
        tax:
          type: number
          description: The tax of this order after refunds have been taken.
          format: float
        currency:
          type: string
          description: 'The currency used for this order, must be 3 characters, upper case, e.g. GBP, USD.

            Follow ISO 4217.

            If left empty this field is set to ''null''.'
          minLength: 3
          maxLength: 3
        web_id:
          type: string
          description: 'The web ID passed through the JavaScript tracker - this is only required if the value is different to the id.

            max length: 32. If you exceed the character limit the field will pass validation but appear truncated in Ometria.'
        status:
          type: string
          description: Code representing the status of this order 'complete', 'pending', 'shipped' etc.
        is_valid:
          type: boolean
          description: Is this order considered valid and should be counted against revenue? Set to false to 'delete'.
        customer:
          $ref: '#/components/schemas/OrderCustomer'
          description: The details of the customer who placed the order.
        lineitems:
          type: array
          description: Array of [OrderLineItem](#definition-OrderLineItem) objects representing the items in this order.
          items:
            $ref: '#/components/schemas/OrderLineItem'
        ip_address:
          type: string
          description: 'The IP address of the visitor who placed order (if known).

            max length: 64.'
        channel:
          type: string
          description: Channel of this order. E.g., 'online', 'instore', 'amazon' etc.
          default: online
        store:
          type: string
          description: 'Code representing the store the order was placed in.

            max length: 32'
        payment_method:
          type: string
          description: 'Code representing payment method, max length: 32.

            If you exceed the character limit this field will pass validation but appear truncated in Ometria.'
        shipping_method:
          type: string
          description: Code representing shipping method.
        shipping_address:
          $ref: '#/components/schemas/OrderAddress'
          description: The address the customer used for shipping.
        billing_address:
          $ref: '#/components/schemas/OrderAddress'
          description: The address the customer used for billing.
        coupon_code:
          description: 'Coupon code applied to this order, max length: 128 characters. Pushed orders with a longer coupon code are rejected.'
          type: string
        properties:
          description: Custom key / value pairs accessible in emails using this order object.
          type: object
        extra_identifiers:
          type:
          - array
          - 'null'
          description: Optional list of extra identifiers (such as a loyalty ID) as per your identity resolution configuration, e.g. `loyalty_id`. Custom identifiers must be configured for your account before you send them. See <a href="https://support.ometria.com/hc/en-gb/articles/32595707442077-Custom-identifiers">Custom identifiers</a> for the full format, multi-valued identifiers, and CSV usage.
          items:
            $ref: '#/components/schemas/ExtraIdentifier'
      example:
        '@type': order
        id: '123553'
        web_id: '891743'
        customer:
          email: john.smith@example.com
          firstname: John
          lastname: Smith
          phone_number: '+447812123456'
        status: complete
        is_valid: true
        timestamp: '2015-01-02T09:00:00+00'
        subtotal: 83.33
        discount: -5
        shipping: 2
        tax: 16.07
        grand_total: 96.4
        ip_address: 127.0.0.1
        currency: GBP
        channel: online
        store: example.com/en
        payment_method: card
        shipping_method: standard
        shipping_address:
          city: London
          state: Greater London
          postcode: W1K 4TG
          country_code: GB
        billing_address:
          city: London
          state: Greater London
          postcode: W1K 4TG
          country_code: GB
        coupon_code: FJ45-TJ5Y-5YK3-T894
        properties:
          custom_key: custom value
        extra_identifiers:
        - type: erp_id
          value: ERP-2025-00451
        - type: fulfilment_id
          value: FL-9988
        lineitems:
        - product_id: SS14-059493
          sku: SS14-059493-S5
          quantity: 2
          unit_price: 50
          total: 100
          properties:
            custom_key: custom value
          variant_options:
          - type: size
            id: large
            label: Large
          - type: color
            id: color-45
            label: Blue
    OrderExtendedLineItemBaseTotal:
      type: object
      description: The totals of this lineitem represented in the base currency
      required:
      - total
      properties:
        currency:
          type: string
          description: The currency of the base lineitem totals - as set for your account. Following ISO 4217
          minLength: 3
          maxLength: 3
        unit_price:
          type: number
          description: The value of the unit price in the base currency
          format: float
        discount:
          type: number
          description: The value of the discount on the lineitem in the base currency as a negative number
          format: float
        refunded:
          type: number
          description: The total price of refunded products in this line item.
          format: float
        subtotal:
          type: number
          description: The subtotal of this lineitem in the base currency (after refunded amounts have been taken into consideration).
          format: float
        tax:
          type: number
          description: The tax of this lineitem in the base currency (after refunded amounts have been taken into consideration).
          format: float
        total:
          type: number
          description: The total price of this line item in the base currency (after refunded amounts have been taken into consideration).
          format: float
      example:
        currency: GBP
        unit_price: 99
        discount: -4
        subtotal: 95
        tax: 0
        total: 95
    OrderAddress:
      type: object
      description: Describes an Address.
      properties:
        city:
          type: string
          description: 'The city or town for this address, max length: 32, lower case.

            Follow ISO 3166-1 alpha-2.

            If you exceed the character limit this field will pass validation but appear truncated in Ometria.

            If left empty this field is set to ''null''.'
        state:
          type: string
          description: 'The state or county of the address, max length: 32, lower case.

            If you exceed the character limit this field will pass validation but appear truncated in Ometria.

            If left empty this field is set to ''null''.'
        postcode:
          type: string
          description: 'The postcode or zipcode of the address, max length: 32, lower case.

            If you exceed the character limit this field will pass validation but appear truncated in Ometria.

            If left empty this field is set to ''null''.'
        country_code:
          type: string
          description: 'The country for this address, must be 2 characters, upper case, e.g. ''GB''.

            Follow ISO 3166-1 alpha-2.

            If left empty this field is set to ''null''.'
          minLength: 2
          maxLength: 2
      example:
        city: London
        state: Greater London
        postcode: W1K 4TG
        country_code: GB
    OrderExtendedLineItemLocalTotal:
      type: object
      description: The totals of this lineitem represented in the local currency
      required:
      - total
      properties:
        currency:
          type: string
          description: The currency of the local lineitem totals. Following ISO 4217
          minLength: 3
          maxLength: 3
        unit_price:
          type: number
          description: The value of the unit price in the local currency
          format: float
        discount:
          type: number
          description: 'The value of any discount applied to the line item.

            This value should be either a negative number, e.g. -`2.99` or `0`.'
          format: float
        refunded:
          type: number
          description: The total price of refunded products in this line item.
          format: float
        subtotal:
          type: number
          description: The subtotal of this lineitem in the local currency (after refunded amounts have been taken into consideration).
          format: float
        tax:
          type: number
          description: The tax of this lineitem in the local currency (after refunded amounts have been taken into consideration).
          format: float
        total:
          type: number
          description: The total price of this lineitem in the local currency (after refunded amounts have been taken into consideration).
          format: float
      example:
        currency: USD
        unit_price: 129
        discount: -9
        subtotal: 120
        tax: 0
        total: 120
    OrderExtendedLineItemTotals:
      type: object
      description: The totals of the lineitem. This can be used to express the order value in a base currency and a local currency.
      properties:
        base:
          $ref: '#/components/schemas/OrderExtendedLineItemBaseTotal'
        local:
          $ref: '#/components/schemas/OrderExtendedLineItemLocalTotal'
      example:
        local:
          currency: USD
          unit_price: 129
          discount: -9
          total: 120
        base:
          currency: GBP
          unit_price: 99
          discount: -4
          total: 95
    OrderCustomer:
      type: object
      description: The details of the customer who placed the order.
      properties:
        id:
          type: string
          description: 'The <a href="https://ometria-api-reference.readme.io/docs/contacts-endpoint#customer-ids" target="_blank">customer''s ID</a>, max length: 255.

            This can be any unique identifier you use for your customers which you''d like to use for reporting in Ometria. It must not contain any personally identifiable information (name, email address etc.)'
        email:
          type: string
          description: 'The customer''s email address, max length: 255, lower case.

            If left empty this field is set to ''null''.'
        firstname:
          type: string
          description: 'The customer''s first name, max length: 64.'
        lastname:
          type: string
          description: 'The customer''s last name, max length: 64.'
        phone_number:
          type: string
          description: The customer's phone number, in E.164/International format (e.g. starting "+447...")
      example:
        id: '546548'
        email: john.smith@example.com
        firstname: John
        lastname: Smith
    OrderLineItemVariantOption:
      type: object
      description: Describes the configurable options attached to a Lineitem.
      required:
      - type
      - id
      - label
      properties:
        type:
          type: string
          description: The type of the variant option.
        id:
          type: string
          description: The id of the variant option.
        label:
          type: string
          description: The label of the variant option.
      example:
        type: size
        id: size:5
        label: '5'
  securitySchemes:
    apikey:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: Ometria API key which can be obtained from your Ometria account administrator
    apiKeyReadTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `read:translations`.'
    apiKeyWriteTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `write:translations`.'
x-explorer-enabled: false
x-readme:
  proxy-enabled: true
  samples-enabled: true