Ship Fulfillment Order

Creates a shipment for items in a fulfillment order.

Line Item Status Requirements

Items must be in allocated or fulfilled status:

  • ✅ allocated - Can be shipped
  • ✅ fulfilled - Can be shipped (additional shipment)
  • ❌ open - Must be allocated first
  • ❌ cancelled - Cannot be shipped
  • ❌ closed - Cannot be shipped

Request Requirements

  • line_items (required): Array of items to ship with quantities

Shipping Process

This endpoint:

  1. Validates that requested items exist in allocated or fulfilled status
  2. Validates that requested quantities don't exceed available quantities
  3. Creates a draft shipment in the Carriyo Shipping API
  4. Confirms the shipment with the carrier (unless create_draft_shipment=true)
  5. Links the shipment ID to the specified line items
  6. Triggers webhooks

Shipment Configuration

Configure the shipment with:

  • Carrier Account: Specify carrier or let automation rules decide
  • Parcels: Dimensions, weights, and contents
  • Delivery: Instructions and scheduling preferences
  • Payment: Cash on delivery and payment details
  • Pre-booking: For externally booked shipments

Draft Shipments

Set create_draft_shipment=true to create a draft for review before booking with the carrier.

Inventory Impact

No direct inventory changes occur - inventory is managed during fulfill/cancel operations.

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.

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
Array of objects (Fulfillment Order Line Item Request)

Specific fulfilled items to ship. Omit to ship all fulfilled items.

object (Carrier Account Request)

Identifies a specific carrier account configured in Carriyo.

Array of objects (Parcel Request)
object (Fulfillment Delivery)

Scheduling window for a fulfillment.

object (Fulfillment Payment)
object (Pre-Booking Info)

Information about a shipment that has already been booked with a carrier outside Carriyo.

Responses
200

Shipment created successfully.

400

Cannot create shipment.

404

Order or fulfillment order not found.

post/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/ship
Request samples
application/json
{
  • "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",
  • "billing_address": {
    },
  • "customer": {
    },
  • "customer_key": "string",
  • "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"
}