---
title: "Search invoices"
description: "Search invoices by customer name, email, invoice number, order name, or country."
url: https://docs.invoicefalcon.com/api/invoices/search-invoices/
api: "API v1 reference"
method: GET
path: "/invoices/search"
---

# Search invoices

`GET https://app.invoicefalcon.com/api/v1/external/invoices/search`

Search invoices by customer name, email, invoice number, order name, or country.

## Query parameters

- `q` (string, required): Search query string.
- `page` (integer): Page number.
- `per_page` (integer): Items per page (max 250).

## Returns

- `invoices` (array of objects)
  - `id` (integer): e.g. `48213`
  - `slug` (string): Unique identifier for API calls.
  - `number` (string): Display number (e.g. INV-001).
  - `invoice_type` (string): e.g. `invoice` One of: `invoice`, `quote`, `pro_forma`, `shopify_order`.
  - `total_price` (string): Decimal string.
  - `currency` (string): ISO 4217 code.
  - `financial_status` (string): e.g. `paid`
  - `order_name` (string): Shopify order name (e.g. #1042).
  - `customer_name` (string): e.g. `Jane Doe`
  - `customer_email` (string): e.g. `jane.doe@example.com`
  - `created_at` (string): e.g. `2026-01-15T09:31:12Z`
  - `updated_at` (string): e.g. `2026-01-15T09:31:40Z`
- `meta` (object)
  - `total` (integer): e.g. `1`
  - `page` (integer): e.g. `1`
  - `per_page` (integer): e.g. `25`
  - `total_pages` (integer): e.g. `1`

Rate limit: this call costs 1 point ([rate limits](https://docs.invoicefalcon.com/docs/rate-limiting/)).

## Example request

```sh
curl "https://app.invoicefalcon.com/api/v1/external/invoices/search?q=Q" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

Matching invoices.

```json
{
  "invoices": [
    {
      "id": 48213,
      "slug": "k7xq2m9d4r",
      "number": "INV-1042",
      "invoice_type": "invoice",
      "total_price": "100.94",
      "currency": "USD",
      "financial_status": "paid",
      "order_name": "#1042",
      "customer_name": "Jane Doe",
      "customer_email": "jane.doe@example.com",
      "created_at": "2026-01-15T09:31:12Z",
      "updated_at": "2026-01-15T09:31:40Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 25,
    "total_pages": 1
  }
}
```

## 401

Missing or invalid API key.

```json
{
  "error": "Invalid API key"
}
```

## 403

The store is not on a paid plan. API access requires a paid Invoice Falcon plan.

```json
{
  "error": "REST API access requires a paid plan"
}
```

## 422

Request could not be processed.

```json
{
  "error": "param is missing or the value is empty: customer",
  "errors": {}
}
```

## 429

Rate limit exceeded. Check `X-RateLimit-Reset` header.

```json
{
  "error": "Rate limit exceeded",
  "retry_after": 30,
  "message": "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 30 second(s)."
}
```

