---
updatedAt: 2026-05-22T15:57:54.000Z
agentTools:
projectIndex: https://docs.ometria.com/llms.txt
---
# List Orders
List orders with optional filters
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"version": "1.1.0",
"title": "Ometria data API",
"description": "Welcome to the Ometria API reference.\n\n\nThe Ometria API is organized around the [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) 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.\n\n### HTTPS\n\nAll 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.\n\n### Message encoding\n\nThe V2 Ometria API uses JSON encoding for all data exchanges and assumes UTF-8 character encoding throughout.\n\n### Rate limits\n\nThe 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.\n\nIn 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"
}
},
"x-explorer-enabled": false,
"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"
}
}
}
}
},
"security": [
{
"apikey": []
}
],
"servers": [
{
"url": "https://api.ometria.com/v2"
}
],
"components": {
"securitySchemes": {
"apikey": {
"type": "apiKey",
"name": "X-Ometria-Auth",
"in": "header",
"description": "Ometria API key which can be obtained from your Ometria account administrator"
}
},
"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"
}
},
"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.\nIf 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.\nFollow 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.\nFollow ISO 4217.\nIf 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.\nmax 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).\nmax 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.\nmax length: 32"
},
"payment_method": {
"type": "string",
"description": "Code representing payment method, max length: 32.\nIf 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",
"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 Custom identifiers for the full format, multi-valued identifiers, and CSV usage.",
"nullable": true,
"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"
}
]
}
]
}
},
"OrderAddress": {
"type": "object",
"description": "Describes an Address.",
"properties": {
"city": {
"type": "string",
"description": "The city or town for this address, max length: 32, lower case.\nFollow ISO 3166-1 alpha-2.\nIf you exceed the character limit this field will pass validation but appear truncated in Ometria.\nIf left empty this field is set to 'null'."
},
"state": {
"type": "string",
"description": "The state or county of the address, max length: 32, lower case.\nIf you exceed the character limit this field will pass validation but appear truncated in Ometria.\nIf left empty this field is set to 'null'."
},
"postcode": {
"type": "string",
"description": "The postcode or zipcode of the address, max length: 32, lower case.\nIf you exceed the character limit this field will pass validation but appear truncated in Ometria.\nIf 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'.\nFollow ISO 3166-1 alpha-2.\nIf left empty this field is set to 'null'.",
"minLength": 2,
"maxLength": 2
}
},
"example": {
"city": "London",
"state": "Greater London",
"postcode": "W1K 4TG",
"country_code": "GB"
}
},
"OrderCustomer": {
"type": "object",
"description": "The details of the customer who placed the order.",
"properties": {
"id": {
"type": "string",
"description": "The customer's ID, max length: 255.\nThis 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.\nIf 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"
}
},
"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 product variant (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.\nIf 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.\nThis 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"
}
]
}
},
"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"
}
},
"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
}
}
},
"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.\nThis 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
}
},
"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
}
}
}
},
"x-readme": {
"proxy-enabled": true,
"samples-enabled": true
}
}
```