Skip to main content

​
Overview

The Orders API enables comprehensive order management including retrieving order details, processing payments, creating fulfillments, and handling returns. Base Path: /admin/orders Source: packages/medusa/src/api/admin/orders/route.ts

​
List Orders

Retrieve a list of orders with filtering and pagination. 
GET /admin/orders

​
Query Parameters

​
fields
string
Comma-separated list of fields to include.
​
limit
number
default:"15"
Maximum number of orders to return.
​
offset
number
default:"0"
Number of orders to skip.
​
status
string
Filter by order status: pending, completed, canceled, requires_action.
​
payment_status
string
Filter by payment status: not_paid, awaiting, captured, partially_refunded, refunded, canceled, requires_action.
​
fulfillment_status
string
Filter by fulfillment status: not_fulfilled, partially_fulfilled, fulfilled, partially_shipped, shipped, partially_delivered, delivered, canceled.
​
sales_channel_id
string
Filter orders by sales channel.
​
customer_id
string
Filter orders by customer.
​
email
string
Filter orders by customer email.
​
region_id
string
Filter orders by region.
​
created_at
object
Filter by creation date range.

​
Request

curl -X GET http://localhost:9000/admin/orders \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "status=completed" \
  --data-urlencode "limit=50"

​
Response

{
  "orders": [
    {
      "id": "order_123",
      "status": "completed",
      "payment_status": "captured",
      "fulfillment_status": "fulfilled",
      "display_id": 1001,
      "customer_id": "cus_123",
      "email": "[email protected]",
      "currency_code": "usd",
      "region_id": "reg_123",
      "sales_channel_id": "sc_123",
      "items": [
        {
          "id": "item_123",
          "title": "Premium T-Shirt",
          "variant_id": "variant_123",
          "quantity": 2,
          "unit_price": 2999,
          "total": 5998
        }
      ],
      "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "123 Main St",
        "city": "New York",
        "country_code": "us",
        "postal_code": "10001"
      },
      "billing_address": {...},
      "shipping_methods": [
        {
          "id": "sm_123",
          "name": "Standard Shipping",
          "amount": 500
        }
      ],
      "payment_collections": [...],
      "fulfillments": [...],
      "subtotal": 5998,
      "tax_total": 480,
      "shipping_total": 500,
      "total": 6978,
      "created_at": "2024-03-03T10:00:00.000Z",
      "updated_at": "2024-03-03T10:30:00.000Z"
    }
  ],
  "count": 150,
  "offset": 0,
  "limit": 50
}
​
orders
Order[]
Array of order objects.
​
count
number
Total number of orders matching the filters.
Source: packages/medusa/src/api/admin/orders/route.ts:8

​
Get Order

Retrieve a single order by ID. 
GET /admin/orders/{id}

​
Path Parameters

​
id
string
required
The order’s ID.

​
Request

curl -X GET http://localhost:9000/admin/orders/order_123 \
  -H "Authorization: Bearer {token}"

​
Response

{
  "order": {
    "id": "order_123",
    "status": "completed",
    "items": [...],
    "shipping_address": {...}
  }
}

​
Update Order

Update order details such as email or metadata. 
POST /admin/orders/{id}

​
Path Parameters

​
id
string
required
The order’s ID.

​
Request Body

​
email
string
Update the order’s email address.
​
shipping_address
object
Update the shipping address.
​
billing_address
object
Update the billing address.
​
metadata
object
Custom metadata key-value pairs.

​
Request

curl -X POST http://localhost:9000/admin/orders/order_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "metadata": {
      "internal_note": "Rush delivery"
    }
  }'

​
Response

{
  "order": {
    "id": "order_123",
    "email": "[email protected]",
    "metadata": {
      "internal_note": "Rush delivery"
    }
  }
}

​
Cancel Order

Cancel an order. 
POST /admin/orders/{id}/cancel

​
Path Parameters

​
id
string
required
The order’s ID.

​
Request

curl -X POST http://localhost:9000/admin/orders/order_123/cancel \
  -H "Authorization: Bearer {token}"

​
Response

{
  "order": {
    "id": "order_123",
    "status": "canceled"
  }
}

​
Fulfillments

​
Create Fulfillment

Create a fulfillment for order items. 
POST /admin/orders/{id}/fulfillments

​
Request Body

​
items
object[]
required
Items to fulfill.
​
location_id
string
required
Stock location to fulfill from.
​
metadata
object
Custom metadata.

​
Request

curl -X POST http://localhost:9000/admin/orders/order_123/fulfillments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "item_123",
        "quantity": 2
      }
    ],
    "location_id": "sloc_123"
  }'

​
Cancel Fulfillment

Cancel a fulfillment. 
POST /admin/orders/{id}/fulfillments/{fulfillment_id}/cancel

​
Ship Fulfillment

Mark a fulfillment as shipped. 
POST /admin/orders/{id}/fulfillments/{fulfillment_id}/shipments

​
Payments

​
Capture Payment

Capture payment for an order. 
POST /admin/orders/{id}/payment-collections/{payment_collection_id}/capture

​
Refund Payment

Refund payment for an order. 
POST /admin/orders/{id}/payment-collections/{payment_collection_id}/refund

​
Request Body

​
amount
number
required
Amount to refund in cents.
​
reason
string
Reason for the refund.

​
Returns

​
Request Return

Initiate a return for order items. 
POST /admin/orders/{id}/returns

​
Request Body

​
items
object[]
required
Items to return.
​
location_id
string
required
Location to receive the return.

​
Receive Return

Mark return items as received. 
POST /admin/orders/{id}/returns/{return_id}/receive

​
Order Changes

​
Get Order Changes

Retrieve all changes made to an order. 
GET /admin/orders/{id}/changes

​
Next Steps

Customers

Manage customer information

Products

View product details

Build docs developers (and LLMs) love

Get started for freeTalk to us