The core entity is Order (class: OrderInfo, API entity key: Order). An order begins as a basket (status = created) and progresses through a lifecycle as it is placed, processed, shipped, and finalised.
Orders support soft deletion: is_deleted is set rather than removing the row. Deleted orders are not returned to regular users; admin users can retrieve them with is_deleted=true.
The current status is a computed field (computed_status) derived from the order_status_changes collection. The most recent OrderChange record with is_current = true holds the active status. Use include=computed_status to request it (see Computed Fields).
| Status | Value | Description |
|---|---|---|
created |
0 | Basket — order initialised but not yet submitted |
placed |
10 | Submitted by the customer |
payment_authorized |
20 | Payment pre-authorised |
accepted |
30 | Accepted/approved by the provider |
printed |
40 | Printed |
processing |
50 | Being manufactured or packed |
packaged |
60 | Ready to ship |
shipped |
70 | Dispatched |
payment_captured |
80 | Deprecated; historical records only, not a fulfillment transition |
delivered |
90 | Delivered to the customer |
finished |
100 | Complete |
declined |
110 | Rejected by the provider |
refunded |
120 | Fully refunded |
cancelled |
130 | Cancelled |
booked |
140 | Bookkeeping done |
Terminal statuses: declined, refunded, cancelled. The booked status can follow finished.
Payment capture does not advance computed_status. An accepted order remains accepted when captured, and a shipped order remains shipped. Value 80 remains reserved for persisted history; it must not be used to infer shipment or delivery. Existing historical records are not rewritten. New OrderChange inserts and OrderUtils.SetStatus normalize this deprecated status to a statusless change, preserving the current fulfillment status. order_status_changed does not emit payment_captured.
| Field | Notes |
|---|---|
id |
Order identifier |
is_deleted |
Soft-delete flag |
placed_time |
When the order was submitted (null if still a basket). Used as the primary "created" timestamp. |
comment |
Customer-supplied comment |
delivery_instructions |
Customer-provided instructions for the selected delivery method. |
note |
Internal staff note (not visible to customers) |
additional_information |
Additional customer-supplied information |
cancellation_reason |
Set when the order is cancelled |
order_method_kind |
How the order was created — see OrderMethodKind below |
requisition_number |
External requisition ID supplied by the customer |
is_manual_acceptance_required |
Order requires explicit manual approval before progressing |
is_test_mode |
Order was placed in test mode |
etag |
Optimistic concurrency token |
token |
Secure access token for the order (used in redemption URLs) |
| Value | Description |
|---|---|
web |
Customer-facing online store |
api |
Created via API |
order_entry |
Manual order entry by staff |
point_of_sale |
POS / till system |
kiosk |
Self-service kiosk |
planner |
Scheduling/planning view |
subscription |
Recurring subscription order |
robot |
Automated system-generated order |
Every order has a customer sub-entity (embedded, not a separate API resource). The customer holds all personal and address data for the order.
| Field | Notes |
|---|---|
customer.invoicing_profile |
Billing contact — name, email, phone |
customer.invoicing_address |
Billing address |
customer.delivery_profile |
Delivery contact (may differ from invoicing) |
customer.delivery_address |
Delivery address |
customer.account |
Customer's account/organisation (B2B context) |
customer.locale |
Preferred language |
customer.kind |
consumer or business |
customer.note |
Internal note on the customer record |
Title resolution for the customer: invoicing profile full name → delivery profile full name → #<id>.
The customer record is created per-order — it is a snapshot of the customer's details at order time, not a live link to a user account. However, customer.account links to the persistent account if the customer is registered.
| Field | Notes |
|---|---|
total_price |
Final order total including shipping and all line items |
shipping_price |
Shipping cost component of the total |
vat_rate |
VAT percentage applied |
vat_amount_added |
VAT added on top of prices (exclusive VAT) |
vat_amount_included |
VAT already included in prices (inclusive VAT) |
captured_amount |
Amount actually charged to the customer's payment method |
captured_gift_card_amount |
Amount covered by gift card redemption |
currency |
Order currency (currency_id / currency) |
total_price is fixed at the time the order is placed and does not change when product prices are later updated. For the per-line breakdown, see Order Items below.
| Field | Notes |
|---|---|
is_paid |
Legacy name for payment authorization, not capture |
is_captured |
Payment has been captured/charged |
payment_method |
Payment method used (payment_method_id / payment_method) |
payment_method_transactions |
Raw payment transactions from the payment provider |
gift_card_application_intents |
Gift card redemption records |
is_payment_method_subscription_desired |
Should create a recurring payment subscription |
payment_method_subscription_id |
Link to the created payment subscription |
is_invoice_desired |
Customer has requested an invoice |
is_invoice_sent |
Invoice has been sent |
pending_payment_intent_id |
Pending payment intent (set during checkout) |
OrderInfo.TotalValue remains the commercial order total. A payment transaction with transaction_fee_treatment = customer_surcharge_included_in_payment_amount contributes its transaction_fee to the payer-facing total shown on confirmations, while the authorised payment amount includes both values.
shop.order_payment_captured reports a successful SetCaptured update independently of fulfillment status, including direct/manual marked-captured operations and provider callbacks. It supplies the usual order fields plus paymentCaptured = true, capturedValue (the increment, nullable for a marked-captured operation), transactions, and dateTime (capture timestamp). Transaction objects and captured-value objects are available at runtime but excluded from approved event-history values. An already-captured no-amount call does not emit another event; additional captured amounts do. The event is raised within the caller's operation and is not a transactional outbox or an exactly-once delivery guarantee.
Custom payment-capture automation must subscribe to order_payment_captured, not filter order_status_changed for value 80. Economic journals, Uniconta journals, Klaviyo purchase tracking and Baker POS payment updates use the capture event. Explicit fulfillment transitions requested alongside capture are still applied unless shouldChangeOrderStatus is false; this flag does not suppress the payment event. Rebuild callers of SetCaptured together with the shared interface because optional defaults are compiled into callers.
Payment views must use is_paid, is_captured, captured amounts and payment_method_transactions, not order-status ordering. These flags retain their existing manual-marking and partial-capture semantics; confirmed gateway settlement and net capture/refund coverage require transaction evidence. The bookkeeping-needed filter and the mark-booked command use is_captured independently of fulfillment progress and exclude already-booked orders. payment_authorized remains an order status; its retirement is outside this contract.
| Field | Notes |
|---|---|
shipping_method |
Selected shipping method (shipping_method_id / shipping_method) |
shipping_plan |
Assigned shipping plan (shipping_plan_id / shipping_plan) |
desired_delivery_time |
Customer's preferred delivery date/time |
desired_delivery_time_kind |
Type of delivery request (asap, specific date, etc.) |
expected_delivery_time |
Calculated delivery date/time |
usage_time |
When the items will actually be used (events, etc.) |
shipping_distance |
Distance in km to delivery address |
shipping_duration |
Estimated transit time |
total_weight |
Total weight of the order in kg |
shipments |
Physical shipment records linked to this order |
Gift-card balances, ledger entries, capture/refund amounts, and hold limits are gross monetary amounts in the specified currency. IGiftCardService uses decimals for these amounts; it does not assign an order VAT rate to a card. Capture results include only money captured by that call. Existing captures are read separately from the ledger, whose negative net amount represents the captured balance after refunds.
PaymentService applies gift-card payments to the remaining order value with SubtractVatInclusiveValue. AllocateVatInclusiveValue supplies the proportional order base/VAT breakdown for CapturedGiftCardValue, payment totals, and refund values. These allocations describe payment coverage and leave the commercial order total unchanged. Intermediate calculations retain decimal precision; VAT is the gross amount minus the allocated base, and full coverage leaves both components zero.
Existing captures, new captures, and active holds reduce the payable gross amount once each. Hold capture debits only the held amount on each card; completed holds are not captured again. Partial refunds use the requested gross amount, refund gift cards first, and send only the remaining amount to the payment provider. Full refunds return the outstanding gift-card balance and the provider transaction independently.
OrderService resolves payment and shipping selection specifications before evaluating an order. A specification can restrict the allowed method IDs, provide a default method ID, and allow or forbid automatic selection. Defaults are only used when they remain accessible and compatible with the order.
For order_entry and point_of_sale orders, the provider department contributes its POS defaults and explicit-selection settings. When explicit selection is required, draft and dry-run evaluation leave an absent method unselected; placement rejects an absent method when one is required.
| Field | Notes |
|---|---|
accepted_time |
When the order was accepted for production |
preparation_start_time |
When preparation should start |
latest_manufacture_start_time |
Latest time manufacturing can begin and still meet delivery |
manufacture_duration |
Total manufacturing time across all items |
packaged_time |
When the order was packaged |
| Field | Notes |
|---|---|
is_editable |
Whether the customer can still edit the order |
edit_deadline_time |
Deadline after which the customer can no longer edit |
items)items is an IList<OrderProduct> — one record per line in the order.
| Field | Notes |
|---|---|
product_id / product |
The product ordered |
item_count |
Quantity ordered |
base_item_price |
Standard unit price at order time |
total_item_price |
Effective per-item price after campaigns/rebates |
acquisition_price |
Total additional cost from acquisition-kind variant add-ons for this line |
item_weight |
Weight per unit in kg |
comment |
Customer comment on this specific line item |
campaign_id / campaign |
Campaign active for this line when ordered |
category_id |
Category the product was ordered from |
is_manual_price |
Admin manually overrode the price |
manufactured_count |
Units already manufactured |
claimed_count |
Units already claimed/handed over |
number_of_people |
Number of people this item serves |
metadata |
Freeform key-value metadata (JSON) |
selected_variants |
Chosen variant options — see Selected Variants below |
selected_booking_periods |
Booked time slots (if product uses bookings) |
claims |
Claim/handover history records |
is_deleted |
Soft-delete flag |
Line total:item_count × total_item_price + acquisition_price
When an order contains a grouped product, the parent OrderProduct has product_type = grouped. The customer's selections appear as entries in selected_variants where the variant's variant_property.product is the selected child product.
Alternatively (legacy): selections may appear as separate OrderProduct records in the order's items list with parent_order_product_id pointing to the grouped product's order item.
selected_variants)Each OrderProductVariantProperty captures one variant option chosen by the customer.
| Field | Notes |
|---|---|
variant_property_id / variant_property |
The variant option selected |
item_count |
Quantity of this variant chosen |
price |
Unit price for this variant at time of order |
free_item_count |
Complimentary units (not charged) |
user_input |
Customer-entered text (for text or file picker kinds) |
is_separate_order_product |
Variant is independent from the parent product quantity |
Line total for a variant:(item_count - free_item_count) × price
computed_variant_property_title and computed_product_variant_property are computed fields available via include=.
order_status_changes)order_status_changes is an IList<OrderChange> — the full audit trail of status transitions.
| Field | Notes |
|---|---|
status |
The OrderStatus set by this change |
timestamp |
When the change occurred |
is_current |
true for the currently active change |
note |
Note or reason recorded with the change |
user_id / user |
User who triggered the change (if applicable) |
initiator_kind |
Type of initiator (user, system, etc.) |
The active status is always the entry where is_current = true. This is exposed as computed_status (must be requested via include=).
order_rebates)order_rebates is an IList<OrderRebate> — discounts applied to the order.
| Field | Notes |
|---|---|
rebate_id / rebate |
The rebate definition |
token_id / token |
Coupon/redemption token used, if any |
rebate_amount |
Discount amount applied |
is_manual_amount |
Amount was manually set by an admin |
granted_tickets)granted_tickets is an IList<EntityGrantedTicket> — vouchers or tickets generated by this order. Each record links to the granted ticket entity with its redemption state.
Orders can be split into a parent order and child sub-orders (e.g. for multi-department or multi-cycle scenarios).
| Field | Notes |
|---|---|
is_parent |
This is a parent order with sub-orders |
is_partial |
This is a sub-order belonging to a parent |
parent_order_id |
Reference to the parent order |
sub_orders |
IList<OrderInfo> — child partial orders |
is_being_delivered_with_parent_order |
Delivery is handled by the parent order |
is_being_invoiced_with_parent_order |
Payment/invoicing is handled by the parent order |
| Field | Notes |
|---|---|
provider_department |
Department responsible for this order (provider_department_id / provider_department). IncludeByDefault=false — request via include=. |
shop_affiliate |
Affiliate that referred this order |
time_cycle / time_cycle_period |
Time cycle and period the order belongs to |
replaces_order_id |
If this order replaces an earlier order |
| Field | Notes |
|---|---|
utm_source |
UTM source parameter from the originating URL |
utm_medium |
UTM medium |
utm_campaign |
UTM campaign |
utm_content |
UTM content |
Computed fields are marked IncludeByDefault=false and are not returned unless explicitly requested. Use the include query parameter:
GET /resources/Order/123?include=computed_status,computed_created
Multiple fields can be comma-separated. See RestApi-en.md for full documentation on include.
Order| Field | Notes |
|---|---|
computed_status |
Current OrderStatus — derived from the is_current = true entry in order_status_changes |
computed_created |
Basket creation time (before placement). placed_time is set when the order is submitted. |
computed_shipped |
Actual ship time |
computed_expected_shipped |
Auto-determined expected ship time |
computed_color |
UI colour indicator for the order |
computed_latest_manufacture_start_time |
Latest manufacture start time to meet delivery |
computed_prepare_duration |
Total preparation time |
computed_manufacture_duration |
Total manufacturing time |
computed_potential_order_rebates |
Rebates that could be applied but haven't been yet |
computed_sub_order_token |
Token for creating sub-orders against this order |
computed_payment_intent_coverage_status |
Whether payment intents cover the full order amount |
provider_department |
Resolving the provider department also requires include=provider_department as it is IncludeByDefault=false |
OrderProduct| Field | Notes |
|---|---|
computed_product_title |
Product title snapshot |
computed_category_title |
Category title at order time |
OrderProductVariantProperty| Field | Notes |
|---|---|
computed_variant_property_title |
Variant option title |
computed_product_variant_property |
Resolved ProductVariantProperty for this selection |
The webadmin order context menu and editor expose a send-confirmation-email action. The permission-checked Order.SendConfirmation action invokes the shared send_order_details mail flow with the order PDF, using the customer's invoicing email. It sends email only, regardless of IsInvoiceDesired and IsInvoiceSent, and does not change either flag. Existing mail templates and department-specific resources apply.