Orders

Admin API endpoints for managing orders, fulfillments, payments, and returns.

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": "[e-mail]",
      "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": "[e-mail]",
    "metadata": {
      "internal_note": "Rush delivery"
    }
  }'

Response

{
  "order": {
    "id": "order_123",
    "email": "[e-mail]",
    "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.

Show child attributes

id · string · required

Order item ID.

quantity · number · required

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

Show child attributes

id · string · required

Order item ID.

quantity · number · required

Quantity to return.

reason_id · string

Return reason ID.

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