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:

​
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

Credit Notes are issued by the merchant to the buyer as a discount or credit to be applied against a future order – for example, as goodwill compensation for a delivery delay or a volume rebate. Unlike refunds, Credit Notes do not reverse an existing invoice. Instead, they create a credit balance for the buyer that reduces the amount due on their next invoice. Credit Notes are created and managed by the merchant.

​
Invoice services

Services represent financial products (such as factoring or receivables financing) that Tilta applies to an invoice. Requesting a Service is what activates the financing on a captured invoice and triggers the payout schedule. Request a Service via POST /v1/services:
In most standard integrations, Tilta automatically applies the appropriate service when an invoice is created with valid payment terms. You only need to call POST /v1/services directly if your integration uses a deferred service activation model. Check with your integration manager if you are unsure.

​
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