Skip to content

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 reportSettlements API
AmountsDecimals by default, 100.00Integers in minor units, 10000
Summary totalstotal_sale_amount, total_fee_amount, …totals.sale_amount, totals.fee_amount, …
Debt balanceopening_debt_balance, closing_debt_balancetotals.opening_debt_balance_amount, totals.closing_debt_balance_amount
Payout currencysettlement_currencycurrency_code
A line’s currencyposting_currencycurrency_code
VAT on Kustom’s fee, per linetax_rate, tax_amountvat_rate, vat_amount
The customer’s VAT, per linetax_rate_1 … tax_rate_4, tax_amount_1 … tax_amount_4consumer_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.

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

Watch for:

  • Fee refunds count once. In the API, fee_amount and tax_amount are before refunds, and fee_correction_amount holds the refunds with their VAT, so don’t add tax_refund_amount too. In the CSV, total_fee_amount and total_tax_amount are already net of refunds, so don’t add total_fee_correction_amount or total_fee_refund_amount.
  • Corrections have no total. Sum the CREDITED_CORRECTION and CORRECTION_DISPUTE lines yourself.
  • Always zero: commission_amount, and the API’s fee_refund_amount.
  • tax_amount is VAT on Kustom’s fees, not on your goods.

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 brings settlement_amount up 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.

FieldWhat it holds
payment_referenceThe payout’s unique ID, also on your bank statement. It joins bank, report and API
external_payment_referenceResurs’s merchant/store reference, shared by the payout’s transactions. Blank on other payouts; separate from Kustom’s payment_reference
payout_dateWhen the payout was created. The API gives the full UTC timestamp; the CSV cuts it to midnight UTC
settlement_currencyThe payout’s settlement currency, which can differ from the order’s original currency
merchant_settlement_typeHow Kustom’s fees are settled, below
merchant_idWho the payout is for
total_settlement_amountThe amount paid out after fees, refunds, other entries and debt movements. See How the settlement amount adds up
total_sale_amountCaptured orders
total_fee_amountKustom’s fees, excluding VAT
total_tax_amountVAT on those fees
total_fee_correction_amount, total_fee_refund_amountThe 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_amountLegacy 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_amountLegacy reporting totals, currently always zero
total_return_amountRefunds you registered
total_reversal_amountAmounts reversed to the customer on disputed orders
total_holdback_amountMoney held back from this payout
total_release_amountHeld-back money now paid out
total_credit_amount, total_charge_amountOther credits and charges. Each line’s detailed_type says what they are
total_repay_amount, total_deposit_amount, opening_debt_balance, closing_debt_balanceThe debt balance
merchant_settlement_typeMeaning
NETFees are deducted from the payout
GROSSSales are paid out in full and fees are settled separately
GROSS_FEEThat separate settlement: a GROSS account’s fees, collected by invoice
DEBT_STATEMENTDebt moved onto a debt statement invoice
FieldWhat it holds
typeThe kind of entry, never null. See Transaction types
detailed_typeThe specific reason; can be null in the API. See Detailed types
order_idThe Kustom order. The best key for matching your own order
short_order_idThe 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_idThe 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_idThe refund behind a RETURN line. Each partial refund has its own
reversal_referenceThe dispute ID (dis_…) on a reversal, dispute fee, dispute credit or dispute fee refund
merchant_reference1, merchant_reference2Your references from when you created the order
merchant_capture_reference, merchant_refund_referenceYour references from the capture or refund
amountThe line’s amount
posting_currencyThe transaction’s settlement currency. For a converted transaction, original_currency holds the order’s original currency
original_amount, original_tax_amount, original_currencyThe transaction amount, fee VAT and currency before conversion. Blank when no currency conversion occurred
exchange_rateThe rate from original to posting currency, with eight decimal places. Blank without a conversion
capture_dateWhen the entry was registered, in UTC. For a SALE, when you captured
sale_dateWhen 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_countryThe order’s purchase country, or yours if it had none
shipping_address_countryWhere the order shipped
initial_payment_method_typeThe payment method chosen at checkout
initial_payment_method_number_of_installmentsThe installments chosen at checkout, if any
payout_idKustom’s encoded payout ID (pay_…), distinct from the bank statement’s payment_reference
pspThe 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_referenceThe merchant and payout fields described under Summary fields, repeated on each line
payout_dateThe payout’s settlement date, or its creation date if not yet settled, truncated to midnight UTC
invoice_referenceThe invoice reference on an invoice-credit entry; blank on other entries
klarna_commentA related payout reference on an account-review hold or release, or a legacy debt-statement entry; otherwise blank
ipp_device_id, ipp_device_nameThe 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_nameThe in-person location’s encoded ID (iloc_…) and name, on those same lines
ipp_fiscalThe 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_sekLegacy columns, currently unpopulated in CSV reports
tax_rate, tax_amountVAT rate in basis points (2500 is 25%) and VAT amount on Kustom’s fee for this line, not the customer’s VAT
vat_amountAn 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_4The 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_idThe 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.

