Create a fulfillment

Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when items is omitted, every not-yet-shipped unit is moved. Pass status: 'shipped' to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When delivery_method_id is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass cost to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with status: 'shipped' (pending fulfillments are re-priced by the rate engine).

Required scope: write_fulfillments (for API-key authentication).

POST

api

admin

orders

{order_id}

fulfillments

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

const fulfillment = await client.orders.fulfillments.create('or_UkLWZg9DAJ', {
  stock_location_id: 'sloc_UkLWZg9DAJ',
  tracking: 'INPOST-12345',
  delivery_method_id: 'dm_UkLWZg9DAJ',
  status: 'shipped',
  items: [{ item_id: 'li_UkLWZg9DAJ', quantity: 1 }],
})

spree api post /orders/{order_id}/fulfillments -d '{"stock_location_id":"sloc_UkLWZg9DAJ","tracking":"INPOST-12345","delivery_method_id":"dm_UkLWZg9DAJ","status":"shipped","items":[{"item_id":"li_UkLWZg9DAJ","quantity":1}]}'

{
  "id": "ful_gbHJdmfrXB",
  "number": "H45341821349",
  "tracking": "INPOST-12345",
  "tracking_url": null,
  "cost": "10.0",
  "display_cost": "$10.00",
  "total": "10.0",
  "display_total": "$10.00",
  "discount_total": "0.0",
  "display_discount_total": "$0.00",
  "additional_tax_total": "0.0",
  "display_additional_tax_total": "$0.00",
  "included_tax_total": "0.0",
  "display_included_tax_total": "$0.00",
  "tax_total": "0.0",
  "display_tax_total": "$0.00",
  "status": "shipped",
  "fulfillment_type": "shipping",
  "fulfilled_at": "2026-07-24T18:11:18Z",
  "items": [
    {
      "item_id": "li_UkLWZg9DAJ",
      "variant_id": "variant_UkLWZg9DAJ",
      "quantity": 1
    }
  ],
  "metadata": {},
  "adjustment_total": "0.0",
  "pre_tax_amount": "0.0",
  "created_at": "2026-07-24T18:11:18.223Z",
  "updated_at": "2026-07-24T18:11:18.339Z",
  "order_id": "or_UkLWZg9DAJ",
  "stock_location_id": "sloc_UkLWZg9DAJ"
}

{
  "error": {
    "code": "processing_error",
    "message": "Fulfillments can only be created manually on completed orders"
  }
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Bearer token for admin authentication

Path Parameters

order_id

string

required

Order ID

Body

application/json

stock_location_id

string

required

Stock location the fulfillment ships from

tracking

string

Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL

Example:

"INPOST-12345"

delivery_method_id

string

Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)

cost

string

Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine

Example:

"7.42"

status

enum<string>

Pass 'shipped' to register the fulfillment as already shipped

Available options:

shipped

items

object[]

Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.

Show child attributes

metadata

object

Response

fulfillment created

List fulfillments

Show a shipment

⌘I

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

const fulfillment = await client.orders.fulfillments.create('or_UkLWZg9DAJ', {
  stock_location_id: 'sloc_UkLWZg9DAJ',
  tracking: 'INPOST-12345',
  delivery_method_id: 'dm_UkLWZg9DAJ',
  status: 'shipped',
  items: [{ item_id: 'li_UkLWZg9DAJ', quantity: 1 }],
})

spree api post /orders/{order_id}/fulfillments -d '{"stock_location_id":"sloc_UkLWZg9DAJ","tracking":"INPOST-12345","delivery_method_id":"dm_UkLWZg9DAJ","status":"shipped","items":[{"item_id":"li_UkLWZg9DAJ","quantity":1}]}'

{
  "id": "ful_gbHJdmfrXB",
  "number": "H45341821349",
  "tracking": "INPOST-12345",
  "tracking_url": null,
  "cost": "10.0",
  "display_cost": "$10.00",
  "total": "10.0",
  "display_total": "$10.00",
  "discount_total": "0.0",
  "display_discount_total": "$0.00",
  "additional_tax_total": "0.0",
  "display_additional_tax_total": "$0.00",
  "included_tax_total": "0.0",
  "display_included_tax_total": "$0.00",
  "tax_total": "0.0",
  "display_tax_total": "$0.00",
  "status": "shipped",
  "fulfillment_type": "shipping",
  "fulfilled_at": "2026-07-24T18:11:18Z",
  "items": [
    {
      "item_id": "li_UkLWZg9DAJ",
      "variant_id": "variant_UkLWZg9DAJ",
      "quantity": 1
    }
  ],
  "metadata": {},
  "adjustment_total": "0.0",
  "pre_tax_amount": "0.0",
  "created_at": "2026-07-24T18:11:18.223Z",
  "updated_at": "2026-07-24T18:11:18.339Z",
  "order_id": "or_UkLWZg9DAJ",
  "stock_location_id": "sloc_UkLWZg9DAJ"
}

{
  "error": {
    "code": "processing_error",
    "message": "Fulfillments can only be created manually on completed orders"
  }
}

API basics

Endpoints

Create a fulfillment

Authorizations

Headers

Path Parameters

Body

Response