page.mdx

generate_toc	true

import { CodeTabs, CodeTab } from "docs-ui"

export const metadata = { title: Fulfillment Module, }

{metadata.title}

In this section of the documentation, you will find resources to learn more about the Fulfillment Module and how to use it in your application.

Refer to the Medusa Admin User Guide to learn how to use the dashboard to:

• Manage order fulfillments.
• Manage shipping options and profiles.

Medusa has fulfillment related features available out-of-the-box through the Fulfillment Module. A module is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Fulfillment Module.

Learn more about why modules are isolated in this documentation.

Fulfillment Features

• Fulfillment Management: Create fulfillments and keep track of their status, items, and more.
• Integrate Third-Party Fulfillment Providers: Create third-party fulfillment providers to provide customers with shipping options and fulfill their orders.
• Restrict By Location and Rules: Shipping options can be restricted to specific geographical locations. You can also specify custom rules to restrict shipping options.
• Support Different Fulfillment Forms: Support various fulfillment forms, such as shipping or pick up.
• Tiered Pricing and Price Rules: Set prices for shipping options with tiers and rules, allowing you to create complex pricing strategies.

---

How to Use the Fulfillment Module

In your Medusa application, you build flows around Commerce Modules. A flow is built as a Workflow, which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.

You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the @medusajs/medusa/core-flows package.

For example:

export const highlights = [ ["12", "Modules.FULFILLMENT", "Resolve the module in a step."] ]

import { 
  createWorkflow, 
  WorkflowResponse,
  createStep,
  StepResponse,
} from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"

const createFulfillmentStep = createStep(
  "create-fulfillment",
  async ({}, { container }) => {
    const fulfillmentModuleService = container.resolve(Modules.FULFILLMENT)

    const fulfillment = await fulfillmentModuleService.createFulfillment({
      location_id: "loc_123",
      provider_id: "webshipper",
      delivery_address: {
        country_code: "us",
        city: "Strongsville",
        address_1: "18290 Royalton Rd",
      },
      items: [
        {
          title: "Shirt",
          sku: "SHIRT",
          quantity: 1,
          barcode: "123456",
        },
      ],
      labels: [],
      order: {},
    })

    return new StepResponse({ fulfillment }, fulfillment.id)
  },
  async (fulfillmentId, { container }) => {
    if (!fulfillmentId) {
      return
    }
    const fulfillmentModuleService = container.resolve(Modules.FULFILLMENT)

    await fulfillmentModuleService.deleteFulfillment(fulfillmentId)
  }
)

export const createFulfillmentWorkflow = createWorkflow(
  "create-fulfillment",
  () => {
    const { fulfillment } = createFulfillmentStep()

    return new WorkflowResponse({
      fulfillment,
    })
  }
)

You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { createFulfillmentWorkflow } from "../../workflows/create-fuilfillment"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await createFulfillmentWorkflow(req.scope)
    .run()

  res.send(result)
}

import {
  type SubscriberConfig,
  type SubscriberArgs,
} from "@medusajs/framework"
import { createFulfillmentWorkflow } from "../workflows/create-fuilfillment"

export default async function handleUserCreated({
  event: { data },
  container,
}: SubscriberArgs<{ id: string }>) {
  const { result } = await createFulfillmentWorkflow(container)
    .run()

  console.log(result)
}

export const config: SubscriberConfig = {
  event: "user.created",
}

import { MedusaContainer } from "@medusajs/framework/types"
import { createFulfillmentWorkflow } from "../workflows/create-fuilfillment"

export default async function myCustomJob(
  container: MedusaContainer
) {
  const { result } = await createFulfillmentWorkflow(container)
    .run()

  console.log(result)
}

export const config = {
  name: "run-once-a-day",
  schedule: `0 0 * * *`,
}

Learn more about workflows in this documentation.

---

Configure Fulfillment Module

The Fulfillment Module accepts options for further configurations. Refer to this documentation for details on the module's options.

---