Medusa v2 Fulfillment
Before writing code
Fetch live docs:
- Web-search
site:docs.medusajs.com fulfillment module for fulfillment data model and service methods
- Web-search
site:docs.medusajs.com fulfillment provider for the provider abstraction interface
- Web-search
site:docs.medusajs.com shipping option for shipping option configuration
- Fetch
https://docs.medusajs.com/resources/references/fulfillment and review the IFulfillmentModuleService interface
- Web-search
medusajs v2 AbstractFulfillmentProviderService 2026 for latest provider interface
Fulfillment Module Architecture
Entity Relationships
| Entity |
Contains |
Key Fields |
| FulfillmentSet |
ServiceZones, Fulfillments |
name, type (shipping, pick-up) |
| ServiceZone |
GeoZones, ShippingOptions |
Geographic area with shipping config |
| ShippingOption |
Rules |
name, price_type, provider_id, type |
| GeoZone |
— |
country, province, city, zip |
| Fulfillment |
Items, Labels |
tracking_numbers, packed/shipped/delivered_at |
| StockLocation |
Link to FulfillmentSet |
Warehouse connection |
Module Links
Fulfillment Module ──link──> Stock Location Module (warehouse)
Fulfillment Module ──link──> Cart Module (shipping methods)
Fulfillment Module ──link──> Order Module (order fulfillments)
Fetch live docs for exact link definitions and how fulfillment sets connect to stock locations.
Fulfillment Provider Interface
All providers extend AbstractFulfillmentProviderService:
// Skeleton: custom fulfillment provider
// Fetch live docs for AbstractFulfillmentProviderService
class MyShippingProvider extends AbstractFulfillmentProviderService {
// Implement: validateFulfillmentData, calculatePrice,
// createFulfillment, cancelFulfillment
// Fetch live docs for exact method signatures
}
Required Provider Methods
| Method |
Purpose |
Returns |
validateFulfillmentData |
Validate shipping data at checkout |
Validated data |
validateOption |
Validate shipping option config |
Boolean |
canCalculate |
Whether provider supports dynamic pricing |
Boolean |
calculatePrice |
Calculate shipping cost dynamically |
Price amount |
createFulfillment |
Create fulfillment (generate label) |
Fulfillment data |
cancelFulfillment |
Cancel an existing fulfillment |
void |
getFulfillmentDocuments |
Get shipping labels/documents |
Document URLs |
createReturnFulfillment |
Create return shipment |
Return data |
Fetch live docs for exact method signatures, input types, and expected return shapes.
Shipping Options
Shipping Option Type
Shipping options reference a ShippingOptionType entity with a label and code. Types are configurable — common patterns include "express", "standard", "economy". The is_return rule on a shipping option determines if it applies to returns.
Fetch live docs for how ShippingOptionType entities are created and linked.
Price Types
| Price Type |
Description |
flat_rate |
Fixed price defined in shipping option |
calculated |
Dynamic price calculated by provider at checkout |
Shipping Option Rules
| Rule Attribute |
Example |
Description |
enabled_in_store |
true |
Visible to customers |
is_return |
false |
Available for returns |
| custom attributes |
varies |
Provider-specific criteria |
Fetch live docs for the full list of rule attributes and how to create custom rules.
Fulfillment Sets and Geo Zones
| Concept |
Description |
| Fulfillment Set |
Named group of service zones linked to a stock location |
| Service Zone |
Geographic area with associated shipping options |
| Geo Zone |
Specific geographic boundary |
| Stock Location Link |
Connects fulfillment set to a warehouse |
Geo Zone Types
| Type |
Scope |
Example |
country |
Entire country |
country_code: "US" |
province |
State/province |
province_code: "CA" |
city |
City |
city: "San Francisco" |
zip |
Postal code range |
postal_expression: "941*" |
Shipping Profiles
| Concept |
Description |
| Shipping Profile |
Links product types to shipping options |
| Default Profile |
Applies to products without explicit assignment |
| Custom Profiles |
For oversized, fragile, or special-handling items |
Multi-Warehouse Support
| Entity |
Key Fields |
| StockLocation |
name, address, FulfillmentSet (link) |
| InventoryItem |
stocked_quantity, reserved_quantity, incoming_quantity |
Each InventoryItem tracks stock per variant per location.
Fulfillment Routing
| Strategy |
Description |
| Nearest warehouse |
Ship from closest location to customer |
| Inventory priority |
Ship from location with highest stock |
| Manual selection |
Admin selects fulfillment location |
Fetch live docs for stock location module service methods and inventory allocation strategies.
Fulfillment Lifecycle
Created ──> Packed ──> Shipped ──> Delivered
└─> Return (if needed)
Key Workflows
| Workflow |
Purpose |
createFulfillmentWorkflow |
Create fulfillment for order items |
cancelFulfillmentWorkflow |
Cancel a pending fulfillment |
createShipmentWorkflow |
Add tracking and mark shipped |
markFulfillmentAsDeliveredWorkflow |
Mark as delivered |
Key Service Methods
| Operation |
Method |
| Create fulfillment set |
fulfillmentModuleService.createFulfillmentSets() |
| Create service zone |
fulfillmentModuleService.createServiceZones() |
| Create shipping option |
fulfillmentModuleService.createShippingOptions() |
| List shipping options |
fulfillmentModuleService.listShippingOptions() |
| Create fulfillment |
fulfillmentModuleService.createFulfillment() |
Best Practices
Provider Implementation
- Always extend
AbstractFulfillmentProviderService — do not implement from scratch
- Implement
calculatePrice accurately — it directly affects checkout totals
- Handle rate API failures gracefully — return cached or fallback rates
- Support both outbound and return fulfillment creation
Shipping Configuration
- Use geo zones to precisely control shipping option availability by location
- Configure shipping profiles for products with different fulfillment requirements
- Set up both
flat_rate and calculated options — flat rate for simplicity, calculated for accuracy
Multi-Warehouse
- Link each fulfillment set to exactly one stock location
- Configure service zones per warehouse based on geographic proximity
- Support split shipments — one order may be fulfilled from multiple locations
Tracking
- Always set tracking numbers when creating shipments
- Subscribe to fulfillment events for customer notification triggers
- Store shipping labels in the fulfillment
data field
Fetch the Medusa v2 fulfillment module documentation and provider interface references for exact method signatures, shipping option configuration, and multi-warehouse patterns before implementing.
OrcaQubits