Customers can cancel their own orders from their account or the order status page when the store turns it on. The cancellation settings hold the rules: a time limit, how far fulfilment may have gone, payment type, sales channels, an order value cap, customer groups and excluded product tags, for the store and for any market with its own rules. Reads use read_orders; every change uses write_orders.
With mode instant, an order every rule allows is cancelled at once. With mode request, the customer asks instead: a cancellation request waits as requested until the store approves it, which cancels the order and returns what was paid to the request's refund_to, or declines it with an optional reason the customer sees. An order has at most one request, and a declined one cannot be asked again.
With limit_enabled, a customer with more than limit_max cancellations in limit_window_days is held for review (limit_action review: the request carries limit_flag with the count, the limit and the period) or is not offered cancellation at all (hide).
A request fires orders/cancellation_requested; a decline fires orders/cancellation_declined; a cancelled order fires orders/cancelled with the customer's reason.
Endpoints#
Get cancellation rules
Read when customers can cancel their own orders.
With enabled, a signed-in customer can cancel an order from their account, and with status_page anyone holding the order's status link can too. Each rule must allow it: window_hours from placement (null: no limit); payment all, cod (cash on delivery orders only) or prepaid; the order's channel_type in channels; its base-currency total at most max_order_value (null: no cap, currency is the store's); no product carrying one of excluded_tag_ids; group_mode only or except the customers in group_ids; and fulfillment_cutoff: before_work (nothing started), before_booking (no shipment or pickup yet) or before_shipping (until a parcel leaves). An order with a Gift Card line is never cancelled by its customer. The customer chooses one of reasons (needed with reason_required); money already paid goes to refund_to, original_payment or store_credit (Store Credit only for orders with a customer account). A cancellation fee is kept from the refund with fee_type fixed (fee_amount in the store's currency, converted at the order's rate) or percent (fee_percent of the order total); none keeps nothing. No fee within fee_free_hours of placement (null: no free period), and never more than was paid, so orders nobody has paid for are cancelled without one. The customer sees the fee before confirming. With mode request the customer asks and the merchant approves or declines (cancellation requests below); instant cancels at once. With limit_enabled, a customer with more than limit_max cancellations in limit_window_days (this one included) is held for the merchant's decision (limit_action review) or not offered cancellation (hide). An order whose request was declined can't be requested again. market_rules lists the markets with their own rules; reason_options and channel_options word every value in the request language. Cancellation fires orders/cancelled with the customer's reason.
Query parameters
| Name | Type | Description |
|---|---|---|
market_id
|
uuid |
A market: its own rules, or the store's rules it follows ( |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400CANCEL_SETTINGS_INVALIDA value is outside its bounds in limits, limit_enabled is set with no limit_max, a tag or customer group isn't the store's, group_mode only/except has no groups, channels is empty, reason_required is set with no reasons, or market_id isn't one of the store's markets.
-
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
Update cancellation rules
Change the store's rules, or a market's.
Send the fields to change; the rest keep their value. With market_id, the market gets its own rules, starting from the store's on the first save; delete them to follow the store's again. clear_window removes the time limit, clear_max_order_value the order value cap and clear_fee_free_hours the free period.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
market_id
|
uuid |
The market whose own rules to save; omit for the store's. |
enabled
|
boolean |
Customers can cancel their own orders. |
window_hours
|
integer |
Hours after placement, 1 to limits.window_hours_max. |
clear_window
|
boolean |
true removes the time limit. |
payment
|
string |
all, cod or prepaid. |
refund_to
|
string |
original_payment or store_credit. |
excluded_tag_ids
|
array<integer> |
Product tags whose orders customers can't cancel; at most limits.excluded_tags_max. |
group_mode
|
string |
all, only (just group_ids) or except (everyone but group_ids). |
group_ids
|
array<uuid> |
Customer groups for group_mode; at most limits.groups_max. |
reasons
|
array<string> |
Reasons customers can choose: changed_mind, ordered_by_mistake, found_better_price, delivery_too_slow, wrong_details, other. |
reason_required
|
boolean |
Customers must choose a reason. |
status_page
|
boolean |
Anyone with the order's status link can cancel, signed in or not. |
fulfillment_cutoff
|
string |
before_work, before_booking or before_shipping. |
max_order_value
|
string |
Largest order total customers can cancel, in the store's currency. |
clear_max_order_value
|
boolean |
true removes the order value cap. |
mode
|
string |
instant (cancel at once) or request (the merchant approves or declines). |
limit_enabled
|
boolean |
Limit how many orders one customer can cancel; needs limit_max. |
limit_max
|
integer |
Cancellations per customer in the window, 1 to limits.limit_max_max. |
limit_window_days
|
integer |
Days the limit counts over, limits.limit_window_days_min to limits.limit_window_days_max. |
limit_action
|
string |
Over the limit: review (hold for the merchant) or hide (don't offer cancellation). |
fee_type
|
string |
none, fixed (needs fee_amount) or percent (needs fee_percent). |
fee_amount
|
string |
Fixed fee in the store's currency, at most 2 decimals. |
fee_percent
|
string |
Percentage of the order total, above 0 and at most limits.fee_percent_max, at most 2 decimals. |
fee_free_hours
|
integer |
No fee within this many hours of placement, 1 to limits.fee_free_hours_max. |
clear_fee_free_hours
|
boolean |
true removes the free period. |
channels
|
array<string> |
Sales channel types whose orders customers can cancel: online_store, marketplace, social, advertising, manual. At least one. |
Errors
-
400CANCEL_SETTINGS_INVALIDA value is outside its bounds in limits, limit_enabled is set with no limit_max, a tag or customer group isn't the store's, group_mode only/except has no groups, channels is empty, reason_required is set with no reasons, or market_id isn't one of the store's markets.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Remove a market's cancellation rules
The market's orders follow the store's rules again.
Returns the store's rules the market now follows (custom false).
Query parameters
| Name | Type | Description |
|---|---|---|
market_id
required
|
uuid |
The market. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400INVALID_INPUTmarket_id is missing or invalid.
-
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
List cancellation requests
Customers' requests to cancel their orders, newest first.
A request exists when the rules use mode request, or held a customer over the cancellation limit (limit_flag). status is requested (waiting for the merchant), approved (the order was cancelled) or declined. Pass next_cursor back as cursor for the next page.
Query parameters
| Name | Type | Description |
|---|---|---|
status
|
string |
requested (default), approved, declined or all. |
limit
|
integer |
Page size, 1 to 100 (default 50). |
cursor
|
string |
next_cursor of the previous page. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400INVALID_INPUTstatus, limit or cursor is invalid.
-
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
Get an order's cancellation request
The order's latest cancellation request.
cancellation_request is null when the customer never asked.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Order id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404ORDER_NOT_FOUNDThe order does not exist in this store.
Approve a cancellation request
Cancel the order as the customer asked.
The order is cancelled with the customer's reason, and money already paid goes where the request says (refund_to), less fee_amount when the request carries a cancellation fee. The customer gets the order cancelled email. Fires orders/cancelled.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Order id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404ORDER_NOT_FOUNDThe order does not exist in this store.
-
409ORDER_CANCEL_REQUEST_NOT_OPENThe order has no cancellation request waiting for a decision.
-
400ORDER_CANCEL_FULFILLED_BLOCKEDA shipment has left since the customer asked: the order can no longer be cancelled. Decline the request.
Decline a cancellation request
Keep the order and tell the customer.
The order continues and its status page shows the customer the decision with reason. The customer can't ask again for this order. Fires orders/cancellation_declined.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Order id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
reason
|
string |
What the customer is told, at most 500 characters. |
Errors
-
404ORDER_NOT_FOUNDThe order does not exist in this store.
-
409ORDER_CANCEL_REQUEST_NOT_OPENThe order has no cancellation request waiting for a decision.
-
400INVALID_INPUTreason is longer than 500 characters.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.