> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List orders
> Retrieve a paginated list of all orders associated with your platform. Use limit and offset parameters to page through large result sets.
This endpoint returns all orders associated with your platform in reverse chronological order. Results are paginated using offset-based pagination – you control the page size with `limit` and navigate through pages by incrementing `offset`. Use this endpoint for administrative dashboards, reconciliation tasks, or bulk exports where you need to enumerate orders across all buyers and merchants.
To retrieve all orders across all pages, increment `offset` by `limit` on each request until the number of returned `items` is
less than `limit`, or until `offset` exceeds `total`.
For filtering orders by buyer or other attributes, use the [Search orders](/api-reference/orders/search-orders) endpoint
instead of paginating through the full list.
## OpenAPI
````yaml GET /v1/orders
openapi: 3.0.0
info:
version: 0.0.1
title: Tilta API
description: Tilta API documentation
servers:
- url: https://api.tilta.io
description: Tilta Production API
- url: https://api.tilta-sandbox.io
description: Tilta Sandbox API
security: []
paths:
/v1/orders:
get:
tags:
- Orders
summary: List orders
description: Returns an array of orders.
parameters:
- schema:
$ref: '#/components/schemas/limit'
required: false
description: The number of records to be taken.
name: limit
in: query
- schema:
allOf:
- $ref: '#/components/schemas/offset'
- nullable: true
required: false
description: The number of records to be skipped.
name: offset
in: query
- schema:
type: string
description: Order's IDs to filter in orders.
example: order_123,order_456
required: false
description: Order's IDs to filter in orders.
name: external_id
in: query
- schema:
type: string
description: Buyer's IDs to filter in orders.
example: buyer_123,buyer_456
required: false
description: Buyer's IDs to filter in orders.
name: buyer_external_id
in: query
- schema:
type: string
description: Merchant's IDs to filter in orders.
example: merchant_123,merchant_456
required: false
description: Merchant's IDs to filter in orders.
name: merchant_external_id
in: query
- schema:
type: string
description: Order statuses to filter in orders.
required: false
description: Order statuses to filter in orders.
name: status
in: query
- schema:
type: string
description: >-
Created at range filter (unix timestamps in seconds). Format:
"gte..lte" where each bound is optional (e.g.
"1580515200..1583020800" or "1580515200..").
example: 1580515200..1583020800
required: false
description: >-
Created at range filter (unix timestamps in seconds). Format:
"gte..lte" where each bound is optional (e.g.
"1580515200..1583020800" or "1580515200..").
name: created_at
in: query
- schema:
type: string
description: >-
Ordered at range filter (unix timestamps in seconds). Format:
"gte..lte" where each bound is optional (e.g.
"1580515200..1583020800").
example: 1580515200..1583020800
required: false
description: >-
Ordered at range filter (unix timestamps in seconds). Format:
"gte..lte" where each bound is optional (e.g.
"1580515200..1583020800").
name: ordered_at
in: query
- schema:
type: string
description: Gross amount to filter in orders.
example: '1000'
required: false
description: Gross amount to filter in orders.
name: amount_gross
in: query
- schema:
type: string
description: Currency to filter in orders.
example: EUR,GBP
required: false
description: Currency to filter in orders.
name: currency
in: query
- schema:
type: string
description: >-
Sort orders by provided field in ascending or descending order.
Prefix field with - for descending order. Example:
sort_by=-created_at
required: false
description: >-
Sort orders by provided field in ascending or descending order.
Prefix field with - for descending order. Example:
sort_by=-created_at
name: sort_by
in: query
- schema:
type: array
nullable: true
items:
type: string
enum:
- buyer
description: >-
Order sub-entities to expand in the response object. Currently
supported: buyer (more coming soon).
example:
- buyer
required: false
description: >-
Order sub-entities to expand in the response object. Currently
supported: buyer (more coming soon).
name: expand
in: query
- schema:
type: string
description: >-
Filter by a Custom Data field. Replace `field` in
`custom_data[field]` with the field name. Bare values are strings;
JSON numbers, booleans, quoted strings, and arrays preserve their
JSON types. A scalar also matches an element of a stored array; an
array matches a stored array containing all supplied values.
required: false
description: >-
Filter by a Custom Data field. Replace `field` in
`custom_data[field]` with the field name. Bare values are strings;
JSON numbers, booleans, quoted strings, and arrays preserve their
JSON types. A scalar also matches an element of a stored array; an
array matches a stored array containing all supplied values.
name: custom_data[field]
in: query
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
minimum: 0
description: The number of taken records.
example: 100
offset:
type: integer
minimum: 0
description: The number of skipped records.
example: 0
total:
type: integer
minimum: 0
description: Total number of records
example: 140
items:
type: array
items:
type: object
properties:
external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of an order.
status:
type: string
enum:
- DRAFT
- CANCELLED
- CLOSED
- PENDING_CONFIRMATION
- CONFIRMED
- EXPIRED
- DISBURSED
description: Order status.
buyer_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a related buyer.
created_at:
type: number
description: >-
Timestamp indicating when the order was created
(unix time in seconds).
example: 1582896122
updated_at:
type: number
description: >-
Timestamp indicating the last time the order was
updated (unix time in seconds).
example: 1582896122
buyer:
type: object
properties:
legal_name:
type: string
required:
- legal_name
merchant_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a related merchant.
ordered_at:
type: integer
description: >-
Order creation date (unix time in seconds). It
cannot be in the future
payment_method:
type: string
enum:
- CASH
- CARD
- TRANSFER
- DEBIT
description: >-
The chosen payment method for a respective order.
Available payment methods depend on a number of
criteria. Check the paymentterms endpoint for
available options. May be left empty if the payment
method has not been chosen yet.
example: TRANSFER
payment_term:
type: string
enum:
- PREPAYMENT
- DEFER_3D
- DEFER_7D
- DEFER_14D
- DEFER_21D
- DEFER_30D
- DEFER_45D
- DEFER_60D
- DEFER_75D
- DEFER_90D
- DEFER_120D
- SPLIT_3M
- SPLIT_6M
description: >-
The chosen payment term for a respective order.
Available payment terms depend on a number of
criteria. Check the payment_terms endpoint for
available options
example: DEFER_30D
amount:
type: object
properties:
net:
type: integer
minimum: 1
description: >-
Total net price. As minimum currency unit (e.g
cents/pence).
tax:
type: integer
nullable: true
minimum: 0
description: >-
Total taxes amount. As minimum currency unit
(e.g cents/pence).
gross:
type: integer
minimum: 1
description: >-
Total gross price. As minimum currency unit (e.g
cents/pence).
currency:
type: string
enum:
- EUR
- GBP
- USD
- CHF
- PLN
- CZK
- RON
- BGN
- DKK
- HUF
- SEK
- NOK
- JPY
- AUD
- NZD
- CAD
description: ISO 4217 three-letter currency code.
required:
- net
- gross
- currency
comment:
type: string
nullable: true
description: >-
Additional order comment added below the order
summary in related communication with the buyer.
example: For Daniel without tomatoes
delivery_address:
type: object
nullable: true
properties:
street:
type: string
description: Address line (e.g. street, road, place).
example: Example Street
house:
type: string
description: House number or denominator.
example: 42b
postcode:
type: string
description: ZIP or postal code.
example: '12345'
city:
type: string
description: City, district, town, or village.
example: Berlin
country:
type: string
enum:
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- CV
- KH
- CM
- CA
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CD
- CG
- CK
- CR
- HR
- CU
- CW
- CY
- CZ
- CI
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MK
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RO
- RU
- RW
- RE
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TM
- TC
- TV
- TR
- UG
- UA
- AE
- GB
- UM
- US
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
- AX
description: Two-letter country code (ISO 3166-1 alpha-2).
additional:
type: string
nullable: true
description: >-
Additional address information (e.g. PO Box, c/o
name etc.).
example: c/o Testimonial
required:
- postcode
- city
- country
description: Delivery or shipping address for orders of goods.
custom_data:
type: object
nullable: true
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
- type: array
items:
anyOf:
- type: string
- type: number
- type: boolean
- nullable: true
- nullable: true
description: >-
Free-form metadata for storing integration-specific
data alongside this order.
line_items:
type: array
items:
type: object
properties:
name:
type: string
description: Item's name.
category:
type: string
description: Item's category.
description:
type: string
nullable: true
description: Item's description.
price:
type: integer
description: >-
Item's price. As minimum currency unit (e.g
cents/pence).
currency:
type: string
enum:
- EUR
- GBP
- USD
- CHF
- PLN
- CZK
- RON
- BGN
- DKK
- HUF
- SEK
- NOK
- JPY
- AUD
- NZD
- CAD
description: ISO 4217 three-letter currency code.
quantity:
type: integer
minimum: 1
description: Number of items in order.
required:
- name
- category
- price
- currency
- quantity
additionalProperties: false
description: >-
Order line items. Please do not merge line items but
provide them individually to allow for subsequent
correlation with invoices.
contact_email:
type: string
nullable: true
format: email
description: >-
Order-specific contact email address, used if
different from the main buyer email. This allows
merchants to specify which individual or entity
should be contacted about this specific order.
example: john.doe@example.com
required:
- external_id
- status
- buyer_external_id
- created_at
- updated_at
- merchant_external_id
- ordered_at
- payment_method
- payment_term
- amount
additionalProperties: false
required:
- limit
- offset
- total
- items
additionalProperties: false
description: A list of orders.
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
security:
- bearerAuth: []
components:
schemas:
limit:
type: integer
description: The number of records to be taken.
example: 100
default: 100
maximum: 100
offset:
type: integer
description: The number of records to be skipped.
example: 0
default: 0
badRequestSchema:
type: object
properties:
code:
type: string
description: Error code
example: BAD_REQUEST
error:
type: string
description: Error message for debugging purposes
example: Request validation failed. 1 issue found.
issues:
type: array
items:
type: object
properties:
code:
type: string
description: Issue code
example: INVALID_TYPE
path:
type: string
description: Issue path starting with body, params, querystring, or headers
example: body.registered_at
message:
type: string
description: Issue message for debugging purposes
example: Invalid type
required:
- code
- path
- message
description: List of issues
example:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
required:
- code
- error
- issues
description: Bad Request, see error message for details.
example:
code: BAD_REQUEST
error: Request validation failed. 1 issue found.
issues:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
unauthorizedRequestSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Unauthorized
code:
type: string
description: Error code.
example: UNAUTHORIZED
required:
- error
- code
description: Unauthorized Request.
example:
error: Unauthorized
code: UNAUTHORIZED
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````