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_)

display_id

number

required

Auto-incrementing display ID for customer reference

custom_display_id

string

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

status

OrderStatus

required

Order status: pending, completed, archived, canceled

version

number

required

Order version number (increments with changes)

customer_id

string

ID of the customer who placed the order

string

Customer email address

currency_code

string

required

Three-letter ISO currency code

region_id

string

ID of the associated region

sales_channel_id

string

ID of the sales channel where order was placed

is_draft_order

boolean

Whether this is a draft order (default: false)

items

OrderItem[]

Order line items

shipping_address

OrderAddress

Shipping address for the order

billing_address

OrderAddress

Billing address for the order

shipping_methods

OrderShippingMethod[]

Shipping methods applied to the order

transactions

OrderTransaction[]

Payment transactions

summary

OrderSummary[]

Order totals summary by version

returns

Return[]

Returns associated with this order

OrderItem

Represents a line item in an order.

string

required

Unique item identifier

order_id

string

required

ID of the parent order

version

number

required

Order version when item was added

item_id

string

required

Reference to the cart line item

product_id

string

ID of the product

variant_id

string

ID of the product variant

quantity

number

required

Item quantity

unit_price

BigNumber

required

Price per unit

detail

OrderLineItem

Detailed line item information including totals

OrderLineItem

Detailed line item with pricing and tax information.

string

required

Unique line item identifier

title

string

required

Line item title

subtitle

string

Line item subtitle

thumbnail

string

Product thumbnail URL

quantity

number

required

Item quantity

unit_price

BigNumber

required

Price per unit before discounts

tax_lines

OrderLineItemTaxLine[]

Tax lines applied to this item

adjustments

OrderLineItemAdjustment[]

Discount adjustments applied to this item

OrderChange

Tracks modifications to an order.

string

required

Unique change identifier

order_id

string

required

ID of the order being changed

version

number

required

Order version this change applies to

change_type

string

Type of change: return, exchange, claim, edit

status

OrderChangeStatus

required

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

requested_by

string

User ID who requested the change

confirmed_by

string

User ID who confirmed the change

actions

OrderChangeAction[]

Individual actions in this change

Return

Represents a product return.

string

required

Unique return identifier (prefix: return_)

order_id

string

required

ID of the order being returned

status

string

Return status

items

ReturnItem[]

Items being returned

location_id

string

Stock location where items will be returned

OrderClaim

Represents a customer claim for damaged or incorrect items.

string

required

Unique claim identifier

order_id

string

required

ID of the order being claimed

claim_items

OrderClaimItem[]

Items being claimed

OrderExchange

Represents an item exchange.

string

required

Unique exchange identifier

order_id

string

required

ID of the order

exchange_items

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

orderId

string

required

The ID of the order to retrieve

config

FindConfig

Configuration for the query

relations

string[]

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

select

string[]

Fields to select from the order

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

filters

FilterableOrderProps

Filters to apply

string | string[]

Filter by order IDs

status

OrderStatus[]

Filter by order status

customer_id

string | string[]

Filter by customer IDs

sales_channel_id

string | string[]

Filter by sales channel IDs

string

Filter by customer email

orders

OrderDTO[]

Array of orders matching the filters

count

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: "[email protected]",
  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,
    },
  ],
})

data

CreateOrderDTO | CreateOrderDTO[]

required

Order data to create

customer_id

string

ID of the customer

string

Customer email

currency_code

string

required

Three-letter ISO currency code

region_id

string

ID of the region

items

CreateOrderLineItemDTO[]

Order line items

shipping_address

CreateOrderAddressDTO

Shipping address

billing_address

CreateOrderAddressDTO

Billing address

order

OrderDTO | OrderDTO[]

The created order(s)

Update Orders

Update order information.

const order = await orderModuleService.updateOrders("order_123", {
  email: "[email protected]",
})

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

data

CreateOrderChangeDTO

required

Order change data

order_id

string

required

ID of the order to change

change_type

string

Type of change: return, exchange, claim, edit

requested_by

string

User ID who requested the change

actions

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

data

CreateReturnDTO | CreateReturnDTO[]

required

Return data

order_id

string

required

ID of the order

items

CreateReturnItemDTO[]

required

Items to return

location_id

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

Build docs developers (and LLMs) love

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

​Related Modules

Build docs developers (and LLMs) love

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