> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Orders

> Find orders carrying Retail's reference. How Retail learns what actually happened.

# Search Orders

Finds every order in your system that carries Retail's `reference`. This is how Retail learns the truth about an order, and it is the endpoint that keeps a lost reply from becoming a double purchase.

Retail calls it:

* after a [Place order](/vendor-api/place-order) call that failed or timed out, before deciding whether to submit again;
* after a [webhook](/vendor-api/webhooks) that names the order;
* on an hourly sweep of orders that have not been accepted yet.

<Warning>
  **Distinguish "searched and found nothing" from "could not search".** `{ "orders": [] }` tells Retail no order exists, which allows it to submit again. If your search failed or timed out, return an error (`502`), never an empty list. Reporting a failed search as empty is how a ticket gets bought twice.
</Warning>

## Query Parameters

<ParamField query="vendorKey" type="string" required>
  Your supplier identifier.
</ParamField>

<ParamField query="reference" type="string" required>
  Retail's reference, as sent on [Place order](/vendor-api/place-order).
</ParamField>

## Response

<ResponseField name="orders" type="array" required>
  Every order carrying this reference, normally zero or one. Each has the same shape as the [Place order](/vendor-api/place-order#response) response: `vendorOrderId`, `state`, `totalCost`, `currency` and optional `raw`.

  Return **all** matches, including cancelled ones. More than one live order for one reference means a possible double purchase, and Retail flags it for a person to review.
</ResponseField>

Report `state` from your system's current record, not from a cache. When you cannot tell, answer `unknown`: Retail leaves its own record unchanged, where a wrong `rejected` strands a buyer who has paid and a wrong `accepted` sells a ticket nobody has.

<Note>
  Search on a field where your system actually stores the reference. Some systems accept a reference on create but return it empty when the order is read back, and only find it through a search filter. Verify on your sandbox that a newly placed order is found here.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -H "X-API-Key: $GOMRY_RETAIL_API_KEY" \
    "https://integration.example.com/api/vendor/v1/orders?vendorKey=acme&reference=8b1f3c5e2a9d4f7081c6e2b4a0d9f3e1"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "orders": [
      {
        "vendorOrderId": "ord_551204",
        "state": "accepted",
        "totalCost": 192.0,
        "currency": "USD"
      }
    ]
  }
  ```

  ```json 200 (no order) theme={null}
  { "orders": [] }
  ```

  ```json 502 theme={null}
  {
    "error": {
      "code": "integration_error",
      "message": "Order search failed upstream: 503 Service Unavailable"
    }
  }
  ```
</ResponseExample>