Skip to content
thrudocs

Changelog

Every change to a public surface: a route, a field, an event, an error body or an SDK export. Newest first. A breaking change always links a migration guide.

New

Payouts report the platform fee

Payout events and GET /v1/sweeps gain platform fee fields, GET /v1/sweeps/:paymentId and refundableAmount are new, and monthly fee receipts arrive at /v1/fee-receipts. Nothing is withheld from any payout.

  • settlement.completed and settlement.failed gain feeBps, feeAmount, feeStatus, feeNotCollected, feeReason, feeTxHash, feeToAddress and feeCollectedTotal. amount is unchanged: it is still this run's transfer to you.

  • trigger on settlement.* events and on runs[] may now be fee_retry: a run started to retry a platform fee transfer that did not complete. When it only sends thru that fee, it sends you nothing and emits no event. When the fee can no longer be collected, it forwards that money to you and emits settlement.completed like any payout (feeStatus: "not_collected"), so handle a fee_retry event like any other payout.

  • GET /v1/sweeps: each row gains feeCollectedTotal, feeNotCollectedTotal and feePending, and each runs[] entry gains feeAmount, feeStatus, feeNotCollected, feeReason, feeTxHash and feeToAddress. On runs[] the fee reads as it stands now: a run whose fee transfer did not complete reads feeStatus: "failed" there (its event said pending), and a later run carries the outcome.

  • New GET /v1/sweeps/:paymentId returns { sweep, feeLegs }: one payment's payout record and every platform-fee decision on it. It needs settlement.read.

  • GET /v1/payments/:id gains refundableAmount: the most a refund of that payment can be right now, "0" when the payment cannot be refunded (by its status, or because the refund route cannot send its token, such as USDC on Base). It is not on GET /v1/payments and not on webhooks.

  • The refund maximum is receivedAmount less the platform fee thru keeps (feeAmount less any part thru decided not to collect) less earlier refunds. At a rate of 0 it equals receivedAmount less earlier refunds, as before.

  • New monthly fee receipts: GET /v1/fee-receipts, GET /v1/fee-receipts/preview, GET /v1/fee-receipts/:id and GET /v1/fee-receipts/:id/export.csv, all with settlement.read. A fee receipt records platform fees already withheld from payouts, numbered FEE-YYYY-NNNN; nothing is due on it.

  • feeSource on a payment may now also be chain: the rate set for the payment's chain and network.

  • Nothing is withheld from any payout in this release, and no fee receipt is issued. While a payment's rate is 0, every new fee field reads 0, none or null. A payment with a non-zero rate shows feeStatus: "not_collected" with feeReason: "collection_disabled": its payout is sent in full, and once that payout has run its refund maximum is the full amount received. A breaking changelog entry will announce withholding before it starts on mainnet.

thru records a platform fee on every payment (feeBps, feeAmount). This release adds the fields that will report, payout by payout, how much of that fee was withheld, plus a monthly record of it. No payout changes in this release: nothing is withheld, and every payout is sent in full as before. While a payment's rate is 0, every new field reads 0, none or null. A payment with a non-zero rate reads feeStatus: "not_collected" and feeReason: "collection_disabled": the fee is recorded, not withheld, and nothing is owed for it. Before thru withholds a fee on mainnet, a breaking changelog entry will say so.

On every payout event

settlement.completed and settlement.failed gain eight fields. amount does not change meaning: it is still this run's transfer to you.

FieldMeaning
feeBpsThe payment's rate, fixed when it was created
feeAmountThe fee withheld in this run; "0" when none
feeStatusnone, collected, pending or not_collected (runs[] can also read failed, below)
feeNotCollected, feeReasonThe part of this run's fee thru did not take, and why
feeTxHash, feeToAddressThe fee transaction and thru's fee address (on Sui, feeTxHash equals txHash)
feeCollectedTotalLifetime fee withheld for this payment, including this run

trigger may now be fee_retry: a run started to retry a platform fee transfer that did not complete. When it only sends thru that fee, it sends you nothing and emits no event. When the fee can no longer be collected, it forwards that money to you and emits settlement.completed like any payout, with feeStatus: "not_collected". Handle it like any other payout.

Payout reads

  • GET /v1/sweeps: rows gain feeCollectedTotal, feeNotCollectedTotal and feePending; runs[] entries gain the run's fee fields, as they stand now. A run whose fee transfer did not complete reads feeStatus: "failed" there (its event said pending); the run that retried it carries the outcome, and feePending holds that fee until it is decided.
  • New GET /v1/sweeps/:paymentId: { sweep, feeLegs }, one payment's payout and every fee decision on it (what was withheld, what was not and why).
  • "Not yet forwarded" is receivedAmount − sweptTotal − feeCollectedTotal. With every fee at 0 that is the same number as before.

