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 Orders API gives you programmatic access to your Sellfern orders, enabling automation of status management, note-taking, and reporting. All endpoints require a valid bearer token; write operations additionally require the appropriate scope on the token.

​
GET /api/v2/orders

List orders with optional filters. Results are paginated. Required scope: orders:read

​
Query parameters

​
q
string
Full-text search across order fields such as order number and customer name.
​
status
string
Filter by order status. Accepted values: New, Pending Cost, In Production, Shipped, Complete, Cancelled.
​
store_id
string
Filter by store ID.
​
created_after
string
Return only orders created after this datetime (ISO 8601, e.g. 2026-01-01T00:00:00Z).
​
created_before
string
Return only orders created before this datetime (ISO 8601).
​
timezone
string
IANA timezone used to interpret date filters (e.g. America/New_York). Defaults to UTC.
​
supplier_id
string
Filter by supplier ID.
​
missingSku
boolean
When true, return only orders that have line items with missing SKUs.
​
missingDesign
boolean
When true, return only orders that have line items with missing design files.
​
sort
string
Sort expression in field:direction format (e.g. created_at:desc).
​
page
integer
default:"1"
Page number (1-indexed).
​
limit
integer
default:"20"
Number of results per page.

​
Example

curl -X GET "https://api.sellfern.com/api/v2/orders?status=Shipped&page=1&limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1042,
        "status": "Shipped",
        "store_id": "store_abc",
        "customer_name": "Jane Smith",
        "created_at": "2026-05-01T10:23:00Z"
      }
    ],
    "total": 142,
    "page": 1,
    "limit": 20
  },
  "meta": { "request_id": "req_xyz789" }
}

​
GET /api/v2/orders/:id

Get full details for a single order, including line items. Required scope: orders:read

​
Path parameters

​
id
integer
required
The numeric order ID.

​
Example

curl -X GET "https://api.sellfern.com/api/v2/orders/1042" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": {
    "id": 1042,
    "status": "Shipped",
    "customer_name": "Jane Smith",
    "store_id": "store_abc",
    "items": [
      {
        "sku": "TSHIRT-RED-M",
        "quantity": 2,
        "unit_price": 18.50
      }
    ],
    "total": 37.00,
    "created_at": "2026-05-01T10:23:00Z"
  },
  "meta": { "request_id": "req_xyz790" }
}

​
PATCH /api/v2/orders/:id/status

Update the status of a single order. Required scope: orders:status:write

​
Path parameters

​
id
integer
required
The numeric order ID.

​
Body parameters

​
status
string
required
The new order status. Accepted values: New, Pending Cost, In Production, Shipped, Complete, Cancelled.

​
Example

curl -X PATCH "https://api.sellfern.com/api/v2/orders/1042/status" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"status": "Shipped"}'

{
  "success": true,
  "data": {
    "id": 1042,
    "status": "Shipped"
  },
  "meta": { "request_id": "req_xyz791" }
}
You can pass an Idempotency-Key header to safely retry this request without risk of applying the status change twice.

​
POST /api/v2/orders/bulk-status

Update the status of multiple orders in a single call. Required scope: orders:status:write

​
Query parameters

​
dry_run
boolean
When true, validates and previews the per-order results without saving any changes.

​
Body parameters

​
updates
object[]
required
Array of update objects. Each object must include orderId (integer) and status (string).

​
Example

curl -X POST "https://api.sellfern.com/api/v2/orders/bulk-status" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "orderId": 1042, "status": "Shipped" },
      { "orderId": 1043, "status": "Shipped" }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      { "orderId": 1042, "status": "ok" },
      { "orderId": 1043, "status": "ok" }
    ],
    "counts": { "ok": 2, "error": 0 }
  },
  "meta": { "request_id": "req_xyz792" }
}

​
POST /api/v2/orders/:id/notes

Append a note to an order. Notes are stored with the timestamp and author of the API token. Required scope: orders:write

​
Path parameters

​
id
integer
required
The numeric order ID.

​
Body parameters

​
content
string
required
The text content of the note.

​
Example

curl -X POST "https://api.sellfern.com/api/v2/orders/1042/notes" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"content": "Customer requested gift wrap."}'

{
  "success": true,
  "data": {
    "id": 88,
    "content": "Customer requested gift wrap.",
    "createdBy": "api-token:my-agent",
    "createdAt": "2026-05-22T14:05:00Z"
  },
  "meta": { "request_id": "req_xyz793" }
}

​
Common errors

StatusMeaning
401 UnauthorizedToken is missing or invalid.
403 missing_scopeToken does not have the required scope for this endpoint.
404 Not FoundNo order exists with the given ID, or the order does not belong to your organization.