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:

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

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

Find the payouts.
```
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.
Match the bank credit by the reference on your statement.
```
GET /settlements/v1/payouts/{payment_reference}
```
Pull every line behind it.
```
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 has what every line field holds, including where the API and the CSV differ.

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

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

Settlement report fields — what every field, transaction type and detailed type means
Refund an order — what a refund does to a settlement
Capture an order — the event that starts the payout clock
Order Management — where settlement sits in the lifecycle

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.