Order handling

An order in Tilta represents a buyer’s purchase intent and acts as the anchor for the entire financing lifecycle. Before a buyer can receive deferred payment terms, the order must be authorized against their credit facility. Only after an invoice is captured against that order does the financing become legally effective and merchant payout scheduled. Understanding each stage of this lifecycle is critical to a correct integration.

Order lifecycle overview

Every order moves through a defined set of states from creation to final settlement. The three core steps you are responsible for are: authorization, invoice capture, and (if needed) cancellation or refund.

Order authorization

Create the order and request authorization against the buyer’s credit facility. Authorization performs two functions simultaneously:

Eligibility check – confirms the buyer has a sufficient credit facility to cover the order, allowing you to show or hide the payment option at checkout.
Authorization hold – reserves the order amount on the credit facility, preventing the buyer from over-committing in simultaneous or parallel orders.

A successfully authorized order enters the PENDING_CONFIRMATION state.

Invoice capture

Once the merchant fulfils the order, create an invoice against it. Invoice capture is the legally effective financing step – it:

Triggers Tilta’s financing of the receivable
Schedules the merchant payout
Starts the buyer’s repayment clock based on the selected payment terms

The order transitions to CONFIRMED when an invoice is successfully captured.

Buyer repayment

Tilta manages buyer repayment directly. You and the merchant have no involvement in this step. Tilta sends automated reminders and handles collections. When the buyer repays in full, the order moves to CLOSED.

Order states

The table below describes every possible order state, how it is reached, and what transitions are available from it.

State	Description	Reached by	Transitions you can request
`DRAFT`	Pre-checkout order, not yet authorized	Creating a draft order	– (system-managed)
`PENDING_CONFIRMATION`	Authorized, awaiting invoice	Creating an order, or a buyer completing checkout	→ `CONFIRMED`, `CANCELLED`
`CONFIRMED`	Order confirmed; ready to be invoiced	Confirming the order, or capturing an invoice against it	→ `CANCELLED`
`CANCELLED`	Cancelled by you	Explicit transition	→ `PENDING_CONFIRMATION`, `CONFIRMED`
`EXPIRED`	No invoice created within the allowed time	Time limit exceeded	– (system-managed)
`DISBURSED`	Order total paid out to the merchant	Tilta payout processing	– (system-managed)
`CLOSED`	Buyer has repaid in full	Full buyer repayment	– (system-managed)

Only PENDING_CONFIRMATION, CONFIRMED, and CANCELLED can be set through Transition an order. DRAFT, EXPIRED, DISBURSED, and CLOSED are managed by Tilta and cannot be requested.

Cancelling is reversible: a CANCELLED order can be transitioned back to PENDING_CONFIRMATION or CONFIRMED. Re-confirming re-runs the authorization check, so it can fail if the buyer’s available credit has fallen in the meantime.

Once an invoice has been captured against an order, cancelling the order does not reverse the financing. Refund the invoice instead.

Creating an order

Submit a new order using the POST /v1/orders endpoint. Every order must reference a buyer with an active credit facility and specify the payment term the buyer has selected.

POST /v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "external_id": "order_2024_00456",
  "buyer_external_id": "buyer_de_001",
  "merchant_external_id": "merchant_abc123",
  "amount": {
    "net": 100000,
    "gross": 119000,
    "tax": 19000,
    "currency": "EUR"
  },
  "payment_term": "DEFER_30D",
  "ordered_at": "2024-06-01T09:00:00Z",
  "delivery_address": {
    "street": "Kaufstraße 12",
    "city": "Munich",
    "postcode": "80331",
    "country": "DE"
  }
}

All monetary values are in the smallest currency unit (euro cents). An order worth €1,000.00 net is submitted as 100000.

Draft orders

For redirect-based checkouts where the final payment term is not known until the buyer selects it, use the draft order flow:

Create a draft order via POST /v1/orders/draft with the basket contents.
Create a checkout session via POST /v1/orders/{external_id}/sessions/checkout, which returns a hosted checkout URL.
Redirect the buyer to the checkout URL. Tilta presents available payment terms and handles authorization.

The draft order enters DRAFT state and only transitions to PENDING_CONFIRMATION once the buyer completes the hosted checkout.

Order authorization at checkout

Use the authorization step as your signal to show or hide the Tilta payment option at checkout. Before presenting “Pay Later” as an option, call POST /v1/orders (or check the buyer’s available credit via their facility). If authorization succeeds, surface the payment term selector. If it fails – for example because the buyer’s facility is exhausted or inactive – do not show the option.

Perform the eligibility check server-side and cache the result for the duration of the checkout session. Avoid repeatedly hitting the authorization endpoint for the same basket, as each call places a temporary hold.

Invoice capture

