> ## 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.
# Search orders
> Search for orders using filters such as buyer_external_id or external_id. Returns matching orders without requiring full list pagination.
The search endpoint matches a single free-text `query` against your orders. Use it to locate an order when you only know part of its identifier, or to build a search box in your platform dashboard.
For paging through every order rather than searching for a specific one, use [List orders](/api-reference/orders/list-orders).
## OpenAPI
````yaml GET /v1/orders/search
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/search:
get:
tags:
- Orders
summary: Search orders
description: Search for 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
minLength: 1
default: ''
required: true
name: query
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
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 `.
````