---
title: "List customers"
description: "Retrieve a paginated list of customers. Supports search by name, email, or tax number."
url: https://docs.invoicefalcon.com/api/customers/list-customers/
api: "API v1 reference"
method: GET
path: "/customers"
---

# List customers

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

Retrieve a paginated list of customers. Supports search by name, email, or tax number.

## Query parameters

- `search` (string): Search by name, email, or tax number.
- `page` (integer): Page number.
- `per_page` (integer): Items per page (max 250).

## Returns

- `customers` (array of objects)
  - `id` (integer): e.g. `9177`
  - `email` (string): e.g. `jane.doe@example.com`
  - `first_name` (string): e.g. `Jane`
  - `last_name` (string): e.g. `Doe`
  - `phone` (string): e.g. `+1 555 010 0199`
  - `tax_number` (string): VAT/GST/tax identification number.
  - `eori_number` (string): EU EORI number.
  - `tags` (string): e.g. `wholesale, newsletter`
  - `shopify_customer_id` (integer): e.g. `7001234567`
  - `created_at` (string): e.g. `2025-09-21T16:45:00Z`
  - `updated_at` (string): e.g. `2026-01-15T09:30:00Z`
- `meta` (object)
  - `total` (integer): e.g. `2`
  - `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/customers" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

A paginated list of customers.

```json
{
  "customers": [
    {
      "id": 9177,
      "email": "jane.doe@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+1 555 010 0199",
      "tax_number": "US-12-3456789",
      "eori_number": null,
      "tags": "wholesale, newsletter",
      "shopify_customer_id": 7001234567,
      "created_at": "2025-09-21T16:45:00Z",
      "updated_at": "2026-01-15T09:30:00Z"
    },
    {
      "id": 9203,
      "email": "sam.rivera@example.com",
      "first_name": "Sam",
      "last_name": "Rivera",
      "phone": null,
      "tax_number": null,
      "eori_number": null,
      "tags": "",
      "shopify_customer_id": 7001234999,
      "created_at": "2025-10-02T11:20:00Z",
      "updated_at": "2025-10-02T11:20:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "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"
}
```

## 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)."
}
```

