Refund a sale
Refunds a completed sale. Its works are re-derived and its pending payables are voided in the same request. A payable already paid stays paid; the answer lists it under `payables_paid`, so the money can be recovered from the payee. A payable with a Stripe payout in flight is listed under `payables_in_flight`; it lands paid or voids once the transfer settles. This records the refund only; it moves no money. Any status but completed answers 409.
Refunds a completed sale. Its works are re-derived and its pending payables are voided in the same request. A payable already paid stays paid; the answer lists it under payables_paid, so the money can be recovered from the payee. A payable with a Stripe payout in flight is listed under payables_in_flight; it lands paid or voids once the transfer settles. This records the refund only; it moves no money. Any status but completed answers 409.
Authorization
bearerAuth sales:update, payables:readA gallery API key, sent as Authorization: Bearer gpk_… (or the x-api-key header).
In: header
Scope: sales:update, payables:read
Path Parameters
The sale id.
Query Parameters
Preview this operation without committing it. When true, the request is authenticated, scoped, and validated, but no side effect runs — no write, no idempotency claim, no audit event, no outbound delivery. The response is HTTP 200 with an X-Dry-Run: true header and a body of { "dry_run": true }, plus an effect object describing what the real call would change when this operation can resolve one.
Header Parameters
Optional. Send a unique key per logical operation to make retries safe: a retry with the same key replays the stored success for 14 days instead of re-running the write. Reusing a key with a different body returns 400.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Refund a completed sale.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
{ "sale": { "id": "string", "buyer_contact_id": "string", "sold_by": "string", "status": "draft", "currency": "string", "sale_date": "string", "gross_cents": -9007199254740991, "discount_cents": -9007199254740991, "net_cents": -9007199254740991, "fx_as_of": "string", "fx_usd_per_unit": 0, "fx_base_currency": "string", "fx_base_usd_per_unit": 0, "base_amount_cents": -9007199254740991, "notes": "string", "metadata": { "property1": "string", "property2": "string" }, "created_at": "string", "updated_at": "string", "items": [ { "id": "string", "artwork_id": "string", "list_price_cents": -9007199254740991, "discount_cents": -9007199254740991, "sold_price_cents": -9007199254740991, "consignor_share_bps": 0, "consignee_share_bps": 0, "third_party_share_bps": 0, "consignor_net_price_cents": 0, "metadata": { "property1": "string", "property2": "string" }, "created_at": "string" } ] }, "payables_voided": [ { "id": "string", "sale_id": "string", "sale_item_id": "string", "artwork_id": "string", "payee_contact_id": "string", "payee_name": "string", "kind": "consignor", "status": "pending", "amount_cents": -9007199254740991, "currency": "string", "basis_bps": 0, "basis_amount_cents": -9007199254740991, "paid_amount_cents": -9007199254740991, "paid_at": "string", "notes": "string", "metadata": { "property1": "string", "property2": "string" }, "created_at": "string", "updated_at": "string" } ], "payables_paid": [ { "id": "string", "sale_id": "string", "sale_item_id": "string", "artwork_id": "string", "payee_contact_id": "string", "payee_name": "string", "kind": "consignor", "status": "pending", "amount_cents": -9007199254740991, "currency": "string", "basis_bps": 0, "basis_amount_cents": -9007199254740991, "paid_amount_cents": -9007199254740991, "paid_at": "string", "notes": "string", "metadata": { "property1": "string", "property2": "string" }, "created_at": "string", "updated_at": "string" } ], "payables_in_flight": [ { "id": "string", "sale_id": "string", "sale_item_id": "string", "artwork_id": "string", "payee_contact_id": "string", "payee_name": "string", "kind": "consignor", "status": "pending", "amount_cents": -9007199254740991, "currency": "string", "basis_bps": 0, "basis_amount_cents": -9007199254740991, "paid_amount_cents": -9007199254740991, "paid_at": "string", "notes": "string", "metadata": { "property1": "string", "property2": "string" }, "created_at": "string", "updated_at": "string" } ]}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}List a sale's payables GET
Lists the payables generated from a sale's consigned lines.
Get a sale's three-way split breakdown GET
Returns the per-party split of a sale, net of production costs: the consignor and third-party legs (mirroring the generated payables) plus the gallery's residual consignee share, with amounts booked at the sale's frozen rate. A missing or unauthorized sale is a 404.