Orders (orders)
Order placement, lifecycle, and access control. Composes the cart price resolution, stock reservation, payment driver dispatch, invoice generation, and audit logging.
Public surface
Admin routes are gated by orders:read (read) / orders:write (mutations).
| Verb + Path | Audience | Purpose |
|---|---|---|
POST /api/v1/orders | customer | Place order from active Cart |
GET /api/v1/orders | customer | List orders: own orders, or the Organization's with orders.view_organization (see below) |
GET /api/v1/orders/:id | customer | Order detail |
GET /api/v1/orders/:id/invoice | customer | Older invoice download: a minimal PDF of the order's first invoice (404 INVOICE_NOT_READY until it is ready); the template-rendered PDF is the invoices module's …/invoices/:invoiceId/pdf |
GET /api/v1/admin/orders | admin | List every order (cross-organization) |
GET /api/v1/admin/orders/:id | admin | Order detail (bypasses customer scope) |
POST /api/v1/admin/orders/:id/status | admin | Status transition (audited) |
POST /api/v1/admin/orders/:id/payment-status | admin | Payment status transition (audited) |
Who sees a colleague's order
A buyer sees the orders they placed. Every other order of their Organization —
in the list, on its detail page, and in every action that reads an order as
its source (reorder, clone to a quote request, starting a return or a complaint
from it, its invoices) — needs the
organization permission View the organization's orders
(orders.view_organization), which this module declares:
| Role | Holds it |
|---|---|
| Administrator | always (every permission, implicitly) |
| Member | no, unless the Organization's administrator grants it to the role |
| a custom role | when the role grants it |
Without the permission a colleague's order answers 404, exactly as an order
of another Organization does, never 403. With it the reach is the
Organization; a head-office login with roll-up enabled reaches its subtree as
well — roll-up widens the reach, it never grants the permission.
Starting a return or a complaint from a colleague's order also needs the
returns module's Create returns and complaints (returns.create); the case
is filed in the name of the member who starts it (see the returns page).
On the storefront the order list and the order page show a colleague's order to
a member holding the permission exactly as their own. The order page offers
Request return / complaint (or File a complaint) only to a member whose
role holds returns.create.
Reordering and cloning to a quote request are also judged by what they build:
POST /api/v1/orders/:id/reorder replaces the active cart and needs
carts.create, POST /api/v1/orders/:id/clone-to-quote creates a quote request
and needs quote_requests.create. The permission is checked before the order
is read, so a member lacking it gets 403 ORGANIZATION_PERMISSION_REQUIRED
whichever order the id names, and a member holding it then meets the order
scope above. With quote_requests switched off its code grants nothing, so the
buyer's clone is refused with that same 403. The order page offers Order
again → cart and Order again → quote request only to a member holding the
matching code.
Which sales channel an order records
An order records one sales channel. Where it comes from depends on who places the order:
| Surface | The order's channel |
|---|---|
Storefront — POST /api/v1/orders, one-click buy | The channel the request resolved: X-Sales-Channel, ?salesChannel=, the host map, else the system default |
Admin order creation — POST /api/v1/admin/orders | The channel the operator chose for the order (salesChannelId in the body) |
| API key — the external order intake | The channel the key is bound to |
On the storefront the optional salesChannelId body field does not choose the
channel. A request that omits it is placed on the resolved channel; one that
sends the resolved channel's id is accepted; one that names a different
channel — another one, one that does not exist, or one that is switched off —
is refused with 422 VALIDATION_FAILED and
details.code = "order_sales_channel_mismatch" (the details carry
requestedSalesChannelId and resolvedSalesChannelId), before anything is
written — the basket is left as it was.
In admin order creation the body's salesChannelId is required and has to be
one of the customer's organization's active sales channels — the channels
the organization is assigned to and that are switched on. Any other channel —
one assigned only to other organizations, one that is switched off, or one
that does not exist — is refused with 422 ORDER_SALES_CHANNEL_NOT_ALLOWED
before anything is written, the customer's basket and any new address
included. POST /api/v1/admin/orders/preview answers the same, so the screen
is never shown totals for an order it cannot create. There is no fallback: a
request without salesChannelId is refused with 400 VALIDATION_FAILED, never
placed on a default channel. This is the rule a quote request created on a
customer's behalf follows. The ordered products are checked against that
channel's assortment, not the one the admin request itself resolved — a
product the chosen channel does not sell is refused with
404 PRODUCT_NOT_FOUND, and one it sells is accepted even when the system
default does not sell it. A product outside the chosen channel's assortment is
refused before the customer's basket is touched, so the basket is left as it
was.
The external order API (POST /api/v1/external/orders) follows the same rule
for the channel its API key is bound to: that channel has to be one of the
bound organization's active sales channels when the order is placed, not
only when the key was issued. A key whose organization was never assigned to
the channel, or was unassigned from it later, is refused with
422 ORDER_SALES_CHANNEL_NOT_ALLOWED before anything is written, the service
account's basket included. A bound channel that is switched off is refused
earlier, with 400 INACTIVE_SALES_CHANNEL.
What is read from an order's channel:
- at placement — the minimum order value (
orders.min_order_value), the candidate warehouses and the channel's fulfilment settings, the order-number prefix and suffix, the extra confirmation recipients, and the channel id the payment and shipping adapters' validators are given; - afterwards — the seller details and number sequence of its invoices, the
language and channel of its order, payment and shipment e-mails, and whether
it may be reordered (
orders.reorder_enabled).
The storefront has to name the channel on the placement request itself. The
reference storefront forwards X-Sales-Channel on order placement, the
order-total preview, one-click buy and "order again as a quote request". One created by an earlier release did not; the steps are in
Upgrading an instance.
What is not tied to the order's channel
- The basket. A basket is created on the system-default channel whatever channel the buyer is shopping, and three things are answered for the basket's channel rather than the order's: whether a product may be added (the assortment of the channel the adding request resolved — admin order creation, above, is the exception), the line prices, and the promotions — at checkout exactly as in the cart. On a multi-channel instance an order can therefore be recorded on a channel that does not sell one of its products, at the default channel's prices, and a promotion restricted to a non-default channel does not yet apply to an order placed there.
- The buyer. Recording the request's channel does not bind a buyer to a
channel.
X-Sales-Channeland?salesChannel=are sent by the client, and nothing restricts which channels a customer or an Organization may order on.
Upgrading
An instance with more than one sales channel. Until this rule, a storefront
order that did not send salesChannelId in the body — which is every order
placed through the reference storefront — was recorded on the system-default
channel whichever channel the buyer was on. New orders placed on a non-default
channel's storefront are now recorded on that channel, so everything listed
above is read for it, and they appear under that channel in the order list and
in reports. Existing orders are not rewritten.
An instance with one sales channel. A storefront order used to reach the minimum-order-value check with no channel at all, and a setting read with no channel answers its platform-wide value. It now arrives with the default channel's id, so a minimum order value set for the default channel rather than for all channels is enforced at checkout where it was not before. The payment and shipping adapters' validators are given that channel id too, where they were given none. An instance that set the minimum platform-wide, or not at all, sees no change.
Cart approval at placement
A member whose role lacks Place orders without approval
(carts.order_without_approval, declared by the Carts module) orders a basket
only once a colleague allowed to approve carts has approved it. Placement asks
the Carts module before anything is reserved or written, reading the basket
owner's role at that moment, and refuses such a basket that is not approved
with 409 ORDER_CART_APPROVAL_REQUIRED;
details carries cartId, approvalStatus and a code naming the state:
details.code | Basket | Sentence (English) |
|---|---|---|
cart_approval_not_submitted | never sent for approval | "Your role requires approval of this cart before it can be ordered. Send it for approval first." |
cart_approval_pending | awaiting an approver | "This cart is awaiting approval by an approver in your organization. You can place the order once it is approved." |
cart_approval_rejected | rejected | "This cart was rejected by an approver in your organization, so it cannot be ordered." |
The basket is kept as it was. Unaffected: the basket of every member whose role holds Place orders without approval (Administrator always does), and orders placed from a working basket — admin order creation, one-click buy and the external order API — which do not place the member's basket.
Method allow-lists at placement
An Organization can be restricted to a subset of delivery and payment methods
(see the organizations module, Per-organization commercial scoping).
Placement and both previews refuse a method outside a non-empty list with
400 ORDER_DELIVERY_METHOD_UNAVAILABLE (a delivery method) or
400 ORDER_PAYMENT_METHOD_UNAVAILABLE (a payment method), and
error.details.code says why:
error.details.code | Also carries | Meaning |
|---|---|---|
delivery_method_not_allowed_for_organization | deliveryMethodId | The Organization's delivery allow-list does not contain the chosen method |
payment_method_not_allowed_for_organization | paymentMethodId | The Organization's payment allow-list does not contain the chosen method |
- Where —
POST /api/v1/orders,POST /api/v1/orders/preview-total,POST /api/v1/admin/orders,POST /api/v1/admin/orders/preview,POST /api/v1/external/orders, and every other caller oforderPlacementPort.placeOrder. One-click buy does not reach the refusal: a default method the list excludes makes the buyer ineligible (one_click_unavailable, reasonmissing_defaults). - Which Organization — the one the order is placed for: the signed-in buyer's, the one an API key is bound to, or the customer's when an administrator creates the order. A request cannot name another.
- Empty means unrestricted — an empty list, or no list, allows every active method, and the two lists are independent.
- Nothing is written — no order, stock reservation or payment, and the customer's basket is unchanged. Admin create and the API-key intake check before they write the order's lines.
- Administrators are bound too — by decision, an order created on a customer's behalf honours that customer's Organization allow-lists, and no setting exempts it. The create form lists every method; the preview and the create answer the refusal above for one the Organization does not allow.
- When both methods are outside the lists the delivery method is the one reported.
- When the lists cannot be read the request answers
500 INTERNALand nothing is placed, as the two method listings do.
Methods and the order's sales channel
A delivery or payment method can also be restricted to sales channels (see the
delivery_methods and payment_methods modules, Sales channels). Placement
and both previews refuse a method that is not offered on the order's channel
with 400 ORDER_DELIVERY_METHOD_UNAVAILABLE or 400 ORDER_PAYMENT_METHOD_UNAVAILABLE,
as above:
error.details.code | Also carries | Meaning |
|---|---|---|
delivery_method_not_in_sales_channel | deliveryMethodId, salesChannelId | The delivery method is restricted to sales channels and the order's is not one of them |
payment_method_not_in_sales_channel | paymentMethodId, salesChannelId | The payment method is restricted to sales channels and the order's is not one of them |
- Where — the same routes as the allow-lists above. One-click buy does not
reach the refusal here either: a default method the request's channel does not
offer makes the buyer ineligible (
one_click_unavailable, reasonmissing_defaults). - Which channel — the one the order records; see Which sales channel an order records above.
- No assignment means every channel — a method assigned to no sales channel is offered on all of them.
- Nothing is written — as for the allow-lists, and admin create and the API-key intake check before they write the order's lines.
A method that fails both
The two refusals are independent, and on every route the Organization's
allow-lists are asked before the order's channel. So a method that is both
outside the Organization's allow-list and not offered on the order's channel
is refused with the allow-list code (…_not_allowed_for_organization); the
channel code (…_not_in_sales_channel) is what a method reports when the
Organization may use it — or has no list — and the channel does not offer it.
Where "the method is active" and the adapter's own validator fall between the two differs by route:
- Storefront placement and one-click buy (
placeOrder) — allow-lists, then the method is active, then its adapter's validator, then the channel. - Storefront preview — allow-lists, then the method is active, then the channel; the adapter's validator is not run for a preview.
- Admin order creation and the API-key intake — allow-lists and the channel
are both asked first, before the customer's basket is touched; the order then
goes through
placeOrder, which repeats them around the active and adapter checks. An inactive method that is also not offered on the channel therefore reports the channel code on these two routes, and "not active" on the storefront. - Admin preview — allow-lists, then the channel; an inactive method is not refused by a preview.
Status machine (configurable)
The order lifecycle is admin-configurable: statuses and allowed
transitions live in the order_statuses and order_status_transitions
tables, seeded on install with nine defaults — new (initial,
non-deletable), pending, paid, processing, shipment_ready,
shipment_sent, completed (terminal), on_hold, cancelled (terminal) —
plus the predefined edges and the universal → on_hold / → cancelled edges
(and on_hold → any). Admins manage them via the
/api/v1/admin/orders/statuses + /transitions endpoints; the graph is
cached in-process and re-validated on every edit.
An edit the graph's state refuses has its own code and a sentence in English
and Polish, read in the operator's language. Until issue #627 these were
VALIDATION_FAILED; the status is unchanged. The status code travels as
details.statusCode, because details.code is the slot for a refusal's token.
| Code | Status | When | details |
|---|---|---|---|
ORDER_STATUS_CODE_TAKEN | 409 | POST …/statuses — another status has the code | statusCode |
ORDER_STATUS_TERMINAL_HAS_TRANSITIONS | 409 / 422 | PATCH …/statuses/:code marking a status with outgoing transitions terminal (code mark_terminal), or PUT …/transitions adding one from a terminal status (code add_transition) | statusCode, and outgoingCount or toStatusCode |
ORDER_STATUS_NOT_DELETABLE | 409 | DELETE …/statuses/:code of the initial (code initial) or a system (code system) status | statusCode |
ORDER_STATUS_IN_USE | 409 | DELETE …/statuses/:code while orders are in it | statusCode, orderCount |
A transition naming a status that does not exist stays VALIDATION_FAILED.
OrderTransitionService.apply() is the single authoritative state machine:
it rejects transitions with no configured edge or out of a terminal status,
runs veto-capable before-guards (onOrderTransitionGuard), then emits the
templated events (below). Payment/shipping events drive automatic transitions
through the OrderStatusRegistry (the method statusOn* columns reference
these status codes); payment_status is retained as a derived/secondary field.
What a transition owes: follow-ups
Cancelling an order gives back what the order was holding: its stock allocations, and — for an order placed against a credit limit — its credit reservation. Marking such an order paid gives back the credit reservation. These releases are the transition's follow-ups.
A follow-up is recorded in the same transaction as the status, as a row in
order_transition_effects, and is run immediately afterwards, in the same
request. So in the ordinary case the stock and the credit are released by the
time the caller is answered. What changed is what happens when a release cannot
complete:
- The transition is still applied, and the caller is told so. Every refusal — an unknown status, no configured edge, a terminal source, a guard's veto — is decided before anything is written. Once the status is committed nothing can turn the answer into an error.
- The release is retried until it completes. A background sweep runs every
minute and attempts every outstanding follow-up that is due, backing off from
one minute up to one hour between attempts. There is no "gave up" state; from
the fifth failure on, each further failure is logged at
warnwith the order id, the release and the last error. - Even the response cannot turn it into an error. If the order cannot be
read back for the response body after the commit,
POST /api/v1/admin/orders/:id/status,POST /api/v1/admin/orders/:id/payment-statusandPOST /api/v1/orders/:id/cancelanswer200with{ data: { id, businessId, status, paymentStatus }, meta: { partial: true } }(orderCommittedWritePartialResponseSchemain@endora-commerce/contracts). Checkmeta.partialbefore treatingdataas a whole order, and read the order again if the rest is needed. - Follow-ups are independent. A credit release that fails does not keep the stock held, and the other way round.
- The status events are always emitted after the commit, whatever happened to the releases.
Repeating a transition to the status an order already has is a no-op, and that is safe: what the status owes is recorded beside it and will run.
With inventory or credit_limits switched off
A follow-up whose owning module is switched off waits. Nothing of that module's is written while it is off, the wait is not counted as a failed attempt, and the release runs within one sweep (a minute) of the module being switched back on.
- With
inventoryoff, a cancelled order keeps its allocations until the module returns. - With
credit_limitsoff, an order placed on credit can still be cancelled or marked paid; its reservation is released when the module returns. Placing a new order against a credit limit is still refused while the module is off.
On the order page
The admin order page shows a notice while an order has follow-ups outstanding:
which release, whether it is waiting for a module, and how many attempts have
failed. The admin order response carries the same information as
pendingEffects — present only when something is outstanding, and never on the
buyer-facing order responses.
Repairing orders stranded by an earlier version
Before follow-ups were recorded, a release that failed or was refused could leave an order cancelled (or paid) while still holding stock or credit, with nothing able to release it afterwards. Those orders have no follow-up row. An operator command finds and repairs them. Run it in the root of your instance:
# List what would be released. Writes nothing.
pnpm run cli orders transition-effects-repair
# Release it.
pnpm run cli orders transition-effects-repair --apply
In a checkout of the Endora Commerce repository the same command is
pnpm --filter backend run cli orders transition-effects-repair, with the same
options. That form does nothing in an instance: the backend member there has
another name, so pnpm prints No projects matched the filters and exits 0
without running the command.
The dry run prints every order found holding stock allocations or an active
credit reservation it should have given back, with what each holds. --apply
records the releases through the same follow-up mechanism, attempts them at
once, and writes one audit entry per page of orders; anything that does not
complete is retried by the sweep. Running it again finds nothing left.
Run the dry run once after upgrading, and read the list before applying it: a release changes reserved-stock counters and available credit. The repair never runs by itself.
What the dry run cannot show. It lists what each order's own rows say the order holds. If somebody has already corrected a stock counter by hand for one of those orders, the order is still listed — its allocation row is unreleased — and applying it lowers the counter a second time, so less stock is reserved than live orders actually hold (the counter is never driven below zero, which hides the error rather than preventing it). Leave such an order out, or repair only the orders you name; both options take the order id the list prints in brackets and may be repeated:
pnpm run cli orders transition-effects-repair --apply --except=<order id>
pnpm run cli orders transition-effects-repair --apply --order=<order id>
If inventory or credit_limits is switched off, the command cannot ask that
module what orders hold. It says so, repairs the rest, and should be run again
once the module is back on.
Entities
Order, OrderItem, Payment, OrderStatus,
OrderStatusTransition, OrderTransitionEffect, OrderComment,
OrderListSavedView, OrderItemGroup (an order's line groups — see Line
groups), OrderExternalReference (see External system references), and the
organizations.order_confirmation_emails column (owned by organizations,
read via a port). OrderItem snapshots the product + variant + unit price +
tax rate at placement so historical orders survive pricing / catalog changes.
It also copies the cart line's price_source — agreed, base, catalogue,
buyer or sale, the price-book step (or the quote agreement) that priced the
line — into order_items.price_source; the column is stored for reporting and
for a later promotions rule, and is not part of the order API's answer.
Events emitted
order.created.v1, order.status_changed.v1, order.cancelled.v1. A
cancellation is announced as order.status_changed.v1 with the new status and,
after it, as order.cancelled.v1 — carrying orderId, organizationId,
salesChannelId, the status it was cancelled from, the actor, the reason
and the businessId — once the cancelling write has committed, whichever path
cancelled the order. order.cancelled.v1 is internal to the event bus: outbound
webhooks deliver a cancellation as order.status_changed.v1. Each
transition X→Y additionally emits four templated events (built by
events/order-status-events.ts):
order.status.from_<x>_to_<y>.before, order.status.from_<x>.before
(synchronous, veto-capable) and order.status.from_<x>_to_<y>.after,
order.status.to_<y>.after (post-commit, isolated).
order.created.v1 carries orderId and organizationId. For an order an
administrator created with an origin (see Create on behalf below) it also
carries that origin, unchanged; for every other order the key is absent.
The value travels wherever the event does — an outbound webhook subscribed to
order.created.v1 receives it in the payload.
order.created.v1 is emitted after the placement has committed, on every
placement path: a subscriber can read the order it names, and a placement
that fails announces nothing.
Admin operations
- Create on behalf —
POST /api/v1/admin/ordersbuilds the customer's cart from admin-entered items and runs on-behalfplaceOrder; the customer is emailed to pay it. The request may carry an optionalorigin: { type, id }saying where the order is being created from —typea lower-case identifier of the sender's own (letters, digits, underscores),ida UUID. The module validates the shape and hands the value on, unread, onorder.created.v1: it is not stored, not returned and changes nothing about the order. A module that recognises thetypemay act on it — the CRM module links such an order to the opportunity it was created from. Only this request accepts it; a storefront placement cannot set one. The create screen (/orders/new) reads the same from its query string when another screen opens it —originType,originId, plusorganizationId,customerAccountIdandsalesChannelIdto preselect, andreturnTo, a path inside the Admin UI to go back to once the order exists. - List —
GET /api/v1/admin/ordersserver-side filter/sort/search + per-status counts. The search (q) matches the order number, the Organization's name, the customer, and an external system's reference for the order (see External system references);GET …/exportstreams CSV; saved views via…/list-views— see Saved views below. - Bulk —
POST …/bulk/status(eligible orders move; skipped reported with reason — a skipped order has not moved) and…/bulk/print-invoices. - Comments — admin/customer
…/:id/commentswith customer-visibility + notify flags; closed on terminal orders (409 ORDER_COMMENTS_CLOSED). The platform also writes internal system notes here for custom-field values not carried into the order — see The system note below. - Reorder —
…/:id/reorderrebuilds the cart (gated byorders.reorder_enabled); clone-to-quote —…/:id/clone-to-quote(an order with no lines is409 ORDER_CLONE_NO_LINES; withquote_requestsabsent, the buyer's clone is refused403 ORGANIZATION_PERMISSION_REQUIREDand the operator's503 MODULE_DISABLED).
The Create order screen
The sales channel is chosen among the customer's organization's active
sales channels. The Sales channel field offers nothing until a customer is
chosen; it then offers exactly the channels the server accepts — never another
active channel, nor an inactive one the organization is assigned to. The only
channel is preselected; with several the operator chooses. A salesChannelId
in the query string is preselected only when it is one of them, and dropped
otherwise. Choosing a customer of another organization clears the choice. When
the organization has no active sales channel the screen says so and Create
order stays disabled until it is assigned to one; when its channels cannot be
read the screen says so with a Retry button, and nothing can be sent.
Items and the order summary appear once the customer and the sales channel
are chosen. They are the two inputs pricing needs; the payment method, the
delivery method and the addresses do not gate anything. Until both are set, one
hint names what is still missing. Clearing either field hides both sections
again without discarding the lines, which come back when the field is set. A
screen opened with customerAccountId and salesChannelId in its query string
shows Items as soon as the organization's channels are read and the named
one is among them.
Products are added in two ways.
- Browse products opens the admin's shared product browser on the Active tab: the catalogue in pages, with status tabs and their counts, a type filter and a search by SKU, slug or name. The selection survives page, page-size and filter changes, and Add N adds every ticked product as a line of quantity 1 — at most 200 in one step. Grouped and bundle parents, and draft and inactive products, are listed with their reason and cannot be ticked. A product already on the order can be added again: it becomes a line of its own (for instance in another group).
- Quick add by name or SKU, beside it, appends one product under the same rules.
Both are disabled, each with a hint, for an operator without catalog:read.
Each line shows the product's name and SKU, an editable quantity, the unit
price, the line total and a remove action. Changing a quantity, the customer,
the sales channel, the delivery method or the payment method prices the lines
again through POST /api/v1/admin/orders/preview (orders:write). A quantity
that is not a whole number of 1 or more marks the line, keeps it out of the
preview and blocks Create order.
A line the preview cannot price shows why, and blocks Create order until it is removed or the cause is fixed. Each unavailable line carries exactly one code — the first that applies, in this order — and shows one reason:
| Preview code | Line reason | What to change |
|---|---|---|
PRODUCT_NOT_FOUND | No price | The product is no longer in the catalogue: remove the line. |
PRODUCT_ARCHIVED | Archived product | The product is archived: restore it in the catalogue, or remove the line. |
PRODUCT_NOT_VISIBLE_TO_CUSTOMER | The customer cannot see this product | The product's visibility or its allowed organizations exclude the customer's Organization: change them on the product in the catalogue, choose another customer, or remove the line. |
PRODUCT_NOT_IN_SALES_CHANNEL | Not in this sales channel's assortment | Choose a sales channel whose assortment holds the product, add the product to this channel's assortment, or remove the line. |
QUOTE_ONLY | No price | The customer's price for the product is quote-only: remove the line, or create a quote request instead. |
UNPRICED | No price | No price book prices the product for this customer, channel and currency — not even a base price: set a base price, remove the line, or create a quote request instead. |
BELOW_MINIMUM_QUANTITY | Below the minimum of N pcs | The product's total on the order is below its minimum order quantity: raise the quantity, or remove the line. |
BELOW_MINIMUM_QUANTITY carries the minimum and is judged only over the
lines that passed the checks above it, summing each product's lines. The lines
are priced from the price books exactly as the customer's basket would price
them — one batched resolution for every line, at each line's own quantity and
variant — so the order created is charged what the preview showed. A
code the screen does not know is shown as No price as well. The other lines
keep their prices and the summary counts only the priced ones. The preview
checks the assortment of exactly the sales channel the request names; a
salesChannelId that names no channel is refused with 404 NOT_FOUND, and the
screen shows Could not calculate prices without marking any line. A
soft-deleted product is PRODUCT_NOT_FOUND, as creating the order answers it
(404 PRODUCT_NOT_FOUND). An archived product is PRODUCT_ARCHIVED whoever
may see it and whichever channel is chosen, and creating the order refuses it
with 409 PRODUCT_ARCHIVED (Product is archived.), naming the archived
products in details.productIds and writing nothing — the reason an
operator's quote request gives. The order created is exactly the
lines and quantities on screen, in the POST /api/v1/admin/orders
payload.
At most 200 lines. POST /api/v1/admin/orders and
POST /api/v1/admin/orders/preview refuse more than 200 items as their first
step, with 422 VALIDATION_FAILED and details: { code: 'too_many_items', maximum: 200 }, before any line is evaluated. Create order also refuses a
request in which a product's total is below its minimum, with the minimum
error and details.lines[] keyed by the item's index.
Line groups. The screen's items can be sorted into named groups — Add
group, rename, delete, drag and drop, the keyboard and each line's Move to
group menu, exactly as on a quote request's Modify tab; a group's own Add
product adds to that group, anything else to Ungrouped. Each group shows its
item count, net, VAT and gross next to the live price summary; for that the
preview answers each priced line's taxRate (a fraction, 0.23, from the
same authority as the summary's tax total; absent on a line it cannot price),
and a group's VAT is the sum of net × rate over its lines. Moving a line between groups does not price the order again. Every
group needs a name before Create order enables. See Line groups below for
what the order keeps.
Split line. A line of quantity 2 or more has a Split line button beside Move to group. It asks for the quantity to move to a new line (from 1 to the line's quantity minus 1) and the group of the new line — the line's own by default — and adds a line of the same product with that quantity, reducing the original. This is how one product goes into two groups: for example 5 pieces in Hall A and 3 in Hall B. Each line is priced at its own quantity.
Custom fields. With custom_fields:read the screen shows the order's custom
fields, and their values are sent as customFieldValues. POST /api/v1/admin/orders checks them with the administrator's rules before the
working basket or any address is written, and enforces every required order
field even when the request sends no values; a refusal is
422 CUSTOM_FIELD_VALUE_INVALID (details entries { path, issue }), shown at
the field it names, and no order is created. The values are written with the
order, over any carried from a quote request, and the order.place_on_behalf
audit entry names their keys (changedCustomFields), never their values.
Custom-field values carried into an order
An order can receive custom-field values from the record it came from, for every field whose Carry value to Order option is on (set on Custom fields; the rules — same key, compatible type and options, the audience rule — are on that module's page). Only an empty order field is filled, and only once.
- From a quote request, at placement. When the customer places an order from the basket filled by ordering an accepted quote request, and the order records that quote request (the same rules that decide whether it does: the request still approved, used by no other order, in the customer's organization, at least one agreed line still in the basket), the request's values — as they are at that moment — are written with the order itself. They are part of its creation, not a later edit. Nothing is carried when the order does not record a quote request, or while the Quote Requests module is switched off.
- From a sales opportunity. An order an administrator creates from an opportunity (Create order on its Links tab) receives the opportunity's values once the CRM module has linked it to that opportunity, in a separate change attributed to the system; the order's creation stays attributed to the administrator. An order linked to an opportunity by hand receives nothing.
- Not the other way. Cloning an order into a quote request carries no value.
- Nothing fails. A value that cannot be carried is skipped, and the order is placed or linked all the same.
For an order placed on a customer's behalf, the order.place_on_behalf audit entry lists the
carried keys as carriedCustomFieldKeys. A customer's own checkout writes no audit entry, as
before. The carried values are on the order from the start, so subscribers of order.created.v1
read them.
What the audit log holds. The platform audit log is read by everybody holding
audit_log:read, whichever organizations they may see, so an order's entries carry names and
structure, never its values. The custom-field change (order.custom_fields.update) and the carry
from an opportunity (order.custom_fields.carry) name the keys that changed as
changedCustomFields, without their values. Neither order.place_on_behalf nor
order.place_via_api_key records the order's total, currency, organization or customer. The order
itself holds the values.
The system note
When a value is skipped, the order's Comments tab holds one note by System for that placement or link, marked Internal: Not carried from quote request …: or Not carried from sales opportunity …:, followed by one line per skipped field — the name of the field it came from, as it read when it was skipped, and the reason (no such field on the order, a different type, a field visible to customers fed by an internal one, a value the field does not accept). Anybody who can open the order can read it; it shows no value.
The note is never shown to the customer — not in the storefront and not on the customer's comments
endpoint — and sends no notification. It has no author: systemNote on the admin comment reply
(GET /api/v1/admin/orders/:id/comments) holds its structure — kind
(custom_field_carry_skipped), source (entityType, recordId, reference) and skipped
(key, reason, label) — and body holds an English sentence for any reader that does not
translate it. Every other comment answers systemNote: null.
Custom-field filters
An order custom field whose Use as list filter option is on (set on Custom fields) is offered as a filter in the order list's advanced filters, labelled in your language: the text it contains, a number or date range, yes or no, or one or more options. An order without a value for the field never matches. Each custom-field filter is shown as a removable chip beside the other active filters, narrows the total and every page, and returns the list to its first page when it changes. The filters are in the page address, so a filtered list can be bookmarked or shared, and the CSV export exports the same orders.
If the address names a filter that is no longer available — its option was switched off or the
field deleted — the list says so by the field's name and offers Remove this filter; the CSV
export is not offered until it is removed. API callers send the filters as customFieldFilters on
GET /api/v1/admin/orders and GET /api/v1/admin/orders/export, and read the offered fields
from GET /api/v1/admin/orders/custom-field-filters (orders:read). An inverted range (min above max, from after to) or an operator that does not apply to the field's type answers 400 VALIDATION_FAILED.
Saved views
A saved view is a named set of order-list filters that an admin can apply again with one selection.
Using saved views
The order list's toolbar carries a Saved views selector, whose first entry is — Select a view —, and two buttons beside it: Save view and Delete view.
- What a view remembers. Every filter on the order list — status, payment status, sales channel, payment method, delivery method, the date range, the search text, the organization and customer names, the total range and the custom-field filters — plus the sort and the visible columns. A custom-field filter that is no longer available when the view is loaded is dropped, with a notice naming it, and the rest of the view loads. Choosing a view replaces all of them with the view's values: a filter the view does not hold is cleared, anything you had changed and not saved is discarded, and the list goes back to its first page.
- Saving. Save view opens one dialog with a Name field and a Share with every admin who can open this list checkbox. The checkbox starts unchecked, so a new view is private unless you tick it. The name is required, leading and trailing spaces are removed, and it can be at most 160 characters long. Problems are shown on the field and nothing is sent until they are fixed; a refusal from the server is shown inside the dialog, which stays open with what you typed.
- Private or shared. A private view is listed only for you. A shared view is listed for every admin who can open the order list, with (shared) after its name. The selector does not show who saved a shared view.
- One name per admin. You cannot hold two views on this list whose names differ only in letter case or in surrounding spaces. The dialog answers You already have a view with this name. before sending anything, and the server refuses the name as well. Accented letters are different letters: Zamówienia and Zamowienia are two names. Names other admins use, and names used on the product or quote request list, do not count. Views whose names already clashed before this rule existed were kept as they are.
- Deleting. Delete view is enabled only when the selected view is one you may delete. It asks for confirmation and names the view — Delete the view “…”? — and for a shared view adds that it will disappear for every admin who can open this list. Nothing is deleted until you press Delete.
- Who may delete or change a shared view. Its owner, or any admin whose
role is not
sales_representative— not only theplatform_adminrole: a custom role counts as well. Such a deletion or change leaves no audit trail: saved views are not written to the audit log. Decide which roles you grant with that in mind before your team relies on shared views. A sales representative can delete only their own views, and nobody can see or delete another admin's private view. - Only save, load and delete. The Admin UI does not rename a view, change whether it is shared, or overwrite it with the current filters; save a new view and delete the old one instead. There is no limit on the number of views.
Saved views API
| Method and path | Answers |
|---|---|
GET /api/v1/admin/orders/list-views | 200 — the caller's own views plus every shared view, ordered by name |
POST /api/v1/admin/orders/list-views | 201 — the created view |
PATCH /api/v1/admin/orders/list-views/:id | 200 — the modified view; any of name, shared, filters, sort, visibleColumns. The Admin UI does not call it. A body that changes nothing — empty, or every value as stored — writes nothing, logs nothing and answers the current view |
DELETE /api/v1/admin/orders/list-views/:id | 200 — { data: { deleted: <id> } } |
- Gate. All four routes are gated by
orders:read; there is no separate permission code. A request without an admin actor is refused with401 UNAUTHORIZED. - Body.
name(trimmed, 1–160 characters, no Unicode control or format characters),shared(boolean),filters(an object, at most 8192 bytes as UTF-8 JSON),sort({ field, dir },fieldat most 64 characters,dirascordesc; required on create) and an optionalvisibleColumns(at most 64 ids of at most 64 characters each, ornullfor the default columns). Anything outside those bounds is400 VALIDATION_FAILED. The shapes arecreateOrderSavedViewRequestSchemaandupdateOrderSavedViewRequestSchemain@endora-commerce/contracts. - Two caller-relative flags. Every view in a response carries
ownedByCallerandcanModify—truewhen the caller owns the view, or the view is shared and the caller is a platform admin in the sense below. The Admin UI enables Delete view fromcanModify, and before saving runs a best-effort duplicate-name pre-check against the listed views withownedByCaller. The server'slower(btrim(name))comparison is authoritative: a name the pre-check lets through can still be refused with409. - Platform admin, for saved views, is an admin whose request tenant context
has
mode === 'all'— every role exceptsales_representative. The order, product and quote request lists derive it the same way, and it fails closed: an admin whose reach cannot be resolved is not a platform admin. - Refusals. An absent view, or another admin's private view, is
404 NOT_FOUND— the two are indistinguishable. A shared view the caller neither owns nor may modify as a platform admin is403 FORBIDDEN. A name whose key the view's owner already uses on this list is409 ORDER_SAVED_VIEW_NAME_TAKEN, "You already have a saved view with this name on the order list. Choose a different name.", in the request's language. - The name key is the name trimmed and lower-cased, compared as
lower(btrim(name))in PostgreSQL — no accent folding. The rule binds the view's owner: a platform admin renaming a colleague's shared view is refused when the colleague already uses that key. Creating a view and changing a name's key take a transaction-scoped advisory lock keyed on the owner, so two concurrent saves under one name leave exactly one view. Rows inorder_list_saved_viewsthat already shared a key were left alone; the rule applies to writes only, and a stored name may be longer than the write rule allows. - No audit. Saved views are personal UI configuration and do not run
through the Command Bus. When an admin modifies or deletes a view they do not
own, the service writes one
infolog record:{ event: 'saved_view.updated' | 'saved_view.deleted', list: 'order_list_saved_views', viewId, ownerAdminUserId, actorAdminUserId }. That log line is the only trace. - Storage.
order_list_saved_views(OrderListSavedView) is platform-global, not organization-scoped: it holds filter values, never list results, and every list read after a view is applied runs under the loader's own scope.
An order placed from an accepted quote request
An order placed from the basket an accepted quote request filled records that
quote request in sourceQuoteRequestId (orders.source_quote_request_id). The
Quote Requests module completes the quote request when it sees such an order,
and other modules read the field to tell which order a quote request became.
The basket only carries a claim, and placement checks it against the quote request as it is at that moment. The order records the quote request when all four hold:
- the quote request belongs to the same organization as the order;
- it is still
Approved— not canceled, expired or already completed; - no other order records it already — when two people of one organization each turned the same quote request into a basket, the first order placed is the quote request's and the second is an ordinary order;
- the basket still holds at least one of its lines — the same product and variant at the agreed unit price.
Otherwise the order is placed all the same and records nothing; the refusal is logged, never shown to the buyer. No request body carries the field: the storefront, the admin create-order screen and the external order API cannot name a quote request.
The agreed prices are a different question, and that one can refuse the
order. Before anything is reserved or written, placement checks every basket
line still priced at a quote's agreement (still at the agreed quantity) against
that quote as it is now, and refuses with 410 QUOTE_VALIDITY_ENDED when the
quote's validity date has passed (details.code lapsed), when it no longer
applies — re-opened, canceled, expired or gone (withdrawn) — or when the Quote
Requests module is switched off and nothing can confirm the prices
(unavailable). The basket stays as it was. A quote another order has already
completed still binds its prices until its validity date. The Quote Requests
module page, under Validity date, describes the rule from the buyer's side.
With the Quote Requests module switched off, a basket without quote prices is placed exactly as before and records no quote request.
Line groups
An order can show its lines in named groups — Hall A, Hall B — with the lines without a group under Other items. Groups are presentation only: they change no price, quantity or total. An order gets them in one of two ways, and never changes them afterwards: no screen and no API edits a placed order's grouping.
From an accepted quote request. When placement records the quote request the basket came from (see the previous section), the order copies the quote's groups in the same transaction. Each order line is matched to a quote line: first every line with the same product, variant, agreed quantity and agreed unit price, then by product, variant and price, then by product, variant and quantity, and finally by product and variant alone, each quote line used once. So a product split over two groups of the quote — 5 pieces in one, 3 in another, at one price — keeps each line in its group. A matched line takes the quote line's group and order; a line that matches nothing — added to the basket after the conversion, or changed so it no longer matches — goes under Other items, after the matched ones. A quote group that receives no line is not copied. When placement does not record the quote request, or the Quote Requests module is switched off, the order is placed without groups, otherwise exactly as before. A later change to the quote leaves the order's groups alone.
From the Create order screen. An operator arranges the lines into groups
before creating the order (see The Create order screen); the order is created
with them in the same transaction, and a refused creation writes no group.
Groups without a line are not created. One product may be on several lines
— in two different groups, or twice in one: each request line becomes an order
line of its own, in its own group, priced at its own quantity (a product's
minimum order quantity is still judged on its total across its lines).
POST /api/v1/admin/orders takes an optional groups list
({ key, name }, in display order, at most 50, names of 1 to 120 characters)
and per item an optional groupKey. The grouping is recorded in the
order.place_on_behalf audit entry (each group's line count, in order; not its
name, which is a value and stays out of the audit log); a
buyer's own checkout stays unaudited, as before.
Where they are shown. The admin order screen and the buyer's order page
show each group as a headed section with its lines and a summary — item count,
net, VAT and gross, adding up the rows above it — then Other items. An order
without groups, and every order placed before groups existed, looks exactly as
before. Every order reply — admin, customer and the external order API —
carries itemGroups ({ id, name, position }) and, per line, groupId and
position, lines in display order; an integration that ignores them keeps
working.
What does not carry groups. Invoices, returns, reorder (it fills a basket), order again as a quote request, the cart and checkout, e-mails, webhooks and the external order intake. There is no order PDF.
Order minimums at placement
Placement applies the catalogue's minimum order quantities to every basket line — the product's minimum in pieces and each packaging unit's minimum in units, counted over every line of the product (the Catalog module's page defines both). It is the last word on every path that ends in an order: checkout, one-click buy, a reorder, a basket filled from a quote request, the admin's Create order and the external order API.
- Before any side effect. The check runs inside the placement transaction right after the basket is read — before the order value and credit checks, the order number, and any stock or credit reservation. A refusal writes nothing.
- What it answers. A line whose product record is gone →
404 PRODUCT_NOT_FOUNDwithdetails.cartItemIds. A line below a minimum →422 PRODUCT_BELOW_MINIMUM_QUANTITYor422 PACKAGING_UNIT_BELOW_MINIMUM_QUANTITYwithdetails.lines[], one entry per offending line (cartItemId,productId,productName,kind,minimum,packagingUnitName). The sentence and the product names are in the language the response is answered in: an administrator's stored language, otherwise the request'sAccept-Language(q-weights honoured), otherwise the channel's default language. - The checkout preview says the same first.
POST /api/v1/orders/preview-totalanswersbelowMinimumLines[]— the lines placement would refuse, with the same exemptions; a line whose product is gone haskind: 'product_unavailable'and no name or minimum. The storefront lists them and disables Place order. The preview takes no lock, so under a race placement decides. - A basket filled from an accepted quote request. The Carts module exempts
each line seeded from the quote while its quantity equals the quote's.
Placement and the preview honour that exemption only while the quote
request is still valid at that moment: it exists, belongs to the buyer's
organization, is still
Approved— not canceled or expired, its validity not ended — no order records it yet, and the basket still holds at least one of its lines at the agreed price. Otherwise every line is judged like any other. The check and its lock run at the start of placement, so the exemption is decided before anything is written. With the Quote Requests module switched off, nothing can vouch for the quote and no line is exempt. The preview's check is also published asorderQuoteSourcePort, which the Carts module asks when a basket is submitted for approval, so submit judges a quote-seeded line as the preview does; placement confirms the quote again. - External order API (
POST /api/v1/external/orders) and admin Create order build a working basket from the request (the Carts module's Working baskets) and judge each product's total over the request's lines; a below-minimum request is refused whole, withdetails.lines[]keyed byindex. The request is judged on its own — the customer's basket counts toward nothing — and refused before anything is written. The customer's basket is never touched, whether the order is placed or refused. The same holds for a line with no price or one sold on request only: it is priced before the working basket is created. Neither carries a packaging unit, so only the pieces minimum applies there. Both refuse more than 200 lines with422 VALIDATION_FAILED,details.code = 'too_many_items'— on the external API this is checked first, before theIdempotency-Keyheader is required, and leaves no idempotency record.
Returnable at purchase
Each order line records whether its product was returnable when the order was
placed (order_items.returnable_at_purchase), on every placement path. Later
changes to the product's Returnable flag do not change it. A line whose
product record or flag cannot be read at placement is recorded as not
returnable, never left empty. Lines of orders placed before this column
existed hold null, which the Returns module treats as returnable. The value
reaches Returns through OrderReturnContextPort (returnableAtPurchase on each
line); Returns reads no Orders table. Placement records it whether or not the
Returns module is switched on.
Migration 20261016T082022_orders_order_item_returnable_at_purchase.ts adds
the column (nullable).
When an order was completed
An order records the moment it first entered completed
(orders.completed_at). OrderTransitionService stamps it in the same
transaction as the status write, and an order created directly in completed
is stamped when it is inserted. It is never rewritten: editing a completed order
afterwards does not move it.
It is the moment the Returns module counts from. OrderReturnContextPort
reports it as completingStatusEnteredAt, and the free-return window and a
consumer's withdrawal period run from it. An order that has never been
completed reports null: its period has not started. Nothing here reads the
Shipments module, so switching Shipments off changes nothing about it.
Complete an order when the goods have been delivered. The platform has no delivery date: a shipment's success means the carrier accepted the parcel. A consumer's withdrawal period counts from the day they receive the goods, and completing the order is how the shop says that day has come. Completing it at dispatch starts the period early; the Returns module keeps a grace after the period for that reason (see the Returns page).
Until this column existed, the moment was read from the order's updated_at,
which every later edit moved forward. Migration
20261108T000543_orders_completed_at.ts adds the column (nullable) and fills it
with updated_at on every order already in completed. That is exactly the
moment those orders were judged by before, so no existing order changes on
upgrade; for an order edited after it was completed, it is the last edit rather
than the completion, an approximation nothing recorded can improve.
Settings
orders.min_order_value (number, gates Checkout + admin create; an amount, so
at most two decimal places — more is refused with 400 AMOUNT_PRECISION_EXCEEDED;
an order below it is refused with 422 ORDER_BELOW_MINIMUM_VALUE, whose details
carry minimum, subtotal and currency, the amounts as two-decimal strings),
orders.reorder_enabled (boolean), orders.confirmation_recipients
(string list) — all global or per-sales-channel. Plus per-org
order_confirmation_emails. The confirmation email CCs the customer + org
list + scope list (best-effort, never blocks placement).
Order-confirmation e-mail
After a successful checkout, OrderService.placeOrder dispatches a
confirmation e-mail (post-commit, best-effort — a mail failure never undoes a
placed order). Built by email-templates/order-confirmation.ts, it contains
the ordered products with amounts, the delivery method + cost, the payment
method with any additional payment cost (e.g. +5.00 PLN for cash on
delivery), the applied discounts, the order-total summary, and both the
shipping and billing addresses. The payment line is rendered through the
payment e-mail renderer registry (payments/services/payment-email-renderer.ts)
— an adapter's renderers.email key overrides the platform default.
Billing company data
An order's billing snapshot carries a company name and a tax ID only when there
is a company to bill. For a company Organization, placeOrder defaults them to
the Organization's legal name (or its name) and tax ID, and the buyer may
override either at checkout for that one order. A personal (B2C) Organization
is not a company, so it contributes no default: its tax ID is an internal
placeholder and its name is the person's. Its order is billed to the person —
no company name, no tax ID — unless the buyer ticks I need a company invoice
at checkout and types the company's name and NIP, which are then validated as
at company registration. The invoice, its PDF, the confirmation e-mail and the
order screen print a tax-ID line only when the order carries one. An order
keeps the snapshot it was placed with. The admin order screen's Organization
panel likewise prints no tax ID for a personal Organization and labels it
Individual customer instead: the admin order reply carries
organization.taxId: null and organization.isPersonal: true for it.
External system references
A module that hands orders over to another system — an ERP, a warehouse system, a fulfilment connector — records on the order what that system answered: its own number for the order, where the hand-over stands, and the other system's own words when it refused. The operator reads it on the order page, where a buyer's call is answered, instead of in the connector's own screens.
Each order holds one entry per system. An entry has:
| Field | Meaning |
|---|---|
| System | The writer's stable key, normally its module id — lower-case letters, digits, _, - or ., starting with a letter, at most 64 characters. |
| Reference | The other system's number for the order, once it has one (at most 255 characters). |
| State | pending (handed over, no answer yet), synced (accepted) or error (refused). |
| Message | The other system's own words, normally on error — plain text, at most 1000 characters. |
| Updated | When the entry last changed. |
On the order page the External systems section lists each entry with its
state as a badge, and says so when no system has reported yet. The message is
shown as text, never as markup. Anyone who can open the order sees it: reading
follows orders:read, and a sales representative sees the entries of the orders
they can see. Buyers never see them.
In the orders list the search finds an order by its reference, as it finds an order number: a fragment, matched case-insensitively, whichever system recorded it. The message is not searched.
For a module author, the seam is the port orderExternalReferencePort
(OrderExternalReferencePort in @endora-commerce/contracts, container name
also exported as ORDER_EXTERNAL_REFERENCE_PORT). Resolve it per use with
lazyPort; it has no admin HTTP route.
set(orderId, system, { state, reference?, message? })creates or updates the system's entry. An omittedreferencekeeps the stored one andnullclears it; an omittedmessagemeans none, so reportingsyncedafter anerrordoes not leave the refusal standing.get(orderId, system),listForOrder(orderId)read entries back, andfindOrderIds(system, reference)finds the orders carrying an exact reference — normally one.
Every change is one Command, order.external_reference.set, audited with the
calling actor, so call it inside a tenant context — a worker under
enterSystemScope. A write that changes nothing records nothing and leaves
Updated where it was, because a sync loop resends. An order the caller cannot
see is refused 404 ORDER_NOT_FOUND, and a malformed system key, state,
reference or message 400 VALIDATION_FAILED, before anything is written.
An entry outlives its writer: uninstalling the module that wrote it leaves the
entry on the order, as history. Migration
20261110T143322_orders_order_external_references.ts creates the table
(order_external_references, unique on order and system), empty.
Extension points
- Payment adapters — see the
payment_methodsmodule.placeOrderdispatches start-payment through thePaymentAdapterRegistry; new methods register an adapter rather than editing the order service. - Access scoping —
order-access-service.tsis the single place that enforces the buyer's order scope (own orders, or the Organization's withorders.view_organization, asked oforganizationPermissionPort); the list, the detail, reorder, clone to a quote request andOrderReadPort.findByIdForCustomerall go through it.invoicesandreturnsreach it through that port. - Panels on the order screen — the admin zone
order.detail.afteris mounted once at the end of an order's screen, below its tabs, and hands a contribution{ orderId }. A module adds a panel by declaringzoneComponent('order.detail.after', …)in its own admin contributions; this module names no contributor. With nothing contributed — no such module, the module switched off, or a person without the panel's permission — the zone renders nothing and the screen is exactly the one without it.
Global search
The admin's global search (the command palette, ⌘K / Ctrl+K) finds orders. This module offers the fields below; which of them are used is chosen on the Global search configuration screen.
| Field | Searched by default |
|---|---|
| Order number | yes |
| Organization name | yes |
| Customer name or e-mail | yes |
| Billing company name | no |
| Billing tax ID | no |
A result shows the order number, the organization, the date placed, the total and the status, and opens the order. An exact order number is listed first. Orders appear for a role holding orders:read, and a sales representative sees only the orders of the organizations assigned to them — the orders the Orders list shows them.