> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Module

> Learn about the Order Module and how to manage orders, order changes, returns, claims, and exchanges in Medusa.

## 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.

<ResponseField name="id" type="string" required>
  Unique order identifier (prefix: `order_`)
</ResponseField>

<ResponseField name="display_id" type="number" required>
  Auto-incrementing display ID for customer reference
</ResponseField>

<ResponseField name="custom_display_id" type="string">
  Custom display ID (e.g., "ORD-2024-001")
</ResponseField>

<ResponseField name="status" type="OrderStatus" required>
  Order status: `pending`, `completed`, `archived`, `canceled`
</ResponseField>

<ResponseField name="version" type="number" required>
  Order version number (increments with changes)
</ResponseField>

<ResponseField name="customer_id" type="string">
  ID of the customer who placed the order
</ResponseField>

<ResponseField name="email" type="string">
  Customer email address
</ResponseField>

<ResponseField name="currency_code" type="string" required>
  Three-letter ISO currency code
</ResponseField>

<ResponseField name="region_id" type="string">
  ID of the associated region
</ResponseField>

<ResponseField name="sales_channel_id" type="string">
  ID of the sales channel where order was placed
</ResponseField>

<ResponseField name="is_draft_order" type="boolean">
  Whether this is a draft order (default: false)
</ResponseField>

<ResponseField name="items" type="OrderItem[]">
  Order line items
</ResponseField>

<ResponseField name="shipping_address" type="OrderAddress">
  Shipping address for the order
</ResponseField>

<ResponseField name="billing_address" type="OrderAddress">
  Billing address for the order
</ResponseField>

<ResponseField name="shipping_methods" type="OrderShippingMethod[]">
  Shipping methods applied to the order
</ResponseField>

<ResponseField name="transactions" type="OrderTransaction[]">
  Payment transactions
</ResponseField>

<ResponseField name="summary" type="OrderSummary[]">
  Order totals summary by version
</ResponseField>

<ResponseField name="returns" type="Return[]">
  Returns associated with this order
</ResponseField>

### OrderItem

Represents a line item in an order.

<ResponseField name="id" type="string" required>
  Unique item identifier
</ResponseField>

<ResponseField name="order_id" type="string" required>
  ID of the parent order
</ResponseField>

<ResponseField name="version" type="number" required>
  Order version when item was added
</ResponseField>

<ResponseField name="item_id" type="string" required>
  Reference to the cart line item
</ResponseField>

<ResponseField name="product_id" type="string">
  ID of the product
</ResponseField>

<ResponseField name="variant_id" type="string">
  ID of the product variant
</ResponseField>

<ResponseField name="quantity" type="number" required>
  Item quantity
</ResponseField>

<ResponseField name="unit_price" type="BigNumber" required>
  Price per unit
</ResponseField>

<ResponseField name="detail" type="OrderLineItem">
  Detailed line item information including totals
</ResponseField>

### OrderLineItem

Detailed line item with pricing and tax information.

<ResponseField name="id" type="string" required>
  Unique line item identifier
</ResponseField>

<ResponseField name="title" type="string" required>
  Line item title
</ResponseField>

<ResponseField name="subtitle" type="string">
  Line item subtitle
</ResponseField>

<ResponseField name="thumbnail" type="string">
  Product thumbnail URL
</ResponseField>

<ResponseField name="quantity" type="number" required>
  Item quantity
</ResponseField>

<ResponseField name="unit_price" type="BigNumber" required>
  Price per unit before discounts
</ResponseField>

<ResponseField name="tax_lines" type="OrderLineItemTaxLine[]">
  Tax lines applied to this item
</ResponseField>

<ResponseField name="adjustments" type="OrderLineItemAdjustment[]">
  Discount adjustments applied to this item
</ResponseField>

### OrderChange

Tracks modifications to an order.

<ResponseField name="id" type="string" required>
  Unique change identifier
</ResponseField>

<ResponseField name="order_id" type="string" required>
  ID of the order being changed
</ResponseField>

<ResponseField name="version" type="number" required>
  Order version this change applies to
</ResponseField>

<ResponseField name="change_type" type="string">
  Type of change: `return`, `exchange`, `claim`, `edit`
</ResponseField>

