Unfulfill Order

Reverses a previous fulfillment, returning items to allocated status.

When to Unfulfill

Use this endpoint when:

  • Items were fulfilled in error
  • Stock is discovered to be unavailable after fulfillment
  • The fulfillment needs to be reassigned to another location
  • A shipment was cancelled before pickup

Request Requirements

You must provide:

  • fulfillment_ids: Array of fulfillment IDs to reverse (required)
  • The fulfillment IDs must exist in the fulfillment order's fulfilled line items

Effects

When you unfulfill:

  1. Associated shipments are cancelled (if not already cancelled)
  2. Line items return to allocated status
  3. Fulfillment ID, shipment IDs, and partner reference are cleared from items
  4. Items with the same ID and status are merged
  5. Order status is recalculated
  6. Webhooks are triggered

Inventory Impact

If inventory management is enabled:

  • on_hand is increased by the unfulfilled quantity (restoring stock)
SecurityOAuth2-Production or OAuth2-Demo
Request
path Parameters
orderReference
required
string

The order reference (order_id or partner_order_reference based on the key parameter).

fulfillmentOrderId
required
string

The unique identifier of the fulfillment order.

query Parameters
key
string
Default: "order_id"

Specifies which reference type is being used for the order reference.

Enum: "order_id" "partner_order_reference"
header Parameters
x-api-key
required
string

Your Carriyo API key for authentication.

tenant-id
required
string

Your unique tenant identifier in Carriyo.

Content-Type
string
Default: application/json
Request Body schema: application/json
required
fulfillment_ids
Array of strings

List of fulfillment IDs to reverse.

partner_fulfillment_order_reference
string

Partner reference to identify the fulfillment to reverse.

Responses
200

Fulfillment reversed successfully.

400

Cannot unfulfill - items may already be shipped.

404

Order or fulfillment order not found.

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/unfulfill
Request samples
application/json
{
  • "fulfillment_ids": [
    ],
  • "partner_fulfillment_order_reference": "string"
}
Response samples
application/json
{
  • "tenant": "string",
  • "order_id": "string",
  • "merchant": "string",
  • "partner_order_reference": "string",
  • "language": "string",
  • "order_date": "2019-08-24T14:15:22Z",
  • "sales_channel": "string",
  • "creation_source": {
    },
  • "update_source": {
    },
  • "carriyo_metadata": [
    ],
  • "status": "open",
  • "auto_allocation_failed": true,
  • "cancellation_reason": "CUSTOMER_CANCELLATION",
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "customer": {
    },
  • "payment": {
    },
  • "redacted": true,
  • "taxes_included": true,
  • "duties_included": true,
  • "discount_applications": [
    ],
  • "line_items": [
    ],
  • "fulfillment_orders": [
    ],
  • "shipping_lines": [
    ],
  • "error_details": [
    ],
  • "creation_date": "2019-08-24T14:15:22Z",
  • "update_date": "2019-08-24T14:15:22Z"
}