Orders — Overview

An Order represents a customer's purchase request. It drives the full fulfillment lifecycle: from creation, through warehouse allocation and shipping, to final delivery. Orders aggregate one or more lines (SKU + quantity), a delivery contact, and fulfillment metadata.

---

Order Flow

---

Order State Machine

---

Order States

State	Description
DRAFT	Order created but not yet submitted for fulfillment. Can be freely edited or cancelled.
OPENED	Order submitted. DeliveryOrders are being created (or have been created). Edits are asynchronous and may be rejected if production has started.
COMPLETED	Terminal state. The order is either fully delivered or cancelled.

---

Order Dispatching Types

Type	Description
AUTOMATIC	The API automatically determines fulfillment locations and creates DeliveryOrders based on available stock.
MANUAL	The caller explicitly controls which warehouse handles each line.

---

Inventory Policy

Controls how the API behaves when stock is insufficient at the time of opening.

Policy	Description
DENY	Reject the open request entirely if any line cannot be fulfilled.
ALLOW	Allow the order to open even if stock is insufficient. Fulfillment proceeds with available stock.
SKIP	Skip lines that cannot be fulfilled and open the rest normally.
ADJUST	Adjust line quantities down to match available stock before opening.

---

Order Contacts

An order can carry up to four contacts:

Contact	Description
seller	The merchant selling the order (formerly merchant).
buyer	The customer purchasing the order.
deliveryContact	The person who will receive the physical shipment.
billingContact	The person who will receive the invoice.

WARNING

Email, phone number, and delivery address are mandatory for fulfillment. HappyColis will not cover delivery issues caused by missing or invalid contact data.

---

Fulfillment Constraints

You can add constraints on order lines to control the dispatching strategy. Constraints are defined in the fulfillment metadata namespace on each line.

Field	Type	Description
locationId	String	Force fulfillment at a specific location
shippingMethodId	String	Force a specific shipping method
prepareAt	DateTime	Schedule preparation for a specific date/time

TIP

When using constraints, HappyColis bypasses its internal dispatching logic. Your order may be rejected if the constraints cannot be satisfied.

---

DispatchableRequest

Most order mutations (orderOpen, orderCancel, orderHold, orderResume, orderComplete, orderRequestFulfillment) return a DispatchableRequest rather than the full order. This is because many operations are processed asynchronously in the background.

Field	Type	Description
id	String	Unique request identifier
type	String	The type of request (e.g. OPEN, CANCEL)
state	String	Current processing state of the request
message	String	Human-readable status message

Each DispatchableRequest has a priority (LOW, NORMAL, HIGH) and is processed sequentially in a FIFO queue, highest priority first. For example, a CANCEL request takes precedence over an UPDATE request — if the cancellation succeeds, the update will be rejected.

WARNING

Once production has started at the warehouse, requests cannot be stopped. Ensure the order is ready before requesting fulfillment.

A DispatchableRequest may be split into multiple FulfillmentActions — one per DeliveryOrder. You can track these via the Order.requests field to see what HappyColis will do on each allocation.

Use webhooks to receive notifications when asynchronous operations complete.

---

Virtual Items

Virtual items (e.g. digital goods, warranties) are items not physically present in stock. HappyColis can track stock for these items, but they are processed in a separate DeliveryOrder marked as VIRTUAL. Virtual delivery orders are not transmitted to the fulfillment location and are automatically marked as shipped when fulfillment is requested.

---

Bundle Fulfillment

When an order contains bundles, each bundle is split into its component lines in the DeliveryOrder. All components of a bundle must be prepared at the same fulfillment location. If some component quantities are missing, the inventoryPolicy determines how the bundle is handled:

• Use DENY or ALLOW for bundles to prevent complex partial fulfillment scenarios
• SKIP or ADJUST policies may result in partial bundle shipments, which complicates quantity tracking

If a bundle component is also ordered separately, HappyColis may merge quantities into a single DeliveryOrder line when compatible.

---

Manual Orders

Orders with dispatchingType set to MANUAL bypass HappyColis dispatching logic. You are responsible for:

1. Creating DeliveryOrders manually via deliveryOrderCreate
2. Managing line allocations and updates yourself
3. Requesting fulfillment for each DeliveryOrder individually
4. Manually fulfilling internal-location delivery orders via deliveryOrderFulfillmentCreate and shipmentCreate

HappyColis accepts any update to manual orders while they are in OPENED state. For mixed-location orders (both INTERNAL and WAREHOUSE), you must manually complete internal delivery orders to see the COMPLETED flag on the parent order.

INFO

HappyColis does not offer shipment tracking for INTERNAL locations or manually created shipments.

---

Operations

Operation	Type	Description
order	Query	Fetch a single order by ID or external reference
orderCreate	Mutation	Create a new order (DRAFT or OPENED)
orderUpdate	Mutation	Update an existing order
orderOpen	Mutation	Submit a DRAFT order for fulfillment
orderCancel	Mutation	Cancel an order
orderHold	Mutation	Pause order fulfillment
orderResume	Mutation	Resume a held order
orderComplete	Mutation	Manually mark an order as completed
orderRequestFulfillment	Mutation	Send the order to the warehouse