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

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

```bash theme={null}
GET /admin/orders
```

### Query Parameters

<ParamField query="fields" type="string">
  Comma-separated list of fields to include.
</ParamField>

<ParamField query="limit" type="number" default="15">
  Maximum number of orders to return.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of orders to skip.
</ParamField>

<ParamField query="status" type="string">
  Filter by order status: `pending`, `completed`, `canceled`, `requires_action`.
</ParamField>

<ParamField query="payment_status" type="string">
  Filter by payment status: `not_paid`, `awaiting`, `captured`, `partially_refunded`, `refunded`, `canceled`, `requires_action`.
</ParamField>

<ParamField query="fulfillment_status" type="string">
  Filter by fulfillment status: `not_fulfilled`, `partially_fulfilled`, `fulfilled`, `partially_shipped`, `shipped`, `partially_delivered`, `delivered`, `canceled`.
</ParamField>

<ParamField query="sales_channel_id" type="string">
  Filter orders by sales channel.
</ParamField>

<ParamField query="customer_id" type="string">
  Filter orders by customer.
</ParamField>

<ParamField query="email" type="string">
  Filter orders by customer email.
</ParamField>

<ParamField query="region_id" type="string">
  Filter orders by region.
</ParamField>

<ParamField query="created_at" type="object">
  Filter by creation date range.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "orders": [
    {
      "id": "order_123",
      "status": "completed",
      "payment_status": "captured",
      "fulfillment_status": "fulfilled",
      "display_id": 1001,
      "customer_id": "cus_123",
      "email": "customer@example.com",
      "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
}
```

<ResponseField name="orders" type="Order[]">
  Array of order objects.
</ResponseField>

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

**Source:** `packages/medusa/src/api/admin/orders/route.ts:8`

## Get Order

Retrieve a single order by ID.

```bash theme={null}
GET /admin/orders/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The order's ID.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "order": {
    "id": "order_123",
    "status": "completed",
    "items": [...],
    "shipping_address": {...}
  }
}
```

## Update Order

Update order details such as email or metadata.

```bash theme={null}
POST /admin/orders/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The order's ID.
</ParamField>

### Request Body

<ParamField body="email" type="string">
  Update the order's email address.
</ParamField>

<ParamField body="shipping_address" type="object">
  Update the shipping address.
</ParamField>

<ParamField body="billing_address" type="object">
  Update the billing address.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata key-value pairs.
</ParamField>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/admin/orders/order_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newemail@example.com",
    "metadata": {
      "internal_note": "Rush delivery"
    }
  }'
```

### Response

```json theme={null}
{
  "order": {
    "id": "order_123",
    "email": "newemail@example.com",
    "metadata": {
      "internal_note": "Rush delivery"
    }
  }
}
```

## Cancel Order

Cancel an order.

```bash theme={null}
POST /admin/orders/{id}/cancel
```

### Path Parameters

<ParamField path="id" type="string" required>
  The order's ID.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "order": {
    "id": "order_123",
    "status": "canceled"
  }
}
```

## Fulfillments

### Create Fulfillment

Create a fulfillment for order items.

```bash theme={null}
POST /admin/orders/{id}/fulfillments
```

### Request Body

<ParamField body="items" type="object[]" required>
  Items to fulfill.

  <Expandable>
    <ParamField body="id" type="string" required>
      Order item ID.
    </ParamField>

    <ParamField body="quantity" type="number" required>
      Quantity to fulfill.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="location_id" type="string" required>
  Stock location to fulfill from.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata.
</ParamField>

### Request

```bash theme={null}
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.

```bash theme={null}
POST /admin/orders/{id}/fulfillments/{fulfillment_id}/cancel
```

### Ship Fulfillment

Mark a fulfillment as shipped.

```bash theme={null}
POST /admin/orders/{id}/fulfillments/{fulfillment_id}/shipments
```

## Payments

### Capture Payment

Capture payment for an order.

```bash theme={null}
POST /admin/orders/{id}/payment-collections/{payment_collection_id}/capture
```

### Refund Payment

Refund payment for an order.

```bash theme={null}
POST /admin/orders/{id}/payment-collections/{payment_collection_id}/refund
```

### Request Body

<ParamField body="amount" type="number" required>
  Amount to refund in cents.
</ParamField>

<ParamField body="reason" type="string">
  Reason for the refund.
</ParamField>

## Returns

### Request Return

Initiate a return for order items.

```bash theme={null}
POST /admin/orders/{id}/returns
```

### Request Body

<ParamField body="items" type="object[]" required>
  Items to return.

  <Expandable>
    <ParamField body="id" type="string" required>
      Order item ID.
    </ParamField>

    <ParamField body="quantity" type="number" required>
      Quantity to return.
    </ParamField>

    <ParamField body="reason_id" type="string">
      Return reason ID.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="location_id" type="string" required>
  Location to receive the return.
</ParamField>

### Receive Return

Mark return items as received.

```bash theme={null}
POST /admin/orders/{id}/returns/{return_id}/receive
```

## Order Changes

### Get Order Changes

Retrieve all changes made to an order.

```bash theme={null}
GET /admin/orders/{id}/changes
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Customers" icon="users" href="/api/admin/customers">
    Manage customer information
  </Card>

  <Card title="Products" icon="box" href="/api/admin/products">
    View product details
  </Card>
</CardGroup>