Skip to main content

Manage orders

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 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):

{
  "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.

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):

{
  "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": "[email protected]",
        "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 and Get 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:

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

Returns the updated order under data.data.order. Editable fields are listed in the Update order reference.

Cancel an order​

Cancel a placed order. Optionally pass a reason.

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

Request body (optional):

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

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

{
  "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 instead. See Cancel order.

Next steps​