Orders, refunds & returns

The server prices every order, applies discounts and tax, draws stock from one or more locations, and posts to the ledger. Refunds move money, returns move goods, and the two are kept separate.

Orders

Tables:

• orders
• order_line_item: per-line location_id, note, preorder snapshot
• order_shipping_line, order_payment, order_transaction, order_adjustment
• shop_pos_customer: the synthetic walk-in buyer
• refund tables
• Lookups: order_source, financial_status, cancel_reason

Pricing rules

1. The unit price comes from the variant, converted from USD. A merchant may override it, or enter a custom line.
2. Modifier deltas are added to the unit price.
3. Line discounts are applied before tax.
4. Tax is computed per line, from the variant's taxable flag and the shop's tax_rate. With taxes_included, tax is backed out of the price instead of added.
5. The order-level discount is applied after tax.

Behaviour

• Idempotent: a repeated idempotency key returns the original order (idempotentReplay).
• Multi-location: each line has its own location_id, or set autoRoute and the server picks.
• Partial payments: mark-order-as-paid takes an amount, and each instalment writes one ledger entry.
• Ledger: the sale posting runs in the order's transaction. The payment posting runs after commit, through accountingClient.

Enumerations

The dashboard asks get-order-actions / get-fulfillment-actions which buttons to render. It never infers allowed actions client-side.

Refunds

Routes: calculate-refund, create-refund, get-order-refunds [oScoped]

• The refund is capped at collected − already refunded. This is re-checked under a row lock.
• Tax is apportioned from the original snapshot, not recalculated.
• Restock types: no_restock, cancel (never shipped), return.
• restockOnly returns goods with no money movement, which the dashboard uses on unpaid orders.
• paidFromDrawer takes cash out of the caller's open drawer, so shift expected cash stays correct.
• Adjustments: shipping refund, discrepancy, restocking fee.

Returns

Tables: order_return*, reverse_fulfillment_order*, reverse_delivery

Routes: get-returnable-items, create-return, get-order-returns, receive-return-items, update-reverse-delivery, cancel-return, close-return [oScoped]

• Only shipped units are returnable.
• A return never touches money.
• Stock moves only when items are received and dispositioned: restocked, damaged, not restocked, disposed, or still processing.
• Statuses: requested, open, closed, declined, canceled.
• Reasons (11): unknown, defective, wrong_item, not_as_described, size_too_large, size_too_small, color, style, unwanted, delivery_failed, other.

Fulfillment

Routes: get-fulfillment-orders, get-order-fulfillment-orders, get-fulfillments, get-order-fulfillments, get-fulfillment-actions, create-fulfillment, cancel-fulfillment, update-fulfillment-shipping [oScoped]

• Partial fulfilment, with quantities per line.
• Tracking is manual (company, URL, number), or uses one of the merchant's own carriers.
• Not ported: live carrier labels and rates (Wakilni). Passing a carrierCode returns 400.
• Deferred: a preorder fulfillment hold (check_later.md #14).

Carriers & packages

Tables:

• carrier: the platform catalogue
• shop_carrier
• package
• merchant_carrier: the shop's own named couriers