Refund order payment
Refund a paid order via Stripe. Supports full and partial refunds.
Requires write access, and refunds must be enabled for your workspace and on the platform — the endpoint returns 404 while refunds are not enabled; contact support to enable them. The customer is refunded first; the platform fee is adjusted for the refunded amount.
Idempotency: when idempotencyKey is omitted, a key is derived from the request (amount, reason, metadata) and the order’s refund state at request time. That protects true retries of an identical request, but a keyless retry after a lost response can be treated as a new request (and refund twice) once the first refund has applied — always send a stable idempotencyKey for retries. Repeating a non-exhausting partial refund with the same idempotencyKey returns the original refund and makes no further changes (no duplicate refund, status change, or notification). A repeat that would now be rejected by a fresh eligibility check — a full refund, an exhausting partial, or one exceeding the currently refundable amount — returns 400 instead; retry with a smaller/different request, or contact support to confirm the original refund’s status.
Path Parameters
PATCH /v0/orders/:orderIdOrNumber/refund Parameter
Body
PATCH /v0/orders/:orderIdOrNumber/refund Request body
x <= 9007199254740991duplicate, fraudulent, requested_by_customer Optional caller-supplied Stripe idempotency key. Prefer this when retrying after a lost response — a keyless retry of a partial refund can double-refund once amount_refunded has changed.
1 - 255