Ometria Orders API
The Orders API from Ometria — 2 operation(s) for orders.
The Orders API from Ometria — 2 operation(s) for orders.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/ometria:ometria-orders-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
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