Order Module

Overview

The Order Module manages the complete order lifecycle including order creation, modifications, fulfillment tracking, returns, claims, and exchanges. It provides versioning support for order changes and maintains detailed transaction history. Key Features:

Order management with status tracking
Order versioning for change history
Line items with tax lines and adjustments
Shipping methods with tax and adjustments
Returns, claims, and exchanges
Order changes with approval workflow
Transaction tracking
Credit lines for store credit

When to Use

Use the Order Module when you need to:

Create orders from completed carts
Track order status and fulfillment
Handle order modifications and cancellations
Process customer returns
Manage product claims and replacements
Handle order exchanges
Apply discounts and promotions to orders
Track payment transactions

Data Models

Order

The core order entity representing a customer purchase.

string

required

Unique order identifier (prefix: order_)

number

required

Auto-incrementing display ID for customer reference

string

Custom display ID (e.g., “ORD-2024-001”)

OrderStatus

required

Order status: pending, completed, archived, canceled

number

required

Order version number (increments with changes)

string

ID of the customer who placed the order

string

Customer email address

string

required

Three-letter ISO currency code

string

ID of the associated region

string

ID of the sales channel where order was placed

boolean

Whether this is a draft order (default: false)

OrderItem[]

Order line items

OrderAddress

Shipping address for the order

OrderAddress

Billing address for the order

OrderShippingMethod[]

Shipping methods applied to the order

OrderTransaction[]

Payment transactions

OrderSummary[]

Order totals summary by version

Return[]

Returns associated with this order

OrderItem

Represents a line item in an order.

string

required

Unique item identifier

string

required

ID of the parent order

number

required

Order version when item was added

string

required

Reference to the cart line item

string

ID of the product

string

ID of the product variant

number

required

Item quantity

BigNumber

required

Price per unit

OrderLineItem

Detailed line item information including totals

OrderLineItem

Detailed line item with pricing and tax information.

string

required

Unique line item identifier

string

required

Line item title

string

Line item subtitle

string

Product thumbnail URL

number

required

Item quantity

BigNumber

required

Price per unit before discounts

OrderLineItemTaxLine[]

Tax lines applied to this item

OrderLineItemAdjustment[]

Discount adjustments applied to this item

OrderChange

Tracks modifications to an order.

string

required

Unique change identifier

string

required

ID of the order being changed

number

required

Order version this change applies to

string

Type of change: return, exchange, claim, edit

OrderChangeStatus

required

Change status: pending, requested, confirmed, declined, canceled

string

User ID who requested the change

string

User ID who confirmed the change

OrderChangeAction[]

Individual actions in this change

Return

Represents a product return.

string

required

Unique return identifier (prefix: return_)

string

required

ID of the order being returned

string

Return status

ReturnItem[]

Items being returned

string

Stock location where items will be returned

OrderClaim

Represents a customer claim for damaged or incorrect items.

string

required

Unique claim identifier

string

required

ID of the order being claimed

OrderClaimItem[]

Items being claimed

OrderExchange

Represents an item exchange.

string

required

Unique exchange identifier

string

required

ID of the order

OrderExchangeItem[]

Items being exchanged

Service Interface

The Order Module service is available at @medusajs/medusa/order.

Retrieve Order

Retrieve a single order with related data.

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

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const orderModuleService: IOrderModuleService = req.scope.resolve(
    Modules.ORDER
  )

  const order = await orderModuleService.retrieveOrder("order_123", {
    relations: [
      "items",
      "items.detail",
      "shipping_address",
      "billing_address",
      "shipping_methods",
      "summary",
    ],
  })

  res.json({ order })
}

string

required

The ID of the order to retrieve

FindConfig

Configuration for the query

string[]

Relations to load (e.g., ["items", "shipping_address"])

string[]

Fields to select from the order

OrderDTO

The retrieved order

List Orders

List orders with filtering and pagination.

const [orders, count] = await orderModuleService.listAndCountOrders(
  {
    customer_id: "cus_123",
    status: ["completed"],
  },
  {
    relations: ["items", "summary"],
    take: 20,
    skip: 0,
    order: { created_at: "DESC" },
  }
)

FilterableOrderProps

Filters to apply

string | string[]

Filter by order IDs

OrderStatus[]

Filter by order status

string | string[]

Filter by customer IDs

string | string[]

Filter by sales channel IDs

string

Filter by customer email

OrderDTO[]

Array of orders matching the filters

number

Total count of matching orders

Create Orders

Create one or more orders (typically from a cart).

const order = await orderModuleService.createOrders({
  customer_id: "cus_123",
  email: "customer@example.com",
  currency_code: "usd",
  region_id: "reg_us",
  sales_channel_id: "sc_web",
  items: [
    {
      product_id: "prod_123",
      variant_id: "variant_456",
      quantity: 2,
      unit_price: 2000,
      title: "Medusa T-Shirt",
    },
  ],
  shipping_address: {
    first_name: "John",
    last_name: "Doe",
    address_1: "123 Main St",
    city: "New York",
    country_code: "us",
    postal_code: "10001",
  },
  shipping_methods: [
    {
      name: "Standard Shipping",
      amount: 500,
    },
  ],
})

CreateOrderDTO | CreateOrderDTO[]

required

Order data to create

string

ID of the customer

string

Customer email

string

required

Three-letter ISO currency code

string

ID of the region

CreateOrderLineItemDTO[]

Order line items

CreateOrderAddressDTO

Shipping address

CreateOrderAddressDTO

Billing address

OrderDTO | OrderDTO[]

The created order(s)

Update Orders

Update order information.

const order = await orderModuleService.updateOrders("order_123", {
  email: "newemail@example.com",
})

