Orders
Lifecycle, statuses, and the refund flow that actually calls the payment provider.
An order is created from a cart at checkout. From that point on it lives independently — variants can be deleted, prices can change, and the order remembers what was sold and for how much via a JSON snapshot of every line.
Statuses
pending → paid → fulfilled → delivered
↓
refunded- pending — order exists, payment intent issued, money not received. Stock is reserved.
- paid — payment provider confirmed (webhook or admin override). Inventory moves from reserved to consumed.
- fulfilled — shipping label generated / pickup ready.
- delivered — terminal happy state.
- cancelled — terminal failure state. Reservations released.
- refunded — payment fully reversed at the provider. See below.
The status enum also has draft, confirmed, processing and
shipped, and may gain values. Treat a status you don't recognize as
"in progress" rather than failing (see
API conventions).
Endpoints
Paths are relative to https://api.mobiari.com/v1.
| Method | Path | Purpose |
|---|---|---|
GET | /stores/{store_id}/orders | List. Filters: status, customer_id, search, include_test. |
POST | /stores/{store_id}/orders | Create an order (admin-created). |
POST | /stores/{store_id}/orders/manual | Record a manual sale. |
GET | /stores/{store_id}/orders/{order_id} | Single order with lines, payment and shipping. |
PATCH | /stores/{store_id}/orders/{order_id}/status | Change the status, e.g. {"status": "fulfilled"}. |
POST | /stores/{store_id}/orders/{order_id}/refund | Refund through the payment provider. |
Moving to the Page envelope
The orders list is being moved to the standard
Page response with cursor paging.
Until Orders appears in the API reference, it answers
with a bare array, or {"orders": [...], "total", "limit", "offset"}
when you pass limit, offset or search.
The refund flow
The Reembolsar button in the admin (and POST .../refund in the
API) doesn't just flip a database column — it actually calls the
payment provider. Today that's Mercado Pago. The handler:
- Loads the latest approved payment intent for this order.
- Calls Mercado Pago's refund API. Empty body = full refund;
{"amount_cents": 1234}= partial refund of R$ 12,34 (capped at the amount paid). - Only on a successful provider response does it touch local state.
A full refund marks the order
refunded, releases inventory reservations, cancels pending build jobs and emitsorders.refunded. A partial refund leaves the status alone and sets the payment status topartially_refunded.
If the provider call fails (network, declined, already refunded), local
state is left alone and you get a 502 bad_gateway, or a 422 when there
is nothing to refund.
Send an Idempotency-Key
Each refund call is a new refund at the provider. If a partial refund
times out and you retry it blindly, the customer can be refunded twice.
Send an Idempotency-Key header and reuse it on the retry: a refund
that went through is replayed instead of repeated. See
Idempotency.
# Full refund:
curl -X POST \
"https://api.mobiari.com/v1/stores/$STORE_ID/orders/$ORDER_ID/refund" \
-H "Authorization: Bearer $BP_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: refund-$ORDER_ID-full" \
-d '{}'
# Partial refund of R$ 30,00:
curl -X POST \
"https://api.mobiari.com/v1/stores/$STORE_ID/orders/$ORDER_ID/refund" \
-H "Authorization: Bearer $BP_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8d4b0c1e-5a8f-4f7e-b1a2-6c3d9e0f1a2b" \
-d '{"amount_cents": 3000}'Pickup orders
If the buyer chose Retirar pedido na loja at checkout instead of
shipping, the order carries a pickup_location_snapshot_json and the
freight section is hidden. The snapshot is intentionally a copy of the
location at the time of purchase — you can later edit or delete the
physical location without changing the order's pickup address.
fulfillment_method on the order is either "shipping" or "pickup"
and tells the admin UI which card to render.
Permission cheatsheet
| Action | Permission |
|---|---|
| List, get | orders.read |
| Create (admin-created) | orders.write |
| Update status, fulfill | orders.edit / orders.fulfill |
| Cancel | orders.cancel |
| Refund | orders.refund |