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

Last updated: September 17, 2026

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",
    ...
  }
}