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.
