How do I hold, release, cancel, or mark a fulfillment order as shipped via the External API?

Fulfillment order status actions — External V1 API

Feature flag required. These four endpoints are only available on tenants where the fulfillment order status API feature has been enabled. When the feature is off the endpoints return 404. Contact support to request access.

The External V1 API exposes four action endpoints that change a fulfillment order's status. Each one applies the same business logic as the manual UI: inventory pending counts are adjusted, a shipment record is created on ship, and every change is recorded in the activity log.

Endpoints

Action	Method + path	What it does
Hold	`POST /external/api/v1/fulfillment-orders/{id}/hold`	Moves the order to On Hold
Release	`POST /external/api/v1/fulfillment-orders/{id}/release`	Returns the order to Pending
Cancel	`POST /external/api/v1/fulfillment-orders/{id}/cancel`	Cancels the order
Mark as shipped	`POST /external/api/v1/fulfillment-orders/{id}/mark-shipped`	Marks the order shipped, optionally recording carrier details

All four require standard External API authentication.

Allowed transitions

The API validates the current status before applying each action and returns a descriptive 422 if the transition is not allowed.

Action	Allowed from
Hold	Pending, Awaiting Shipment, Error
Release	On Hold
Cancel	Pending, Awaiting Shipment, On Hold, Error
Mark as shipped	Pending, Awaiting Shipment, On Hold, Error

Shipped and Cancelled are terminal states — no further status changes are accepted from either.

Mark as shipped — optional body

{
  "tracking_number": "1Z999AA10123456784",
  "carrier_code": "ups"
}

Both fields are optional. If omitted the shipment is created without carrier details.

Response

All four endpoints return the updated FulfillmentOrderResource on success (200). Error responses:

404 — fulfillment order not found, or the feature is not enabled for this tenant
422 — transition not allowed (message explains why, e.g. "Fulfillment order has already shipped and can no longer be changed.")

Example — place an order on hold

POST /external/api/v1/fulfillment-orders/8421/hold
Authorization: Bearer <token>

{
  "data": {
    "id": 8421,
    "order_status": "on_hold",
    ...
  }
}