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

# Eaglecart Orders API: Create, Update & Refund Orders

> Full reference for the Eaglecart Orders API — list, retrieve, create, update, and refund orders with request examples and response schemas.

The Orders API gives you programmatic access to every order in your Eaglecart store. Use it to sync orders with fulfillment services, build custom order management dashboards, trigger downstream workflows on status changes, or process refunds without touching the admin UI.

> [!NOTE]
>
> Order status values are: `pending`, `confirmed`, `fulfilled`, `cancelled`, and `refunded`. The `fulfillment_status` and `payment_status` fields track fulfillment and payment pipelines independently from the top-level order status.

***

## The Order Object

**id** `string`

Unique identifier for the order (e.g. `ord_01HXYZ123`).

**status** `string`

The overall order status. One of `pending`, `confirmed`, `fulfilled`, `cancelled`, or `refunded`.

**total** `number`

The total order amount in the store's currency, as a decimal (e.g. `149.99`).

**currency** `string`

ISO 4217 currency code (e.g. `USD`, `EUR`, `GBP`).

**created\_at** `string`

ISO 8601 timestamp of when the order was placed.

**fulfillment\_status** `string`

The fulfillment pipeline status. One of `unfulfilled`, `partial`, `fulfilled`.

**payment\_status** `string`

The payment pipeline status. One of `pending`, `paid`, `partially_refunded`, `refunded`, `voided`.

**customer** `object`

The customer who placed the order.

**customer fields**

**id** `string`

Unique customer identifier.

**first\_name** `string`

Customer's first name.

**last\_name** `string`

Customer's last name.

**email** `string`

Customer's email address.

**line\_items** `array`

The products included in the order.

**line\_item fields**

**variant\_id** `string`

ID of the product variant ordered.

**title** `string`

Product title at time of purchase.

**quantity** `integer`

Number of units ordered.

**unit\_price** `number`

Price per unit at time of purchase.

***

## List Orders

Retrieve a paginated list of all orders in your store. Filter by status or date range to narrow results.

`GET /orders`

**status** `string`

Filter orders by status. One of `pending`, `confirmed`, `fulfilled`, `cancelled`, `refunded`.

**since** `string`

Return only orders created at or after this ISO 8601 timestamp (e.g. `2024-01-01T00:00:00Z`).

**until** `string`

Return only orders created at or before this ISO 8601 timestamp.

**limit** `integer`

Number of orders to return per page. Defaults to `20`. Maximum is `100`.

**page** `integer`

Page number to retrieve. Defaults to `1`.

```bash cURL theme={null}
curl "https://api.eaglecart.com/v1/orders?status=confirmed&limit=5" \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/orders?status=confirmed&limit=5',
  { headers: { 'Authorization': 'Bearer ec_live_xxxxxxxxxxxx' } }
);
const data = await response.json();
```

```json Response theme={null}
{
  "data": [
    {
      "id": "ord_01HXYZ123",
      "status": "confirmed",
      "total": 149.99,
      "currency": "USD",
      "created_at": "2024-06-10T14:32:00Z",
      "fulfillment_status": "unfulfilled",
      "payment_status": "paid",
      "customer": {
        "id": "cus_01HABC456",
        "first_name": "Jamie",
        "last_name": "Rivera",
        "email": "jamie@example.com"
      },
      "line_items": [
        {
          "variant_id": "var_01HDEF789",
          "title": "Classic Tee — Medium / Black",
          "quantity": 2,
          "unit_price": 49.99
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total": 84
  }
}
```

***

## Get an Order

Retrieve a single order by its ID.

`GET /orders/:id`

**id** `string` *required*

The unique ID of the order to retrieve.

```bash cURL theme={null}
curl https://api.eaglecart.com/v1/orders/ord_01HXYZ123 \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/orders/ord_01HXYZ123',
  { headers: { 'Authorization': 'Bearer ec_live_xxxxxxxxxxxx' } }
);
const order = await response.json();
```

```json Response theme={null}
{
  "id": "ord_01HXYZ123",
  "status": "confirmed",
  "total": 149.99,
  "currency": "USD",
  "created_at": "2024-06-10T14:32:00Z",
  "fulfillment_status": "unfulfilled",
  "payment_status": "paid",
  "customer": {
    "id": "cus_01HABC456",
    "first_name": "Jamie",
    "last_name": "Rivera",
    "email": "jamie@example.com"
  },
  "line_items": [
    {
      "variant_id": "var_01HDEF789",
      "title": "Classic Tee — Medium / Black",
      "quantity": 2,
      "unit_price": 49.99
    }
  ]
}
```

***

## Create an Order

Create a new order programmatically. Use this endpoint to import orders from external sales channels or build custom checkout flows.

`POST /orders`

**customer\_id** `string` *required*

The ID of the existing customer placing the order.

**line\_items** `array` *required*

