Skip to main content
An invoice in Tilta is the legally effective step that transforms an authorized order into a financed receivable. The moment you capture an invoice, Tilta schedules the merchant payout and starts the buyer’s repayment clock. Everything before invoice capture – order creation, authorization, amount adjustments – is preparatory. The invoice is where the financing contract takes effect.

Invoice and order relationship

Tilta supports flexible mappings between orders and invoices to accommodate real-world fulfilment scenarios:
  • One invoice covers multiple orders – useful for consolidated billing where a merchant ships multiple orders in a single delivery and issues one invoice to the buyer.
  • Multiple invoices for one order – useful for partial fulfilment, where goods ship in stages and each shipment triggers a separate invoice.
In both cases, the total financed amount is the sum of all invoice amounts tied to the underlying orders. Each invoice is independently financed and generates its own payout schedule.

Creating an invoice

Capture an invoice by calling POST /v1/invoices after the merchant has fulfilled the order. The invoice amount does not need to exactly match the order amount – minor differences are permitted – but if the invoice amount differs materially, update the order amount in Tilta first before creating the invoice.
All monetary values are in the smallest currency unit (euro cents), so an invoice for €1,190.00 gross is submitted as 119000. Dates are unix timestamps in seconds, not ISO strings.
A successful response includes the invoice object with a status of OPEN. Every order referenced by the invoice is transitioned to CONFIRMED as part of the creation.

Retrieving and listing invoices

Fetch a single invoice by its external_id:
List all invoices for your platform, with optional filters for date range, status, and buyer:
Export invoices as a CSV file for accounting or reconciliation:

Updating an invoice

You can update an invoice after creation, but only while Tilta’s financial services are not yet active. Once services have been activated on an invoice (i.e., financing is underway), the invoice becomes immutable.
Attempting to update an invoice after its associated services are active will return a 409 Conflict error. If you need to correct the amount after services are active, use the Refund endpoint instead.

Refunds

Submit a Refund when you need to reverse or partially reduce an invoice after it has been captured. Refunds are triggered by the merchant (or you on their behalf) – not by the buyer.

Refund reasons and rules

Partial refunds are permitted for price adjustments and buyer-initiated withdrawals. All other reasons require a full refund of the invoice amount.

Submitting a refund

A refund reverses the invoice in full and takes no request body:
To reduce an invoice by part of its value rather than reversing it, issue a credit note instead:
See Credit notes for how Tilta applies the credit note to the invoice.

Payout impact

The timing of the refund relative to payout affects how Tilta settles with the merchant:
Tilta handles buyer-facing adjustments automatically when a refund is processed. The buyer’s repayment obligation is reduced by the refunded amount and any associated fees.

Credit notes

A credit note reduces the outstanding amount of an existing invoice – for example, as goodwill compensation for a delivery delay or a price adjustment agreed after invoicing. The merchant issues the credit note, and you submit it to Tilta with POST /v1/credit_notes, referencing the invoice in invoice_external_id. Tilta applies the credit note to that invoice only:
  • The invoice’s outstanding amount is reduced by the credit note’s gross amount. Tilta derives the tax portion proportionally from the invoice.
  • If the credit note covers the remaining outstanding amount or more, Tilta closes the invoice.
  • A credit note never carries over to other or future invoices.
You cannot issue a credit note while financing on the invoice is IN_REVIEW or ACCEPTED, after financing is SETTLED or DEFAULTED, or once the invoice is closed or cancelled. Credit notes remain allowed when financing is PAID_OUT. Each credit note external_id must be unique within your Tilta account. Submitting an external_id that is already in use returns 409 Conflict and leaves the invoice unchanged.

Invoice services

Services are the products Tilta applies to a captured invoice. Each service has a service_type: Creating an invoice does not request a service on its own. Request one explicitly via POST /v1/services:
The external_id identifies the service, not the invoice. Each service external_id must be unique within your Tilta account, so generate a new one for every service you request. Two different errors can reject the request, and Tilta checks them in this order: Neither error creates a service.
Before you request a service, call GET /v1/invoices/{external_id}/services/{service_type}/requirements to check that the invoice meets every prerequisite.

Calculating fees before capture

Before capturing an invoice, use the fee calculation endpoint to preview the buyer and merchant fees that will apply. This is useful for displaying accurate total costs at checkout or in merchant dashboards.
See the Fee Configuration guide for a detailed explanation of fee structures and worked examples.

Uploading invoice documents

Attach a PDF of the original invoice document for compliance and record-keeping purposes:
Accepted file types are application/pdf. The uploaded document is stored by Tilta and can be retrieved on request.

Marking an invoice as paid

In cases where the buyer repays through a channel that Tilta does not automatically detect (rare in standard integrations), you can manually mark an invoice as paid:
The endpoint takes no request body. Tilta records the repayment against the invoice and releases the financed amount back to the buyer’s credit facility.
Only use this endpoint when instructed by Tilta. Incorrectly marking an invoice as paid will affect merchant payout reconciliation and buyer credit facility accounting.

API reference summary