Skip to main content

Cancel Fulfillment Order

POST 
/api/fulfillment-orders/:fulfillmentOrder/cancel

Cancels the fulfillment order, releases its line budgets back to the parent sales-order lines (so a different fulfillment order can pick them up), and optionally records a reason. Sets status=cancelled + cancelled_at.

Required scope: orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Provider recall. If the fulfillment order has already been submitted to a shipping provider, cancelling first attempts to recall (cancel) it at the provider, then cancels it in SKU. Set local_only=true to skip the provider recall and cancel only in SKU — leaving any live provider order in place (use this when the provider can't or won't recall the order).

Mutability gate. Rejected if the fulfillment order is already terminal (status=closed/cancelled) or is currently in-flight with the provider (request_status=submitting/cancellation_requested).

Body fields:

  • reason (optional, string, max 1000) — stored for audit.
  • local_only (optional, boolean, default false) — cancel only in SKU without recalling the provider order.

Recall failure (409). When a provider recall fails, the response carries needs_local_only: true so you can retry with local_only=true. provider_unsupported is true when the provider has no cancel capability at all (the order can never be recalled automatically), and false when the order may already have shipped.

Required permission: fulfillment_orders.cancel (Fulfillment Orders → Cancel) and fulfillment_orders.index (Fulfillment Orders → View). A token also needs its orders scope; the owner needs these role permissions.

Request​

Responses​

OK

Response Headers
    Content-Type