# Settlement report fields

What every settlement field means — how settlement_amount adds up, the debt balance, each type and detailed_type, and where the CSV differs from the API.

A settlement report is one payout: a summary of totals and, underneath, one line per
transaction that went into it. This page explains what those fields mean. The same data comes
from three places — the CSV and PDF in the [Kustom Portal](https://portal.kustom.co/), the same
files over SFTP, and the [Settlements API](/api/settlements/) — and they don't spell it
identically:

| | CSV report | Settlements API |
|---|---|---|
| Amounts | Decimals by default, `100.00` | Always integers in minor units, `10000` |
| Summary totals | `total_sale_amount`, `total_fee_amount`, … | `totals.sale_amount`, `totals.fee_amount`, … |
| Debt balance | `opening_debt_balance`, `closing_debt_balance` | `totals.opening_debt_balance_amount`, `totals.closing_debt_balance_amount` |
| Payout currency | `settlement_currency` | `currency_code` |
| A line's currency | `posting_currency` | `currency_code` |
| VAT on Kustom's fee, per line | `tax_rate`, `tax_amount` | `vat_rate`, `vat_amount` |
| The customer's VAT, per line | `tax_rate_1` … `tax_rate_4`, `tax_amount_1` … `tax_amount_4` | `consumer_vat`, on `SALE` lines |

The CSV's format is yours to configure in the Portal: amounts in minor units instead of
decimals, the decimal separator, minus signs on debit columns, and which columns appear at all.
Know which settings your import expects before you change them, and never mix CSV and API
amounts in one calculation — a decimal read as minor units is off by a factor of a hundred, and
nothing will tell you.

## How the settlement amount adds up

The payout is the sales less everything taken off them, plus everything added back. The API's
totals and the CSV's are named alike but don't hold quite the same numbers, so the sum is
written differently for each.

**From the API's `totals`:**

```
settlement_amount = sale_amount
                  − return_amount
                  − reversal_amount
                  − fee_amount − tax_amount        // fees and their VAT, before any refund
                  + fee_correction_amount          // fee refunds, with their VAT
                  − charge_amount
                  + credit_amount
                  − holdback_amount
                  + release_amount
                  − repay_amount
                  + deposit_amount
                  + corrections
```

**From the CSV's summary:**

```
total_settlement_amount = total_sale_amount
                        − total_return_amount
                        − total_reversal_amount
                        − total_fee_amount − total_tax_amount   // already net of fee refunds
                        − total_charge_amount
                        + total_credit_amount
                        − total_holdback_amount
                        + total_release_amount
                        − total_repay_amount
                        + total_deposit_amount
                        + corrections
```

What trips up a recomputation:

- **Fee refunds are counted once.** The API's `fee_amount` and `tax_amount` are before refunds,
  and the refunds come back in `fee_correction_amount`; `tax_refund_amount` is the VAT inside
  that, not something to add again. The CSV's `total_fee_amount` and `total_tax_amount` are
  already net of refunds, and `total_fee_correction_amount` and `total_fee_refund_amount` both
  repeat that refund — add either one and you count it twice.
- **Corrections have no total of their own.** `CREDITED_CORRECTION` and `CORRECTION_DISPUTE`
  lines are part of the payout but appear in no summary field, so sum them from the lines.
- **Some totals are always zero** for Kustom payouts: `commission_amount`, and the API's
  `fee_refund_amount`.
- **`tax_amount` is VAT on Kustom's fees**, not the customer's VAT on your goods.

### When a payout would be negative

If returns, fees and charges in a period come to more than its sales, there is nothing to pay
out, and the shortfall becomes debt you owe Kustom:

- **`deposit_amount`** is that shortfall — the increase in your debt this period. Adding it is
  what brings `settlement_amount` to zero rather than below it.
- **`opening_debt_balance`** is the debt carried in: the closing balance of your previous
  payout in the same currency.
- **`repay_amount`** is how much of that debt this payout paid off — the smaller of the opening
  balance and what the payout would otherwise have been.
- **`closing_debt_balance`** = `opening_debt_balance` − `repay_amount` + `deposit_amount`, and
  becomes the next payout's opening balance.

Checking that each payout's opening balance equals the previous one's closing balance is the
cheapest way to notice a missing payout. Include `DEBT_STATEMENT` payouts in that chain.

## Summary fields

| Field | What it holds |
|---|---|
| `payment_reference` | The payout's unique id. It's on the transfer in your bank statement, and it's the key that joins bank, report and API |
| `payout_date` | When the payout was created. The API gives the full UTC timestamp; the CSV gives the date only |
| `settlement_currency` | You're settled like-for-like in the currency you sold in, so expect one payout per currency |
| `merchant_settlement_type` | How the payout treats Kustom's fees — see below |
| `merchant_id` | Who the payout is for |
| `total_sale_amount` | Captured orders |
| `total_fee_amount` | Kustom's fees on those sales, excluding VAT |
| `total_tax_amount` | VAT on those fees |
| `total_fee_correction_amount` | Fees refunded to you |
| `total_return_amount` | Refunds you registered |
| `total_reversal_amount` | Amounts reversed on disputed orders, in the customer's favor |
| `total_holdback_amount` | Money held back from this payout — see `HOLDBACK` below |
| `total_release_amount` | Held-back money released and paid to you |
| `total_credit_amount`, `total_charge_amount` | Other credits and charges; `detailed_type` on each line says what they are |
| `total_repay_amount`, `total_deposit_amount`, `opening_debt_balance`, `closing_debt_balance` | The debt balance, [above](#when-a-payout-would-be-negative) |

`merchant_settlement_type` takes four values:

| Value | Meaning |
|---|---|
| `NET` | Kustom's fees are deducted from the payout |
| `GROSS` | The payout carries your sales without fees deducted; the fees are settled separately |
| `GROSS_FEE` | That separate settlement: the fees on a `GROSS` account, collected by invoice rather than deducted |
| `DEBT_STATEMENT` | A settlement of debt moved onto a debt statement invoice |

## Transaction fields

| Field | What it holds |
|---|---|
| `type` | What kind of entry this is — see [Transaction types](#transaction-types) |
| `detailed_type` | Why, more precisely — see [Detailed types](#detailed-types) |
| `order_id` | The Kustom order. The recommended key for joining a line to your own order |
| `short_order_id` | The customer-facing order number |
| `capture_id` | The capture behind the line. On a reversal, the capture the dispute was raised on. On a return it's empty in the CSV, while the API puts the refund's id here |
| `refund_id` | The refund behind a `RETURN` line. Each partial refund has its own |
| `reversal_reference` | The dispute behind a `REVERSAL` line |
| `merchant_reference1`, `merchant_reference2` | The references you set when you created the order |
| `merchant_capture_reference`, `merchant_refund_reference` | The references you sent with the capture or refund |
| `amount` | The line's amount |
| `posting_currency` | The currency the order was placed in |
| `capture_date` | When the entry was registered, in UTC. For a `SALE`, when you captured |
| `sale_date` | When the order was created, in UTC |
| `purchase_country` | The order's purchase country, or your own country where the order had none |
| `shipping_address_country` | The country the order shipped to |
| `initial_payment_method_type` | The payment method the customer chose at checkout |
| `initial_payment_method_number_of_installments` | The number of installments chosen at checkout, where there was a plan |
| `tax_rate`, `tax_amount` | VAT on Kustom's fee for this line — not the customer's VAT |
| `tax_rate_1` … `tax_rate_4`, `tax_amount_1` … `tax_amount_4` | The customer's VAT on your goods, one pair per rate, in basis points (`2500` is 25%). Shown only when consumer VAT is turned on in your report settings, and left empty for an order with more than four rates |
| `settlement_merchant_id` | The merchant ID the line was settled under |

Partial captures and partial refunds give one order several lines, so key a line on `order_id`
together with `capture_id` or `refund_id` and `type` — never on `order_id` alone.

## Transaction types

| `type` | Meaning |
|---|---|
| `SALE` | A captured order |
| `FEE` | A Kustom fee. One sale can carry several |
| `FEE_REFUND` | A fee refunded to you |
| `RETURN` | A refund you registered |
| `REVERSAL` | An amount reversed on a disputed order, in the customer's favor |
| `CORRECTION` | A manual correction |
| `HOLDBACK` | Money held back from the payout |
| `RELEASE` | Held-back money paid out to you |
| `CREDIT` | Another credit — see its `detailed_type` |
| `CHARGE` | Another charge — see its `detailed_type` |
| `THIRD_PARTY_FEE` | A fee charged by a third party, reported for information. It isn't part of the payout amount |

## Detailed types

| `type` | `detailed_type` | Meaning |
|---|---|---|
| `SALE` | `PURCHASE` | A captured order |
| `FEE` | `PURCHASE_FEE_FIXED` | The fixed fee on a captured order |
| `FEE` | `PURCHASE_FEE_PERCENTAGE` | The percentage fee on a captured order |
| `FEE` | `AGE_VERIFICATION_FEE_FIXED`, `AGE_VERIFICATION_FEE_PERCENTAGE` | The fee for an age-verified purchase |
| `FEE` | `FX_FEE` | Currency conversion |
| `FEE` | `DISPUTE_FEE` | The fee for a dispute on a captured order |
| `FEE_REFUND` | `DISPUTE_FEE_REFUND` | A dispute fee refunded, because the dispute went your way |
| `FEE_REFUND` | `APPLICATION_FEE_REFUND` | Another fee refunded to you |
| `RETURN` | `PURCHASE_RETURN` | A refund you registered |
| `REVERSAL` | `REVERSAL` | An amount reversed on a disputed order |
| `CORRECTION` | `CREDITED_CORRECTION` | A manual correction |
| `CREDIT` | `CORRECTION_DISPUTE` | A dispute correction credited to you. Counted with the corrections, not in `credit_amount` |
| `CREDIT` | `INVOICE_CREDITED`, `GROSS_FEE_INVOICE_CREDITED`, `DEBT_STATEMENT_INVOICE_CREDITED` | A credit against a Kustom invoice |
| `CREDIT` | `CREDIT` | A general credit, such as a correction, a released negative balance or a rounding adjustment |
| `CHARGE` | `TRANSFER_FROM_LEGACY_INTEGRATION` | Debt moved over from a legacy integration, in place of an invoice |
| `CHARGE` | `CHARGE` | A general charge, such as a correction, debt moved to a debt statement or a rounding adjustment |
| `HOLDBACK`, `RELEASE` | `ROLLING_RESERVE` | A share of funds held as collateral, and released after the agreed period |
| `HOLDBACK`, `RELEASE` | `UNDER_REVIEW` | A hold on all or part of your payouts while Kustom reviews your account and transactions, and its release |
| `HOLDBACK` | `INSUFFICIENT_BANK_ACCOUNT_DETAILS` | Money that couldn't be paid out because your bank details are missing or wrong |
| `THIRD_PARTY_FEE` | `THIRD_PARTY_PURCHASE_FEE` | A third party's fee on a purchase, for information |

**`INSUFFICIENT_BANK_ACCOUNT_DETAILS` is the one that needs you.** Correct your bank details in
the Kustom Portal under **Settings → Bank account details**. The amount stays held until they
are.

**Expect values this table doesn't list, and expect `null`.** The API's enum is larger than
what is booked into Kustom payouts, and new values are added. Some values the CSV prints —
`FX_FEE`, `APPLICATION_FEE_REFUND`, the three `*_INVOICE_CREDITED` values and the bare `CHARGE`
and `CREDIT` — currently arrive from the API as `detailed_type: null`. Store the raw `type` and
`detailed_type` on every line, key your logic on `type`, and send a value you don't recognize
to someone to review instead of failing the import.

## Related

- [Settlements and getting paid](/finance/) — the payout schedule, and reconciling with the API
- [Settlements API reference](/api/settlements/) — every endpoint and field