typeMeaning
SALEA captured order
FEEA Kustom fee. One sale can carry several
FEE_REFUNDA fee refunded to you
RETURNA refund you registered
REVERSALAn amount reversed to the customer on a disputed order
CORRECTIONA manual correction
HOLDBACKMoney held back from the payout
RELEASEHeld-back money paid out
CREDITAnother credit. See its detailed_type
CHARGEAnother charge. See its detailed_type
THIRD_PARTY_FEEA third party’s fee, for information only. Not part of the payout
typedetailed_typeMeaning
SALEPURCHASEA captured order
FEEPURCHASE_FEE_FIXEDThe fixed fee on a capture
FEEPURCHASE_FEE_PERCENTAGEThe percentage fee on a capture
FEEAGE_VERIFICATION_FEE_FIXED, AGE_VERIFICATION_FEE_PERCENTAGEThe fee for an age-verified purchase
FEEFX_FEECurrency conversion
FEEDISPUTE_FEECharged when the dispute is lost, often in a later payout than its opening reversal
FEE_REFUNDDISPUTE_FEE_REFUNDA previously charged dispute fee refunded when a lost dispute is later decided in your favor
FEE_REFUNDAPPLICATION_FEE_REFUNDAnother fee refunded to you
RETURNPURCHASE_RETURNA refund you registered
REVERSALREVERSALAn amount reversed on a disputed order
CORRECTIONCREDITED_CORRECTIONA manual correction
CREDITCORRECTION_DISPUTEA disputed amount credited back to you. A correction, not part of credit_amount
CREDITINVOICE_CREDITED, GROSS_FEE_INVOICE_CREDITED, DEBT_STATEMENT_INVOICE_CREDITEDA credit against a Kustom invoice
CREDITCREDITA general credit, such as a correction, a released negative balance or rounding
CHARGETRANSFER_FROM_LEGACY_INTEGRATIONDebt moved over from a legacy integration instead of invoiced
CHARGECHARGEA general charge, such as a correction, debt moved to a debt statement or rounding
HOLDBACK, RELEASEUNDER_REVIEWFunds held while Kustom reviews your account, and their release
THIRD_PARTY_FEETHIRD_PARTY_PURCHASE_FEEA 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.

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.

SampleWhat it shows
Sales and returns, SEKA normal week: sales with their fees, full and partial returns, and a split capture
High volume, SEKAbout 1,200 orders, for testing an import
Disputes, EURThree different disputes: one opened (REVERSAL), an older one lost (FEE) and a plain win (CREDIT, no fee refund)
Negative payout, SEKReturns exceed sales. Pays 0.00, and the shortfall becomes debt
Debt repaid, SEKThe next week, repaying that debt in total_repay_amount

Two further files show optional columns, with the default amount and date formatting:

SampleWhat it shows
All columns, SEKAll 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, SEKA 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.

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