<ResponseField name="status" type="OrderChangeStatus" required>
  Change status: `pending`, `requested`, `confirmed`, `declined`, `canceled`
</ResponseField>

<ResponseField name="requested_by" type="string">
  User ID who requested the change
</ResponseField>

<ResponseField name="confirmed_by" type="string">
  User ID who confirmed the change
</ResponseField>

<ResponseField name="actions" type="OrderChangeAction[]">
  Individual actions in this change
</ResponseField>

### Return

Represents a product return.

<ResponseField name="id" type="string" required>
  Unique return identifier (prefix: `return_`)
</ResponseField>

<ResponseField name="order_id" type="string" required>
  ID of the order being returned
</ResponseField>

<ResponseField name="status" type="string">
  Return status
</ResponseField>

<ResponseField name="items" type="ReturnItem[]">
  Items being returned
</ResponseField>

<ResponseField name="location_id" type="string">
  Stock location where items will be returned
</ResponseField>

### OrderClaim

Represents a customer claim for damaged or incorrect items.

<ResponseField name="id" type="string" required>
  Unique claim identifier
</ResponseField>

<ResponseField name="order_id" type="string" required>
  ID of the order being claimed
</ResponseField>

<ResponseField name="claim_items" type="OrderClaimItem[]">
  Items being claimed
</ResponseField>

### OrderExchange

Represents an item exchange.

<ResponseField name="id" type="string" required>
  Unique exchange identifier
</ResponseField>

<ResponseField name="order_id" type="string" required>
  ID of the order
</ResponseField>

<ResponseField name="exchange_items" type="OrderExchangeItem[]">
  Items being exchanged
</ResponseField>

## Service Interface

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

### Retrieve Order

Retrieve a single order with related data.

<CodeGroup>
  ```typescript Example theme={null}
  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 })
  }
  ```
</CodeGroup>

<ParamField path="orderId" type="string" required>
  The ID of the order to retrieve
</ParamField>

<ParamField path="config" type="FindConfig">
  Configuration for the query

  <ParamField path="relations" type="string[]">
    Relations to load (e.g., `["items", "shipping_address"]`)
  </ParamField>

  <ParamField path="select" type="string[]">
    Fields to select from the order
  </ParamField>
</ParamField>

<ResponseField name="order" type="OrderDTO">
  The retrieved order
</ResponseField>

### List Orders

List orders with filtering and pagination.

<CodeGroup>
  ```typescript Example theme={null}
  const [orders, count] = await orderModuleService.listAndCountOrders(
    {
      customer_id: "cus_123",
      status: ["completed"],
    },
    {
      relations: ["items", "summary"],
      take: 20,
      skip: 0,
      order: { created_at: "DESC" },
    }
  )
  ```
</CodeGroup>

<ParamField path="filters" type="FilterableOrderProps">
  Filters to apply

  <ParamField path="id" type="string | string[]">
    Filter by order IDs
  </ParamField>

  <ParamField path="status" type="OrderStatus[]">
    Filter by order status
  </ParamField>

  <ParamField path="customer_id" type="string | string[]">
    Filter by customer IDs
  </ParamField>

  <ParamField path="sales_channel_id" type="string | string[]">
    Filter by sales channel IDs
  </ParamField>

  <ParamField path="email" type="string">
    Filter by customer email
  </ParamField>
</ParamField>

<ResponseField name="orders" type="OrderDTO[]">
  Array of orders matching the filters
</ResponseField>

<ResponseField name="count" type="number">
  Total count of matching orders
</ResponseField>

### Create Orders

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

<CodeGroup>
  ```typescript Example theme={null}
  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,
      },
    ],
  })
  ```
</CodeGroup>

<ParamField path="data" type="CreateOrderDTO | CreateOrderDTO[]" required>
  Order data to create

  <ParamField path="customer_id" type="string">
    ID of the customer
  </ParamField>

  <ParamField path="email" type="string">
    Customer email
  </ParamField>

  <ParamField path="currency_code" type="string" required>
    Three-letter ISO currency code
  </ParamField>

  <ParamField path="region_id" type="string">
    ID of the region
  </ParamField>

  <ParamField path="items" type="CreateOrderLineItemDTO[]">
    Order line items
  </ParamField>

  <ParamField path="shipping_address" type="CreateOrderAddressDTO">
    Shipping address
  </ParamField>

  <ParamField path="billing_address" type="CreateOrderAddressDTO">
    Billing address
  </ParamField>
