Fulfillment Module

Overview

The Fulfillment Module manages shipping and delivery operations including shipping profiles, service zones, geographic zones, shipping options with rule-based pricing, and fulfillment tracking. It provides a flexible system for configuring complex shipping scenarios. Key Features:

Shipping profile management
Service zones with geographic coverage
Rule-based shipping options
Multi-provider fulfillment support
Fulfillment tracking and labeling
Dynamic shipping calculations
Fulfillment set organization

When to Use

Use the Fulfillment Module when you need to:

Configure shipping options for products
Define geographic shipping zones
Calculate shipping costs based on rules (weight, price, etc.)
Manage multiple fulfillment providers
Create and track fulfillments
Generate shipping labels
Handle multi-location shipping
Support pickup and delivery options

Data Models

ShippingProfile

Groups products with similar shipping requirements.

string

required

Unique shipping profile identifier

string

required

Profile name (e.g., “Standard Products”, “Fragile Items”)

string

required

Profile type: default, gift_card, custom

ServiceZone

Defines a shipping service area with associated shipping options.

string

required

Unique service zone identifier

string

required

Service zone name

string

required

ID of the parent fulfillment set

GeoZone[]

Geographic areas covered by this zone

ShippingOption[]

Available shipping options in this zone

GeoZone

Defines a geographic area within a service zone.

string

required

Unique geo zone identifier

string

required

Zone type: country, province, city, zip

string

required

Two-letter ISO country code

string

Province or state code

string

City name

string

Regex pattern for postal codes

string

required

ID of the parent service zone

ShippingOption

Represents a shipping method available to customers.

string

required

Unique shipping option identifier

string

required

Shipping option name (e.g., “Express Shipping”)

string

required

ID of the service zone

string

required

ID of the shipping profile

string

required

Fulfillment provider ID (e.g., “manual”, “shippo”)

string

required

ID of the shipping option type

object

Provider-specific configuration data

ShippingOptionRule[]

Rules for pricing and availability

ShippingOptionRule

Defines conditions and pricing for shipping options.

string

required

Unique rule identifier

string

required

ID of the shipping option

string

required

Rule attribute (e.g., “total”, “weight”, “quantity”)

string

required

Comparison operator: eq, ne, gt, gte, lt, lte, in

string | number

Rule value to compare against

Fulfillment

Tracks order fulfillment.

string

required

Unique fulfillment identifier

string

required

Stock location fulfilling the items

string

required

Fulfillment provider ID

string

ID of the shipping option used

object

Provider-specific fulfillment data

DateTime

When fulfillment was shipped

DateTime

When fulfillment was delivered

DateTime

When fulfillment was canceled

FulfillmentItem[]

Items in this fulfillment

FulfillmentLabel[]

Shipping labels

FulfillmentSet

Organizes fulfillment configuration.

string

required

Unique fulfillment set identifier

string

required

Fulfillment set name

string

required

Set type: pickup, shipping

ServiceZone[]

Service zones in this set

Service Interface

The Fulfillment Module service is available at @medusajs/medusa/fulfillment.

Create Shipping Profile

Create a shipping profile for products.

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IFulfillmentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"

export async function POST(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const fulfillmentModuleService: IFulfillmentModuleService = req.scope.resolve(
    Modules.FULFILLMENT
  )

  const shippingProfile = await fulfillmentModuleService.createShippingProfiles({
    name: "Heavy Items",
    type: "custom",
  })

  res.json({ shipping_profile: shippingProfile })
}

CreateShippingProfileDTO

required

Shipping profile data

string

required

Profile name

string

required

Profile type: default, gift_card, custom

Create Fulfillment Set

Create a fulfillment set with service zones.

const fulfillmentSet = await fulfillmentModuleService.createFulfillmentSets({
  name: "US Shipping",
  type: "shipping",
  service_zones: [
    {
      name: "US East Coast",
      geo_zones: [
        {
          type: "country",
          country_code: "us",
        },
      ],
    },
  ],
})

CreateFulfillmentSetDTO

required

Fulfillment set data

string

required

Fulfillment set name

string

required

Set type: pickup, shipping

CreateServiceZoneDTO[]

Service zones to create

Create Service Zone

Create a service zone with geographic coverage.

const serviceZone = await fulfillmentModuleService.createServiceZones({
  name: "California",
  fulfillment_set_id: "fset_123",
  geo_zones: [
    {
      type: "province",
      country_code: "us",
      province_code: "CA",
    },
  ],
})

