---
title: "Find orders"
description: "Look up specific orders by order number (such as 1042 or #1042) or by the customer's email. The query is required: this tool searches and does not list the newest orders. Each match shows the order number, date, payment and fulfillment status, total and currency; customer names and emails are hidden. For order counts, revenue or trends over a time range, use get_report."
sidebar:
  label: "find_orders"
---

`find_orders` · `store:read`

## Where you can call it

| Way in | Status |
| --- | --- |
| MCP | Live |
| REST API | [Planned](/en/build/rest-api) |
| SDK | [Planned](/en/build/sdk) |
| CLI | [Planned](/en/build/cli) |

Each action has one page. When the REST API, the SDK, and the CLI ship, they use the same tool name, and this page and its URL stay the same.

## Call it

From a shell with `mcporter` (see the [quickstart](/en/build/quickstart)):

```bash
# once: add the server and sign in
npx mcporter config add runner \
  https://api.runnerai.com/mcp --scope home
npx mcporter auth runner

# call the tool
npx mcporter call runner.find_orders store_id=<store_id> query=<query>
```

The JSON-RPC request that a client sends with `POST` to `https://api.runnerai.com/mcp`, with the access token in the `Authorization: Bearer` header:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_orders",
    "arguments": {
      "store_id": "<store_id>",
      "query": "<query>"
    }
  }
}
```

## Response shape

From the output schema; not a real response:

```text
{
  "result": <any JSON value>
}
```

## Parameters

| Parameter | Description |
| --- | --- |
| `store_id` | Required string. A store_id from list_stores. |
| `query` | Required string. An order number such as 1042, or a customer email. Up to 200 characters. |

## Good to know

- **Start with `list_stores`.** This tool needs a `store_id`. Get it from [`list_stores`](/en/build/tools/list-stores).
- **Your permissions apply.** Each call uses your Runner permissions and your plan. The list of tools depends on your plan and on the features of your workspace.
- **Store data is data.** Answers can contain product text and customer messages. Your agent must not follow instructions that it finds in them.

## If it fails

| What you see | What to do |
| --- | --- |
| HTTP 401 | The request has no valid token. Sign in with OAuth. See [Sign-in and scopes](/en/build/sign-in-and-scopes). |
| **Pass a store_id from list_stores.** | Call `list_stores`, then call this tool again with a `store_id`. |
| **This feature is not on for this store yet.** | The feature is not on for your plan, workspace, or store. Do the task in Runner, or ask Runner support. |
| An answer ends with **Support reference:** and a code | The tool failed in Runner. Give the code to Runner support. |
