Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sellfern.com/llms.txt

Use this file to discover all available pages before exploring further.

The Fulfillment API exposes the fulfillment queue and supplier assignment so automation agents and workflows can manage order production status without manual intervention. Read access lets you inspect which orders need action; write access lets you assign suppliers in bulk.

​
GET /api/v2/fulfillment/queue

List orders that are currently awaiting a fulfillment action. You can filter the queue by status, supplier, or store, and paginate through large result sets. Required scope: fulfillment:read

​
Query parameters

​
status
string
Filter by fulfillment status. Accepted values: New, In Production. Omit to return all queue items.
​
supplier_id
string
Filter by a specific supplier ID.
​
page
integer
default:"1"
Page number (1-indexed).
​
page_size
integer
default:"20"
Number of results per page.

​
Example

curl -X GET "https://api.sellfern.com/api/v2/fulfillment/queue?status=New&page=1" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": {
    "items": [
      {
        "order_id": 1042,
        "status": "New",
        "supplier_id": null,
        "created_at": "2026-05-20T09:14:00Z"
      },
      {
        "order_id": 1043,
        "status": "New",
        "supplier_id": null,
        "created_at": "2026-05-20T11:30:00Z"
      }
    ],
    "total": 28,
    "page": 1,
    "page_size": 20
  },
  "meta": { "request_id": "req_ful001" }
}

​
POST /api/v2/fulfillment/assign

Assign a supplier to one or more orders for fulfillment. After a successful assignment, the affected orders move to the supplier’s production queue. Required scope: fulfillment:write

​
Query parameters

​
dry_run
boolean
When true, validates and previews the per-order assignment results without saving any changes. Use this to check for errors before committing.

​
Headers

​
Idempotency-Key
string
Optional key for safely retrying the same assignment request. If you send the same key a second time, the API returns the original result rather than executing the assignment again.

​
Body parameters

​
order_ids
integer[]
required
Array of numeric order IDs to assign.
​
supplier_id
string
required
The ID of the supplier to assign to these orders.

​
Example

curl -X POST "https://api.sellfern.com/api/v2/fulfillment/assign" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ids": [1042, 1043],
    "supplier_id": "sup_789"
  }'

{
  "success": true,
  "data": {
    "results": [
      { "order_id": 1042, "status": "ok", "supplier_id": "sup_789" },
      { "order_id": 1043, "status": "ok", "supplier_id": "sup_789" }
    ],
    "counts": { "ok": 2, "error": 0 }
  },
  "meta": { "request_id": "req_ful002" }
}

​
Fulfillment statuses

Orders move through fulfillment statuses in sequence. Understanding these transitions helps you filter the queue and trigger the right actions.
StatusMeaning
Pending CostOrder has been imported but costs have not been assigned yet. It cannot be sent to production until costs are resolved.
NewCosts are assigned and the order is ready for supplier assignment. This is the primary queue state you act on via the API.
In ProductionThe order has been assigned to a supplier and production has begun.
ShippedThe order has left the supplier and tracking information is available.
CompleteThe order has been delivered and the lifecycle is closed.
How status transitions work:
  • Marking an order as “Ready” (resolving its costs) moves it from Pending Cost to New.
  • Calling POST /api/v2/fulfillment/assign moves orders from New to In Production once a supplier is assigned.
  • Updating an order’s status to Shipped via PATCH /api/v2/orders/:id/status moves it out of the production queue.