Create Geo Zone

Define a geographic area.

const geoZone = await fulfillmentModuleService.createGeoZones({
  type: "country",
  country_code: "us",
  service_zone_id: "sz_123",
})

const geoZone = await fulfillmentModuleService.createGeoZones({
  type: "province",
  country_code: "us",
  province_code: "CA",
  service_zone_id: "sz_123",
})

const geoZone = await fulfillmentModuleService.createGeoZones({
  type: "zip",
  country_code: "us",
  postal_expression: "^94", // ZIP codes starting with 94
  service_zone_id: "sz_123",
})

Create Shipping Option

Create a shipping method with rules.

const shippingOption = await fulfillmentModuleService.createShippingOptions({
  name: "Express Shipping",
  service_zone_id: "sz_123",
  shipping_profile_id: "sp_standard",
  provider_id: "manual",
  shipping_option_type_id: "sot_express",
  data: {
    // Provider-specific data
  },
  rules: [
    {
      attribute: "total",
      operator: "gte",
      value: "5000", // Free shipping over $50
    },
  ],
})

CreateShippingOptionDTO

required

Shipping option data

string

required

Shipping option name

string

required

ID of the service zone

string

required

ID of the shipping profile

string

required

Fulfillment provider ID

CreateShippingOptionRuleDTO[]

Pricing and availability rules

List Shipping Options for Context

Find available shipping options for an address.

const shippingOptions = await fulfillmentModuleService.listShippingOptionsForContext(
  {
    address: {
      country_code: "us",
      province_code: "CA",
      postal_code: "94102",
    },
    context: {
      total: 7500,
      weight: 2000,
    },
  },
  {
    relations: ["rules"],
  }
)

FilterableShippingOptionForContextProps

required

Context filters

object

Shipping address to match against geo zones

object

Values for rule evaluation (total, weight, quantity, etc.)

Create Fulfillment

Create a fulfillment for order items.

const fulfillment = await fulfillmentModuleService.createFulfillment({
  location_id: "sloc_warehouse",
  provider_id: "manual",
  shipping_option_id: "so_express",
  items: [
    {
      line_item_id: "item_123",
      quantity: 2,
    },
  ],
  data: {
    // Provider-specific data
  },
})

CreateFulfillmentDTO

required

Fulfillment data

string

required

Stock location ID

string

required

Fulfillment provider ID

CreateFulfillmentItemDTO[]

required

Items to fulfill

string

ID of the shipping option

object

Provider-specific data

Create Shipping Labels

Generate shipping labels for fulfillment.

const labels = await fulfillmentModuleService.createFulfillmentLabels(
  "ful_123",
  {
    // Provider-specific label data
  }
)

Update Fulfillment

Update fulfillment status.

const fulfillment = await fulfillmentModuleService.updateFulfillments(
  "ful_123",
  {
    shipped_at: new Date(),
  }
)

const fulfillment = await fulfillmentModuleService.updateFulfillments(
  "ful_123",
  {
    delivered_at: new Date(),
  }
)

Cancel Fulfillment

Cancel an active fulfillment.

const fulfillment = await fulfillmentModuleService.cancelFulfillment("ful_123")

Integration Examples

With Cart Module

Add shipping method to cart.

import { Modules } from "@medusajs/framework/utils"

const fulfillmentModule = container.resolve(Modules.FULFILLMENT)
const cartModule = container.resolve(Modules.CART)

// Get cart
const cart = await cartModule.retrieveCart("cart_123", {
  relations: ["shipping_address"],
})

// Find available shipping options
const shippingOptions = await fulfillmentModule.listShippingOptionsForContext(
  {
    address: cart.shipping_address,
    context: {
      total: cart.total,
    },
  }
)

// Add shipping method to cart
await cartModule.createShippingMethods({
  cart_id: cart.id,
  name: shippingOptions[0].name,
  amount: 500,
  shipping_option_id: shippingOptions[0].id,
})

With Stock Location Module

Multi-location fulfillment.

import { Modules } from "@medusajs/framework/utils"

const stockLocationModule = container.resolve(Modules.STOCK_LOCATION)
const fulfillmentModule = container.resolve(Modules.FULFILLMENT)

// Get stock locations
const locations = await stockLocationModule.listStockLocations()

