# Manage orders

> Read and manage a Shoplazza store's orders with the Open API: list them, look one up, update it, or cancel it from your app or back office.

Read and manage a store's orders with the Open API — list them, look one up, update it, or cancel it.

## When to use this

Building an order dashboard, syncing orders to an ERP, or a support tool that acts on orders.

## Prerequisites

- A working public app with OAuth and token storage — follow [Develop a standalone app](/docs/app/getting-started/create-public-app/develop-app) first. Every request below carries an `Access-Token: {token}` header, using the token you saved for each shop.
- The order access scope granted during OAuth.

### List orders

Cursor pagination: pass `per_page` (max 250) and, after the first page, the `cursor` from the previous response.

`GET /openapi/2026-01/orders`

Response (excerpt, list under `data.data.orders`, cursor under `data.data.cursor`):

```json
{
  "code": "Success",
  "data": {
    "orders": [
      {
        "id": "2386979206089232618121",
        "number": "VMT95165",
        "total_price": "205.51",
        "currency": "USD",
        "financial_status": "refunded",
        "status": "placed",
        "fulfillment_status": "shipped",
        "created_at": "2026-07-01T07:00:32Z",
        "line_items": [
          {
            "id": "ee73a839-61a2-4504-b4b6-ea55f73f1340",
            "product_id": "27e4f0cd-a115-475b-a3a8-ac9661ed4ccb",
            "product_title": "Denim dress",
            "variant_id": "3e88624d-8535-4720-a781-2257bacd222e",
            "quantity": 1,
            "price": "205.51",
            "sku": "A002013",
            "fulfillment_status": "shipped"
          }
        ]
      }
    ],
    "cursor": "Y3JlYXRlZF9hdCMyMDI2..."
  }
}
```

Full filters and fields: see [List orders](/api/orders).

### Look up one order

Fetch a single order by id, or by its human-facing order number.

`GET /openapi/2026-01/orders/{id}`

Response (excerpt, order under `data.data.order`):

```json
{
  "code": "Success",
  "data": {
    "order": {
      "id": "2386979206089232618121",
      "number": "VMT95165",
      "total_price": "205.51",
      "currency": "USD",
      "financial_status": "refunded",
      "status": "placed",
      "fulfillment_status": "shipped",
      "placed_at": "2026-07-01T07:00:32Z",
      "created_at": "2026-07-01T07:00:32Z",
      "line_items": [
        {
          "id": "ee73a839-61a2-4504-b4b6-ea55f73f1340",
          "product_title": "Denim dress",
          "quantity": 1,
          "price": "205.51",
          "sku": "A002013",
          "fulfillment_status": "shipped"
        }
      ],
      "fulfillments": [
        {
          "id": "92db3f11-39ca-4253-8b26-6e2408e5ea21",
          "order_id": "2386979206089232618121",
          "status": "shipped",
          "created_at": "2026-07-01T07:05:00Z",
          "line_items": [
            { "id": "ee73a839-61a2-4504-b4b6-ea55f73f1340", "quantity": 1, "sku": "A002013" }
          ]
        }
      ],
      "customer": {
        "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "order_count": 3,
        "total_spent": "612.40"
      },
      "shipping_address": {
        "name": "Jane Doe",
        "city": "Los Angeles",
        "province": "California",
        "country": "United States",
        "country_code": "US"
      }
    }
  }
}
```

Full fields: see [Get order](/api/order-detail) and [Get order by number](/api/order-by-number).

### Update an order

Change editable order-level fields with `PUT`; only the fields you send are updated.

`PUT /openapi/2026-01/orders/{id}`

Request body:

```json5
{
  "order": {
    // fields to change, e.g. note, tags
  }
}
```

Returns the updated order under `data.data.order`. Editable fields are listed in the [Update order](/api/order-update) reference.

### Cancel an order

Cancel a placed order. Optionally pass a `reason`.

`POST /openapi/2026-01/orders/{id}/cancel`

Request body (optional):

```json5
{
  "reason": "..." // optional, explains why the order was canceled
}
```

Response (excerpt, order under `data.data.order`; the key signal is `status` turning `cancelled`):

```json
{
  "code": "Success",
  "data": {
    "order": {
      "id": "2386979200059560122875",
      "number": "NPI71329",
      "status": "cancelled",
      "cancelled_at": "2026-07-02T03:25:57Z",
      "financial_status": "waiting",
      "fulfillment_status": "initialled",
      "total_price": "7.00",
      "currency": "CNY"
    }
  }
}
```

:::note
Canceling a **paid** order triggers a fund recall (a refund). If the payment method can't be recalled, the cancel may not fully complete — check the order's `status` field (`cancelled`) rather than only `financial_status`, which can stay `paid` when the recall fails. To return money without canceling the order, use [Refunds and post-sales](/docs/app/use-cases/orders-and-fulfillment/refunds-and-post-sales) instead. See [Cancel order](/api/order-cancel).
:::

## Next steps

- [Fulfill orders](/docs/app/use-cases/orders-and-fulfillment/fulfill-orders)
- [Listen for order events](/docs/app/use-cases/orders-and-fulfillment/listen-for-order-events)