Cancellations, Refunds & Returns

Three different actions, often confused. Pick by where the goods are:

The goods are…	Use	Result
Still with you	Cancel	Order closed, pending work stopped, stock optionally returned
With the customer	Return	Tracked request → refund → restock
Irrelevant — you just owe money back	Refund	Payment record adjusted

---

Cancelling an order

Cancelling stops everything that hasn't shipped, without rewriting what already did.

Only Open orders can be cancelled. An already-cancelled order fails with ORDER_ALREADY_CANCELLED; an archived one with ORDER_NOT_CANCELLABLE.

What happens, in order:

1. The order is marked Cancelled with the reason you chose (items unavailable, out of stock, payment issue, fraud, staff error, other).
2. The payment is settled:
   • Authorized (awaiting screenshot approval) → voided, releasing the hold.
   • Paid or Partially refunded, and you ticked refund remaining amount → the still-captured balance is refunded.
   • Unpaid, failed, expired, already voided or refunded → nothing to do.
3. Unshipped fulfillment work is closed. Items not yet shipped are marked removed; items already shipped keep their status, so the record stays honest about what physically left.
4. Stock is returned if you ticked restock items — and only for the unshipped remainder. Units already shipped are not restocked, because they've left your warehouse.
5. Digital downloads are revoked.
6. The customer is emailed, unless you turned that off for the order or disabled cancellation emails in your store's notification settings.

This is the right tool for a refused COD delivery

An unpaid COD order has nothing to refund. Cancel it with restock items ticked.

---

Returns

Use a return when the customer already has the goods and is sending them back. Unlike a bare refund, a return is a tracked request with its own lifecycle.

Eligibility

Rule	Detail
Payment must be Paid or Partially paid	Otherwise PAYMENT_NOT_ELIGIBLE_FOR_REFUND
Within 14 days of the order	Otherwise RETURN_WINDOW_EXPIRED. The window is fixed and not configurable.
Only items that were actually shipped	You can't return more units than were fulfilled (INVALID_RETURN_QUANTITY)
One return per order	A second request fails with RETURN_ALREADY_EXISTS

Statuses

Pending → Processing → Refunded → optionally Restocked. A return can be Cancelled while it's still Pending or Processing; after that it's fixed (RETURN_INVALID_STATE).

Cancelling a return unlinks it from the order, so a fresh return can be raised.

Refunding a return

The refund amount is computed from the returned items, plus shipping if you tick refund shipping. If you pass an amount that doesn't match, the request is rejected with the expected figure in the message — a guard against a fat-fingered refund.

Restocking

Restocking is a separate step from refunding, and only runs when the return was created with restock enabled. It can only run once (RESTOCK_ALREADY_PROCESSED). Custom items — lines that aren't real catalog products — are skipped.

Do it when the goods physically arrive back, not when the refund is issued.

---

Refunds

A direct refund adjusts the payment without a return record. Full rules are in How payments work; the essentials:

• Only Paid or Partially refunded payments can be refunded.
• Never more than was collected — enforced at write time, so simultaneous refunds can't both slip through.
• The same item and quantity can't be refunded twice.
• Refunding everything → Refunded; part → Partially refunded.
• You choose the refund method — the original method, or something else like cash or store credit.

The money doesn't move by itself

TakeTheme records the refund; it does not call your gateway's refund API. Issue the refund in Kashier, Paymob, PayTabs, PayPal, or Stripe, then record it here so reporting matches.

---

API reference

Action	Endpoint
Cancel an order	POST /v1/order/vendor/cancel/:orderId
Archive an order	POST /v1/order/vendor/archive/:orderId
Create a return	POST /v1/order/:orderId/returns
Refund a return	POST /v1/order/:orderId/returns/refund
Restock a return	POST /v1/order/:orderId/returns/restock
Cancel a return	POST /v1/order/:orderId/returns/cancel

---

Related

• Order lifecycle
• Editing orders — removing items refunds automatically
• How payments work