> ## 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.

# Order handling

> Complete guide to Tilta's order lifecycle – from authorization holds at checkout through invoice capture, cancellations, refunds, and dispute resolution.

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**.

<Steps>
  <Step title="Order authorization">
    Create the order and request authorization against the buyer's credit facility. Authorization performs two functions simultaneously:

    1. **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.
    2. **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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

***

## 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](/api-reference/orders/transition-order). `DRAFT`, `EXPIRED`, `DISBURSED`, and `CLOSED` are managed by Tilta and cannot be requested.

<Note>
  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.
</Note>

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

***

## 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.

```http theme={null}
POST /v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json theme={null}
{
  "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"
  }
}
```

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

### Draft orders

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

1. Create a draft order via `POST /v1/orders/draft` with the basket contents.
2. Create a checkout session via `POST /v1/orders/{external_id}/sessions/checkout`, which returns a hosted checkout URL.
3. 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.

<Tip>
  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.
</Tip>

***

## Invoice capture

When the merchant ships or fulfils the order, capture the invoice via `POST /v1/invoices`. See the [invoices guide](/docs/invoices) 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.

<Warning>
  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.
</Warning>

***

## 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.

```http theme={null}
POST /v1/orders/{external_id}/transition
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json theme={null}
{
  "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](/docs/invoices) 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     |

<Info>
  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.
</Info>

***

## 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.

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

### 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.                                    |

<Warning>
  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.
</Warning>

***

## 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                                  |