</ParamField>

<ResponseField name="order" type="OrderDTO | OrderDTO[]">
  The created order(s)
</ResponseField>

### Update Orders

Update order information.

<CodeGroup>
  ```typescript By ID theme={null}
  const order = await orderModuleService.updateOrders("order_123", {
    email: "newemail@example.com",
  })
  ```

  ```typescript By Selector theme={null}
  const orders = await orderModuleService.updateOrders(
    { status: "pending" },
    { no_notification: true }
  )
  ```
</CodeGroup>

### Create Order Change

Initiate a change to an order.

<CodeGroup>
  ```typescript Example theme={null}
  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,
        },
      },
    ],
  })
  ```
</CodeGroup>

<ParamField path="data" type="CreateOrderChangeDTO" required>
  Order change data

  <ParamField path="order_id" type="string" required>
    ID of the order to change
  </ParamField>

  <ParamField path="change_type" type="string">
    Type of change: `return`, `exchange`, `claim`, `edit`
  </ParamField>

  <ParamField path="requested_by" type="string">
    User ID who requested the change
  </ParamField>

  <ParamField path="actions" type="OrderChangeActionDTO[]">
    Individual actions in this change
  </ParamField>
</ParamField>

### Confirm Order Change

Confirm and apply an order change.

<CodeGroup>
  ```typescript Example theme={null}
  const order = await orderModuleService.confirmOrderChange(
    "change_123",
    "user_123"
  )
  ```
</CodeGroup>

### Create Return

Create a product return.

<CodeGroup>
  ```typescript Example theme={null}
  const orderReturn = await orderModuleService.createReturns({
    order_id: "order_123",
    items: [
      {
        item_id: "item_456",
        quantity: 1,
        reason_id: "reason_defective",
      },
    ],
    location_id: "sloc_warehouse",
  })
  ```
</CodeGroup>

<ParamField path="data" type="CreateReturnDTO | CreateReturnDTO[]" required>
  Return data

  <ParamField path="order_id" type="string" required>
    ID of the order
  </ParamField>

  <ParamField path="items" type="CreateReturnItemDTO[]" required>
    Items to return
  </ParamField>

  <ParamField path="location_id" type="string">
    Stock location for return
  </ParamField>
</ParamField>

### Create Order Claim

Create a claim for damaged or incorrect items.

<CodeGroup>
  ```typescript Example theme={null}
  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" },
        ],
      },
    ],
  })
  ```
</CodeGroup>

### Create Order Exchange

Create an item exchange.

<CodeGroup>
  ```typescript Example theme={null}
  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,
      },
    ],
  })
  ```
</CodeGroup>

## Integration Examples

### With Cart Module

Orders are typically created from completed carts.

<CodeGroup>
  ```typescript Example in Workflow theme={null}
  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
    }
  )
  ```
</CodeGroup>

### With Payment Module

Track payment transactions for orders.

<CodeGroup>
  ```typescript Example theme={null}
  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,
  })
  ```
</CodeGroup>

### With Fulfillment Module

Create fulfillments for order items.

<CodeGroup>
  ```typescript Example theme={null}
  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,
    })),
  })
  ```
</CodeGroup>

## Best Practices

1. **Order Versioning**: The order version increments with each modification. Always reference the version when making changes.

2. **Order Changes**: Use the OrderChange entity for tracking modifications. This provides an audit trail and approval workflow.

3. **Status Management**: Follow the order status flow: `pending` → `completed` → `archived`. Use `canceled` for cancelled orders.

4. **Transaction Tracking**: Create OrderTransaction entries for all payment-related activities to maintain a complete financial record.

5. **Returns and Exchanges**: Use dedicated return and exchange entities rather than modifying the original order.

6. **Display IDs**: Use `display_id` for customer-facing order numbers. Optionally set `custom_display_id` for custom formatting.

## Related Modules

* [Cart Module](/modules/cart) - Create orders from carts
* [Payment Module](/modules/payment) - Process order payments
* [Fulfillment Module](/modules/fulfillment) - Fulfill order items
* [Inventory Module](/modules/inventory) - Reserve and adjust inventory
* [Customer Module](/modules/customer) - Associate orders with customers