Refunds

GET /v1/payments/:id gains refundableAmount, the most a refund can be right now: what was received, less the platform fee thru keeps, less earlier refunds. A refund never returns the fee. It is "0" for a payment the refund route cannot refund, including a token it cannot send (a USDC payment on Base or BNB Chain, Sui USDC, Robinhood USDG). At a rate of 0 it is receivedAmount less earlier refunds, exactly as before.

Monthly fee receipts

GET /v1/fee-receipts lists your fee receipts (the same keyset walk as GET /v1/receipts), GET /v1/fee-receipts/:id reads one with its lines, GET /v1/fee-receipts/:id/export.csv exports it, and GET /v1/fee-receipts/preview shows the current month so far. A fee receipt records fees already withheld from your payouts in one UTC month, per chain, network and token; it is not a bill and nothing is due. With every fee at 0 none is issued.

feeSource

A payment's feeSource may now also be chain: the rate set for the payment's chain and network. As before, treat a value you do not recognise as opaque.

New

A payment's fee rate is fixed when it is created

feeBps is now set once, when the payment is created, instead of being re-read at each confirmation. Payments gain feeSource. The fee is still 0 for every account and is not deducted from payouts.

  • feeBps on a payment is set when the payment is created and never changes afterwards, so it already appears in the POST /v1/payments response. Before this change it was re-read from the platform setting each time money was confirmed.

  • For a checkout session or an invoice, the payment is created when the customer picks a chain, so that is when its rate is fixed.

  • feeAmount is receivedAmount × feeBps / 10000, rounded down to the token's smallest unit. It still grows as money arrives.

  • New field feeSource wherever the full payment object appears: POST /v1/payments, GET /v1/payments/:id, GET /v1/payments, and data.payment on the payment.confirmed, payment.underpaid, payment.overpaid, payment.amount_increased, payment.refunded, receipt.issued, receipt.supplemented and receipt.credit_note.issued webhooks. Its value is global, plan or merchant, and null on payments created before this change. More values may be added.

  • payment.expired and the payment.flow.* events carry no payment object, so they have no fee fields and are unchanged.

  • The fee is 0 for every account today and automatic payouts never deduct it. Reconcile payouts against receivedAmount.

A payment records a platform fee in two fields, feeBps (the rate, in basis points: 100 = 1%) and feeAmount (the amount). Until now the rate was looked up again every time money for the payment was confirmed, so a payment could show one rate when it was created and another after a late transfer. From this release the rate is fixed once, when the payment is created, and never changes afterwards.

  • feeBps is final from the start. It is set when the payment is created, so the POST /v1/payments response already carries the rate that will apply.
  • Checkout sessions and invoices. The payment is created when the customer picks a chain, so that is the moment its rate is fixed. Switching chains creates a new payment, which gets its own rate at that moment.
  • feeAmount is receivedAmount × feeBps / 10000, rounded down to the token's smallest unit (6 decimals for USDC on most chains). It still grows as money arrives, always at the fixed rate.
  • New field feeSource says where the rate came from: global (the platform default), plan, or merchant (a rate set for your account). It is null on payments created before this change. More values may be added later, so treat a value you do not recognise as opaque. It appears everywhere the full payment object does: the create response, GET /v1/payments/:id, GET /v1/payments, and data.payment on the payment.confirmed, payment.underpaid, payment.overpaid, payment.amount_increased, payment.refunded and receipt.* webhooks. payment.expired and the payment.flow.* events carry no payment object, so they have no fee fields and are unchanged. The hosted checkout's public payment view carries no fee fields, as before.
json
{
  "receivedAmount": "37",
  "feeBps": 0,
  "feeAmount": "0",
  "feeSource": "global"
}

Nothing changes about the money. The fee is 0 for every account today, and automatic payouts never deduct it: they forward what the payment address received. Reconcile payouts against receivedAmount, not against receivedAmount − feeAmount.

New

Settlement coverage now counts open invoices

An open, unpaid invoice on a rail with no settlement address is now a coverage gap. Every gap gains invoiceNumbers, and reason gains the value invoice.

  • GET /v1/settlement/routing: coverage.missing now includes rails that an open invoice can be paid on, even when no product sells there. Those gaps have reason: "invoice".

  • Every entry in coverage.missing now carries invoiceNumbers — the open invoices without a payment yet that can be paid on that rail — whatever its reason. It is [] when there are none.

  • An invoice counts only while it is open and has no payment. A draft has not been sent, and once a payment exists the rail is fixed to that payment, which the payment_seen source already covers.

  • missing is still ordered most-exposed-first. Exposure now counts products and open invoices together.

  • If your code switches on reason, handle values it does not recognise as a gap, not an error. reason explains why a rail matters; the gap is real whatever the value.

