Skip to content
thrudocs

Refunds and settlement

Refunds

POST /v1/payments/:id/refund, with x-api-key. The body is optional:

json
{
  "amount": "5",
  "reason": "Customer request"
}
FieldRules
amountOptional decimal string in token units. Leave it out to refund everything that remains.
reasonOptional, up to 1000 characters
toAddressOptional, up to 128 characters. The default is the address that sent the payment's first transfer.
  • Only payments in confirmed or overpaid can be refunded; anything else returns 409. An underpaid payment cannot be refunded through the API.
  • The most you can refund is receivedAmount − the platform fee thru keeps − earlier refunds. GET /v1/payments/:id returns it as refundableAmount ("0" for a payment that cannot be refunded, including a token the refund route cannot send; see below). A larger amount returns 400 with the maximum. A refund never returns the platform fee. The fee thru keeps is feeAmount less any part thru decided not to collect (see "The platform fee" below); both are 0 for every account today.
  • To return only an overpayment, refund receivedAmount − expectedAmount.
  • If the payer sent from an exchange, the default address belongs to the exchange. Ask the payer for an address and pass toAddress.
  • Refunds currently send the chain's NATIVE asset only. The refund is sent on the payment's own chain, but if the payment's token is not that chain's native asset the call is a 400 — "<Chain> withdrawals currently support native <TOKEN> only". In practice that means an Arc USDC payment can be refunded (USDC is Arc's native asset) while a USDC payment on Base or BNB Chain, a Sui USDC payment and a Robinhood USDG payment cannot. Use an off-platform transfer for those and reconcile it yourself.
  • A refund is funded from a payment address that still holds a balance — not from your settlement wallet and not from thru. thru looks for one of your own payments on that chain whose custodial address has not been swept yet and has enough for the amount plus gas. If none does, the call is a 409. So in an account where the auto-sweep is keeping up, refunds will usually fail: the money is already in your settlement wallet, and thru cannot pull it back. Plan refunds as something you send from your own wallet, and treat the API as a convenience for the window before a payment is swept.
  • If sending fails for any other reason the call returns 409 with the reason.
  • A full refund (all that remains) moves the payment to refunded and fires payment.refunded. If the payment came from a checkout session, the session moves to failed and checkout.session.failed fires. A partial refund fires no event.
  • GET /v1/refunds lists your newest 100 refunds. There is no pagination and no updatedAfter on this endpoint, so it is not a complete recovery path for a missed payment.refunded. A full refund also flips the payment to refunded, which moves that payment's updatedAt — so the payments walk will show you the payment even when the refund list has rolled past 100. A partial refund emits no event at all; record it when you create it.

Receipts and credit notes

thru issues an accounting document whenever money is credited to a payment — on every path, not only invoices. You do not ask for it and the customer does not either.

DocumentIssued whenWhat its amount is
receiptThe first money documented on a paymentThe transfers it covers. One per payment, ever.
supplementMoney arrives after a document already covered the earlier moneyThe delta only
credit_noteAny refund, including a partial oneThe amount refunded

Nothing issued is ever rewritten, and that is the reason for the chain rather than one updatable document. A receipt has to follow the amount actually received AND stay true once a customer is holding the PDF; both cannot hold if the row is edited. Two ordinary situations grow the amount after a receipt exists — an underpaid payment topping up, and a late transfer recovered by support weeks later — so the chain is the common case, not an exotic one.

Every document also carries receivedAmountAtIssue, the running total as it stood. Show a customer the newest document's total; do not add the amounts up yourself.

Reading them

EndpointReturns
GET /v1/payments/:id/receiptsEvery document for one payment, oldest first, plus received, refunded and net
GET /v1/receiptsYour newest 100, or the same keyset walk GET /v1/payments has — updatedAfter, cursor, limit, same envelope, same 60-second lag. Optional kind filter
GET /v1/receipts/:idOne document

Filtering this walk by kind is safe, unlike filtering the payments walk by status: a document's kind is frozen at issue, so a row cannot leave the filtered set while you are walking it.

The hosted document

Every document has publicId, and https://thru.la/r/<publicId> renders it for anyone with the link — no key. That page is also the PDF: it prints, and the browser's own "Save as PDF" produces the file. There is no .pdf endpoint.

It shows the WHOLE chain whichever document was linked, so a customer holding an older email still sees the current, complete story rather than a figure that understates what was received. It states every transfer behind the total with its confirmation depth at issue and the threshold it was judged against — the part a crypto receipt can do that a paper one cannot. Your reference is never rendered there; it is often an internal id, so it stays in the API and the console.

Delivery, honestly

thru emails the document only when it has a customer address, which in practice means the invoice path. A checkout session carries your own reference, not an email, and a payment link carries nothing. Everywhere else the receipt.* webhook carries the document and your return page can link it — forwarding it to your customer is yours to do. emailedAt on the document tells you whether anything was actually sent.

The letterhead

A document prints the issuing entity from Settings → Business: legal name, address, tax identifier. Set it before you take real payments — the details are SNAPSHOTTED onto each document at issue, so filling them in later fixes future documents and not past ones. Until then a document prints "issuer details not set" rather than guessing from your workspace name.

Settlement: where your money goes

Each payment is received on an address thru controls. Once the payment is confirmed or overpaid, thru forwards the funds to your settlement address for that chain and network. settlement.completed fires when the funds have been sent to you, and settlement.failed if sending failed. The full payload, and the fields that matter when a payment pays out twice, are in webhooks.

  • Set a settlement address for every chain and network you accept before you go live. If there is none, the funds stay on the payment address and nothing is forwarded.
  • Native SUI is not forwarded automatically. Withdraw it from Treasury in the console. No platform fee is withheld on native SUI.
  • settlement.* events report treasury movements. Never use them as the signal to fulfil an order: the payer paid when the payment was confirmed, not when you were paid out.

A payment can pay out more than once

If money lands on a payment after it has already been paid out — a payer sent a second transfer, or support credited a late one — the payout is re-opened and the next run forwards the rest. You get a second settlement.completed for the same paymentId with sequence: 2. Dedupe on runId, order on sequence, and never key your ledger on paymentId alone.

Reading your payouts: GET /v1/sweeps

Newest 100 by default; add updatedAfter, cursor or limit for the same keyset walk (and the same 60-second lag) GET /v1/payments has — see payments, "Reconciliation". Each row is a payment's current payout state, plus:

FieldMeaning
runsEvery payout attempt for this payment, oldest first: { id, sequence, status, amount, toAddress, txHash, gasFundingTxHash, trigger, error, startedAt, completedAt, feeAmount, feeStatus, feeNotCollected, feeReason, feeTxHash, feeToAddress }. id here is the runId the webhook carries. The fee* fields are that run's platform fee as it stands now (see webhooks for each field). They match its settlement.* event with one exception: a run whose fee transfer did not complete reads feeStatus: "failed" here (its event said pending). Its fee went back to outstanding, and the run that retried it carries the outcome. feeAmount is always what that run withheld, so summing it across runs is right.
sweptTotalLifetime forwarded for this payment. amount is the LAST run's transfer, not the total.
runCountHow many runs actually forwarded.
payoutStatescheduled, reopened, paid_out, held, awaiting_settlement_address or manual_required. (A payment with no payout record yet has no row here at all, so you will never read a seventh not_started value from this endpoint.)
requiresManualPayouttrue only for manual_required — money no run will ever forward (a chain with no payout rail, native SUI, a payout past its retry cap). Everything else is already scheduled.
payoutNotePlain-language reason, whenever there is something to know.
reopenedAt, reopenReasonSet while money is waiting for a further run.
feeCollectedTotalLifetime platform fee withheld from this payment's payouts and sent to thru. "0" when nothing was withheld.
feeNotCollectedTotalLifetime platform fee thru decided not to collect on this payment. It is final: never taken from later money.
feePendingPlatform fee not settled yet: being sent or confirmed, or held back for a scheduled retry of a fee transfer that did not complete. "0" otherwise.

id on the row is the payout record for that payment (one per payment, overwritten by each run) — not a payout id. Use runs[].id.

One payment's payout: GET /v1/sweeps/:paymentId returns { sweep, feeLegs }: the same row as above (null when the payment has no payout record yet) and every platform-fee decision on that payment, oldest first. A payment that belongs to another workspace is a 404. Each fee decision reads:

FieldMeaning
statuscollected (withheld and sent to thru), pending (being sent or confirmed), failed (the fee transfer did not happen; the fee is still outstanding and a later run tries again) or not_collected (thru decided not to take it; final)
reasonWhy not, or why only part: one of the reason codes below. null on a fully collected decision
receivedFrom, receivedToThe slice of receivedAmount this decision covers: (receivedFrom, receivedTo]. A payment that pays out twice has one decision per run, covering what arrived since the previous one
due, withheld, notCollectedThe fee on that slice, the part withheld from you, and the part not taken. withheld + notCollected = due once decided
toFeeAddressWhat reached thru's fee address. Equal to withheld on token rails; on native coins it is withheld less the network fee of thru's own transfer, which thru pays
feeToAddress, txHash, sharedTxthru's fee address and the fee transaction. sharedTx: true on Sui, where your payout and the fee are one transaction
runSequence, sweepRunIdThe payout run that decided it; both null on a decision made without a run (for example a refund before payout)
feeBps, token, rail, decidedAt, collectedAt, verifiedAtThe payment's rate, the token, how the fee was taken (none = your payout was sent exactly as before), and when it was decided, withheld and confirmed on chain

How much has not been forwarded yet: receivedAmount (from GET /v1/payments) minus sweptTotal minus feeCollectedTotal (both here). There is no separate field, deliberately: a stored number could disagree with the ones it is derived from.

On a native-asset rail that difference is never zero, and that is correct. Where the asset being paid is the chain's own gas asset, the payout must leave enough behind to pay for itself, so the amount forwarded is the balance minus a gas reserve. Arc is the case that surprises people: its USDC is the native asset, so an Arc payout is net of roughly 0.0005 USDC and that dust stays on the payment address for good. The same applies to native ETH, BNB, SOL and TRX. On token rails — ERC-20, SPL, TRC-20, Sui coins — thru pays the gas from its own tank and the full balance is forwarded, so the difference really is zero.

The platform fee

feeBps and feeAmount are recorded on every payment (see payments). Today both are 0 for every account and nothing is withheld from any payout, so every fee* field below reads 0, none or null. Before thru withholds a fee on mainnet, a breaking changelog entry announces it.

When thru collects the fee, it takes it from the payout itself, in the same settlement: your net goes to your settlement address and the fee goes to thru's fee address for that chain and network. No invoice follows, and nothing is ever due afterwards.

  • The fee is charged on the gross amount received, overpayment included, at the rate fixed when the payment was created, and rounded down to the token's smallest unit.
  • A refund never returns the fee (see Refunds above).
  • A fee thru did not collect is never taken later. Each decision not to collect is final and says why (reason). On a chain or token that cannot split a payout safely, and whenever thru is not collecting, your payout is sent exactly as before and the fee is recorded as not collected.
  • Who pays the network fee of the fee transfer: thru. On token rails thru's gas tank pays it. On native coins (Arc USDC, BNB, ETH) it comes out of the fee, so toFeeAddress is a little below withheld; your payout is the balance less the fee withheld and the network fee of your own transfer, as before.
  • Your payout on each settlement.completed: amount stays the net sent to you, feeAmount is the fee withheld in that run, and feeCollectedTotal the lifetime total.

The reconciliation identity, per payment:

receivedAmount = sweptTotal + feeCollectedTotal + (native coins: network gas and reserve dust) + not yet forwarded

Reason codes (reason on a fee decision, feeReason on a run and an event). They are opaque strings and more may be added, so treat one you do not recognise as "not collected". When several apply, the first in this table wins.

CodeMeaningWhat you receive
legacy_ratePayment created before rates were fixed at creationthe full amount
created_before_collectionA non-zero rate fixed before fee collection existedthe full amount
not_auto_sweptNative SUI, never forwarded automaticallyit stays on the payment address, as before
chain_not_sweepableNo automatic payout on this chainas before
token_not_in_registryToken not supported for payoutas before
rail_not_supportedThis chain or token cannot split the fee safelythe full amount
refunded_before_settlementFully refunded before the fee was collectedas before
rate_above_collection_capThe payment's rate is above thru's current rate capthe full amount
collection_disabledthru was not collecting feesthe full amount
rail_disabledFee collection not enabled for this tokenthe full amount
no_fee_addressNo thru fee address for this chain and networkthe full amount
fee_address_pendingthru's fee address for this chain is not active yetthe full amount
fee_address_changedthru's fee address changed before collectionthe full amount, in a second payout
split_failedThe split transfer failed on this paymentthe full amount
planner_errorThe fee could not be worked out at payoutthe full amount
below_minimumThe fee was below the minimum worth sendingthe full amount
below_collection_costNative coin: the fee was below the cost of sending itthe full amount
unit_roundingA remainder below the token's smallest unitthat remainder
insufficient_balanceThe payment address held less than the fee duewhat was there, less what was collected
forwarded_before_creditA payout sent this money before it was creditedalready received
operator_waivedWaived by thruthe leftover fee is forwarded to you

A payout run that finds nothing to send emits no event, and neither does a run that only sends thru a leftover platform fee (a fee_retry run after a fee transfer did not complete): your money did not move, so there is no settlement.* event. That run closes as completed with amount: "0" and no txHash, and you see it in runs[] but never as a settlement.completed. A fee_retry run that sends YOU money is announced like any payout: when the fee can no longer be collected (collection was turned off, the fee address changed, or the fee fell below the minimum), that money is yours, and the run forwards it with settlement.completed, trigger: "fee_retry" and feeStatus: "not_collected". Nor is there an event when a run merely starts, or when a payout is marked held or skipped — only the two terminal outcomes are announced.

Monthly fee receipts

When thru withholds platform fees from your payouts, it issues a fee receipt for each UTC calendar month in which something was withheld: a record of fees already taken, not a bill. Nothing is due on it.

  • Numbered FEE-YYYY-NNNN, one series across thru (thru is the issuer), restarting each calendar year of issue.
  • Issued from 00:15 UTC on the 1st for the month before. No receipt for a month with nothing withheld.
  • One line per fee withheld on mainnet and confirmed on chain. A fee appears on exactly one receipt, ever. A fee confirmed on chain after its month's receipt was issued appears on the next receipt, with carriedForward: true.
  • Totals are per chain, network and token (totals[]), never added across tokens: legCount, paymentCount, feeBase (the gross amount the fees were charged on), fee and feeAtomic (the same in the token's smallest unit). Each line's fee is rounded down on the payment's cumulative amount, so a line can differ by one smallest unit from feeBase × feeBps / 10000. The exception is a line where only part of the fee could be withheld (the address held less than the fee due, insufficient_balance): its fee is what was withheld, below feeBase × feeBps / 10000, and the rest is never taken. GET /v1/sweeps/:paymentId shows that decision's due and notCollected.
  • notWithheldCount counts the payments that month that carried a fee thru did not withhold. Nothing is owed for them.
  • Never edited after issue. contentHash is a SHA-256 fingerprint of the frozen content, so two copies can be compared.
  • Email: the workspace's owners are emailed a copy only when thru's email delivery is configured; emailedAt says whether one went out. The receipt is in the API and the console either way.
  • A receipt with network: "testnet" (test: true, numbered FEE-TEST-YYYY-NNNN) is a test document. It is never emailed.
  • Agent payments (HTTP 402) settle directly to you and carry no platform fee.
EndpointReturns
GET /v1/fee-receiptsYour newest 100 receipts, or the same keyset walk GET /v1/receipts has (updatedAfter, cursor, limit, same envelope, same 60-second lag). Optional network filter
GET /v1/fee-receipts/preview?month=YYYY-MMThis month so far (or an earlier month), live: the same totals[] plus verifiedFee and unverifiedLegCount, on every network. No number and no fingerprint: a preview is not a receipt, and it changes until the month closes
GET /v1/fee-receipts/:idOne receipt with its lines[]: paymentId, chain, network, token, paymentCreatedAt, collectedAt, carriedForward, runSequence, feeBase, feeBps, fee, feeAtomic, feeTxHash, payoutTxHash, reference
GET /v1/fee-receipts/:id/export.csvThe receipt's lines as CSV

A receipt also carries periodStart and periodEnd (exclusive: the first instant of the next month), issuedAt, issuer (thru's letterhead) and recipient (your workspace name and your Settings → Business details, snapshotted at issue). All four need permission to read settlement data, which every built-in role has, the same as GET /v1/sweeps.

Managing settlement addresses

Use the console: Treasury → Settlement. You can hold several addresses per chain and network (up to 20). One of them is the default, which receives everything not routed elsewhere, including all direct payments and invoices. You can route an individual product's sales to a different address.

The first address for a chain and network is active immediately. Adding another address, or changing an existing one, is staged behind a cool-down (24 hours by default) during which it can be cancelled. The events settlement.address.created, settlement.address.change_staged and settlement.address.change_cancelled report these changes. Subscribe to settlement.* so you notice a change you did not make.

The same operations are available with an API key:

Rails with nowhere to settle

GET /v1/settlement/routing also answers the question you would otherwise only discover by noticing money had not arrived:

json
"coverage": {
  "missing": [
    { "chain": "arc", "network": "mainnet", "productSlugs": [], "invoiceNumbers": ["INV-0007"], "reason": "invoice" },
    { "chain": "base", "network": "mainnet", "productSlugs": ["credit-9c2e"], "invoiceNumbers": [], "reason": "product_rail" }
  ],
  "covered": [{ "chain": "sui", "network": "mainnet" }]
}

A rail is missing when you can receive money on it and it has no activated default settlement address. You can receive money on a rail when:

  • an active product sells on it (product_rail, with the product slugs);
  • an open invoice with no payment yet can be paid on it: the invoice's own chain or one of its enabledChains (invoice);
  • a payment has been created on it (payment_seen).

reason is the strongest of these for the rail, and invoiceNumbers lists the open invoices payable there whatever the reason ([] when there are none). missing is ordered most-exposed-first, counting products and open invoices together. Treat a reason you do not recognise as a gap; new sources may be added.

Money on a missing rail is not lost, and you do not have to do anything to recover it. The payment is detected, credited and receipted exactly as normal; only the payout is deferred. The sweep records skipped with "No settlement wallet configured", and the retry scan re-selects precisely those rows — so the moment you set an address, the money is forwarded on the next tick. What you lose by leaving a gap open is time and visibility, not funds.

An address that exists but is not the activated default does not cover the rail: an unrouted payment falls back to the default, so a rail whose only address is still inside its change cool-down is correctly still a gap.

EndpointDoes
GET /v1/settlementLists your settlement addresses and the products routed to each
GET /v1/settlement/routingAddresses, products and current routes in one read, plus coverage — see below
POST /v1/settlement/addresses { chain, network?, address, label? }Adds an address
PATCH /v1/settlement/addresses/:id { label }Renames it
POST /v1/settlement/addresses/:id/defaultMakes it the default
PUT /v1/settlement/addresses/:id/address { address }Stages a change of address
POST /v1/settlement/addresses/:id/cancelCancels a staged change
DELETE /v1/settlement/addresses/:idRemoves an address that is not the default and has no products routed to it
PUT /v1/settlement/routes { changes: [{ productId, chain, network?, settlementAccountId }] }Routes products to addresses; settlementAccountId: null sends a product back to the default
PUT /v1/settlement { chain, network?, address }Sets the default address for a chain and network
POST /v1/settlement/cancel { chain, network? }Cancels a staged change of the default

network defaults to mainnet on all of these. Because an API key can change where your money goes, guard it accordingly.