Orders

Creates a new order.

Auto-customer creation: If customerId is not found in the customers table (e.g. walk-in / manual entry), the customer is automatically created using customerName, phone, wilayaId, and address. Pass a client-generated UUID (e.g. crypto.randomUUID()) as customerId in this case.

Inventory: Products with trackInventory enabled will have their stock decremented automatically.

Delivery fee: decided as the storefront checkout decides it (POST /orders/delivery-quote shows it): every product's shipping profile, the dearest winning; a commune's own price; free at the store's free-delivery amount; free by an offer for a basket of its product alone, which the order records (deliveryOfferId). An offline order may pass an explicit deliveryFee, which is then kept as typed. Where the store does not deliver, an online order is refused (422 DELIVERY_NOT_AVAILABLE).

Delivery is chosen later, when the ready order is handed to a carrier or a driver (POST /orders/{id}/shipment).

What delivery would cost on an order being entered, decided as the storefront checkout decides it — the fee POST /orders charges when no fee is typed — and why it is free when it is: { by: "threshold", threshold } (the store's free-delivery amount) or { by: "offer", offerId, offerName }. { available: false } where the store does not deliver. A read: nothing is written.

Returns full order detail including products and status history.

Partially edits an order's customer and destination fields: customerName, phone, customerEmail, wilayaId, communeId, city, address, deliveryType, notes. All fields optional — omitted fields stay untouched.

This is how a merchant records an address collected over the phone when the checkout hid the address field.

The linked customer record is updated in the same operation with the fields this request changes (name, phone, wilaya/commune, address) — an order and its customer never disagree on contact details. If the corrected phone already belongs to a different customer record, the order is re-pointed to that record instead of overwriting its phone. customerEmail is stored on the order only.

customerEmail / address: an empty (or whitespace) value clears the field; a value is stored trimmed (email also lower-cased), matching POST /orders.

Rejected with 409 ORDER_HAS_SHIPMENT when the order has a shipment and the edit touches what the parcel carries (name, phone, wilaya, commune, city, address, delivery type) — change those through PATCH /shipments/{id}; the email and notes still change. Rejected with 422 for a legacy order that already has a tracking number, or one in a terminal state (returned/cancelled). Rejected with 400 MISSING_ADDRESS when the edit would leave a home delivery without a street address. Wilaya/commune are checked against the reference tables (400 MISSING_WILAYA_COMMUNE).

Permanently deletes an order never handed to delivery, in any status: the goods still out of stock go back, the customer's order count and spend are undone, and its lines, history, reviews and logs go with it. 409 ORDER_HAS_SHIPMENT once it has a shipment — its parcel, the driver's cash and the carrier's records rest on it; archive it when its delivery has ended (POST /orders/{id}/archive), or void the shipment first. The database refuses it too.

Whether the order can be deleted (never handed to delivery) or archived (finished: cancelled, or its shipment delivered, returned or cancelled), and what deleting it would undo — read before asking the merchant to confirm.

Takes a finished order — cancelled, or its shipment delivered, returned or cancelled — out of the working lists and their counts. It still counts in sales and the customer's history, and can be restored. Archiving it again keeps the first date. 409 ORDER_NOT_FINISHED before then.

Brings an archived order back to the working lists.

Moves the order's processing and appends a record to its status history (cod-shared/orders/lifecycle.ts):

• new → confirmed | unreachable | cancelled
• confirmed → preparing | ready | unreachable | cancelled
• unreachable → confirmed | cancelled (the customer did not answer; call again)
• preparing → ready | cancelled
• ready → cancelled; a ready order is handed off with POST /orders/{id}/shipment
• cancelled is final

Any other move returns 400 INVALID_STATUS_TRANSITION with the allowed next statuses.

Side effects: confirmed starts the Meta CAPI confirmed stage (when the store tracks it); cancelled restores inventory for products with trackInventory and rolls back the customer's spend. Delivery and return are the shipment's milestones, with their own effects.

Each effect applies exactly once, even when the same change is sent twice at once. An order with a shipment has no status change (409 ORDER_HAS_SHIPMENT): its delivery is the shipment's, and cancelling it means voiding the shipment first.

Records how many units on a single order line the customer refused at the door. Used for the Algerian "open the box at delivery" workflow where a customer may accept part of an order and return the rest.

The server computes the line status ("fulfilled" | "partially_returned" | "returned") from returnedQuantity vs. the line quantity, restocks the delta (repeated calls are idempotent), and logs an ORDER_RETURNED stock movement.

Only on a delivered order: the customer opened the parcel at the door and kept part of it. Before delivery nothing has been refused (422 ORDER_NOT_DELIVERED) — a parcel refused whole comes back as a return, and its stock with it.

Refused (422) once the order is cancelled or its parcel came back — every remaining unit is already back in stock. Both are checked in the same write, so neither can happen in between.