Settlement report fields
What every settlement field means — how settlement_amount adds up, the debt balance, each type and detailed_type — plus sample CSV reports to download.
A settlement report covers one payout: a summary of totals, then one line per transaction. You get it as CSV or PDF from the Kustom Portal, over SFTP, or from the Settlements API. The CSV and the API name things differently:
| CSV report | Settlements API | |
|---|---|---|
| Amounts | Decimals by default, 100.00 | 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 |
You set the CSV’s format in the Portal: minor units or decimals, the decimal separator, minus signs and which columns appear. Never mix CSV and API amounts in one calculation. A decimal read as minor units is off by a factor of 100, and nothing warns you.
How the settlement amount adds up
Section titled “How the settlement amount adds up”The API and the CSV name their totals alike, but the numbers differ slightly, so the formulas do too.
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 + correctionsFrom 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 + correctionsWatch for:
- Fee refunds count once. In the API,
fee_amountandtax_amountare before refunds, andfee_correction_amountholds the refunds with their VAT, so don’t addtax_refund_amounttoo. In the CSV,total_fee_amountandtotal_tax_amountare already net of refunds, so don’t addtotal_fee_correction_amountortotal_fee_refund_amount. - Corrections have no total. Sum the
CREDITED_CORRECTIONandCORRECTION_DISPUTElines yourself. - Always zero:
commission_amount, and the API’sfee_refund_amount. tax_amountis VAT on Kustom’s fees, not on your goods.
When a payout would be negative
Section titled “When a payout would be negative”If returns, fees and charges come to more than sales, the payout is zero and the shortfall becomes debt you owe Kustom:
deposit_amount: the shortfall added to your debt. It bringssettlement_amountup to zero.opening_debt_balance: the debt carried in from your previous payout in the same currency.repay_amount: the debt this payout paid off, the smaller of the opening balance and what you’d otherwise have been paid.closing_debt_balance:opening_debt_balance−repay_amount+deposit_amount. It becomes the next payout’s opening balance.
To spot a missing payout, check that each opening balance equals the previous closing balance,
DEBT_STATEMENT payouts included.
Summary fields
Section titled “Summary fields”| Field | What it holds |
|---|---|
payment_reference | The payout’s unique ID, also on your bank statement. It joins bank, report and API |
external_payment_reference | Resurs’s merchant/store reference, shared by the payout’s transactions. Blank on other payouts; separate from Kustom’s payment_reference |
payout_date | When the payout was created. The API gives the full UTC timestamp; the CSV cuts it to midnight UTC |
settlement_currency | The payout’s settlement currency, which can differ from the order’s original currency |
merchant_settlement_type | How Kustom’s fees are settled, below |
merchant_id | Who the payout is for |
total_settlement_amount | The amount paid out after fees, refunds, other entries and debt movements. See How the settlement amount adds up |
total_sale_amount | Captured orders |
total_fee_amount | Kustom’s fees, excluding VAT |
total_tax_amount | VAT on those fees |
total_fee_correction_amount, total_fee_refund_amount | The same fee refunds including VAT. Already accounted for in the net fee and tax totals; don’t add them to the CSV settlement formula |
total_commission_amount | Legacy commission total, always zero |
total_fee_amount_in_currency_of_registration_country, total_fee_amount_sek, total_fee_vat_amount_sek, total_tax_amount_in_currency_of_registration_country, total_tax_refund_amount | Legacy reporting totals, currently always zero |
total_return_amount | Refunds you registered |
total_reversal_amount | Amounts reversed to the customer on disputed orders |
total_holdback_amount | Money held back from this payout |
total_release_amount | Held-back money now paid out |
total_credit_amount, total_charge_amount | Other credits and charges. Each line’s detailed_type says what they are |
total_repay_amount, total_deposit_amount, opening_debt_balance, closing_debt_balance | The debt balance |
merchant_settlement_type | Meaning |
|---|---|
NET | Fees are deducted from the payout |
GROSS | Sales are paid out in full and fees are settled separately |
GROSS_FEE | That separate settlement: a GROSS account’s fees, collected by invoice |
DEBT_STATEMENT | Debt moved onto a debt statement invoice |
Transaction fields
Section titled “Transaction fields”| Field | What it holds |
|---|---|
type | The kind of entry, never null. See Transaction types |
detailed_type | The specific reason; can be null in the API. See Detailed types |
order_id | The Kustom order. The best key for matching your own order |
short_order_id | The customer-facing number derived from order_id. Capture and purchase-fee lines append -N for the capture number; return lines use the bare number. Blank on dispute lines |
capture_id | The capture behind the line; on a reversal, the disputed capture. Empty on a CSV return line, where the API gives the refund’s ID |
refund_id | The refund behind a RETURN line. Each partial refund has its own |
reversal_reference | The dispute ID (dis_…) on a reversal, dispute fee, dispute credit or dispute fee refund |
merchant_reference1, merchant_reference2 | Your references from when you created the order |
merchant_capture_reference, merchant_refund_reference | Your references from the capture or refund |
amount | The line’s amount |
posting_currency | The transaction’s settlement currency. For a converted transaction, original_currency holds the order’s original currency |
original_amount, original_tax_amount, original_currency | The transaction amount, fee VAT and currency before conversion. Blank when no currency conversion occurred |
exchange_rate | The rate from original to posting currency, with eight decimal places. Blank without a conversion |
capture_date | When the entry was registered, in UTC. For a SALE, when you captured |
sale_date | When the order was created for capture and return entries; the transaction’s occurrence time for disputes and entries without that order data, in UTC |
purchase_country | The order’s purchase country, or yours if it had none |
shipping_address_country | Where the order shipped |
initial_payment_method_type | The payment method chosen at checkout |
initial_payment_method_number_of_installments | The installments chosen at checkout, if any |
payout_id | Kustom’s encoded payout ID (pay_…), distinct from the bank statement’s payment_reference |
psp | The transaction’s payment service provider, such as STRIPE, PAYPAL or RESURS. A deferred PayPal fee can be collected in a Kustom payout alongside Stripe transactions |
merchant_id, merchant_settlement_type, payment_reference, external_payment_reference | The merchant and payout fields described under Summary fields, repeated on each line |
payout_date | The payout’s settlement date, or its creation date if not yet settled, truncated to midnight UTC |
invoice_reference | The invoice reference on an invoice-credit entry; blank on other entries |
klarna_comment | A related payout reference on an account-review hold or release, or a legacy debt-statement entry; otherwise blank |
ipp_device_id, ipp_device_name | The in-person device’s encoded ID (idev_…) and name, on capture and related fee lines with point-of-sale data |
ipp_location_id, ipp_location_name | The in-person location’s encoded ID (iloc_…) and name, on those same lines |
ipp_fiscal | The point-of-sale fiscal flag, true or false; blank when absent |
currency_code_of_registration_country, initial_payment_method_monthly_downpayments, tax_in_currency_of_registration_country, vat_sek | Legacy columns, currently unpopulated in CSV reports |
tax_rate, tax_amount | VAT rate in basis points (2500 is 25%) and VAT amount on Kustom’s fee for this line, not the customer’s VAT |
vat_amount | An alias of tax_amount, with the same fee VAT. Don’t add them together |
tax_rate_1 … tax_rate_4, tax_amount_1 … tax_amount_4 | The customer’s VAT, one pair per nonzero rate, in basis points (2500 is 25%). Included with consumer VAT enabled or these columns explicitly configured; empty for an order with more than four rates. Unused pairs stay blank |
settlement_merchant_id | The merchant ID the line settled under |
Partial captures and refunds give one order several lines. Fixed and percentage fees can also
share order_id, capture_id and type, so these references do not uniquely identify a line.
Store the complete report as a snapshot under its payment_reference. When refreshing it,
replace that payout’s stored rows together, preserving every row in the new report.
Transaction types
Section titled “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 to the customer on a disputed order |
CORRECTION | A manual correction |
HOLDBACK | Money held back from the payout |
RELEASE | Held-back money paid out |
CREDIT | Another credit. See its detailed_type |
CHARGE | Another charge. See its detailed_type |
THIRD_PARTY_FEE | A third party’s fee, for information only. Not part of the payout |
Detailed types
Section titled “Detailed types”type | detailed_type | Meaning |
|---|---|---|
SALE | PURCHASE | A captured order |
FEE | PURCHASE_FEE_FIXED | The fixed fee on a capture |
FEE | PURCHASE_FEE_PERCENTAGE | The percentage fee on a capture |
FEE | AGE_VERIFICATION_FEE_FIXED, AGE_VERIFICATION_FEE_PERCENTAGE | The fee for an age-verified purchase |
FEE | FX_FEE | Currency conversion |
FEE | DISPUTE_FEE | Charged when the dispute is lost, often in a later payout than its opening reversal |
FEE_REFUND | DISPUTE_FEE_REFUND | A previously charged dispute fee refunded when a lost dispute is later decided in your favor |
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 disputed amount credited back to you. A correction, not part of 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 rounding |
CHARGE | TRANSFER_FROM_LEGACY_INTEGRATION | Debt moved over from a legacy integration instead of invoiced |
CHARGE | CHARGE | A general charge, such as a correction, debt moved to a debt statement or rounding |
HOLDBACK, RELEASE | UNDER_REVIEW | Funds held while Kustom reviews your account, and their release |
THIRD_PARTY_FEE | THIRD_PARTY_PURCHASE_FEE | A third party’s purchase fee, for information |
Expect unlisted values and a nullable detailed_type. type is never null. New values
get added, and seven values the CSV prints (FX_FEE, APPLICATION_FEE_REFUND, INVOICE_CREDITED,
GROSS_FEE_INVOICE_CREDITED, DEBT_STATEMENT_INVOICE_CREDITED, CHARGE and CREDIT) arrive
from the API as detailed_type: null. Store the raw type and
detailed_type, key your logic on type and flag unknown values for review instead of
failing the import.
Sample reports
Section titled “Sample reports”These five files each show one payout in the default CSV layout, with 15 summary columns and 10 transaction columns. Orders, amounts and pricing are illustrative.
| Sample | What it shows |
|---|---|
| Sales and returns, SEK | A normal week: sales with their fees, full and partial returns, and a split capture |
| High volume, SEK | About 1,200 orders, for testing an import |
| Disputes, EUR | Three different disputes: one opened (REVERSAL), an older one lost (FEE) and a plain win (CREDIT, no fee refund) |
| Negative payout, SEK | Returns exceed sales. Pays 0.00, and the shortfall becomes debt |
| Debt repaid, SEK | The next week, repaying that debt in total_repay_amount |
Configured samples
Section titled “Configured samples”Two further files show optional columns, with the default amount and date formatting:
| Sample | What it shows |
|---|---|
| All columns, SEK | All 28 summary and 53 transaction columns, including four consumer VAT rate/amount pairs. Detailed types, partial debt repayment, charge and credit totals, capture and refund references, a converted PayPal deferred fee and in-person fields |
| Resurs, SEK | A separate Resurs payout, with external_payment_reference added to both sections and psp added to transactions. The Resurs reference is 1811298; the other samples leave it blank or omit the column |
The all-columns file shows a dispute opening and being lost a day later: the DISPUTE_FEE
is dated at the loss. Another dispute was lost and charged in an earlier payout, then decided
in the merchant’s favor here: its CREDIT and DISPUTE_FEE_REFUND appear together. A plain win,
as in the default EUR sample, has no fee refund.
These layouts need configuration beyond the Portal. Ten supported fields aren’t available
in the Portal’s column selector: payout_id, psp, invoice_reference, vat_amount,
external_payment_reference, ipp_device_id, ipp_device_name, ipp_location_id,
ipp_location_name and ipp_fiscal. Ask Kustom support about enabling
them for your account. A custom report configuration must include the column names and order;
the all-columns sample also enables consumer VAT. Selecting every Portal column alone won’t
produce that file. The tables above explain all exported fields.
Blank cells are intentional: fields only apply to certain entries, and some legacy fields are
currently unpopulated (currency_code_of_registration_country,
initial_payment_method_monthly_downpayments, tax_in_currency_of_registration_country and
vat_sek). The legacy summary currency-conversion totals and total_tax_refund_amount are
always zero. total_fee_correction_amount and total_fee_refund_amount both show the gross fee
refund; do not add either to the settlement formula again. In the all-columns sample,
total_deposit_amount is zero because that payout repays debt rather than adding to it.
Each file starts with the summary header and its one row of totals, then the transaction header and lines, newest first. Amounts are positive, because minus signs are off by default, and dates are UTC.
Turn on the columns you need. The default leaves out detailed_type, the debt balances and
the charge, credit and deposit totals. Without them, a dispute fee reads only FEE and a
negative payout’s shortfall doesn’t appear at all.
Related
Section titled “Related”- Settlements and getting paid — the payout schedule, and reconciling with the API
- Settlements API reference — every endpoint and field
This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.