Fulfillment Providers

Learn how to configure and use fulfillment providers in Medusa for managing order fulfillment and shipping.

Fulfillment Providers

Fulfillment providers handle shipping, delivery, and order fulfillment operations. They calculate shipping prices, validate fulfillment data, create shipments, and manage returns.

Available Fulfillment Providers

Manual Fulfillment Provider

The manual fulfillment provider (@medusajs/medusa/fulfillment-manual) is a simple provider for self-managed fulfillment where you handle shipping logistics yourself.

Features:

• No external shipping integrations
• Manual fulfillment process
• Supports both regular fulfillment and returns
• Does not calculate shipping prices

Installation

The manual fulfillment provider is included in the core Medusa package:

npm install @medusajs/medusa

Configuration

Configure the fulfillment provider in your medusa-config.ts:

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

export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          {
            resolve: "@medusajs/medusa/fulfillment-manual",
            id: "manual",
          },
        ],
      },
    },
  ],
})

Fulfillment Provider Interface

All fulfillment providers extend AbstractFulfillmentProviderService and implement the following methods:

getFulfillmentOptions(): Promise<FulfillmentOption[]>

Returns available fulfillment options.

const options = await fulfillmentProvider.getFulfillmentOptions()
// Result:
// [
//   { id: "manual-fulfillment" },
//   { id: "manual-fulfillment-return", is_return: true }
// ]

validateFulfillmentData(optionData, data, context): Promise<any>

Validates fulfillment data before creating a fulfillment.

Parameters:

• optionData - Configuration data for the fulfillment option
• data - Fulfillment data to validate
• context - Additional context including cart/order data

const validatedData = await fulfillmentProvider.validateFulfillmentData(
  { option_id: "manual-fulfillment" },
  {
    tracking_number: "TRACK123",
  },
  {
    cart_id: "cart_123",
  }
)

validateOption(data): Promise<boolean>

Validates a fulfillment option configuration.

const isValid = await fulfillmentProvider.validateOption({
  id: "manual-fulfillment",
})

canCalculate(): Promise<boolean>

Indicates whether the provider can calculate shipping prices.

const canCalculate = await fulfillmentProvider.canCalculate()
// false for manual provider

calculatePrice(optionData, data, context): Promise<CalculatedShippingOptionPrice>

Calculates shipping price (not supported by manual provider).

Parameters:

• optionData - Shipping option configuration
• data - Calculation data (items, destination, etc.)
• context - Additional context

The manual fulfillment provider throws an error when calculatePrice is called, as it does not support price calculation.

createFulfillment(): Promise<CreateFulfillmentResult>

Creates a fulfillment (shipment).

const result = await fulfillmentProvider.createFulfillment()
// Result: { data: {}, labels: [] }

Returns:

• data - Provider-specific fulfillment data
• labels - Shipping labels (if applicable)

cancelFulfillment(): Promise<any>

Cancels an existing fulfillment.

await fulfillmentProvider.cancelFulfillment()

createReturnFulfillment(): Promise<CreateFulfillmentResult>

Creates a return fulfillment.

const result = await fulfillmentProvider.createReturnFulfillment()
// Result: { data: {}, labels: [] }

Using the Fulfillment Module

Access fulfillment providers through the Fulfillment Module:

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

const fulfillmentModule = container.resolve(Modules.FULFILLMENT)

// Get fulfillment options
const options = await fulfillmentModule.listFulfillmentOptions(
  "manual"
)

// Create a fulfillment
const fulfillment = await fulfillmentModule.createFulfillment({
  provider_id: "manual",
  order_id: "order_123",
  items: [
    {
      line_item_id: "item_123",
      quantity: 1,
    },
  ],
  labels: [],
  data: {
    tracking_number: "TRACK123",
  },
})

Fulfillment Workflows

Use fulfillment workflows from @medusajs/core-flows:

import { createFulfillmentWorkflow } from "@medusajs/core-flows"

const { result } = await createFulfillmentWorkflow(container).run({
  input: {
    order_id: "order_123",
    provider_id: "manual",
    items: [
      {
        line_item_id: "item_123",
        quantity: 1,
      },
    ],
  },
})

Creating Custom Fulfillment Providers

Create a custom fulfillment provider by extending AbstractFulfillmentProviderService:

