Refunds
Refund an order payment in full or in part, from the dashboard or the Merchant API. The refund follows the original payment.
A refund gives back part or all of what a customer paid for an order. You ask for it with
POST /orders/{order}/refunds; Queek decides where the money goes from the payment being refunded,
records it on the order, and tells you when it lands. The dashboard's Refund button calls the
same operation, so a refund made by hand and one made by an app look identical on the order.
The call needs the merchant-orders-refund-create scope. It moves money, so the scope is
review-required for apps and a store owner (or an admin granting a custom role) holds it by
default. See Scopes.
What a refund is
- One refund refunds one payment. An order can hold several payments (a split tender, or a
second payment after a failed one). Name the payment with
payment, or leave it out and Queek refunds the newest received payment that still has something left. To refund two payments, send two requests. - The amount is always yours to send.
amountis a decimal string in the order's currency ("2500.00"). It may not exceed what is left on that payment and on the order. Queek never computes it fromline_items. - It cannot be undone. Once a refund is created it is final.
Where the money goes
You never choose the destination. It follows the original payment:
| The payment was | The refund is | What happens |
|---|---|---|
| Collected by Queek through its payment provider (card or bank) | original_payment | Goes back to the customer's card or bank through the provider. Starts pending. |
| Paid from the customer's Queek wallet | wallet_credit | Credited back to the wallet straight away. |
| Collected on the store's own gateway account, or taken offline (cash, point of sale, bank transfer to the store) | recorded | Queek records the refund and moves no money: the store refunds the customer itself. |
The destination is the refund's type. A dev store refunds instantly and moves no
real money.
Request
curl -X POST https://api.usequeek.com/api/v1/merchant/orders/58213/refunds \
-H "X-Client-Key: sk_live_..." \
-H "Idempotency-Key: 0c9d1f55-6b7e-4a52-9e63-1d8a2f4c7b10" \
-H "Content-Type: application/json" \
-d '{
"amount": "2500.00",
"line_items": [{ "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "quantity": 1, "restock": true }],
"reason": "damaged",
"notify": true,
"note": "Tray arrived crushed."
}'| Field | Required | Meaning |
|---|---|---|
amount | yes | What to refund, a decimal string with no more decimals than the currency has. A refund back through the payment provider cannot be below 50.00 NGN. |
payment | no | The payment to refund, a payment id from the order's transactions. Without it, the newest received payment with something left. |
line_items | no | The lines refunded: order_item (a line id from the order), quantity, and restock (default true). Used to put tracked stock back and to cap the quantity per line. Never sets the amount. |
notify | no | Tell the customer when the refund lands (a notice and an email). Default true. |
reason | no | requested_by_customer, damaged, out_of_stock or other (default). For your records. |
note | no | Up to 500 characters, for your records. Never sent to the customer or in a webhook. |
pin | no | The store transaction PIN. Asked of a dashboard session that refunds money Queek holds (a wallet credit or a card or bank refund); ignored for API keys and apps. A refund that is only recorded needs none. |
Idempotency-Key is required on this call. A request without it answers
400 idempotency_key_required and nothing is refunded.
- The same key with the same body returns the refund already made.
- The same key with a different body is
409 idempotency_key_reuse. - Use one new key per refund and reuse it only to retry that same refund after a timeout or a network failure. A retry can never refund the customer twice.
See Idempotency & rate limits.
Response
A new refund answers 201; a repeat of the same key and body answers the same refund.
{
"status": "success",
"message": "Refund created",
"data": {
"id": 992002,
"order": 58213,
"transaction_id": 992001,
"type": "recorded",
"reason": "merchant_refund",
"status": "success",
"amount": "2500.00",
"currency": "USD",
"created_at": "2026-09-24T14:20:00+01:00",
"refundable": { "amount": "33300.00", "currency": "USD" },
"restocked": []
}
}| Field | Meaning |
|---|---|
id, order, transaction_id | The refund, the order, and the payment that was refunded (id in the order's transactions). |
type | original_payment, wallet_credit or recorded. |
reason | merchant_refund for a refund you asked for, order_cancelled for one made by a cancellation. |
status | pending, success or failed. |
refundable | What can still be refunded on the order after this one. |
restocked | The stock that went back on the shelf, one entry per product or variant; empty when nothing was restocked. |
Reading the order afterwards shows the same facts: refunds[] lists every refund with its type,
reason and status, refundable gives the amount still refundable, and each line carries
refundable_quantity. The order's payment_status moves to partially_refunded or refunded
once a refund succeeds. These read fields need the merchant-orders-read scope.
Statuses
| Status | Meaning |
|---|---|
success | The money is back (or, for a recorded refund, the refund is recorded). Wallet and recorded refunds are success immediately. |
pending | A card or bank refund the payment provider has accepted and not finished. |
failed | The refund did not happen. Nothing was taken from the customer's side or your balance, and the amount can be refunded again. |
Why a card or bank refund stays pending. The provider processes refunds in batches and the
bank then takes time to return the money. The refund is pending until the provider reports it
processed; the customer may wait up to 10 business days for the money to reach their account, and a
bank-transfer refund can need the customer's bank details at the provider first. A pending refund
already holds its amount: it counts against what is refundable, so you cannot refund the same money
twice.
Knowing when it finishes
refunds/createis sent once, when the refund is created, with its state at that moment (usuallypendingfor a card refund). It is sent for every kind of refund: wallet, card or bank, and recorded. There is no separate topic for a refund finishing.orders/updatedis sent when a card or bank refund finishes or fails. Re-read the order and look at the refund'sstatusinrefunds[].
See Webhooks. Delivery is at least once; a refund made before your app was
installed is read from the order's refunds list.
Who bears the cost
- The payment provider keeps its own fee on a card or bank payment; it is not refunded. On a refund made through the dashboard or the API, the store bears that fee's share: the share is debited from the store's balance along with the store's share of the refunded amount.
- A refund made by a cancellation (the customer or Queek cancelled the order) does not charge the store the provider's fee.
- Queek never fronts the money. The store's share comes out of a settlement not yet paid, or out of its balance. A balance can go negative; later settlements repay it, and a withdrawal is refused while it is negative.
Errors
A refusal answers in the one error envelope. Switch on error.code.
error.code | Status | Cause |
|---|---|---|
idempotency_key_required | 400 | No Idempotency-Key header was sent. |
idempotency_key_reuse | 409 | The key was already used with a different body. |
insufficient_scope | 403 | The key does not carry merchant-orders-refund-create. |
not_found | 404 | No such order in this store. |
validation_failed | 422 | The body is invalid; error.errors names the field. |
invalid_refund_amount | 422 | The amount is not positive or has more decimals than the currency. |
refund_amount_exceeds_refundable | 422 | More than what is left. data.refundable and data.currency give the most this request may ask for; data.payments gives what each payment can still give back. |
refund_amount_below_minimum | 422 | A refund through the payment provider is below the provider's smallest (data.minimum, data.currency). |
nothing_to_refund | 422 | Everything received has already been refunded. |
order_not_refundable | 422 | The order has received no payment to refund. |
refund_payment_not_found | 422 | payment is not a received payment of this order. |
refund_line_invalid | 422 | A line is not on this order, or asks for more than was ordered less what was already refunded. |
refund_provider_unavailable | 422 | Refunds back through the payment provider are switched off for now. Nothing was created. |
refund_provider_unsupported | 422 | The payment cannot be refunded through its provider (another provider, a currency other than NGN, or a payment taken into a store-specific account). |
refunds_disabled | 503 | Refunds are switched off. |
too_many_requests | 429 | More than 20 refund requests a minute for the store, or 5 a minute for one order. Honour Retry-After. |
Limits
- Capture and void are not offered: Queek charges the customer immediately, so there is no authorised-but-uncaptured payment to capture or void.
- There is no return workflow. A refund can put stock back, but there is no return request, receipt or inspection step, and no exchange.
- There is no store credit. A refund goes to the original payment or the customer's wallet.
- Refunds back through the payment provider are for payments Queek collected through the provider, in Naira, within the provider's window of one year from the payment.
- A
recordedrefund moves no money: the store refunds the customer outside Queek.