> ## 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.
# Transition an order
> Move an order between lifecycle states such as confirmed and cancelled. Tilta validates that the requested transition is permitted.
Order lifecycle management is handled through explicit status transitions. Rather than setting `status` through a replace, use this dedicated endpoint to move an order from one state to another. Tilta validates that the requested transition is permitted from the order's current status and rejects invalid transitions with a descriptive error.
Cancelling an order releases the reserved amount back to the buyer's credit facility. If you later transition a cancelled
order back to `CONFIRMED` and the buyer's available credit has fallen in the meantime, re-authorization can fail.
To reinstate a cancelled purchase, transition the order to `PENDING_CONFIRMATION` and then to `CONFIRMED`. That re-runs the
authorization check against the buyer's current credit facility.
## OpenAPI
````yaml POST /v1/orders/{external_id}/transition
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}/transition:
post:
tags:
- Orders
summary: Transition an order status
description: >-
Transitions an order to a new status.
Allowed transitions:
- `PENDING_CONFIRMATION` → `CONFIRMED` or `CANCELLED`
- `CONFIRMED` → `CANCELLED`
- `CANCELLED` → `PENDING_CONFIRMATION` or `CONFIRMED`
System-managed statuses (`DRAFT`, `EXPIRED`, `DISBURSED`, `CLOSED`)
cannot be set through this endpoint.
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
requestBody:
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- PENDING_CONFIRMATION
- CONFIRMED
- CANCELLED
description: Target status to transition the order to.
required:
- status
description: Order status transition request.
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 status has been successfully transitioned.
'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 `.
````