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": "R1001-F1",
  "tracking": "INPOST-12345",
  "tracking_url": null,
  "pickup_point_data": null,
  "selected_delivery_rate_id": "dr_EfhxLZ9ck8",
  "unpriced": false,
  "cost": "100.00",
  "total": "100.00",
  "discount_total": "0.00",
  "additional_tax_total": "0.00",
  "included_tax_total": "0.00",
  "tax_total": "0.00",
  "status": "fulfilled",
  "fulfillment_type": "shipping",
  "fulfilled_at": "2026-01-15T12:00:00.000Z",
  "delivered_at": null,
  "items": [
    {
      "item_id": "li_UkLWZg9DAJ",
      "variant_id": "variant_UkLWZg9DAJ",
      "quantity": 1
    }
  ],
  "deliveries": [
    {
      "id": "dlv_gbHJdmfrXB",
      "tracking_number": "INPOST-12345",
      "carrier": null,
      "carrier_name": null,
      "service": null,
      "status": "pending",
      "tracking_url": null,
      "estimated_delivery_at": null,
      "delivered_at": null,
      "details": null,
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z",
      "shipping_label_id": null
    }
  ],
  "external_references": {},
  "metadata": {},
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "adjustment_total": "0.00",
  "pre_tax_amount": "0.00",
  "order_id": "or_UkLWZg9DAJ",
  "stock_location_id": "sloc_UkLWZg9DAJ",
  "documents": [],
  "labels": [],
  "provider_generates_labels": false
}

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

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. Exchange and claim replacements are moved only out of a named source_fulfillment_id, which is how a canceled replacement is sent again. 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": "R1001-F1",
  "tracking": "INPOST-12345",
  "tracking_url": null,
  "pickup_point_data": null,
  "selected_delivery_rate_id": "dr_EfhxLZ9ck8",
  "unpriced": false,
  "cost": "100.00",
  "total": "100.00",
  "discount_total": "0.00",
  "additional_tax_total": "0.00",
  "included_tax_total": "0.00",
  "tax_total": "0.00",
  "status": "fulfilled",
  "fulfillment_type": "shipping",
  "fulfilled_at": "2026-01-15T12:00:00.000Z",
  "delivered_at": null,
  "items": [
    {
      "item_id": "li_UkLWZg9DAJ",
      "variant_id": "variant_UkLWZg9DAJ",
      "quantity": 1
    }
  ],
  "deliveries": [
    {
      "id": "dlv_gbHJdmfrXB",
      "tracking_number": "INPOST-12345",
      "carrier": null,
      "carrier_name": null,
      "service": null,
      "status": "pending",
      "tracking_url": null,
      "estimated_delivery_at": null,
      "delivered_at": null,
      "details": null,
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z",
      "shipping_label_id": null
    }
  ],
  "external_references": {},
  "metadata": {},
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "adjustment_total": "0.00",
  "pre_tax_amount": "0.00",
  "order_id": "or_UkLWZg9DAJ",
  "stock_location_id": "sloc_UkLWZg9DAJ",
  "documents": [],
  "labels": [],
  "provider_generates_labels": false
}

{
  "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

The location the fulfillment ships from. On update, moving it re-prices the fulfillment against that location's rates.

external_references

object

Identities the record has in external systems, keyed by system: the same { system: external_id } map the Admin API renders, so what you read can be sent straight back. Systems you do not name keep the reference they have. A list of { system, external_id } entries is accepted too.

source_fulfillment_id

string

The only fulfillment of this order to move units from, its exchange and claim replacements included: how a canceled replacement is sent again. Omitted, the customer's bought units are taken from every unshipped fulfillment.

tracking

string

Carrier tracking number, or a full https:// tracking link, which is served back as tracking_url unchanged.

delivery_method_id

string

Delivery method attached as the selected rate. Defaults to the delivery method of the fully drained source fulfillments.

cost

string<decimal>

Explicit shipping cost, such as the 3PL price. Defaults to the summed cost of the fully drained source fulfillments, which keeps the order total unchanged. Persists only with status: shipped; pending fulfillments are re-priced by the rate engine.

Pattern: ^-?\d+(\.\d+)?$

Example:

"7.42"

status

enum<string>

Pass shipped to register an already-shipped external fulfillment.

Available options:

shipped

metadata

object

items

object[]

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

Show child attributes

Response

fulfillment created

⌘I

API basics

Endpoints

Create a fulfillment

Authorizations

Headers

Path Parameters

Body

Response