Guides

Track orders

Find the shopper's orders and shipments with search_orders, and read their status, tracking and totals without reading more into them than they say.

View as Markdown

search_orders searches the order history Shop keeps for the signed-in shopper. That includes orders from Shopify stores, and purchases and shipments that Shop found in an email inbox the shopper connected to it. The tool needs sign-in.

Search orders

Every argument is optional. With none, it returns the most recent orders:

JSON

{ "query": "running shoes", "activity": "active", "pagination": { "limit": 10 } }

Argument	Value
`query`	Words to match against the merchant, the items or the order number, up to 200 characters
`activity`	`active` for orders that haven’t been delivered, `past` for delivered or closed ones, or `all`, the default
`date_from`, `date_to`	The first and last order dates to include, as `YYYY-MM-DD`
`pagination`	`limit` takes 1 to 25 and defaults to 10. To get the next page, pass back the returned `cursor` unchanged.

Search with what the shopper tells you, such as a store or an item. They don’t need to find an order number first.

From the CLI:

Shell

shop order search 'running shoes' --activity active --limit 10

Fetch only the pages you need to answer the question. Shop limits how often each shopper can search through each client, currently to 10 searches a minute, 40 an hour, 100 a day and 200 a week. If a search comes back rate_limited, don’t repeat it in a loop.

Read the results

The result has orders, shipments and pagination. This order is shortened, with made-up values:

JSON

{
  "orders": [
    {
      "id": "<order id>",
      "label": "#2042",
      "placed_at": "2026-09-20T12:00:00Z",
      "source": "shopify",
      "seller": { "name": "Example Running Co.", "domain": "running.example" },
      "status": "delivered",
      "currency": "USD",
      "totals": [{ "type": "total", "amount": 12000 }],
      "line_items": [
        {
          "id": "<line id>",
          "item": { "title": "Trail shoes", "price": 12000 },
          "quantity": { "original": 1, "total": 1, "fulfilled": 1 },
          "status": "fulfilled"
        }
      ],
      "fulfillment": {
        "events": [
          {
            "type": "delivered",
            "status": "DELIVERED",
            "occurred_at": "2026-09-22T12:00:00Z",
            "carrier": "Example Post",
            "tracking_number": "<tracking number>",
            "tracking_url": "https://carrier.example/track/<tracking number>"
          }
        ]
      },
      "permalink_url": "<order page URL>"
    }
  ],
  "shipments": [],
  "pagination": { "has_next_page": false }
}

Field	What it holds
`label`	The order number the merchant shows, such as `#2042`
`source`	`shopify` for an order from a Shopify store, or `email` for a purchase Shop found in the shopper’s inbox
`status`, `delivery_status`, `payment_status`	Shop’s statuses for the order, as Shop reports them. Orders found by email have no `payment_status`.
`line_items`	Each item, with its unit `price` and a `quantity` made of `original`, the count at checkout, `total`, the count still active after returns or cancellations, and `fulfilled`
`totals`	The order total, and a subtotal when Shop has one
`fulfillment.events`	The latest state of each shipment, with its carrier and tracking
`fulfillment.expectations`	Delivery estimates
`adjustments`	Refunds, returns and other changes after the order was placed
`permalink_url`	The shopper’s page for the order
`return_url`	The merchant’s page for starting a return, when it has one

shipments lists parcels Shop is tracking that don’t belong to an order it knows about, usually found by email. Each has a label, seller_name, state and a delivery estimate.

Amounts

Amounts are integers in minor units of the order’s currency. A currency of XXX means Shop doesn’t know it. Those amounts still count hundredths, so show 1250 as 12.50 with no currency symbol. Never add amounts in different or unknown currencies into one total.

Shipping status

Each event in fulfillment.events is one shipment’s latest known state, not its full history. Its status is Shop’s own delivery status, such as LABEL_CREATED or DELIVERED. type maps it to a broader UCP value such as in_transit or delivered, and several statuses share one type, so use status and the carrier’s tracking for detail.

A LABEL_CREATED status only says a shipping label exists. A line marked fulfilled hasn’t necessarily shipped either. Neither one means the parcel is on its way or has arrived.

Missing fields

A missing field means Shop doesn’t know, not that the order is unpaid or undelivered. Orders found by email can lack prices, tracking and links, and lines without a price come back in unpriced_line_items. Even an order from a Shopify store can lack permalink_url. Don’t build a link yourself, or show an order ID in its place.

If quantity.original is missing, quantity.total still gives the count that’s active now, but not how many the shopper bought.

Buy something again

Don’t take an ID from an order line and check out with it. Find the item in the catalog with search_catalog or lookup_catalog, check its current options, stock and price with the shopper, then create a checkout as usual.

What isn’t supported

Shop MCP can’t look up an order at the merchant, start a return or cancel an order. When an order has a return_url or permalink_url, give it to the shopper for those.