Fulfillment
A Fulfillment represents the delivery of items from an order to the customer. Once an order has been paid for, one or more fulfillments are created to track the shipment (or digital delivery) of the purchased items.
Physical vs. digital fulfillment
Fulfillments are not limited to physical shipments. The same model works for any type of delivery:
- Physical goods — A fulfillment represents a package with a tracking code, shipped via a carrier like UPS or FedEx.
- Digital goods — A fulfillment might represent a download link, a license key, or access credentials sent to the customer.
The flexibility comes from the FulfillmentHandler, which defines what actually happens when a fulfillment is created. The handler for physical goods might call a carrier's API to generate a shipping label, while a handler for digital goods might generate a download token.
Fulfillment state machine
Each fulfillment progresses through a state machine with the following default states:
- Pending — The fulfillment has been created but not yet shipped or delivered.
- Shipped — The items are in transit (for physical goods) or have been dispatched (for digital goods).
- Delivered — The items have arrived at their destination.
- Cancelled — The fulfillment was cancelled before delivery.
Like the order state machine, the fulfillment state machine can be extended with custom states and transitions to match your operational workflow — for example, adding a "Packed" state between Pending and Shipped, or a "ReturnInitiated" state after Delivered.
Partial fulfillment
A single order can have multiple fulfillments. This is necessary when:
- Items ship from different warehouses or locations.
- Some items are available immediately while others are backordered.
- Physical and digital items are delivered through different mechanisms.
Each fulfillment tracks which OrderLines (and quantities) it covers. An order is only considered fully fulfilled when every line has been accounted for across all its fulfillments.
FulfillmentHandlers
A FulfillmentHandler is a pluggable component that defines the logic for creating a fulfillment. When an administrator creates a fulfillment in the Admin UI or via the Admin API, they select a handler and provide any required arguments (such as a tracking code).
The handler's onFulfillmentTransition hook can also execute logic when the fulfillment changes state — for example, sending a shipping notification email when the state transitions to "Shipped", or triggering a webhook to an external logistics system.
Vendure includes a basic manualFulfillmentHandler out of the box, which simply records a tracking code and method. For production use, you would typically implement custom handlers that integrate with your shipping carriers or digital delivery systems.
Fulfillment and order state
The creation and progression of fulfillments is tightly linked to the order state machine. When all items in an order have been assigned to fulfillments that have reached the "Shipped" state, the order itself can transition to "Shipped". Likewise, when all fulfillments reach "Delivered", the order transitions to "Delivered".
If only some items have been fulfilled, the order remains in a partially-fulfilled state until the remaining items are accounted for. This relationship between fulfillment states and order states is managed automatically by Vendure.
Integration with shipping
Fulfillments are related to but distinct from shipping methods. A shipping method determines how an order will be delivered and at what cost (calculated during checkout). A fulfillment is the actual record of delivery after the order has been placed. The selected shipping method influences which fulfillment handler is available, but the two are separate concepts.