Inventory and fulfillment

These operational routes are served by the shop-admin backend. Use an admin session for workflow mutations. Token access is limited to the reads and stock adjustment explicitly allowed by the policy.

Warehouses

GET /api/admin/warehouses returns warehouses; the same path accepts POST to create a warehouse. Update or delete with PATCH or DELETE /api/admin/warehouses/:id.

Warehouse locations use GET and POST /api/admin/warehouses/:id/locations, with deletion at /api/admin/warehouse-locations/:id. The separate /api/admin/storage-locations resource manages storage-location assignments and barcodes.

Inventory

GET /api/admin/inventory/by-warehouse/:warehouseId returns items. It is supported by inventory:read.

curl "$SELLFORGE_ADMIN_URL/api/admin/inventory/by-warehouse/$WAREHOUSE_ID" \
  -H "Authorization: Bearer $SELLFORGE_API_TOKEN"

POST /api/admin/inventory/adjust records a stock movement. Its body uses product_id, optional variant_id and warehouse_id, a signed quantity, type, and optional notes.

{
  "product_id": "prod_example",
  "warehouse_id": "wh_example",
  "quantity": 5,
  "type": "MANUAL_CORRECTION",
  "notes": "Stock count found five additional units"
}

Supported types include PURCHASE_RECEIVED, MANUAL_CORRECTION, STOCKTAKE_ADJUSTMENT, DAMAGED, and RETURN_RECEIVED. Machine writes require inventory:write and additional write validation, including a reason/note and a maximum adjustment size. This is a movement, not an absolute replacement of the current stock count.

Admin-session routes also include /api/admin/inventory, /api/admin/inventory/low-stock, and /api/admin/inventory/:productId/transactions. The current token read allowlist does not cover all of these paths.

Fulfillments

GET /api/admin/fulfillments lists fulfillments; GET /api/admin/fulfillments/:id retrieves details. These reads support orders:read.

Create with POST /api/admin/fulfillments, providing order_id, optional warehouse_id, and optionally items containing order_item_id and quantity.

The workflow uses these POST operations:

1. /api/admin/fulfillments/:id/start-picking
2. /api/admin/pick-list-items/:id/pick with quantity
3. /api/admin/fulfillments/:id/complete-picking
4. /api/admin/fulfillments/:id/packages
5. /api/admin/fulfillments/:id/ship

Cancellation uses /api/admin/fulfillments/:id/cancel. Each action validates its business state; a fulfillment is not shipped by simply changing a display field.

Returns

GET /api/admin/returns and /api/admin/returns/:id support orders:read. Operational POST actions under /api/admin/returns/:id/ are approve, receive, inspect, refund, and reject.

Refunding uses amount_cents and requires an authorized session. The public request endpoint is POST /api/returns; it validates the order/customer context and applies its own rate limit.

Transfers

Use GET /api/admin/transfers or /api/admin/transfers/:id to inspect warehouse transfers. Create with POST to the collection, then POST to /:id/send, /:id/receive, or /:id/cancel to progress the workflow. These routes require an admin session; inventory:read does not grant transfer access.

Production orders

Use GET or POST /api/admin/production-orders, and GET /api/admin/production-orders/:id for details. The /:id/material-plan GET route shows materials. POST actions include start, complete, produced, and cancel.

Bills of materials and production steps are separate resources under /api/admin/products/:id/bom and /api/admin/products/:id/production-steps.

Purchase orders

GET /api/admin/purchase-orders is supported by inventory:read. Creation uses POST on the collection; receiving uses POST /api/admin/purchase-orders/:id/receive. Mutations require an admin session.

Shipping and tracking

Administrative shipping methods use /api/admin/shipping-methods. Customer-facing method selection uses GET /api/shipping-methods?country=AT and returns methods. The checkout also exposes session-specific shipping selection.

The kernel registers GET /api/tracking/:trackingNumber, but the split backend definitions do not currently expose /api/tracking. Check your deployment's routing before offering this legacy endpoint to customers.