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.
1---2name: medusa-fulfillment3description: Implement Medusa v2 fulfillment — fulfillment module, provider interface, shipping options, fulfillment sets, shipping profiles, and multi-warehouse support. Use when adding fulfillment providers.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-fulfillment7---89# Medusa v2 Fulfillment1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.medusajs.com fulfillment module` for fulfillment data model and service methods152. Web-search `site:docs.medusajs.com fulfillment provider` for the provider abstraction interface163. Web-search `site:docs.medusajs.com shipping option` for shipping option configuration174. Fetch `https://docs.medusajs.com/resources/references/fulfillment` and review the `IFulfillmentModuleService` interface185. Web-search `medusajs v2 AbstractFulfillmentProviderService 2026` for latest provider interface1920## Fulfillment Module Architecture2122### Entity Relationships2324| Entity | Contains | Key Fields |25|--------|----------|------------|26| **FulfillmentSet** | ServiceZones, Fulfillments | name, type (`shipping`, `pick-up`) |27| **ServiceZone** | GeoZones, ShippingOptions | Geographic area with shipping config |28| **ShippingOption** | Rules | name, price_type, provider_id, type |29| **GeoZone** | — | country, province, city, zip |30| **Fulfillment** | Items, Labels | tracking_numbers, packed/shipped/delivered_at |31| **StockLocation** | Link to FulfillmentSet | Warehouse connection |3233### Module Links3435```36Fulfillment Module ──link──> Stock Location Module (warehouse)37Fulfillment Module ──link──> Cart Module (shipping methods)38Fulfillment Module ──link──> Order Module (order fulfillments)39```4041> **Fetch live docs** for exact link definitions and how fulfillment sets connect to stock locations.4243## Fulfillment Provider Interface4445All providers extend `AbstractFulfillmentProviderService`:4647```ts48// Skeleton: custom fulfillment provider49// Fetch live docs for AbstractFulfillmentProviderService50class MyShippingProvider extends AbstractFulfillmentProviderService {51 // Implement: validateFulfillmentData, calculatePrice,52 // createFulfillment, cancelFulfillment53 // Fetch live docs for exact method signatures54}55```5657### Required Provider Methods5859| Method | Purpose | Returns |60|--------|---------|---------|61| `validateFulfillmentData` | Validate shipping data at checkout | Validated data |62| `validateOption` | Validate shipping option config | Boolean |63| `canCalculate` | Whether provider supports dynamic pricing | Boolean |64| `calculatePrice` | Calculate shipping cost dynamically | Price amount |65| `createFulfillment` | Create fulfillment (generate label) | Fulfillment data |66| `cancelFulfillment` | Cancel an existing fulfillment | void |67| `getFulfillmentDocuments` | Get shipping labels/documents | Document URLs |68| `createReturnFulfillment` | Create return shipment | Return data |6970> **Fetch live docs** for exact method signatures, input types, and expected return shapes.7172## Shipping Options7374### Shipping Option Type7576Shipping 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.7778> **Fetch live docs** for how `ShippingOptionType` entities are created and linked.7980### Price Types8182| Price Type | Description |83|------------|-------------|84| `flat_rate` | Fixed price defined in shipping option |85| `calculated` | Dynamic price calculated by provider at checkout |8687### Shipping Option Rules8889| Rule Attribute | Example | Description |90|----------------|---------|-------------|91| `enabled_in_store` | `true` | Visible to customers |92| `is_return` | `false` | Available for returns |93| custom attributes | varies | Provider-specific criteria |9495> **Fetch live docs** for the full list of rule attributes and how to create custom rules.9697## Fulfillment Sets and Geo Zones9899| Concept | Description |100|---------|-------------|101| Fulfillment Set | Named group of service zones linked to a stock location |102| Service Zone | Geographic area with associated shipping options |103| Geo Zone | Specific geographic boundary |104| Stock Location Link | Connects fulfillment set to a warehouse |105106### Geo Zone Types107108| Type | Scope | Example |109|------|-------|---------|110| `country` | Entire country | `country_code: "US"` |111| `province` | State/province | `province_code: "CA"` |112| `city` | City | `city: "San Francisco"` |113| `zip` | Postal code range | `postal_expression: "941*"` |114115## Shipping Profiles116117| Concept | Description |118|---------|-------------|119| Shipping Profile | Links product types to shipping options |120| Default Profile | Applies to products without explicit assignment |121| Custom Profiles | For oversized, fragile, or special-handling items |122123## Multi-Warehouse Support124125| Entity | Key Fields |126|--------|------------|127| **StockLocation** | name, address, FulfillmentSet (link) |128| **InventoryItem** | stocked_quantity, reserved_quantity, incoming_quantity |129130Each InventoryItem tracks stock per variant per location.131132### Fulfillment Routing133134| Strategy | Description |135|----------|-------------|136| Nearest warehouse | Ship from closest location to customer |137| Inventory priority | Ship from location with highest stock |138| Manual selection | Admin selects fulfillment location |139140> **Fetch live docs** for stock location module service methods and inventory allocation strategies.141142## Fulfillment Lifecycle143144```145Created ──> Packed ──> Shipped ──> Delivered146 └─> Return (if needed)147```148149### Key Workflows150151| Workflow | Purpose |152|----------|---------|153| `createFulfillmentWorkflow` | Create fulfillment for order items |154| `cancelFulfillmentWorkflow` | Cancel a pending fulfillment |155| `createShipmentWorkflow` | Add tracking and mark shipped |156| `markFulfillmentAsDeliveredWorkflow` | Mark as delivered |157158### Key Service Methods159160| Operation | Method |161|-----------|--------|162| Create fulfillment set | `fulfillmentModuleService.createFulfillmentSets()` |163| Create service zone | `fulfillmentModuleService.createServiceZones()` |164| Create shipping option | `fulfillmentModuleService.createShippingOptions()` |165| List shipping options | `fulfillmentModuleService.listShippingOptions()` |166| Create fulfillment | `fulfillmentModuleService.createFulfillment()` |167168## Best Practices169170### Provider Implementation171- Always extend `AbstractFulfillmentProviderService` — do not implement from scratch172- Implement `calculatePrice` accurately — it directly affects checkout totals173- Handle rate API failures gracefully — return cached or fallback rates174- Support both outbound and return fulfillment creation175176### Shipping Configuration177- Use geo zones to precisely control shipping option availability by location178- Configure shipping profiles for products with different fulfillment requirements179- Set up both `flat_rate` and `calculated` options — flat rate for simplicity, calculated for accuracy180181### Multi-Warehouse182- Link each fulfillment set to exactly one stock location183- Configure service zones per warehouse based on geographic proximity184- Support split shipments — one order may be fulfilled from multiple locations185186### Tracking187- Always set tracking numbers when creating shipments188- Subscribe to fulfillment events for customer notification triggers189- Store shipping labels in the fulfillment `data` field190191Fetch the Medusa v2 fulfillment module documentation and provider interface references for exact method signatures, shipping option configuration, and multi-warehouse patterns before implementing.