Skip to main content
POST
Create refund with restock_all_items accounting for existing partial refunds

Authorizations

Authorization
string
header
required

Bearer token authentication

Headers

Idempotency-Key
string

Optional client-generated key (UUID recommended) that makes a resend safe. A refund pays money out, so a client that resends after losing a response should send the same key. The key is stored with the refund it records, for that order. Resending the same request under the key answers with that refund and records nothing more; a different request under the key answers 422. The key must be 1 to 255 characters, or the request answers 422. A request that is refused records nothing, so the same key can send the corrected request.

Body

application/json
order_id
integer
required

ID of the order to refund.

type
enum<string>
required

Which portion of the order to refund.

Available options:
all,
tax,
shipping,
product_price,
cv,
qv,
partial
reason
string

Optional human-readable reason for the refund.

amount
number<float>

Cash amount to refund. It is ignored for cv and qv; to refund cash and volume together, send type: partial with cv or qv. A partial refund of 0 must reverse cv or qv or set refund_points, unless the order has no payment method and no original payment.

Required range: x >= 0
shipping
number<float>

Shipping amount to refund. With type: shipping it is the amount refunded. With all, cv or qv it is added to the refund, whose total cannot pass what the order has left to refund. An all, cv or qv refund that resolves to partial ignores it, and so do the other types.

Required range: x >= 0
tax
number<float>

Tax amount to refund. With type: tax it is the amount refunded. With all, cv or qv it is added to the refund, whose total cannot pass what the order has left to refund, though a cv or qv refund that also sends shipping uses only the shipping. An all, cv or qv refund that resolves to partial ignores it, and so do the other types.

Required range: x >= 0
cv

CV (commissionable volume) to deduct with the refund. A cv refund must send more than 0, and the order must have been paid.

Required range: x >= 0
qv

QV (qualifying volume) to deduct with the refund. A qv refund must send more than 0, and the order must have been paid.

Required range: x >= 0
restock_all_items
boolean

When true, restock every remaining (not-yet-refunded) order item. A cv or qv refund returns no goods and ignores it.

restock_items
object[]

Specific items to restock; ignored when restock_all_items is true, and by a cv or qv refund.

refund_points
boolean

When true and the order was paid with a split card+points payment, refund redeemed points back to the customer. No-op if the order has no points portion or points have already been refunded. Most companies get back every redeemed point not yet returned. For a company whose refunds return points in proportion to the money refunded, type all still returns every point left, and any other refund, product_price included, returns the share of the base's card money it gives back, so tax and shipping return none when points apply to the subtotal. Shares are counted with the earlier refunds that asked for points back and rounded down to whole points. There, a refund that refunds no money, reverses no CV or QV and would return no points is refused with 422.

cancel_order
boolean

Whether this refund also ends the sale. When true and the refund leaves the order fully refunded and still unshipped, the order is cancelled. Omit the field to take the company default; send false to refund without cancelling, as for a goodwill refund on an order that should still ship. Sending true needs orders.delete.

Response

object | null

Refund created. order is the refunded order.

refund
object | null
meta
object | null