Orders

An order in Distribu is the record of a purchase — one or more line items, an optional PO number, a shipping address, a total, and a status that moves through a fixed lifecycle. Everything about an order is frozen at creation time: line-item prices, product names, the shipping address, the customer email — so historical orders never change when your catalog or customer data changes later.

You'll find every order at /dashboard/orders, sortable by date, status, or total.

Two ways an order gets created

Path	Who creates it	`customerId`	`createdById`
Storefront — customer logs in, adds to cart, checks out	Customer	Set	`null`
Dashboard — staff uses `+ New order` on Orders	Staff member	`null`	Set

Every order belongs to exactly one company. The two fields above record where it came from — the Placed-by column on the orders list shows whichever one exists. Most B2B distributors see mostly storefront orders, with dashboard orders used for samples, phone orders staff enter manually, or internal consumption.

Storefront and REST-API orders decrement stock atomically and respect per-customer price overrides. Dashboard-entered orders do not touch stock — they're meant for internal bookkeeping where you're recording a sale after the fact, not triggering fulfillment. Adjust stock manually in Inventory if you need to.

What's in this section

Creating orders — the New order flow from the dashboard.
Status workflow — the five statuses and allowed transitions.
Filtering & search — search bar, status dropdown, date range, total range, customer lookup.
Invoice PDFs — downloadable invoice for every order, from both dashboard and storefront.
Exporting orders — current options for getting your orders out of Distribu.

Anatomy of an order

Field	Type	Notes
`id`	string	Displayed as `#{last 8 chars, uppercase}` in the UI — e.g. `#A1B2C3D4`. Full id in URLs and API.
`status`	enum	`SUBMITTED`, `CONFIRMED`, `SHIPPED`, `DELIVERED`, `CANCELLED`. Defaults to `SUBMITTED`.
`total`	decimal	Up to 2 decimal places. Sum of all line items. Frozen at creation.
`poNumber`	string, optional	Customer-supplied purchase order number. Up to 100 chars. Shown on the invoice and searchable in the list.
`notes`	string, optional	Free-form. Up to 2000 chars. Shown to staff and on the invoice.
Shipping address	reference, optional	The address the customer picked, plus a frozen snapshot taken at order time. Used for display and on the invoice, even if the customer later edits or deletes the source address.
`customerId`	reference, optional	Set for storefront and API-placed orders; null for staff-created dashboard orders.
`createdById`	reference, optional	Set for dashboard-created orders; null for storefront and API orders.
`items`	relation	Line items — each with a `productId`, `quantity`, and `unitPrice`. Unit price is a snapshot — if you later change the product price or delete the override, the order keeps its original unit price.

Anatomy of a line item

Every line item has:

productId — reference to the product. If the product is later deleted, the line item stays with the unitPrice snapshot and a link to the original product.
quantity — positive integer.
unitPrice — decimal snapshot. Whatever price applied at checkout time: catalog price, or the per-customer override, whichever was in effect for this customer on this product when the order was placed.

The line item's subtotal in the UI is computed as quantity × unitPrice. The order's total is the sum of all subtotals. There's no tax, shipping, or discount logic layered on top right now — if you need those, the REST API's order-create endpoint lets you set total directly, but the storefront checkout just sums line items.

Immutability

After creation, an order's line items and total are never edited. The only thing that changes is the status field, via the status controls on the detail page or the PATCH endpoint in the API.

There's no "edit order" flow today. If a customer needs a correction, the workflow is: cancel the wrong order, place a new one.