When the merchant ships or fulfils the order, capture the invoice via POST /v1/invoices. See the invoices guide for full details on the invoice object. Amount differences between order and invoice are permitted within a small tolerance – for example, if a line item was out of stock. However, if the invoice amount differs from the authorized order amount, you must update the order amount first via POST /v1/orders/{external_id}/transition before creating the invoice.

Always update the order amount in Tilta before capturing the invoice if the invoiced amount differs from the original order. Attempting to create an invoice with a higher amount than the authorized order will return a validation error.

Order cancellation

You can cancel an order at any point after authorization but before an invoice is created. Cancellation is initiated by the merchant (or you, on the merchant’s behalf) – buyers do not cancel orders directly.

POST /v1/orders/{external_id}/transition
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "status": "CANCELLED"
}

Cancellation releases the authorization hold on the buyer’s credit facility, restoring the reserved amount for future orders. If the order has already been invoiced, submit a Refund on the invoice instead. See the invoices guide for refund instructions.

Automated buyer emails

Tilta sends the following transactional emails to the buyer automatically. You do not need to send these yourself.

Trigger	Email sent
Successful order authorization	Order confirmation
Successful buyer repayment	Payment confirmation
3 days before repayment due date	Payment reminder

These emails are sent from Tilta’s infrastructure using your platform’s white-label branding configuration. Contact your integration manager to configure the sender name, logo, and colour scheme.

Dispute resolution

When a buyer challenges an invoice – for example, because goods were not delivered or were defective – they initiate a dispute via a dedicated web form linked in their email communications from Tilta.

Unauthorized purchase / fraud

The buyer claims the purchase was made without their authorisation. This is the most time-sensitive dispute type.

The merchant must respond within 48 hours of the dispute being raised.
If the merchant cannot demonstrate the buyer’s authorisation, Tilta treats the invoice as defective and the financing obligation is reversed.
Tilta may pause merchant payouts during investigation.

Goods not delivered

The buyer claims the ordered goods or services were never received.

The merchant must respond within 5 Bank business Days with proof of delivery (tracking number, signed delivery receipt, etc.).
The merchant and buyer have 14 calendar days to resolve the dispute bilaterally from the date it was raised.
If no resolution is reached within 14 days, Tilta escalates to arbitration.

Goods defective or not as described

The buyer claims the goods received do not match the order description or arrived in a defective state.

The merchant must respond within 5 Bank business Days.
Supporting evidence such as product specifications, photographs, or quality certifications strengthens the merchant’s position.
After 14 days without bilateral resolution, Tilta escalates to arbitration.

Invoice amount incorrect

The buyer disputes the invoice amount – for example, because an agreed discount was not applied.

The merchant must respond within 5 Bank business Days.
If the merchant agrees the amount is wrong, submit a partial Refund to correct the discrepancy.
If disputed, Tilta reviews the evidence and issues an arbitration decision.

Other reasons

For any dispute not covered by the specific categories above, the standard timeline applies:

Merchant responds within 5 Bank business Days.
14-day bilateral resolution window.
Tilta escalates to arbitration if unresolved.

Arbitration outcomes

After Tilta escalates a dispute to arbitration, one of two outcomes is possible:

Outcome	Meaning
Decision against merchant	The invoice is considered defective. Tilta reverses the financing. Any payout already made will be offset against future merchant payouts.
Decision in favour of merchant	The dispute is rejected. The buyer’s payment obligation stands. Tilta resumes normal payout processing.

Tilta may pause all pending merchant payouts during an active arbitration, not just those related to the disputed invoice. Ensure your merchants are aware of this possibility and that your support team is prepared to respond quickly to dispute notifications.

API reference summary

Endpoint	Method	Purpose
`/v1/orders`	`POST`	Create and authorize an order
`/v1/orders/{external_id}`	`GET`	Retrieve an order by external ID
`/v1/orders/draft`	`POST`	Create a draft order for redirect checkout
`/v1/orders/{external_id}/sessions/checkout`	`POST`	Create a hosted checkout session for a draft order
`/v1/orders/{external_id}/transition`	`POST`	Transition order status (e.g., cancel)
`/v1/invoices`	`POST`	Create an invoice (capture)
`/v1/invoices/{external_id}/refund`	`POST`	Refund an invoice

Get Started

Integration

Onboarding

Orders & Payments

Notifications & Communication

Platform & Reference

Order handling

Order lifecycle overview

Order states

Creating an order

Draft orders

Order authorization at checkout

Invoice capture

Order cancellation

Automated buyer emails

Dispute resolution

Arbitration outcomes

API reference summary

​Order lifecycle overview

​Order states

​Creating an order

​Draft orders

​Order authorization at checkout

​Invoice capture

​Order cancellation

​Automated buyer emails

​Dispute resolution

​Arbitration outcomes

​API reference summary

Order lifecycle overview

Order states

Creating an order

Draft orders

Order authorization at checkout

Invoice capture

Order cancellation

Automated buyer emails

Dispute resolution

Arbitration outcomes

API reference summary