Fenicia models the order lifecycle as a finite state machine. This article groups every endpoint that changes an order's status, from simple actions like accept to bulk transitions with audit metadata.
Which endpoint should I use?
Use accept, reject, and cancel for the common merchant actions. Use the generic transition endpoint when you need to record a custom reason, attach metadata, or move to a non-trivial status.
Accept a pending order. Requires orders:update scope.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/accept \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json"Reject a pending order. Requires orders:cancel scope.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/reject \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"reason":"out_of_stock","description":"SKU ABC-123 unavailable"}'Cancel an accepted or preparing order. Requires orders:cancel scope.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/cancel \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"reason":"customer_request","description":"Customer changed mind"}'Directly set an order's status. Requires orders:update scope.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/status \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"status":"preparing"}'Transition an order with required reason and optional metadata. Stored in the audit log. Requires orders:update scope.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/transition \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"toStatus":"on_hold","reason":"awaiting_payment","metadata":{"provider":"stripe"}}'Transition many orders at once. Partial success is reported per order. Requires orders:update scope.
curl -X POST https://api.fenicia.io/orders/bulk/transition \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"orderIds":["ord_01","ord_02"],"toStatus":"accepted","reason":"bulk_accept"}'Returns the set of statuses an order can transition to from its current state. Requires orders:read scope.
curl https://api.fenicia.io/orders/ord_01HXYZ/valid-transitions \
-H "Authorization: Bearer fn_live_your_api_key"Tip
Drive your UI with GET /orders/{id}/valid-transitions. The actions map tells you which endpoints are reachable and the scopes required, so you can hide disallowed buttons.