medusa-fulfillment

name	medusa-fulfillment
description	Implement Medusa v2 fulfillment — fulfillment module, provider interface, shipping options, fulfillment sets, shipping profiles, and multi-warehouse support. Use when adding fulfillment providers.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

Medusa v2 Fulfillment

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com fulfillment module for fulfillment data model and service methods
2. Web-search site:docs.medusajs.com fulfillment provider for the provider abstraction interface
3. Web-search site:docs.medusajs.com shipping option for shipping option configuration
4. Fetch https://docs.medusajs.com/resources/references/fulfillment and review the IFulfillmentModuleService interface
5. 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.