Fulfill Order

Marks items in a fulfillment order as fulfilled and creates a shipment.

Line Item Status Requirements

Only items in pending status (open or allocated) can be fulfilled:

  • open - Item awaiting allocation
  • allocated - Item assigned to a location
  • fulfilled - Already fulfilled
  • cancelled - Cannot be fulfilled
  • closed - Cannot be fulfilled

Fulfillment Process

When you fulfill an order:

  1. Validates that requested line items exist and are in pending status
  2. Validates that requested quantities don't exceed available quantities
  3. Creates a shipment (unless skip_shipping=true)
  4. Marks line items as fulfilled with a unique fulfillment ID
  5. Updates order status based on overall fulfillment progress
  6. Triggers webhooks

Line Items (Required)

You must provide line_items array specifying which items to fulfill:

  • Each item needs id matching an order line item
  • Each item needs quantity to fulfill (must be ≤ pending quantity)

Shipment Creation

Control shipment creation with query parameters:

  • create_draft_shipment=true: Creates a draft shipment for review before carrier booking
  • skip_shipping=true: Fulfills without creating any shipment (items auto-close)

Inventory Impact

If inventory management is enabled with stock_reduction_timing = ON_ORDER_FULFILLED:

  • on_hand is reduced by the fulfilled quantity
  • reserved is reduced by the fulfilled quantity

If shipping is not required (or skip_shipping=true), items are automatically set to closed status.

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"
create_draft_shipment
boolean
Default: false

If true, creates a draft shipment instead of immediately booking with a carrier.

skip_shipping
boolean
Default: false

If true, fulfills the order without creating a shipment.

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
optional
partner_fulfillment_reference
string

Your system's reference for this fulfillment.

Array of objects (Fulfillment Order Line Item Request)

Specific line items to fulfill. Omit to fulfill all pending items.

object (Carrier Account Request)
Array of objects (Parcel Request)

Parcel details for the shipment.

object (Fulfillment Delivery)
object (Fulfillment Payment)
object (Pre-Booking Info)
Responses
200

Fulfillment order fulfilled successfully.

400

Invalid request or fulfillment not possible.

404

Order or fulfillment order not found.

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/fulfill
Request samples
application/json
{
  • "partner_fulfillment_reference": "string",
  • "line_items": [
    ],
  • "carrier_account": {
    },
  • "parcels": [
    ],
  • "delivery": {
    },
  • "payment": {
    },
  • "pre_booking_info": {
    }
}
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"
}