> ## 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.
# Retrieve an order
> Fetch the full details of a single order, including its current status, authorization state, line items, amounts, and payment information.
Use this endpoint to fetch the complete, up-to-date state of any order on your platform. The response includes the order's lifecycle status, authorization result, associated buyer and merchant identifiers, line items, delivery address, and all financial details. This is the primary endpoint for polling order state or for confirming status after receiving a webhook event.
If you receive an order webhook event, use this endpoint to fetch the full order state immediately after – webhook payloads
may not include the complete object.
## OpenAPI
````yaml GET /v1/orders/{external_id}
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/{external_id}:
get:
tags:
- Orders
summary: Retrieve an order
description: Returns an order object.
parameters:
- schema:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of an order.
required: true
description: Unique identifier of an order.
name: external_id
in: path
- 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
responses:
'200':
description: ''
content:
application/json:
schema:
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
description: Order is returned.
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/orderNotFoundSchema'
security:
- bearerAuth: []
components:
schemas:
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
orderNotFoundSchema:
type: object
properties:
error:
type: string
description: Error details.
example: No Entity found
code:
type: string
description: Error code.
example: NOT_FOUND
required:
- error
- code
description: Order not found
example:
error: No Entity found
code: NOT_FOUND
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````