# Settlements and getting paid

How captured orders become money in your bank account — the payout schedule and delay, the settlement reports, and reconciling payouts with the Settlements API.

Capturing an order doesn't put money in your bank account that day. Kustom pays out on a
schedule set in your contract, after a deliberate delay, and sends a settlement report for
every payout so you can reconcile it against your orders. This page explains that timing
and where the reports come from. It assumes you've captured at least one order.

## Payout schedule and payout delay

Two numbers govern when you get paid, and both are in your contract — also visible in the
Settlements app in the [Kustom Portal](https://portal.kustom.co/):

- **Payout schedule** — how often payouts run, for example weekly on Wednesdays.
- **Payout delay** — how long a captured order waits before it's eligible for the next
  payout.

They compose, and the result surprises people the first time. With weekly Wednesday
payouts and a one-week delay, an order captured on Friday does *not* settle on the
Wednesday four days later. It waits for the Wednesday after that. You receive the
settlement report the following day, the money leaves Kustom's account that same day, and
it lands in yours over the next few days.

The delay isn't Kustom holding your money for its own sake. It exists so that a return
registered shortly after a sale nets off inside one settlement, instead of money moving to
you and then back again for the same invoice.

## The cut-off is midnight UTC

The day boundary that decides which payout an order falls into is midnight UTC, all year
round — not your local midnight. In Central European time that's 01:00 in winter and 02:00 in
summer, so an order captured just after midnight local time still counts toward the previous
day.

## Reconciling a payout

Each payout has a unique **payment reference**, and that reference appears on your bank
statement. It's the join key: match the reference on the statement to the settlement
report carrying the same one, and the report itemizes the orders that make up the amount.

Reports come in three formats, and they are for different jobs:

| Format | Use it for |
|---|---|
| CSV | Order-level reconciliation — one row per transaction |
| PDF | A summary, and a VAT invoice for tax reporting in the EU, Australia and Canada |
| JSON | Programmatic reconciliation via the Settlements API |

A dispute — a customer's bank reversing a payment — appears on the settlement report as its own
transaction type rather than as a change to the original order. Disputes are handled in the
[Kustom Portal](https://portal.kustom.co/) today. There's no API for them yet.

If your accounting system wants a particular shape, the CSV is configurable in the Portal:
add or remove columns, change the delimiter and set the date and amount formats. What every
column means, and how the totals add up to the payout, is in
[Settlement report fields](/finance/settlement-report-fields/).

## Getting the reports automatically

Downloading from the Portal by hand is fine at low volume. Above that, there are two
automated routes:

- **Settlements API** — the preferred route at volume. Requires technical setup.
- **SFTP** — Kustom drops the CSV and PDF into a pre-configured location. Ask
  [support@kustom.co](mailto:support@kustom.co) to enable it.

Both deliver the same reports as the Portal, so you can start manual and move over without
changing how you reconcile.

## Reconciling with the Settlements API

The API serves the same reports as data, from `https://api.kustom.co/settlements/v1`, with the
same [API credentials](/api/authentication/) as every other Kustom API. It knows about a payout
before your bank shows the money, so a payout with no bank credit yet isn't missing. Reconcile from the bank statement inward: the payout first, then its lines.

1. **Find the payouts.**

   ```http
   GET /settlements/v1/payouts?start_date=2026-09-01T00:00:00Z&end_date=2026-09-07T23:59:59Z&size=500
   ```

   Send full UTC date-times. A bare date means midnight UTC, so `end_date=2026-09-07` stops at
   the start of the 7th and leaves that day's payouts out — the one exception is a start and end
   that are identical, which is widened to the whole day. Pages default to 20 results; ask for
   up to 500, as anything larger is quietly capped there, and follow `pagination.next` until it's
   `null`. Let each run's window overlap the last one and upsert on `payment_reference`, so
   running twice never books a payout twice. Without `currency_code` you get every currency, one
   payout per currency.

   The list includes payouts still pending at the payment provider and payouts that failed
   there, not only settled ones. Reading one payout tells you which in its
   `K-Settlement-Status` response header.

2. **Match the bank credit** by the reference on your statement.

   ```http
   GET /settlements/v1/payouts/{payment_reference}
   ```

3. **Pull every line behind it.**

   ```http
   GET /settlements/v1/transactions?payment_reference={payment_reference}&size=500
   ```

   Upsert lines on `order_id` with `capture_id` or `refund_id`, and `type`. Partial shipments
   and partial refunds put several lines on one order, so `order_id` alone collides.
   [Settlement report fields](/finance/settlement-report-fields/) has what every line field
   holds, including where the API and the CSV differ.

4. **Archive the PDF**, the VAT invoice, against the payout.

   ```http
   GET /settlements/v1/reports/payout?payment_reference={payment_reference}
   ```

Then check the payout before you book it:

- **Amounts are integers in minor units.** The CSV report uses decimals. Convert once, at the
  edge of your accounting system, and never mix the two.
- **Recompute `totals.settlement_amount`** from the other totals — the
  [formula](/finance/settlement-report-fields/#how-the-settlement-amount-adds-up) — and again
  from the summed lines, and check that each payout's opening debt balance equals the previous
  one's closing balance. A mismatch is the most useful alert a settlement job can raise.
- **Read `merchant_settlement_type` on every payout.** `NET` means Kustom's fees are already
  deducted; `GROSS` means they're settled separately, in a `GROSS_FEE` settlement collected by
  invoice. They're booked differently.
- **Store unknown `type` and `detailed_type` values** as they came, and send them for review.
  New values appear, some lines carry `detailed_type: null`, and the import shouldn't stop on
  either.
- **Keep the `correlation_id`** from any error response. It's what support asks for.

The references you set earlier are what make this automatic: `merchant_reference1` from order
creation and your capture and refund references come back on every line, so each one joins to
an order, a shipment and a refund in your own system.

## Related

- [Settlement report fields](/finance/settlement-report-fields/) — what every field, transaction type and detailed type means

- [Refund an order](/order-management/refunds/) — what a refund does to a settlement
- [Capture an order](/order-management/capture/) — the event that starts the payout clock
- [Order Management](/order-management/) — where settlement sits in the lifecycle