An invoice is a way to be paid that your catalogue does not show. Before this change, an invoice sent on a chain that no product sold on did not show up in coverage until the customer paid it. After that, the money waited in its payment address and nothing had said the rail was unset.

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" }]
}

An invoice's rails are its own chain plus its enabledChains: the same set the hosted invoice page lets the customer choose from. Only an open invoice with no payment yet counts. A draft has not been sent to anyone. A paid or void invoice cannot be paid again. Once an invoice has a payment, the customer can no longer choose a chain.

reason is the strongest reason the rail matters: product_rail, then invoice, then payment_seen. A rail that a product sells on AND that has open invoices keeps reason: "product_rail" and lists the invoices in invoiceNumbers.

Nothing changes about what happens to the money. On an uncovered rail it is still detected, credited and receipted, and it is paid out automatically once you set an address.

New

Rails with nowhere to settle are now visible, and receipts export as CSV

GET /v1/settlement/routing gains coverage, naming the rails you can take money on but cannot pay out from. Issued documents export as CSV over a date range.

  • GET /v1/settlement/routing now returns coverage: { missing, covered }. A rail is missing when an active product sells on it (or a payment has been created on it) and it has no activated default settlement address.

  • Money on a missing rail is still detected, credited and receipted. Only the payout waits, and it resumes automatically once an address is set — the sweep retry scan re-selects exactly those skipped rows.

  • New: GET /v1/receipts/export.csv?from=&to=&kind= returns issued documents over a date range as text/csv, covering the whole range rather than the newest 100.

New

Base mainnet is live

USDC and native ETH on Base mainnet now confirm. USDT on Base is registered but still not watched.

  • USDC and native ETH on Base mainnet now confirm. A Base listener runs in production; before today the tokens were registered but nothing watched the chain.

  • USDT on Base is still registered and NOT watched — a payment in it is accepted and never confirms. Only USDC and ETH are live.

  • Base is now a valid rail on a custom_amount product, alongside USDC on BNB, Sui and Arc.

New

Receipts and credit notes

Every payment that receives money now produces a numbered receipt with a public page, and every refund produces a credit note. Additive: nothing you already listen to changed shape.

  • New event family receipt.*: receipt.issued, receipt.supplemented, receipt.credit_note.issued. The event carries the document itself, including its public url.

  • New endpoints: GET /v1/payments/:id/receipts (the whole chain for one payment, with received, refunded and net), GET /v1/receipts (keyset walk, optional kind filter), GET /v1/receipts/:id.

  • New public endpoint GET /v1/public/receipts/:id — no API key. It is what the customer opens, and it strips reference.

  • A partial refund now issues a credit note and emits an event. Before this it emitted nothing, touched no row, and past the newest 100 refunds could not be found again.

  • GET /v1/public/invoices/:publicId now carries the latest receipt.

  • A merchant billing profile (the letterhead a receipt is issued under) is edited in the console under Settings → Business.

Breaking

The flow.* webhook filter is refused — use payment.flow.*

The webhook API used to accept the filter flow.*, which could never match any event. It is now rejected with 400. No delivery changes, because it never delivered anything.

Read the migration guide
  • The wildcard flow.* is no longer a valid eventTypes entry. Sending it to POST /v1/webhooks or an update now returns 400.

  • The flow family is offered as payment.flow.*, which is the prefix its three event types actually share (payment.flow.step, payment.flow.approved, payment.flow.rejected).

  • No endpoint starts or stops receiving anything: flow.* matched zero events, so a subscriber on it was already receiving nothing.

  • checkout.* and facilitator.* are unchanged and still accepted, even though their types share a longer prefix.

New

An event for money that moves no status, second payouts, and a reconciliation walk

Three gaps an integrator hit while building a recovery flow: money could land with no webhook, a second payout could not be attributed, and there was no way to find payments whose events you missed.

  • New event payment.amount_increased, in the payment.* family. It fires when more money lands on a payment whose status does not change — an underpaid payment topped up but still short, a further transfer onto an overpaid one, a manual recovery credit onto a confirmed one.

  • GET /v1/payments and GET /v1/sweeps gain updatedAfter, limit and a keyset cursor over (updatedAt, id), in the same envelope GET /v1/checkout/sessions already returned.

  • A page of that walk is clamped to rows older than a 60-second safety lag, so the cursor cannot advance past a row that was still committing.

  • settlement.completed carries the payout sequence and the lifetime total, so a second payout for the same payment can be attributed.

  • requiresManualPayout narrowed to what it says: a chain with no sweep support, a held sweep, or native SUI.

