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

# Invoices

> Learn how to create invoices to trigger merchant payouts, manage refunds and credit notes, and request financial services on financed receivables.

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.

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

```json theme={null}
{
  "external_id": "invoice_2024_00789",
  "order_external_ids": ["order_2024_00456"],
  "merchant_external_id": "merchant_abc123",
  "buyer_external_id": "buyer_de_001",
  "amount": {
    "net": 100000,
    "gross": 119000,
    "tax": 19000,
    "currency": "EUR"
  },
  "payment_method": "TRANSFER",
  "invoice_number": "RE-2024-789",
  "invoiced_at": 1717545600,
  "due_at": 1720137600,
  "line_items": [
    {
      "name": "Industrial pump model X200",
      "category": "Pumps",
      "description": "Industrial pump, 2 units",
      "quantity": 2,
      "price": 50000,
      "currency": "EUR"
    }
  ],
  "delivery_address": {
    "street": "Kaufstraße 12",
    "city": "Munich",
    "postcode": "80331",
    "country": "DE"
  }
}
```

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

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.

| Status      | Meaning                                                         |
| ----------- | --------------------------------------------------------------- |
| `OPEN`      | The invoice is live and the buyer's repayment period is running |
| `DUE`       | The repayment date has passed and the invoice is outstanding    |
| `CLOSED`    | The invoice has been settled                                    |
| `CANCELLED` | The invoice was cancelled                                       |

***

## Retrieving and listing invoices

Fetch a single invoice by its `external_id`:

```http theme={null}
GET /v1/invoices/{external_id}
Authorization: Bearer YOUR_API_KEY
```

List all invoices for your platform, with optional filters for date range, status, and buyer:

```http theme={null}
GET /v1/invoices?buyer_external_id=buyer_de_001&status=ACTIVE
Authorization: Bearer YOUR_API_KEY
```

Export invoices as a CSV file for accounting or reconciliation:

```http theme={null}
GET /v1/invoices/export/csv?from=2024-01-01&to=2024-06-30
Authorization: Bearer YOUR_API_KEY
```

***

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

```http theme={null}
PUT /v1/invoices/{external_id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json theme={null}
{
  "amount": {
    "net": 95000,
    "gross": 113050,
    "tax": 18050,
    "currency": "EUR"
  },
  "invoice_number": "RE-2024-789-REV"
}
```

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

***

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

| Reason                                         | Partial refund allowed? | Timeline            |
| ---------------------------------------------- | ----------------------- | ------------------- |
| Buyer withdrawal or right of rescission        | ✅ Yes                   | Without undue delay |
| Invoice changed (discount or price adjustment) | ✅ Yes                   | Without undue delay |
| Buyer details changed                          | ❌ No – full refund only | Without undue delay |
| Unauthorized purchase or fraud                 | ❌ No – full refund only | Without undue delay |
| Other                                          | ❌ No – full refund only | Without undue delay |

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:

```http theme={null}
POST /v1/invoices/{external_id}/refund
Authorization: Bearer YOUR_API_KEY
```

To reduce an invoice by part of its value rather than reversing it, issue a credit note instead:

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

```json theme={null}
{
  "external_id": "credit_note_2024_00012",
  "invoice_external_id": "invoice_2024_00789",
  "amount": {
    "net": 10000,
    "gross": 11900,
    "tax": 1900,
    "currency": "EUR"
  },
  "invoiced_at": 1720137600
}
```

### Payout impact

The timing of the refund relative to payout affects how Tilta settles with the merchant:

| Refund timing              | Effect on merchant payout                                                   |
| -------------------------- | --------------------------------------------------------------------------- |
| Before payout is processed | Payout is cancelled or adjusted to the reduced invoice amount               |
| After payout has been made | Payout is reversed and the amount is offset against future merchant payouts |

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

***

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

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

```json theme={null}
{
  "invoice_external_id": "invoice_2024_00789",
  "service_type": "FACTORING"
}
```

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

***

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

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

```json theme={null}
{
  "amount": {
    "net": 100000,
    "gross": 119000,
    "tax": 19000,
    "currency": "EUR"
  },
  "payment_term": "DEFER_30D",
  "buyer_external_id": "buyer_de_001",
  "merchant_external_id": "merchant_abc123"
}
```

See the [Fee Configuration guide](/docs/fee-configuration) 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:

```http theme={null}
POST /v1/invoices/{external_id}/files
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data
```

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:

```http theme={null}
POST /v1/invoices/{external_id}/paid
Authorization: Bearer YOUR_API_KEY
```

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.

<Warning>
  Only use this endpoint when instructed by Tilta. Incorrectly marking an invoice as paid will affect merchant payout reconciliation and buyer credit facility accounting.
</Warning>

***

## API reference summary

| Endpoint                            | Method | Purpose                                   |
| ----------------------------------- | ------ | ----------------------------------------- |
| `/v1/invoices`                      | `POST` | Create an invoice (capture)               |
| `/v1/invoices/{external_id}`        | `GET`  | Retrieve a single invoice                 |
| `/v1/invoices`                      | `GET`  | List invoices with filters                |
| `/v1/invoices/{external_id}`        | `PUT`  | Update invoice (before services active)   |
| `/v1/invoices/{external_id}/refund` | `POST` | Refund an invoice                         |
| `/v1/invoices/{external_id}/files`  | `POST` | Upload invoice document                   |
| `/v1/invoices/{external_id}/paid`   | `POST` | Mark invoice as paid                      |
| `/v1/invoices/calculate_fees`       | `POST` | Preview fees before capture               |
| `/v1/invoices/export/csv`           | `GET`  | Export invoices as CSV                    |
| `/v1/services`                      | `POST` | Request a financial service on an invoice |