Refunds and returns

Four ways to give a buyer their money back — refund, cancel, return, or exchange — and which one fits the situation you are actually in.

Throttle gives money back through four different mechanisms, and picking the wrong one is the most common source of “why didn’t the buyer get refunded?” tickets. They differ in what they touch: a refund moves money and nothing else; a return also tracks goods; a cancel settles the whole order; an exchange swaps goods and settles only the difference.

Which one do I use

If you only need the money to move, reach for a refund. Returns exist because someone needs to know a box is in transit and whether it arrived — that tracking is the whole point, and it costs you an approval step you don’t otherwise need.

Refunds

A refund is a single call against a captured payment. Omit amount to refund it all; pass one, in minor units, to refund part of it.

curl -X POST https://api.usethrottle.dev/api/v1/payments/pay_88ce.../refund \
  -H "X-API-Key: $THROTTLE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1500, "reason": "Goodwill — late delivery" }'

There is also an order-scoped form, POST /api/v1/orders/{id}/refund, which resolves the order’s captured payment for you. Both take the same body and both need the payment_refunds:write scope.

Partial refunds accumulate: refunding $15 twice against a $60 payment leaves $30 refundable. You cannot refund more than was captured — and on a partially captured payment the ceiling is what you captured, not what you authorized. See Authorize and capture for why those two figures differ.

Cancelling an order

Cancelling settles an order that is being abandoned rather than returned:

• Open authorizations are always voided. You never need to release a hold by hand.
• Captured money is only refunded if you ask, by passing refundCapturedPayments: true.

That default catches people out. A cancel on an order you already captured leaves the buyer’s money with you unless you opt in. The response includes a paymentActions array reporting what actually happened to each payment, which is the thing to assert on rather than assuming.

Returns

A return (RMA) tracks goods coming back, and issues the refund at the end. It moves through an explicit sequence:

requested → approve → approved → receive → received → complete → completed

reject (from requested) and cancel (from requested or approved) are the two ways out. Only requested, approved, received, and completed hold a returned quantity against the order — rejecting or cancelling frees it, so the buyer can open a fresh return for the same line later.

Throttle computes the refund figure when the return is opened, so you can show the buyer the exact number before anyone approves anything. It is what they actually paid for those units: the line subtotal, plus its tax, minus any discount on that line, minus that line’s share of any order-level discount — prorated across the returned quantity.

Completing a return does not guarantee a refund. If the order has no captured payment — an unpaid Net-N invoice, or an order captured outside Throttle — the return still moves to completed and no money moves. The API returns 200 either way. If you need to know money actually moved, check that refundPaymentId is set rather than trusting the status.

Full request and response shapes are in the developer docs.

Exchanges

An exchange is an alternative ending to a return: instead of refunding, you create a replacement order and settle only the difference. The return must be in approved or received, and it lands in completed like any other finished return.

Throttle charges the customer’s stored card when the replacement costs more, and refunds when it costs less.

Replacement items are not taxed. This path has no address-aware tax quote yet, so replacements are charged at list price. Because the difference is measured against what the buyer paid — which did include tax — an even swap produces a small refund roughly equal to the returned line’s tax. It favours the buyer, never you, but it is worth knowing about if you run high exchange volume.

What the buyer sees

Every mechanism above emits a webhook, and money reaching the buyer’s statement is the processor’s timeline, not ours — typically 5–10 business days for a card refund, regardless of how fast the API returned. Set that expectation in your own emails; a buyer who sees “refunded” in your UI and nothing in their bank for a week will contact you.

Last updated August 9, 2026