Orders
Read order lists and detail records for your shop.
List orders
GET /api/admin/orders
Requires an admin identity. Machine callers need the orders:read scope.
curl --get "$SELLFORGE_ADMIN_URL/api/admin/orders" \
-H "Authorization: Bearer $SELLFORGE_API_TOKEN" \
--data-urlencode 'status=paid' \
--data-urlencode 'limit=25'
Query parameters
| Parameter | Behavior |
|---|---|
q | Searches email, customer name, internal ID, and numeric display number |
status | Filters by a valid order status; unknown values are rejected |
channel_id | Filters to a channel the caller is allowed to access |
limit, offset | Pagination parameters |
Results are ordered newest first. The response contains orders, count, limit, and offset. Each list entry also includes items_count, the sum of ordered quantities.
An unknown or inaccessible channel_id returns 404. Channel restrictions on a team member apply in addition to the tenant boundary.
Retrieve an order
GET /api/admin/orders/:id
curl "$SELLFORGE_ADMIN_URL/api/admin/orders/$ORDER_ID" \
-H "Authorization: Bearer $SELLFORGE_API_TOKEN"
The response contains two top-level fields:
| Field | Contents |
|---|---|
order | The serialized order, including customer and total information |
line_items | The order's serialized line items |
Use the internal order id in the URL. The human-readable display number is for presentation and search.
Historical pricing
Order line items preserve the product, price, tax, and commission values relevant to the order. A later catalog change does not mean an existing order should be recalculated from today's product price.
Read all amounts as integer cents and respect the fields returned by the server.
Write operations
The kernel includes manual order and operational mutation routes. The scoped API-token policy does not offer an orders:write scope. Do not assume that orders:read can create an order, issue a refund, or change its state.
For a storefront purchase, start with Checkout sessions. For a server-side extension that reacts to an order, use Plugin hooks.
Found something unclear? Let us know