// Create fulfillments from different locations
for (const location of locations) {
  const itemsAtLocation = orderItems.filter(
    item => item.location_id === location.id
  )
  
  if (itemsAtLocation.length) {
    await fulfillmentModule.createFulfillment({
      location_id: location.id,
      provider_id: "manual",
      items: itemsAtLocation,
    })
  }
}

With Order Module

Create fulfillments for orders.

import { Modules } from "@medusajs/framework/utils"

const orderModule = container.resolve(Modules.ORDER)
const fulfillmentModule = container.resolve(Modules.FULFILLMENT)

// Get order
const order = await orderModule.retrieveOrder("order_123", {
  relations: ["items"],
})

// Create fulfillment
const fulfillment = await fulfillmentModule.createFulfillment({
  location_id: "sloc_warehouse",
  provider_id: "manual",
  items: order.items.map(item => ({
    line_item_id: item.id,
    quantity: item.quantity,
  })),
})

Fulfillment Providers

Medusa supports multiple fulfillment providers:

Manual Provider

Built-in provider for manual fulfillment processes.

const shippingOption = await fulfillmentModuleService.createShippingOptions({
  name: "Standard Shipping",
  provider_id: "manual",
  // ... other fields
})

Shippo

npm install @medusajs/medusa-fulfillment-shippo

// medusa-config.js
module.exports = {
  modules: [
    {
      resolve: "@medusajs/medusa-fulfillment-shippo",
      options: {
        api_key: process.env.SHIPPO_API_KEY,
      },
    },
  ],
}

Best Practices

Shipping Profiles: Group products with similar shipping requirements (fragile, oversized, standard) into profiles.
Service Zones: Structure zones hierarchically - start with broad zones (country), then narrow (province, city, ZIP).
Rule-Based Pricing: Use rules to implement complex pricing:
- Free shipping over certain total
- Weight-based pricing
- Quantity discounts
Geo Zone Expressions: Use postal_expression with regex for flexible postal code matching (e.g., ^94 for San Francisco area).
Multi-Location: Configure fulfillment sets per location for complex inventory scenarios.
Provider Data: Store provider-specific configuration in the data field for flexibility.

Cart Module - Add shipping methods to carts
Order Module - Create order fulfillments
Stock Location Module - Multi-location fulfillment
Inventory Module - Reserve inventory for fulfillments
Region Module - Configure region fulfillment providers

Get Started

Core Concepts

Commerce Modules

Building with Medusa

Providers

Admin Dashboard

Deployment

Fulfillment Module

Overview

When to Use

Data Models

ShippingProfile

ServiceZone

GeoZone

ShippingOption

ShippingOptionRule

Fulfillment

FulfillmentSet

Service Interface

Create Shipping Profile

Create Fulfillment Set

Create Service Zone

Create Geo Zone

Create Shipping Option

List Shipping Options for Context

Create Fulfillment

Create Shipping Labels

Update Fulfillment

Cancel Fulfillment

Integration Examples

With Cart Module

With Stock Location Module

With Order Module

Fulfillment Providers

Manual Provider

Shippo

Best Practices

​Overview

​When to Use

​Data Models

​ShippingProfile

​ServiceZone

​GeoZone

​ShippingOption

​ShippingOptionRule

​Fulfillment

​FulfillmentSet

​Service Interface

​Create Shipping Profile

​Create Fulfillment Set

​Create Service Zone

​Create Geo Zone

​Create Shipping Option

​List Shipping Options for Context

​Create Fulfillment

​Create Shipping Labels

​Update Fulfillment

​Cancel Fulfillment

​Integration Examples

​With Cart Module

​With Stock Location Module

​With Order Module

​Fulfillment Providers

​Manual Provider

​Shippo

​Best Practices

​Related Modules

Overview

When to Use

Data Models

ShippingProfile

ServiceZone

GeoZone

ShippingOption

ShippingOptionRule

Fulfillment

FulfillmentSet

Service Interface

Create Shipping Profile

Create Fulfillment Set

Create Service Zone

Create Geo Zone

Create Shipping Option

List Shipping Options for Context

Create Fulfillment

Create Shipping Labels

Update Fulfillment

Cancel Fulfillment

Integration Examples

With Cart Module

With Stock Location Module

With Order Module

Fulfillment Providers

Manual Provider

Shippo

Best Practices

Related Modules