const orders = await orderModuleService.updateOrders(
  { status: "pending" },
  { no_notification: true }
)

Create Order Change

Initiate a change to an order.

const orderChange = await orderModuleService.createOrderChange({
  order_id: "order_123",
  change_type: "edit",
  requested_by: "user_123",
  actions: [
    {
      action: "ITEM_ADD",
      details: {
        variant_id: "variant_789",
        quantity: 1,
      },
    },
  ],
})

CreateOrderChangeDTO

required

Order change data

string

required

ID of the order to change

string

Type of change: return, exchange, claim, edit

string

User ID who requested the change

OrderChangeActionDTO[]

Individual actions in this change

Confirm Order Change

Confirm and apply an order change.

const order = await orderModuleService.confirmOrderChange(
  "change_123",
  "user_123"
)

Create Return

Create a product return.

const orderReturn = await orderModuleService.createReturns({
  order_id: "order_123",
  items: [
    {
      item_id: "item_456",
      quantity: 1,
      reason_id: "reason_defective",
    },
  ],
  location_id: "sloc_warehouse",
})

CreateReturnDTO | CreateReturnDTO[]

required

Return data

string

required

ID of the order

CreateReturnItemDTO[]

required

Items to return

string

Stock location for return

Create Order Claim

Create a claim for damaged or incorrect items.

const claim = await orderModuleService.createOrderClaims({
  order_id: "order_123",
  type: "replace",
  claim_items: [
    {
      item_id: "item_456",
      quantity: 1,
      reason: "defective",
      images: [
        { url: "https://example.com/damage.jpg" },
      ],
    },
  ],
})

Create Order Exchange

Create an item exchange.

const exchange = await orderModuleService.createOrderExchanges({
  order_id: "order_123",
  return_items: [
    {
      item_id: "item_456",
      quantity: 1,
    },
  ],
  additional_items: [
    {
      variant_id: "variant_789",
      quantity: 1,
    },
  ],
})

Integration Examples

With Cart Module

Orders are typically created from completed carts.

import { Modules } from "@medusajs/framework/utils"
import { createStep } from "@medusajs/framework/workflows-sdk"

const createOrderFromCartStep = createStep(
  "create-order-from-cart",
  async ({ cart_id }, { container }) => {
    const cartModule = container.resolve(Modules.CART)
    const orderModule = container.resolve(Modules.ORDER)
    
    const cart = await cartModule.retrieveCart(cart_id, {
      relations: ["items", "shipping_address", "billing_address"],
    })
    
    const order = await orderModule.createOrders({
      customer_id: cart.customer_id,
      email: cart.email,
      currency_code: cart.currency_code,
      items: cart.items,
      shipping_address: cart.shipping_address,
      billing_address: cart.billing_address,
    })
    
    return order
  }
)

With Payment Module

Track payment transactions for orders.

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

const paymentModule = container.resolve(Modules.PAYMENT)

// Create payment for order
const payment = await paymentModule.createPayments({
  amount: order.total,
  currency_code: order.currency_code,
  provider_id: "stripe",
})

// Create order transaction
await orderModule.createOrderTransactions({
  order_id: order.id,
  amount: payment.amount,
  currency_code: payment.currency_code,
  reference: payment.id,
  reference_id: payment.id,
})

With Fulfillment Module

Create fulfillments for order items.

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

const fulfillmentModule = container.resolve(Modules.FULFILLMENT)

// 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,
  })),
})

Best Practices

Order Versioning: The order version increments with each modification. Always reference the version when making changes.
Order Changes: Use the OrderChange entity for tracking modifications. This provides an audit trail and approval workflow.
Status Management: Follow the order status flow: pending → completed → archived. Use canceled for cancelled orders.
Transaction Tracking: Create OrderTransaction entries for all payment-related activities to maintain a complete financial record.
Returns and Exchanges: Use dedicated return and exchange entities rather than modifying the original order.
Display IDs: Use display_id for customer-facing order numbers. Optionally set custom_display_id for custom formatting.

Cart Module - Create orders from carts
Payment Module - Process order payments
Fulfillment Module - Fulfill order items
Inventory Module - Reserve and adjust inventory
Customer Module - Associate orders with customers

Get Started

Core Concepts

Commerce Modules

Building with Medusa

Providers

Admin Dashboard

Deployment

Overview

When to Use

Data Models

Order

OrderItem

OrderLineItem

OrderChange

Return

OrderClaim

OrderExchange

Service Interface

Retrieve Order

List Orders

Create Orders

Update Orders

Create Order Change

Confirm Order Change

Create Return

Create Order Claim

Create Order Exchange

Integration Examples

With Cart Module

With Payment Module

With Fulfillment Module

Best Practices

​Overview

​When to Use

​Data Models

​Order

​OrderItem

​OrderLineItem

​OrderChange

​Return

​OrderClaim

​OrderExchange

​Service Interface

​Retrieve Order

​List Orders

​Create Orders

​Update Orders

​Create Order Change

​Confirm Order Change

​Create Return

​Create Order Claim

​Create Order Exchange

​Integration Examples

​With Cart Module

​With Payment Module

​With Fulfillment Module

​Best Practices

​Related Modules

Overview

When to Use

Data Models

Order

OrderItem

OrderLineItem

OrderChange

Return

OrderClaim

OrderExchange

Service Interface

Retrieve Order

List Orders

Create Orders

Update Orders

Create Order Change

Confirm Order Change

Create Return

Create Order Claim

Create Order Exchange

Integration Examples

With Cart Module

With Payment Module

With Fulfillment Module

Best Practices

Related Modules