An array of items to include in the order. Each item must have a `variant_id` and `quantity`.

**currency** `string`

ISO 4217 currency code. Defaults to your store's base currency.

**note** `string`

An optional private note to attach to the order. Visible only in your store admin.

```bash cURL theme={null}
curl -X POST https://api.eaglecart.com/v1/orders \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_01HABC456",
    "currency": "USD",
    "line_items": [
      { "variant_id": "var_01HDEF789", "quantity": 2 }
    ]
  }'
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.eaglecart.com/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ec_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: 'cus_01HABC456',
    currency: 'USD',
    line_items: [{ variant_id: 'var_01HDEF789', quantity: 2 }]
  })
});
const order = await response.json();
```

```json Response theme={null}
{
  "id": "ord_01HNEW999",
  "status": "pending",
  "total": 99.98,
  "currency": "USD",
  "created_at": "2024-06-11T09:00:00Z",
  "fulfillment_status": "unfulfilled",
  "payment_status": "pending",
  "customer": {
    "id": "cus_01HABC456",
    "first_name": "Jamie",
    "last_name": "Rivera",
    "email": "jamie@example.com"
  },
  "line_items": [
    {
      "variant_id": "var_01HDEF789",
      "title": "Classic Tee — Medium / Black",
      "quantity": 2,
      "unit_price": 49.99
    }
  ]
}
```

***

## Update Order Status

Update the status of an existing order. Use this endpoint to move orders through your fulfillment pipeline.

`PATCH /orders/:id`

**id** `string` *required*

The unique ID of the order to update.

**status** `string` *required*

The new order status. One of `confirmed`, `fulfilled`, `cancelled`.

**note** `string`

An optional note to record alongside the status change.

```bash cURL theme={null}
curl -X PATCH https://api.eaglecart.com/v1/orders/ord_01HXYZ123 \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "fulfilled" }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/orders/ord_01HXYZ123',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer ec_live_xxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ status: 'fulfilled' })
  }
);
const updated = await response.json();
```

```json Response theme={null}
{
  "id": "ord_01HXYZ123",
  "status": "fulfilled",
  "fulfillment_status": "fulfilled",
  "payment_status": "paid",
  "updated_at": "2024-06-11T10:15:00Z"
}
```

***

## Refund an Order

Issue a full or partial refund for an order. Refunds are processed against the original payment method.

`POST /orders/:id/refund`

**id** `string` *required*

The unique ID of the order to refund.

**amount** `number` *required*

The amount to refund in the order's currency. Must not exceed the remaining refundable amount.

**reason** `string`

The reason for the refund. Recorded in the order timeline and audit log.

**restock** `boolean`

Set to `true` to return refunded line item quantities back to inventory. Defaults to `false`.

```bash cURL theme={null}
curl -X POST https://api.eaglecart.com/v1/orders/ord_01HXYZ123/refund \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "reason": "Customer returned item",
    "restock": true
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/orders/ord_01HXYZ123/refund',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ec_live_xxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 49.99,
      reason: 'Customer returned item',
      restock: true
    })
  }
);
const refund = await response.json();
```

```json Response theme={null}
{
  "id": "ref_01HREFUND1",
  "order_id": "ord_01HXYZ123",
  "amount": 49.99,
  "currency": "USD",
  "reason": "Customer returned item",
  "restocked": true,
  "created_at": "2024-06-11T11:00:00Z",
  "payment_status": "partially_refunded"
}
```

***

## Error Handling

The Orders API uses standard HTTP status codes. All error responses include a JSON body with a `code` field and a human-readable `message`.

| Status | Code | What it means | How to fix it |
| - | - | - | - |
| `400 Bad Request` | `invalid_params` | A required field is missing or has an invalid value (e.g. unrecognised `status` value). | Check the `message` field for details and correct your request body. |
| `401 Unauthorized` | `missing_api_key` / `invalid_api_key` | No `Authorization` header was sent, or the key is revoked. | Add a valid `Authorization: Bearer <key>` header. |
| `403 Forbidden` | `insufficient_scope` | Your key does not have the required scope (`read:orders` or `write:orders`). | Re-generate your key with the correct scopes in **Settings → Developer → API Keys**. |
| `404 Not Found` | `order_not_found` | No order with the given ID exists in your store. | Confirm the order ID is correct. |
| `422 Unprocessable Entity` | `refund_exceeds_balance` | The refund amount is greater than the remaining refundable balance. | Reduce the `amount` to at most the order's remaining refundable total. |
| `429 Too Many Requests` | `rate_limit_exceeded` | You have exceeded 1,000 requests per minute. | Wait until `X-RateLimit-Reset` and retry with exponential backoff. |
| `500 Internal Server Error` | `internal_error` | An unexpected server error occurred. | Retry after a short delay. If the problem persists, contact Eaglecart support. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.