Settle an approved order claim
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Path Parameters
Body
Takes no parameters, and an empty body is expected. THIS IS THE CALL THAT MOVES REAL MONEY, and it is LEGAL ONLY FROM approved. ON A refund-TYPE CLAIM it reverses the captured charge for the figure computed when the claim was OPENED, an integer in the MINOR UNITS of the order's currency, split at settle time: the card takes back only what it actually charged (the order total less what gift cards, store credit and loyalty paid), and the tender-funded remainder is returned to the customer as store credit. The amount is never the caller's to choose, which is what keeps a settlement on the same grant as the rest of this family: the token decides WHETHER to settle and never HOW MUCH. On an order with no customer record the tender-funded remainder cannot be credited to anybody, so it is recorded in the store's audit log rather than paid, and the claim still resolves. ON A replace-TYPE CLAIM no money moves at all; the replacement fulfillment is what is triggered instead. THE MONEY MOVES BEFORE THE STATUS FLIPS, so a failed settlement leaves the claim APPROVED and returns the failure rather than a 500: 409 not_refundable when the order has no captured payment to reverse, and 409 refund_exceeds_charge when earlier refunds against it have already taken part of the charge. Read the claim back to see where it ended up. WHAT A RETRY DOES. Replaying the SAME Idempotency-Key answers the stored response and re-runs nothing, so one key cannot settle twice. A FRESH key on a claim that already resolved answers 409 invalid_transition under the same row lock rather than paying again. A fresh key after a settlement that moved money but lost the status flip is safe as well: the card refund is keyed on this claim id and the store credit on its own claim reference, so the provider is not charged a second time and the retry only finishes the transition. resolved_at is stamped the first time the claim enters resolved. The claim resource publishes no money and no currency, so what was actually paid is read from the order under read_orders rather than from here. IT EMAILS THE SHOPPER, on the same terms as the approve route: a claim opened through this API cannot suppress the mail, and the mail is best effort, so a 200 is not evidence of delivery. THE BODY IS READ ONLY TO REFUSE IT, and refund_amount and refund_amount_minor are refused BY NAME here above all: a client that sent a figure would otherwise get a plain resolve answering 200 and would believe it had chosen how much the shopper was paid. status and reason are refused too. The response is the WHOLE claim in the shape GET /api/v1/order-claims/{claimId} serves.
Response
Success