> ## 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 invoices
> Search invoices using filters like buyer_external_id or external_id. Efficiently retrieve targeted invoice subsets without full list pagination.
The search endpoint matches a single free-text `query` against your invoices. Use it when you have a fragment of an invoice number or a buyer's name and need to find the matching records quickly.
For structured filtering – by buyer, merchant, status, due date, or days past due – use [List
invoices](/api-reference/invoices/list-invoices), which accepts a dedicated query parameter per field and combines them as AND
conditions.
## OpenAPI
````yaml GET /v1/invoices/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/invoices/search:
get:
tags:
- Invoices
summary: Search invoices
description: Searches for invoices.
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
- services
description: >-
Invoice sub-entities to expand in the response object. Currently
supported: buyer, services (more coming soon).
example:
- buyer
- services
required: false
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 invoice.
buyer_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a buyer.
merchant_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a merchant.
created_at:
type: number
description: >-
Timestamp indicating when the invoice was created
(unix time in seconds).
example: 1582896122
updated_at:
type: number
description: >-
Timestamp indicating the last time the invoice was
updated (unix time in seconds).
example: 1582896122
due_at:
type: number
description: Invoice due date (unix time in seconds).
example: 1582896122
status:
type: string
enum:
- OPEN
- DUE
- CLOSED
- CANCELLED
description: The current status of the invoice.
days_past_due:
type: integer
nullable: true
description: >-
Days past due. Only available for invoices with
status DUE.
contact:
type: object
nullable: true
properties:
external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a contact.
buyer_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: >-
External identifier of the buyer this contact
belongs to.
salutation:
type: string
nullable: true
enum:
- MR
- MS
- OTHER
description: Contact salutation.
first_name:
type: string
nullable: true
description: Contact first name.
last_name:
type: string
nullable: true
description: Contact last name.
email:
type: string
nullable: true
format: email
description: Contact email.
phone:
type: string
nullable: true
description: >-
Contact phone number in E.164 format (e.g.
+491711010101).
example: '+491711010101'
assign_to_all_invoices:
type: boolean
description: >-
Whether this contact should automatically be
assigned to all invoices created for the buyer.
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: Contact's address.
created_at:
type: number
description: >-
Timestamp indicating when the contact was
created (unix time in seconds).
example: 1582896122
updated_at:
type: number
description: >-
Timestamp indicating the last time the contact
was updated (unix time in seconds).
example: 1582896122
required:
- external_id
- buyer_external_id
- assign_to_all_invoices
- created_at
- updated_at
additionalProperties: false
description: >-
The buyer contact associated with this invoice (if
any).
paid_at:
type: number
description: >-
Timestamp indicating when the invoice was marked as
paid (unix time in seconds).
payment_method:
type: string
enum:
- CASH
- CARD
- TRANSFER
- DEBIT
description: Invoice payment method.
buyer:
type: object
properties:
legal_name:
type: string
services:
type: array
items:
type: object
properties:
external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
invoice_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
service_type:
type: string
enum:
- FINANCING
- INSURANCE
- COLLECTION
status:
type: string
enum:
- IN_REVIEW
- ACCEPTED
- REJECTED
- CANCELLED
- PAID_OUT
- SETTLED
- DEFAULTED
- CLAIM_NOTIFIED
- CLAIM_IN_ASSESSMENT
- CLAIM_PAID
- CLAIM_DENIED
- COVER_EXPIRED
- EARLY_COLLECTION
- LATE_COLLECTION
- COLLECTED
- UNCOLLECTIBLE
created_at:
type: number
updated_at:
type: number
requirements:
type: array
items:
type: object
properties:
code:
type: string
enum:
- INVOICE_INELIGIBLE
- FACILITY_MISSING
- MERCHANT_NOT_ENROLLED
- FACILITY_CURRENCY_CONFLICT
- FACILITY_EXCEEDED_AVAILABLE_AMOUNT
- FACILITY_EXPIRED
- >-
INVOICE_DUE_DATE_BIGGER_FACILITY_EXP_DATE
- FROZEN_FACILITY
- NO_ACTIVE_MANDATE
- INVOICE_CURRENCY_NOT_SUPPORTED
- INVOICE_PAYMENT_TERM_EXCEEDED
- INVOICE_ISSUE_DATE_TOO_OLD
- NO_INVOICE_FILE_FOUND
- BUYER_CONTACT_REQUIRED
- INVOICE_FILE_DATA_MISMATCH
description:
type: string
required:
- code
- description
advance:
type: object
properties:
value:
type: integer
description: >-
Amount actually transferred to the
merchant after fee deduction, in the
smallest currency unit (e.g. cents).
required:
- value
description: >-
Advance amount paid out to the merchant for
this invoice. Each invoice receives its own
SEPA transfer (or N transfers when split above
100K), with the invoice number leading the
remittance information for `startsWith`
reconciliation.
fee:
type: object
properties:
gross:
type: integer
net:
type: integer
tax:
type: integer
required:
- gross
- net
- tax
description: >-
Fees applied to this invoice, in the smallest
currency unit. `gross = net + tax`.
required:
- external_id
- invoice_external_id
- service_type
- status
- created_at
- updated_at
description: >-
Invoice services with their current status. Returned
only when `expand` includes `services`. Ordered
oldest first; a service type may appear more than
once after a resubmission.
credit_note_summary:
type: object
properties:
count:
type: integer
minimum: 1
amount:
type: object
properties:
gross:
type: integer
minimum: 0
net:
type: integer
minimum: 0
tax:
type: integer
nullable: true
minimum: 0
currency:
type: string
enum:
- EUR
- GBP
- USD
- CHF
- PLN
- CZK
- RON
- BGN
- DKK
- HUF
- SEK
- NOK
- JPY
- AUD
- NZD
- CAD
required:
- gross
- net
- tax
- currency
additionalProperties: false
original_invoice_amount:
type: object
properties:
gross:
type: integer
minimum: 0
net:
type: integer
minimum: 0
tax:
type: integer
nullable: true
minimum: 0
currency:
type: string
enum:
- EUR
- GBP
- USD
- CHF
- PLN
- CZK
- RON
- BGN
- DKK
- HUF
- SEK
- NOK
- JPY
- AUD
- NZD
- CAD
required:
- gross
- net
- tax
- currency
additionalProperties: false
has_active_mandate:
type: boolean
financing_status:
type: string
nullable: true
enum:
- IN_REVIEW
- ACCEPTED
- REJECTED
- CANCELLED
- PAID_OUT
- SETTLED
- DEFAULTED
- CLAIM_NOTIFIED
- CLAIM_IN_ASSESSMENT
- CLAIM_PAID
- CLAIM_DENIED
- COVER_EXPIRED
- EARLY_COLLECTION
- LATE_COLLECTION
- COLLECTED
- UNCOLLECTIBLE
required:
- count
- amount
- original_invoice_amount
- has_active_mandate
- financing_status
additionalProperties: false
description: >-
Summary of all Credit Notes associated with this
invoice.
example:
count: 2
amount:
gross: 1000
net: 800
tax: 200
currency: EUR
original_invoice_amount:
gross: 5000
net: 4000
tax: 1000
currency: EUR
has_active_mandate: true
financing_status: IN_REVIEW
order_external_ids:
type: array
items:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
default: []
description: IDs of related orders.
invoice_number:
type: string
description: Invoice number or reference.
invoiced_at:
type: number
description: Invoice creation date (unix time in seconds).
example: 1582896122
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
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.
billing_address:
type: object
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: >-
Billing address. If it is not provided, this will be
filled with the buyer's business address.
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 address. If it is not provided, this will
be filled with the buyer's default delivery address
when set.
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 invoice.
required:
- external_id
- buyer_external_id
- merchant_external_id
- created_at
- updated_at
- due_at
- status
- days_past_due
- payment_method
- invoice_number
- invoiced_at
- amount
required:
- limit
- offset
- total
- items
additionalProperties: false
description: A list of invoices.
'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 `.
````