Order cancellation

Set when customers can cancel their own orders, and approve or decline the cancellations they ask for.

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

GET read_orders

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 (custom false). Omit for the store's rules.

Example: fd32d8a5-4a9c-4540-804f-1232e5aa306f

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 CANCEL_SETTINGS_INVALID

    A 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.

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

Update cancellation rules

PUT write_orders

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.

Example: fd32d8a5-4a9c-4540-804f-1232e5aa306f
enabled boolean

Customers can cancel their own orders.

Example: true
window_hours integer

Hours after placement, 1 to limits.window_hours_max.

Example: 24
clear_window boolean

true removes the time limit.

Example: false
payment string

all, cod or prepaid.

Example: all
refund_to string

original_payment or store_credit.

Example: original_payment
excluded_tag_ids array<integer>

Product tags whose orders customers can't cancel; at most limits.excluded_tags_max.

Example: [42]
group_mode string

all, only (just group_ids) or except (everyone but group_ids).

Example: all
group_ids array<uuid>

Customer groups for group_mode; at most limits.groups_max.

Example: []
reasons array<string>

Reasons customers can choose: changed_mind, ordered_by_mistake, found_better_price, delivery_too_slow, wrong_details, other.

Example: ["changed_mind","ordered_by_mistake","other"]
reason_required boolean

Customers must choose a reason.

Example: false
status_page boolean

Anyone with the order's status link can cancel, signed in or not.

Example: false
fulfillment_cutoff string

before_work, before_booking or before_shipping.

Example: before_booking
max_order_value string

Largest order total customers can cancel, in the store's currency.

Example: 5000.00
clear_max_order_value boolean

true removes the order value cap.

Example: false
mode string

instant (cancel at once) or request (the merchant approves or declines).

Example: instant
limit_enabled boolean

Limit how many orders one customer can cancel; needs limit_max.

Example: false
limit_max integer

Cancellations per customer in the window, 1 to limits.limit_max_max.

Example: 3
limit_window_days integer

Days the limit counts over, limits.limit_window_days_min to limits.limit_window_days_max.

Example: 90
limit_action string

Over the limit: review (hold for the merchant) or hide (don't offer cancellation).

Example: review
fee_type string

none, fixed (needs fee_amount) or percent (needs fee_percent).

Example: fixed
fee_amount string

Fixed fee in the store's currency, at most 2 decimals.

Example: 50.00
fee_percent string

Percentage of the order total, above 0 and at most limits.fee_percent_max, at most 2 decimals.

Example: 10
fee_free_hours integer

No fee within this many hours of placement, 1 to limits.fee_free_hours_max.

Example: 2
clear_fee_free_hours boolean

true removes the free period.

Example: false
channels array<string>

Sales channel types whose orders customers can cancel: online_store, marketplace, social, advertising, manual. At least one.

Example: ["online_store"]

Errors

  • 400 CANCEL_SETTINGS_INVALID

    A 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.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Remove a market's cancellation rules

DELETE write_orders

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.

Example: fd32d8a5-4a9c-4540-804f-1232e5aa306f

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 INVALID_INPUT

    market_id is missing or invalid.

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

List cancellation requests

GET read_orders

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.

Example: requested
limit integer

Page size, 1 to 100 (default 50).

Example: 50
cursor string

next_cursor of the previous page.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 INVALID_INPUT

    status, limit or cursor is invalid.

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

Get an order's cancellation request

GET read_orders

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.

Example: da9b07a6-803f-4e41-8a18-97ff831bd588

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 ORDER_NOT_FOUND

    The order does not exist in this store.

Approve a cancellation request

POST write_orders

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.

Example: da9b07a6-803f-4e41-8a18-97ff831bd588

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 ORDER_NOT_FOUND

    The order does not exist in this store.

  • 409 ORDER_CANCEL_REQUEST_NOT_OPEN

    The order has no cancellation request waiting for a decision.

  • 400 ORDER_CANCEL_FULFILLED_BLOCKED

    A shipment has left since the customer asked: the order can no longer be cancelled. Decline the request.

Decline a cancellation request

POST write_orders

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.

Example: da9b07a6-803f-4e41-8a18-97ff831bd588

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.

Example: Your order is already packed.

Errors

  • 404 ORDER_NOT_FOUND

    The order does not exist in this store.

  • 409 ORDER_CANCEL_REQUEST_NOT_OPEN

    The order has no cancellation request waiting for a decision.

  • 400 INVALID_INPUT

    reason is longer than 500 characters.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.