orcaqubits/medusa-fulfillment

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.