packages/modules/providers/fulfillment-custom/src/services/custom-fulfillment.ts

import { AbstractFulfillmentProviderService } from "@medusajs/framework/utils"
import {
  CalculatedShippingOptionPrice,
  CalculateShippingOptionPriceContext,
  CreateFulfillmentResult,
  FulfillmentOption,
  ValidateFulfillmentDataContext,
} from "@medusajs/types"

export class CustomFulfillmentService extends AbstractFulfillmentProviderService {
  static identifier = "custom-fulfillment"

  constructor(container, options) {
    super()
    this.options_ = options
    // Initialize shipping provider SDK
    this.client_ = new ShippingProviderSDK(options.apiKey)
  }

  async getFulfillmentOptions(): Promise<FulfillmentOption[]> {
    // Return available shipping options
    return [
      {
        id: "standard-shipping",
      },
      {
        id: "express-shipping",
      },
      {
        id: "return-shipping",
        is_return: true,
      },
    ]
  }

  async validateFulfillmentData(
    optionData: Record<string, unknown>,
    data: Record<string, unknown>,
    context: ValidateFulfillmentDataContext
  ): Promise<any> {
    // Validate shipping address, items, etc.
    if (!context.shipping_address) {
      throw new Error("Shipping address is required")
    }

    return data
  }

  async validateOption(data: Record<string, any>): Promise<boolean> {
    // Validate the option configuration
    const validOptions = ["standard-shipping", "express-shipping"]
    return validOptions.includes(data.id)
  }

  async canCalculate(): Promise<boolean> {
    return true
  }

  async calculatePrice(
    optionData: Record<string, unknown>,
    data: Record<string, unknown>,
    context: CalculateShippingOptionPriceContext
  ): Promise<CalculatedShippingOptionPrice> {
    // Calculate shipping price from provider
    const rate = await this.client_.getRates({
      from: context.from_address,
      to: context.shipping_address,
      items: context.items,
      service: optionData.id,
    })

    return {
      calculated_amount: rate.amount,
    }
  }

  async createFulfillment(
    data: Record<string, unknown>,
    items: any[],
    order: any,
    fulfillment: any
  ): Promise<CreateFulfillmentResult> {
    // Create shipment with provider
    const shipment = await this.client_.createShipment({
      order_id: order.id,
      items: items,
      from_address: order.warehouse_address,
      to_address: order.shipping_address,
      service: data.option_id,
    })

    return {
      data: {
        shipment_id: shipment.id,
        tracking_number: shipment.tracking_number,
      },
      labels: [
        {
          url: shipment.label_url,
          format: "pdf",
        },
      ],
    }
  }

  async cancelFulfillment(fulfillment: any): Promise<any> {
    // Cancel shipment with provider
    await this.client_.cancelShipment(fulfillment.data.shipment_id)
    return {}
  }

  async createReturnFulfillment(
    fulfillment: any
  ): Promise<CreateFulfillmentResult> {
    // Create return shipment
    const returnShipment = await this.client_.createReturnShipment({
      original_shipment_id: fulfillment.data.shipment_id,
    })

    return {
      data: {
        shipment_id: returnShipment.id,
        tracking_number: returnShipment.tracking_number,
      },
      labels: [
        {
          url: returnShipment.label_url,
          format: "pdf",
        },
      ],
    }
  }
}

Register your custom provider:

packages/modules/providers/fulfillment-custom/src/index.ts

import { ModuleProvider, Modules } from "@medusajs/framework/utils"
import { CustomFulfillmentService } from "./services/custom-fulfillment"

export default ModuleProvider(Modules.FULFILLMENT, {
  services: [CustomFulfillmentService],
})

Configure your custom provider:

medusa-config.ts

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

export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          {
            resolve: "./src/modules/providers/fulfillment-custom",
            id: "custom-fulfillment",
            options: {
              apiKey: process.env.SHIPPING_PROVIDER_API_KEY,
            },
          },
        ],
      },
    },
  ],
})

Reference

• Source: packages/modules/providers/fulfillment-manual/src/services/manual-fulfillment.ts
• Base class: packages/core/utils/src/fulfillment/abstract-fulfillment-provider.ts
• Types: packages/core/types/src/fulfillment/provider.ts

Next Steps

Payment Providers

Configure payment processing

Notification Providers

Send shipping confirmation emails