> ## 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.
# Replace an order
> Fully replace an existing order using PUT semantics. Only orders in PENDING_CONFIRMATION status can be updated. Line items are replaced wholesale.
Use this endpoint to replace the full contents of an order before it is confirmed. Because this operation uses PUT semantics, every field you include overwrites the corresponding value on the existing order – fields you omit are cleared rather than left unchanged. This means you should retrieve the current order first, apply your changes to the full object, and then submit the complete updated payload. Only orders in `PENDING_CONFIRMATION` status are eligible for replacement; attempting to update a Confirmed, Cancelled, or system-managed order returns an error.
PUT semantics apply to the entire order including `line_items`. If you omit `line_items` from the request body, all existing
line items are cleared. Always include the complete set of line items you want to retain.
Changing the `amount` of an order may affect its authorization status. If the new amount exceeds the buyer's available Credit
facility limit, the order may become `NOT_AUTHORIZED`.
## OpenAPI
````yaml PUT /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}:
put:
tags:
- Orders
summary: Replace an order
description: >-
Replaces an order. This is a full-replacement update (PUT semantics):
all required fields must be provided.
Only orders in `PENDING_CONFIRMATION` status can be updated. Line items
are replaced wholesale.
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:
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:
- ordered_at
- payment_method
- payment_term
- amount
additionalProperties: false
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
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
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
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````