Skip to main content
GET
Retrieve an invoice
Use this endpoint to fetch the complete, current state of any invoice on your platform. The response includes the invoice’s lifecycle status, the amount financed, the buyer’s repayment due date, the associated order identifiers, and any financial services active on the invoice. This is the primary way to check invoice state after receiving a webhook event or to confirm that a financing capture was successful.
Subscribe to the INVOICE webhook events to be notified when an invoice is created, becomes due, is paid out, or closes – rather than polling this endpoint.

Authorizations

Authorization
string
header
required

Your Tilta API key, sent as Bearer <key>.

Path Parameters

external_id
string
required

Unique identifier of an invoice.

Maximum string length: 100
Pattern: ^[a-zA-Z0-9-_]+$

Query Parameters

expand
enum<string>[] | null

Invoice sub-entities to expand in the response object. Currently supported: buyer, services (more coming soon).

Available options:
buyer,
services
Example:

Response

Invoice is returned.

external_id
string
required

Unique identifier of an invoice.

Maximum string length: 100
Pattern: ^[a-zA-Z0-9-_]+$
buyer_external_id
string
required

Unique identifier of a buyer.

Maximum string length: 100
Pattern: ^[a-zA-Z0-9-_]+$
merchant_external_id
string
required

Unique identifier of a merchant.

Maximum string length: 100
Pattern: ^[a-zA-Z0-9-_]+$
created_at
number
required

Timestamp indicating when the invoice was created (unix time in seconds).

Example:

1582896122

updated_at
number
required

Timestamp indicating the last time the invoice was updated (unix time in seconds).

Example:

1582896122

due_at
number
required

Invoice due date (unix time in seconds).

Example:

1582896122

status
enum<string>
required

The current status of the invoice.

Available options:
OPEN,
DUE,
CLOSED,
CANCELLED
days_past_due
integer | null
required

Days past due. Only available for invoices with status DUE.

payment_method
enum<string>
required

Invoice payment method.

Available options:
CASH,
CARD,
TRANSFER,
DEBIT
invoice_number
string
required

Invoice number or reference.

invoiced_at
number
required

Invoice creation date (unix time in seconds).

Example:

1582896122

amount
object
required
contact
object | null

The buyer contact associated with this invoice (if any).

paid_at
number

Timestamp indicating when the invoice was marked as paid (unix time in seconds).

buyer
object
services
object[]

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
object

Summary of all Credit Notes associated with this invoice.

Example:
order_external_ids
string[]

IDs of related orders.

Maximum string length: 100
Pattern: ^[a-zA-Z0-9-_]+$
line_items
object[]

Order line items.

billing_address
object

Billing address. If it is not provided, this will be filled with the buyer's business address.

delivery_address
object | null

Delivery address. If it is not provided, this will be filled with the buyer's default delivery address when set.

custom_data
object | null

Free-form metadata for storing integration-specific data alongside this invoice.