> For the complete documentation index, see [llms.txt](https://docs.fulfillmenttools.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fulfillmenttools.com/documentation/by-pillar/order-management.md).

# Order Management

In fulfillmenttools, an order represents the consumer's intent as captured in the shop system. It describes what the customer wants, independent of how it will fulfill it later. The order is the starting point for all subsequent [routing](/documentation/by-pillar/advanced-order-routing.md) and [fulfillment](/documentation/by-pillar/store-operations.md) activities.

The order entity has its own lifecycle and can be in several states that describe the condition of the consumer request.

## Order statuses

The order status reflects the state of the consumer's request. This is the status shown in the [orders API](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/orders/-orderId-).

<table><thead><tr><th width="129.3828125">Status</th><th width="611.734375">Description</th></tr></thead><tbody><tr><td><code>OPEN</code></td><td>The order has been created and is ready for further processing.</td></tr><tr><td><code>PROMISED</code></td><td><p>This state represents a preliminary order created for availability and feasibility checks. In this state, the platform can evaluate stock availability, earliest possible delivery dates, carrier options, and other fulfillment constraints before the order becomes binding. A promised order either expires and transitions to an <code>OBSOLETE</code> status, or it's confirmed and becomes a real customer order in the <code>OPEN</code> status.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>For more details on availability checks and promising logic, see the <a href="/pages/cb157c370145ca3a7f3b674477c90356c754b01e">Availability and Promising documentation</a>.</p></div></td></tr><tr><td><code>LOCKED</code></td><td><p>In some cases, it might be necessary to perform manual checks on an order, for example, customer verification or fraud detection. Locked orders are routed to a facility but don't result in a pick job until they are unlocked. Unlocking can be done manually in <a href="/pages/35e48e20209b4f28e9203d9952469bf02ab27b53">Backoffice</a> or using the <a href="https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/orders/-orderId-/actions">orders action REST API</a>.</p><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Since a locked order doesn't create a pick job, it's not affected by a <a href="/pages/fc7a560690675a9455f9cbe190d946634ca5487c#time-triggered-reroute-for-started-pick-jobs">time-triggered reroute</a>.</p></div></td></tr><tr><td><code>CANCELLED</code></td><td>The order was canceled manually or automatically, depending on the configuration.</td></tr><tr><td><code>OBSOLETE</code></td><td>A promised order expires and transitions to this state.</td></tr></tbody></table>

These statuses belong to the order entity itself and don't represent operational progress. They determine whether and when the consumer request can move into operational handling.

## Order definition

### Consumer information

The `consumer` section describes the party on whose behalf the order is placed. The consumer may represent:

* A consumer (for example, an end customer who places an eCommerce order)
* A facility (for example, a supply order)
* A consumer on whose behalf an order is placed by a facility or store

Consumer information may include:

* One or more addresses (for example, postal address, invoice address, or parcel locker address)
* Facility references for supply orders
* Custom attributes for tenant-specific extensions

For supply orders, consumer addresses aren't supported, except for addresses of type `INVOICE_ADDRESS` when the order is placed on behalf of a consumer.

### **Items and product information**

The `orderLineItems` section contains the articles being purchased, including:

* Quantities
* Measurement units
* Scannable codes
* Custom attributes
* Measurement units and their tolerance validations
* Allowed substitutes
* Pricing information
* Tags

If all relevant attributes are maintained in the listing, an item can be provided in its minimal form: `tenantArticleId` and `quantity`**.** All additional article information is then resolved from the [listing](/documentation/by-pillar/global-inventory-hub/listing.md).

### **Custom services**

[Custom services](/documentation/by-pillar/store-operations/services/custom-services.md) extend the order with additional tasks that must be performed after picking. This enables complex service workflows such as engraving, tailoring, or appointment-based services. They can be attached to the entire order or to specific order line items.

Each service includes:

* Service definition
* Nested service items (optional)
* Article references
* Additional information fields

### **Delivery preferences and order types**

Delivery preferences describe how an order should be fulfilled. They also implicitly define the order type. fulfillmenttools doesn't require an explicit order type field. Instead, the type is derived from the provided delivery preferences.

* If delivery preferences specify `collect`, the order becomes a click-and-collect order.
* If delivery preferences specify `shipping`, the order becomes a ship‑from‑store order.
* If no delivery preference is provided, the system defaults to ship‑from‑store.
* If the consumer is a facility, the order becomes a supply order.

Delivery preferences may include:

* Collect preferences
* Shipping preferences
* Reservation preferences
* Sourcing options reference
* Supplying facilities
* Target times

#### **Click-and-collect order**

A click-and-collect order is created implicitly when the delivery preferences specify a collection at a facility.

The `Order.deliveryPreferences` object identifies the order for in-store collection.

The following attributes in `Order.deliveryPreferences` mark an order as a collect order:

* `paid`: A boolean flag indicating if the consumer has already paid for the order. This flag must be set to `false` for click-and-reserve orders.
* `provisioningTime`: Represents the appointment time for consumer pickup. This appointment time can be changed during the fulfillment process if the consumer's plans change. Based on the `provisioningTime`, it is possible to configure an automatic cancellation timeframe if the consumer doesn't arrive for pickup.
* `facilityRef`: Specifies the pickup facility. This must be a valid `facilityRef`. For details on configuring facilities, see the [Facilities article](/documentation/getting-started/facilities.md).

**Facility reference:** The consumer's chosen facility location for picking up their order. The [service type fence](/documentation/by-pillar/advanced-order-routing/fences.md#service-type) will evaluate this attribute.

**Provisioning time**: Indicates when the order is expected to be ready for consumer pickup at the selected facility.

**Supplying facility configuration:**

* These facilities serve as backups for the primary facility in case the primary facility can't fulfill all ordered items. In this case, a [reroute](/documentation/by-pillar/advanced-order-routing/reroute.md) can be triggered into one of the supplying facilities (which have to be of service type ship-from-store). The supplying facility then fulfills the order and sends it back to the primary facility, where the consumer can pick it up. This limits the number of facilities the [routing rules](/documentation/by-pillar/advanced-order-routing/routing-strategy.md) must consider. The [service type fence](/documentation/by-pillar/advanced-order-routing/fences.md#service-type) will evaluate this attribute.
* If supplying facilities are specified for a click-and-collect order, they will compete against the primary click-and-collect facility during initial routing. If a supplying facility performs better than the primary click-and-collect facility, this order will be routed directly to the supplying facility. The supplying facility, in turn, fulfills the order and sends it back to the primary facility.

#### **Ship‑from‑store order**

A ship‑from‑store order is created implicitly when the delivery preferences specify shipment to a consumer address. If no delivery preference is provided, this is the default. The `Order.deliveryPreferences` object identifies the order for shipping. Typically, a shipping label is required to send the parcels.

The following attributes in `Order.deliveryPreferences` mark an order as a shipping order:

* `preferredCarriers`: Defines the logistics carrier chosen for delivery.
* `serviceLevel`: Specifies the service level, which is either `DELIVERY` for standard shipping or `SAMEDAY` for same-day delivery.
* `desiredDeliveryTime`: Contains the delivery time selected by the consumer during checkout. This value, combined with the reservation preference mode, determines when fulfillmenttools checks for stock reservation.
* `reservationPreferences`: Defines behavior for orders that can't be fulfilled immediately after routing. This is relevant when a consumer places an order for future delivery, and the stock shouldn't be reserved instantly (for example, for items with a best-before date).

fulfillmenttools calculates the `targetTime` attribute based on facility and carrier configurations; it is not set directly in the order.

fulfillmenttools performs routing based on:

* Facility configuration
* Listings
* Stock
* Routing parameters (optional)

Relevant delivery preference attributes:

* **Service level:** Defines whether the consumer requires [same day](/documentation/by-pillar/store-operations/carrier-management/carrier-features-and-requirements.md#same-day-delivery) or standard delivery. The [service type fence](/documentation/by-pillar/advanced-order-routing/fences.md#service-type) will evaluate this attribute.
* **Preferred carrier:** Can be used if the consumer wants their order delivered by a specific carrier. The [carrier availability fence](/documentation/by-pillar/advanced-order-routing/fences.md#carrier-availability) will evaluate this attribute.
* **Preselected facilities**: Specifies several facilities that should be taken into consideration when performing a routing decision instead of all facilities within the network. The [preselected facility fence](/documentation/by-pillar/advanced-order-routing/fences.md#preselected-facilities) will evaluate this attribute.
* **Desired delivery time/target time:** Used for prioritization and promise calculations.

The `Order.consumer.email` address is forwarded to the logistics carrier when a shipping label is requested. Consumer consent is required to process this personal data; otherwise, a generic email address must be supplied.

#### **Supply order**

A supply order is created implicitly when the consumer information indicates that a facility is placing the order on its own behalf.

Characteristics:

* The requesting facility appears as the consumer.
* fulfillmenttools identifies the best supplying facility.
* The order is fulfilled as an internal [interfacility transfer](/documentation/by-pillar/store-operations/interfacility-transfer.md).

#### **Payment information**

The `paymentInfo` section captures the payment method and currency. It doesn't influence routing but is relevant for operational visibility and customer communication.

#### Custom attributes, stickers, and tags

[Custom attributes](/documentation/getting-started/custom-attributes.md) or [tags](/documentation/getting-started/tags.md) allow tenants to add additional, tenant‑specific information to an order. They can be used to influence routing logic through the [custom routing rules](/documentation/by-pillar/advanced-order-routing/doms-toolkit.md) or to attach [stickers](/documentation/getting-started/stickers.md) to operational entities for better visibility during fulfillment.

## Order events

You can find the relevant order management events in the [available events article](/documentation/getting-started/eventing/available-events.md).

## **Process**

While the order describes the consumer request, the process represents the complete lifecycle required to fulfill it. A process begins once the platform starts processing the order and continues through fulfillment, cancellation, and returns.

A process may include:

* Routing decisions
* Reservations
* Picking and packing
* Hand over to carriers and consumers
* Rerouting
* Expiry handling
* Shipping
* Returns or operational cancellations

### Process flow

This graphic illustrates how order flows through the fulfillmenttools modules.

<figure><img src="/files/zQejyJXYltRG8uP2QyVQ" alt=""><figcaption></figcaption></figure>

### **Status model**

The process status model provides status information at multiple levels of granularity. This enables consumers to monitor a process from a high-level business perspective while still allowing detailed analysis of the underlying operational activities. This is the status model found in the [process API](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/process).

The status hierarchy is structured as follows:

```
Process
 └─ Domains
     └─ Modules
         └─ Module entities
```

Each level aggregates the status information of the level below it.

Statuses are aggregated bottom-up through the hierarchy. Module statuses are derived from module entity statuses, domain statuses from module statuses, and the overall process status from domain statuses. Aggregation follows predefined precedence rules to ensure a single consistent status representation at each level.

* [**Process status**](#overall-process-status) provides an overall view of the entire process.
* [**Domain statuses**](#domain-statuses) provide a business-oriented view of specific process areas.
* **Module statuses** represent the status of individual functional modules.
* **Module entity statuses** represent the status of the concrete entity.

#### **Overall process status**

The process status represents the highest level of status aggregation within the process.

It provides a consolidated view across all domains and is intended as the primary indicator of the overall process state.

<table><thead><tr><th width="160.5">Process status</th><th width="605.5625">Description</th></tr></thead><tbody><tr><td><code>CREATED</code></td><td>The process has been created and is ready for further processing.</td></tr><tr><td><code>IN_PROGRESS</code></td><td>The process is actively being executed. This includes running routing operations, ongoing fulfillment tasks, or an initiated return.</td></tr><tr><td><code>FINISHED</code></td><td>All underlying modules and their entities have completed their lifecycles, and the process is fully resolved.</td></tr><tr><td><code>CANCELED</code></td><td>The process has been terminated because the associated order was canceled.</td></tr><tr><td><code>ERROR</code></td><td>The process can't progress because one or more underlying modules and entities are stuck or have failed, for example, due to unroutable items or an unsuccessful shipping‑label creation.</td></tr></tbody></table>

#### Domain statuses

Domain statuses group related modules into logical business areas.

They provide a business-centric view of the process and allow consumers to focus on specific aspects of process execution without analyzing individual modules.

The following domains are available:

<table><thead><tr><th width="201.4140625">Domain</th><th>Aggregated modules</th><th>Description</th></tr></thead><tbody><tr><td><code>domsStatuses</code></td><td><code>ORDER</code>, <code>ROUTING</code></td><td>Order orchestration and routing-related activities.</td></tr><tr><td><code>operativeStatuses</code></td><td><code>PICKING</code>, <code>PACKING</code>, <code>SHIPMENT</code>, <code>HANDOVER</code>, <code>SERVICE_JOB</code></td><td>Operational fulfillment activities.</td></tr><tr><td><code>inventoryStatuses</code></td><td><code>RESERVATION</code></td><td>Inventory-related activities.</td></tr><tr><td><code>returnStatuses</code></td><td><code>RETURN</code></td><td>Return processing activities.</td></tr></tbody></table>

Each domain status is represented by a `processStatusDetail` object:

```json
{
  "status": "IN_PROGRESS",
  "subStatuses": ["DELAYED"],
  "subStatusHistory": ["DELAYED"]
}
``
```

#### Substatus

The substatus provides additional operational context to the process status by highlighting specific conditions that may require attention or indicate a risk to the fulfillment process. While the process status represents the overall fulfillment phase, the substatus identifies exceptional situations detected during order execution.\
\
Substatuses can exist at different levels of the status hierarchy, including module entities, modules, domains, and the overall process. As status information is aggregated through the hierarchy, substatuses may also be aggregated or generalized to provide an appropriate level of detail for each level.\
\
Multiple substatuses can be associated with the same process status. They don't represent a separate lifecycle, but rather operational indicators that supplement the current process status with more detailed information.\
\
A substatus remains active as long as the underlying condition exists. Once the condition is resolved, the substatus is removed from the active `subStatuses` list and considered historical. Historical substatuses are retained in `subStatusHistory` to provide visibility into previously occurring conditions during the process lifecycle.

<table><thead><tr><th width="155.7109375">Substatus</th><th>Description</th></tr></thead><tbody><tr><td><code>MISMATCH</code></td><td><p>A discrepancy has been detected between the expected fulfillment outcome and the actual execution result.</p><p>This substatus is assigned when the fulfillment execution deviates from the originally expected outcome and may require review or follow-up actions.</p><p>Examples include:</p><ul><li>A short pick, where the picked quantity is lower than the requested quantity.</li><li>A zero pick, where no quantity could be picked although fulfillment was expected.</li><li>A split order scenario where fulfillment was planned across multiple facilities and one part of the order was subsequently canceled, resulting in a deviation from the original fulfillment plan.</li></ul></td></tr><tr><td><code>DELAYED</code></td><td><p>The process has missed its committed fulfillment timeline.</p><p>For example, a <code>DELAYED</code> substatus is generated when the current time exceeds the pick job's <code>pickingTimes.startLatestAt</code> value.</p></td></tr></tbody></table>

## Backoffice order view

For operational users, Backoffice provides a consolidated view of the order and all related process entities. It allows you to inspect routing decisions, monitor fulfillment progress, review operational tasks such as pick and pack jobs, and execute permitted actions. For more details on how orders and processes are represented operationally, see the [Backoffice order view article](/documentation/backoffice/network-view/orders.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fulfillmenttools.com/documentation/by-pillar/order-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.