New@thru-payment/server 0.3.1

Amount-based products — a locked amount per checkout session

A product is now fixed or custom_amount. On a custom-amount product your server names the amount per checkout session, bounded by the product, and the shopper cannot change it. Additive: a fixed-price integration is untouched.

  • Product.pricingMode is fixed (unchanged) or custom_amount. A custom-amount product has no price; it has minAmount / maxAmount instead.

  • POST /v1/checkout/sessions accepts amount on a custom-amount product; POST /v1/public/products/:slug/checkout accepts it too, so the hosted page can let the shopper name it.

  • The amount is locked on the session and copied to the bound payment’s expectedAmount. No public redeem body accepts an amount — a test fails if one is ever added.

  • An amount outside the bounds is a 400 whose body carries minAmount, maxAmount and currency as fields. The effective minimum is max(the merchant’s, 0.01).

  • The checkout-session payload gains amount and currency. Both are null on a fixed-price session, so one handler reads either kind.

  • Every payment.* event and GET /v1/payments/:id now carry checkoutSession { id, reference, metadata } for a session-bound payment.

  • Idempotent create compares (source, amount): the same key with a different amount is a 409.

  • Every rail on a custom-amount product must be a token thru actually detects, refused at write time — enabledChains had been bypassing that check.

  • @thru-payment/server 0.3.1 is the published version and adds payments.retrieve.

New

Arc mainnet is on

Arc (Circle’s stablecoin L1) mainnet payments are now detected. Until this shipped, the console would let you create one and nothing would ever confirm it.

  • A mainnet listener for arc is running, so an Arc mainnet payment is detected, confirmed and swept like any other chain.

  • Arc chainId 5042 and the USDC contract were verified on chain before the listener was turned on.

  • Before this, arc was already offered in the console’s payment chains while no mainnet listener existed — an Arc mainnet payment could be created and would never be detected.

  • Chain RPC reads now rotate off endpoint rate limits (JSON-RPC -32005 / -32029) instead of treating them as the chain’s answer; a BNB detection stall on 2026-09-17 was caused by exactly that.

New

Multiple settlement addresses, routed per product

A merchant can hold several settlement addresses per chain and network, and route each product’s sales to one of them. Everything unrouted goes to that chain’s default. Additive: one address per chain keeps behaving exactly as before.

  • Several settlement addresses are allowed per (chain, network). Exactly one is the default for each; existing addresses became the defaults.

  • The routing key is the product, per (chain, network). Everything unrouted — including payments with no product, created through POST /v1/payments — goes to the default.

  • A new permission, settlement.route, governs routing. It can only choose among addresses that already went through settlement.write plus the cool-down, so it cannot introduce a new destination.

  • The cool-down survives, per address. A new address and a changed address both wait it out before a sweep can land there; an address inside its cool-down is never a destination, whatever routes to it.

  • Routing to an address that is already active takes effect immediately — that address was vetted when it activated.

  • Promoting a due address change is now conditional on the exact pending change that was read, so a cancel can no longer be overwritten by a racing promotion. The promotion is written to the merchant audit trail.

  • The console gets a routing board: drag a product onto an address, or use "Move to…".

Breaking@thru-payment/* 0.2.0

Direct Pay and subscriptions are removed

The recurring-billing product is gone: 13 endpoints, the subscription.* event family, six fields on the checkout-session payload, and the tables behind them. thru is a payments rail. This is the breaking change on this list.

Read the migration guide
  • All 11 merchant endpoints under /v1/direct-pay/* and both public ones are removed and return 404.

  • The subscription.* event family (activated, extended, expired, plan_change_scheduled, plan_changed) is removed from the catalogue. Nothing emits it.

  • Six fields leave the checkout-session payload: kind, subscriptionId, planId, payerAddress, subscriptionExpiresAt, periodSeconds. Use source (product | invoice) where you used kind.

  • POST /v1/products with kind: "subscription" is a 400. A legacy subscription product answers 410 on its public page and 409 on a checkout session; the row itself survives.

  • The tables are dropped. thru can no longer answer "who had access, until when" — an export was taken immediately before the migration ran.

  • @thru-payment/server, checkout-core and pay-sdk ship the break as 0.2.0. The removed fields are deleted from the types rather than deprecated-and-nulled, on purpose: the compiler is the only place you can be told.

  • @thru-payment/x402 is untouched. Agent payments are a separate rail.

  • A stored webhook filter naming subscription.* is now silently dropped when you save the endpoint, rather than refused — you did not make a typo, thru withdrew the events.