Orders

list_orders

read

List orders

Copy page

Survey a Store trading activity and obtain the order ids get_order takes, without pulling customer data into the answer.

Overview

Lists orders synchronised into the connected Store from its selling platform, newest first, with each order id, its external order id and display number, its status and status display name, its line-item count, and its total in integer minor units with the currency. Filters narrow the list by status, by originating customiser and by UTC creation date range. Customer and line-item detail is a separate read. It requires the orders:read scope and has no side effects.

Permission

Requires theorders:readpermission. A connection without it answersinsufficient_scopenaming the permission to approve.

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A merchant has connected this store and approved the orders:read scope.

Arguments

limitinteger

How many orders to return per page, between 1 and 100. Defaults to 20.

cursorstring

The opaque next_cursor value from the previous page, sent back with identical filters.

filterobject

Optional filters. An unknown filter is rejected, never ignored.

filter.statusstring

Only orders in this status. Expected to grow: tolerate unknown values.

One of: received

filter.customiser_idinteger

Only orders with a line item from this customiser. Legacy order projections carry no modern line items and so never match.

filter.created_fromstring

Inclusive UTC start date, YYYY-MM-DD.

filter.created_tostring

Inclusive UTC end date, YYYY-MM-DD. It must not precede created_from.

Result

Up to `limit` order summaries, newest first, plus the cursor for the next page. No customer, address or line-item detail: those are get_order.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

ordersarray of objectalways present

The page of order summaries, newest first.

orders[].idintegeralways present

orders[].store_order_idstring or null

orders[].store_order_numberstring or null

orders[].statusstringalways present

orders[].status_display_namestring or null

orders[].total_amountinteger or null

Integer minor units of currency.

orders[].currencystring or null

orders[].line_item_countinteger or null

orders[].created_atstring or null

orders[].updated_atstring or null

paginationobjectalways present

pagination.has_morebooleanalways present

pagination.next_cursorstring or null

Error cases

insufficient_scope

The connection was approved without orders:read.

invalid_cursor

The cursor was altered or reused with different filters; restart with no cursor.

invalid_parameter

A date filter is not YYYY-MM-DD in UTC, or created_to precedes created_from.

unsupported_value

A filter value is not one this API accepts; allowed_values lists the accepted set.

Orders created in one UTC window

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_orders",
    "arguments": {
      "limit": 1,
      "filter": {
        "created_from": "2026-07-01",
        "created_to": "2026-07-31"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "orders": [
        {
          "id": 123,
          "store_order_id": "gid://shopify/Order/1001",
          "store_order_number": "#1001",
          "status": "received",
          "status_display_name": "Received",
          "total_amount": 31900,
          "currency": "AUD",
          "line_item_count": 2,
          "created_at": "2026-07-18T02:15:00Z",
          "updated_at": "2026-07-18T02:16:00Z"
        }
      ],
      "pagination": {
        "has_more": false,
        "next_cursor": null
      }
    }
  }
}

A date filter in the wrong format (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_orders",
    "arguments": {
      "filter": {
        "created_from": "18/07/2026"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "invalid_parameter",
        "title": "Invalid query parameter",
        "detail": "The filter[created_from] parameter must be a UTC date in YYYY-MM-DD format.",
        "recovery": "Correct the parameter named in parameter. Dates are YYYY-MM-DD in UTC and identifiers are integers between 1 and 2147483647.",
        "parameter": "filter[created_from]"
      }
    }
  }
}