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 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).