---
title: "Find orders by reference or metadata"
description: "Searches the account's orders by `reference` or `metadata`, and can limit the fields returned."
canonical: "https://docs.printags.com/find-orders-by-reference-or-metadata/"
last_updated: "2026-11-16"
---

# Find orders by reference or metadata

`GET /v2/accounts/{accountId}/orders/find`

Searches the account's orders by `reference` or `metadata`, and can limit the fields returned. The response is not paginated. A test key (`sk_test_`) only finds test orders, a live key only real orders.

## Authentication

An API key as a Bearer token: `Authorization: Bearer <key>`. A `sk_test_` key creates and sees test orders only. Keys and test mode: [overview](/).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | string | yes | Unique identifier of the account |
| `metadata` | query | string | no | Filter orders based on metadata |
| `reference` | query | string | no | Filter orders based on reference |
| `fields` | query | string | no | Get only wanted fields |

## Responses

| Status | Description |
| --- | --- |
| 200 | Successfully retrieved orders |
| 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) |
| 403 | The API key is inactive or revoked (`INACTIVE_API_KEY`), or targets another account (`ACCOUNT_ACCESS_DENIED`, refused once the account guard is enforced); with an OAuth access token: a token of scope `mcp` (`INSUFFICIENT_SCOPE`), a path naming another account or a person no longer a member of it (`ACCOUNT_ACCESS_DENIED`), a real token on the sandbox host (`SANDBOX_REQUIRES_TEST_KEY`) |
| 429 |  |
| 500 | Server error |

### 200 response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | no |  |
| `orders` | array of [Order](/schemas/order/) | no |  |

```json
{
  "success": true,
  "orders": [
    {
      "id": "987e6543-e21a-11d4-a789-0242ac120002",
      "reference": "Order-JeanDupont-2024",
      "accountId": "123e4567-e89b-12d3-a456-426614174000",
      "status": "created",
      "statusHistory": [
        {}
      ],
      "units": [],
      "items": [],
      "shipments": [],
      "total": 50.99,
      "files": [
        {}
      ]
    }
  ]
}
```

## Example

```bash
curl -X GET "https://api.printags.com/v2/accounts/123e4567-e89b-12d3-a456-426614174000/orders/find" \
  -H "Authorization: Bearer $PRINTAGS_API_KEY"
```
