# List orders (`list_orders`)

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.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/list_orders/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/list_orders.md
- MCP endpoint: https://web.signcustomiser.com/mcp
- Required scope: `orders:read`
- Behaviour: read

## Purpose

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

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | true |
| destructiveHint | false |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

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

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | How many orders to return per page, between 1 and 100. Defaults to 20. |
| `cursor` | string | no | The opaque next_cursor value from the previous page, sent back with identical filters. |
| `filter` | object | no | Optional filters. An unknown filter is rejected, never ignored. |
| `filter.status` | string | no | Only orders in this status. Expected to grow: tolerate unknown values. One of: `received`. |
| `filter.customiser_id` | integer | no | Only orders with a line item from this customiser. Legacy order projections carry no modern line items and so never match. |
| `filter.created_from` | string | no | Inclusive UTC start date, YYYY-MM-DD. |
| `filter.created_to` | string | no | 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.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `orders` | array of object | yes | The page of order summaries, newest first. |
| `orders[].id` | integer | yes |  |
| `orders[].store_order_id` | string or null | no |  |
| `orders[].store_order_number` | string or null | no |  |
| `orders[].status` | string | yes |  |
| `orders[].status_display_name` | string or null | no |  |
| `orders[].total_amount` | integer or null | no | Integer minor units of currency. |
| `orders[].currency` | string or null | no |  |
| `orders[].line_item_count` | integer or null | no |  |
| `orders[].created_at` | string or null | no |  |
| `orders[].updated_at` | string or null | no |  |
| `pagination` | object | yes |  |
| `pagination.has_more` | boolean | yes |  |
| `pagination.next_cursor` | string or null | no |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `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. |

## Example: Orders created in one UTC window

Request:

```json
{
  "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"
      }
    }
  }
}
```

Response:

```json
{
  "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
      }
    }
  }
}
```

## Example: A date filter in the wrong format (error)

Request:

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

Response:

```json
{
  "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]"
      }
    }
  }
}
```