# Orders · Management API

> Management API reference for orders: GET /sites/{id}/orders, GET /sites/{id}/orders/{orderId}.

> Markdown version of https://kanorio.com/en/developers/management-api/orders. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp

Base URL: `https://app.kanorio.com/api/v1` · [Errors](https://kanorio.com/en/developers/basics/errors) · [Pagination](https://kanorio.com/en/developers/basics/pagination)

### List orders

`GET /sites/{id}/orders`

- Stability: beta
- Permission: `orders:view`
- Rate limit: default (120/minute per token)
- MCP tool: `orders_list`

List orders newest first with line items and shipment summary (amounts in minor units of order.currency). Refunds, payment settings and invoices are not available to agents. Errors: FORBIDDEN, INVALID_CURSOR.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |
| `status` | query | "UNPAID" \| "PAID" \| "PARTIALLY_REFUNDED" \| "REFUNDED" \| "DISPUTED" \| "PAYMENT_REVERSED" \| "CANCELLED" | no | — |
| `limit` | query | integer | no | Maximum number of items to return, 1–100. Defaults to 20. |
| `cursor` | query | string | no | Opaque cursor from the previous page's nextCursor. Omit for the first page. |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | yes | — |
| `data[].id` | string | yes | — |
| `data[].orderNumber` | integer \| null | yes | Human-readable per-store number (#1001...). |
| `data[].status` | string | yes | — |
| `data[].currency` | string | yes | — |
| `data[].subtotalAmount` | integer | yes | — |
| `data[].discountAmount` | integer | yes | — |
| `data[].amount` | integer | yes | Items after discount, excluding shipping. |
| `data[].shippingFee` | integer | yes | — |
| `data[].totalRefunded` | integer | yes | — |
| `data[].itemCount` | integer | yes | — |
| `data[].customerEmail` | string | yes | — |
| `data[].customerName` | string \| null | yes | — |
| `data[].customerPhone` | string \| null | yes | — |
| `data[].buyerNote` | string \| null | yes | — |
| `data[].metadata` | object | yes | Public integration fields on the order. |
| `data[].privateMetadata` | object | yes | Private integration fields on the order (console, members and service accounts only). |
| `data[].promotionCode` | string \| null | yes | — |
| `data[].paymentProvider` | string | yes | — |
| `data[].paidAt` | string \| null | yes | — |
| `data[].refundedAt` | string \| null | yes | — |
| `data[].createdAt` | string | yes | — |
| `data[].items` | object[] | yes | — |
| `data[].items[].id` | string | yes | — |
| `data[].items[].productId` | string | yes | — |
| `data[].items[].tierId` | string \| null | yes | — |
| `data[].items[].productTitle` | string | yes | — |
| `data[].items[].tierName` | string \| null | yes | — |
| `data[].items[].productType` | string | yes | — |
| `data[].items[].unitPrice` | integer | yes | — |
| `data[].items[].quantity` | integer | yes | — |
| `data[].items[].lineAmount` | integer | yes | — |
| `data[].items[].refundedQuantity` | integer | yes | — |
| `data[].items[].refundedAmount` | integer | yes | — |
| `data[].shipments` | object[] | yes | — |
| `data[].shipments[].id` | string | yes | — |
| `data[].shipments[].status` | string | yes | — |
| `data[].shipments[].provider` | string | yes | — |
| `data[].shipments[].method` | string | yes | — |
| `data[].shipments[].trackingNo` | string \| null | yes | — |
| `data[].shipments[].trackingUrl` | string \| null | yes | — |
| `hasMore` | boolean | yes | True when another page exists; pass nextCursor to fetch it. |
| `nextCursor` | string \| null | yes | Cursor for the next page, or null on the last page. |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `FORBIDDEN` | 403 | — |
| `INVALID_CURSOR` | 400 | — |

```bash
curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/orders" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
```

```json
{
  "data": [
    {
      "id": "order_example01",
      "orderNumber": 1024,
      "status": "PAID",
      "currency": "TWD",
      "subtotalAmount": 880,
      "discountAmount": 0,
      "amount": 980,
      "shippingFee": 100,
      "totalRefunded": 0,
      "itemCount": 1,
      "customerEmail": "customer@example.com",
      "customerName": "Alex Chen",
      "customerPhone": "+886912345678",
      "buyerNote": "Pickup on Saturday at 2 p.m.",
      "metadata": {},
      "privateMetadata": {},
      "promotionCode": null,
      "paymentProvider": "STRIPE",
      "paidAt": "2026-10-06T08:00:00.000Z",
      "refundedAt": null,
      "createdAt": "2026-10-06T08:00:00.000Z",
      "items": [
        {
          "id": "item_example01",
          "productId": "prod_example01",
          "tierId": "tier_example01",
          "productTitle": "Strawberry Birthday Cake",
          "tierName": "6-inch",
          "productType": "PHYSICAL",
          "unitPrice": 880,
          "quantity": 1,
          "lineAmount": 880,
          "refundedQuantity": 0,
          "refundedAmount": 0
        }
      ],
      "shipments": [
        {
          "id": "ship_example01",
          "status": "PENDING",
          "provider": "MANUAL",
          "method": "PICKUP",
          "trackingNo": null,
          "trackingUrl": null
        }
      ]
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

### Retrieve an order

`GET /sites/{id}/orders/{orderId}`

- Stability: beta
- Permission: `orders:view`
- Rate limit: default (120/minute per token)
- MCP tool: `orders_get`

Get one order with line items and shipments. Errors: FORBIDDEN, ORDER_NOT_FOUND.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |
| `orderId` | path | string | yes | — |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | — |
| `orderNumber` | integer \| null | yes | Human-readable per-store number (#1001...). |
| `status` | string | yes | — |
| `currency` | string | yes | — |
| `subtotalAmount` | integer | yes | — |
| `discountAmount` | integer | yes | — |
| `amount` | integer | yes | Items after discount, excluding shipping. |
| `shippingFee` | integer | yes | — |
| `totalRefunded` | integer | yes | — |
| `itemCount` | integer | yes | — |
| `customerEmail` | string | yes | — |
| `customerName` | string \| null | yes | — |
| `customerPhone` | string \| null | yes | — |
| `buyerNote` | string \| null | yes | — |
| `metadata` | object | yes | Public integration fields on the order. |
| `privateMetadata` | object | yes | Private integration fields on the order (console, members and service accounts only). |
| `promotionCode` | string \| null | yes | — |
| `paymentProvider` | string | yes | — |
| `paidAt` | string \| null | yes | — |
| `refundedAt` | string \| null | yes | — |
| `createdAt` | string | yes | — |
| `items` | object[] | yes | — |
| `items[].id` | string | yes | — |
| `items[].productId` | string | yes | — |
| `items[].tierId` | string \| null | yes | — |
| `items[].productTitle` | string | yes | — |
| `items[].tierName` | string \| null | yes | — |
| `items[].productType` | string | yes | — |
| `items[].unitPrice` | integer | yes | — |
| `items[].quantity` | integer | yes | — |
| `items[].lineAmount` | integer | yes | — |
| `items[].refundedQuantity` | integer | yes | — |
| `items[].refundedAmount` | integer | yes | — |
| `shipments` | object[] | yes | — |
| `shipments[].id` | string | yes | — |
| `shipments[].status` | string | yes | — |
| `shipments[].provider` | string | yes | — |
| `shipments[].method` | string | yes | — |
| `shipments[].trackingNo` | string \| null | yes | — |
| `shipments[].trackingUrl` | string \| null | yes | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `FORBIDDEN` | 403 | — |
| `ORDER_NOT_FOUND` | 404 | — |

```bash
curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/orders/{orderId}" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
```

```json
{
  "id": "order_example01",
  "orderNumber": 1024,
  "status": "PAID",
  "currency": "TWD",
  "subtotalAmount": 880,
  "discountAmount": 0,
  "amount": 980,
  "shippingFee": 100,
  "totalRefunded": 0,
  "itemCount": 1,
  "customerEmail": "customer@example.com",
  "customerName": "Alex Chen",
  "customerPhone": "+886912345678",
  "buyerNote": "Pickup on Saturday at 2 p.m.",
  "metadata": {},
  "privateMetadata": {},
  "promotionCode": null,
  "paymentProvider": "STRIPE",
  "paidAt": "2026-10-06T08:00:00.000Z",
  "refundedAt": null,
  "createdAt": "2026-10-06T08:00:00.000Z",
  "items": [
    {
      "id": "item_example01",
      "productId": "prod_example01",
      "tierId": "tier_example01",
      "productTitle": "Strawberry Birthday Cake",
      "tierName": "6-inch",
      "productType": "PHYSICAL",
      "unitPrice": 880,
      "quantity": 1,
      "lineAmount": 880,
      "refundedQuantity": 0,
      "refundedAmount": 0
    }
  ],
  "shipments": [
    {
      "id": "ship_example01",
      "status": "PENDING",
      "provider": "MANUAL",
      "method": "PICKUP",
      "trackingNo": null,
      "trackingUrl": null
    }
  ]
}
```