Skip to main content

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 + PathAudiencePurpose
POST /api/v1/orderscustomerPlace order from active Cart
GET /api/v1/orderscustomerList orders: own orders, or the Organization's with orders.view_organization (see below)
GET /api/v1/orders/:idcustomerOrder detail
GET /api/v1/orders/:id/invoicecustomerOlder 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/ordersadminList every order (cross-organization)
GET /api/v1/admin/orders/:idadminOrder detail (bypasses customer scope)
POST /api/v1/admin/orders/:id/statusadminStatus transition (audited)
POST /api/v1/admin/orders/:id/payment-statusadminPayment 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:

RoleHolds it
Administratoralways (every permission, implicitly)
Memberno, unless the Organization's administrator grants it to the role
a custom rolewhen 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:

SurfaceThe order's channel
Storefront — POST /api/v1/orders, one-click buyThe channel the request resolved: X-Sales-Channel, ?salesChannel=, the host map, else the system default
Admin order creation — POST /api/v1/admin/ordersThe channel the operator chose for the order (salesChannelId in the body)
API key — the external order intakeThe 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-Channel and ?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.codeBasketSentence (English)
cart_approval_not_submittednever sent for approval"Your role requires approval of this cart before it can be ordered. Send it for approval first."
cart_approval_pendingawaiting an approver"This cart is awaiting approval by an approver in your organization. You can place the order once it is approved."
cart_approval_rejectedrejected"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.codeAlso carriesMeaning
delivery_method_not_allowed_for_organizationdeliveryMethodIdThe Organization's delivery allow-list does not contain the chosen method
payment_method_not_allowed_for_organizationpaymentMethodIdThe 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 of orderPlacementPort.placeOrder. One-click buy does not reach the refusal: a default method the list excludes makes the buyer ineligible (one_click_unavailable, reason missing_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 INTERNAL and 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.codeAlso carriesMeaning
delivery_method_not_in_sales_channeldeliveryMethodId, salesChannelIdThe delivery method is restricted to sales channels and the order's is not one of them
payment_method_not_in_sales_channelpaymentMethodId, salesChannelIdThe 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, reason missing_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.

CodeStatusWhendetails
ORDER_STATUS_CODE_TAKEN409POST …/statuses — another status has the codestatusCode
ORDER_STATUS_TERMINAL_HAS_TRANSITIONS409 / 422PATCH …/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_DELETABLE409DELETE …/statuses/:code of the initial (code initial) or a system (code system) statusstatusCode
ORDER_STATUS_IN_USE409DELETE …/statuses/:code while orders are in itstatusCode, 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 warn with 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-status and POST /api/v1/orders/:id/cancel answer 200 with { data: { id, businessId, status, paymentStatus }, meta: { partial: true } } (orderCommittedWritePartialResponseSchema in @endora-commerce/contracts). Check meta.partial before treating data as 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 inventory off, a cancelled order keeps its allocations until the module returns.
  • With credit_limits off, 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/orders builds the customer's cart from admin-entered items and runs on-behalf placeOrder; the customer is emailed to pay it. The request may carry an optional origin: { type, id } saying where the order is being created from — type a lower-case identifier of the sender's own (letters, digits, underscores), id a UUID. The module validates the shape and hands the value on, unread, on order.created.v1: it is not stored, not returned and changes nothing about the order. A module that recognises the type may 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, plus organizationId, customerAccountId and salesChannelId to preselect, and returnTo, a path inside the Admin UI to go back to once the order exists.
  • List — GET /api/v1/admin/orders server-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 …/export streams 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/comments with 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/reorder rebuilds the cart (gated by orders.reorder_enabled); clone-to-quote — …/:id/clone-to-quote (an order with no lines is 409 ORDER_CLONE_NO_LINES; with quote_requests absent, the buyer's clone is refused 403 ORGANIZATION_PERMISSION_REQUIRED and the operator's 503 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 codeLine reasonWhat to change
PRODUCT_NOT_FOUNDNo priceThe product is no longer in the catalogue: remove the line.
PRODUCT_ARCHIVEDArchived productThe product is archived: restore it in the catalogue, or remove the line.
PRODUCT_NOT_VISIBLE_TO_CUSTOMERThe customer cannot see this productThe 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_CHANNELNot in this sales channel's assortmentChoose a sales channel whose assortment holds the product, add the product to this channel's assortment, or remove the line.
QUOTE_ONLYNo priceThe customer's price for the product is quote-only: remove the line, or create a quote request instead.
UNPRICEDNo priceNo 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_QUANTITYBelow the minimum of N pcsThe 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 the platform_admin role: 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 pathAnswers
GET /api/v1/admin/orders/list-views200 — the caller's own views plus every shared view, ordered by name
POST /api/v1/admin/orders/list-views201 — the created view
PATCH /api/v1/admin/orders/list-views/:id200 — 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/:id200 — { 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 with 401 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 }, field at most 64 characters, dir asc or desc; required on create) and an optional visibleColumns (at most 64 ids of at most 64 characters each, or null for the default columns). Anything outside those bounds is 400 VALIDATION_FAILED. The shapes are createOrderSavedViewRequestSchema and updateOrderSavedViewRequestSchema in @endora-commerce/contracts.
  • Two caller-relative flags. Every view in a response carries ownedByCaller and canModify — true when 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 from canModify, and before saving runs a best-effort duplicate-name pre-check against the listed views with ownedByCaller. The server's lower(btrim(name)) comparison is authoritative: a name the pre-check lets through can still be refused with 409.
  • Platform admin, for saved views, is an admin whose request tenant context has mode === 'all' — every role except sales_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 is 403 FORBIDDEN. A name whose key the view's owner already uses on this list is 409 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 in order_list_saved_views that 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 info log 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_FOUND with details.cartItemIds. A line below a minimum → 422 PRODUCT_BELOW_MINIMUM_QUANTITY or 422 PACKAGING_UNIT_BELOW_MINIMUM_QUANTITY with details.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's Accept-Language (q-weights honoured), otherwise the channel's default language.
  • The checkout preview says the same first. POST /api/v1/orders/preview-total answers belowMinimumLines[] — the lines placement would refuse, with the same exemptions; a line whose product is gone has kind: '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 as orderQuoteSourcePort, 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, with details.lines[] keyed by index. 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 with 422 VALIDATION_FAILED, details.code = 'too_many_items' — on the external API this is checked first, before the Idempotency-Key header 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:

FieldMeaning
SystemThe writer's stable key, normally its module id — lower-case letters, digits, _, - or ., starting with a letter, at most 64 characters.
ReferenceThe other system's number for the order, once it has one (at most 255 characters).
Statepending (handed over, no answer yet), synced (accepted) or error (refused).
MessageThe other system's own words, normally on error — plain text, at most 1000 characters.
UpdatedWhen 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 omitted reference keeps the stored one and null clears it; an omitted message means none, so reporting synced after an error does not leave the refusal standing.
  • get(orderId, system), listForOrder(orderId) read entries back, and findOrderIds(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_methods module. placeOrder dispatches start-payment through the PaymentAdapterRegistry; new methods register an adapter rather than editing the order service.
  • Access scoping — order-access-service.ts is the single place that enforces the buyer's order scope (own orders, or the Organization's with orders.view_organization, asked of organizationPermissionPort); the list, the detail, reorder, clone to a quote request and OrderReadPort.findByIdForCustomer all go through it. invoices and returns reach it through that port.
  • Panels on the order screen — the admin zone order.detail.after is mounted once at the end of an order's screen, below its tabs, and hands a contribution { orderId }. A module adds a panel by declaring zoneComponent('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.

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.

FieldSearched by default
Order numberyes
Organization nameyes
Customer name or e-mailyes
Billing company nameno
Billing tax IDno

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.