---
title: "List customers"
description: "The customers Invoice Falcon stores: those on one of its documents, edited in the app or added in it. Not every Shopify customer (Invoice Falcon no longer copies them). Alphabetical, with contact details, tax and EORI nu"
url: https://docs.invoicefalcon.com/v3-reference/customers/list-customers/
api: "API v3 reference"
method: GET
path: "/customers"
---

# List customers

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

The customers Invoice Falcon stores: those on one of its documents, edited in the app or added in it. Not every Shopify customer (Invoice Falcon no longer copies them). Alphabetical, with contact details, tax and EORI numbers, tags and default address. `q` searches name, email, phone, tax number, EORI number and tags. Offset pages (`page`, `per_page`). Read-only.

## Query parameters

- `page` (integer): Page number, from 1.
- `per_page` (integer): Rows per page, 1-100 (default 25).
- `q` (string): Free text matched against name, email, phone, tax number, EORI number and tags.

## Returns

- `items` (array of objects, required)
  - `id` (integer): e.g. `34`
  - `shopify_customer_id` (string): e.g. `gid://shopify/Customer/9001`
  - `name` (string): e.g. `Zoe Quinn`
  - `first_name` (string): e.g. `Zoe`
  - `last_name` (string): e.g. `Quinn`
  - `email` (string): e.g. `zoe@example.com`
  - `phone` (string, nullable)
  - `tax_number` (string): e.g. `DE123`
  - `eori_number` (string, nullable)
  - `tags` (array of strings)
  - `edited_in_app` (boolean): e.g. `false`
  - `default_address` (object)
    - `id` (integer): e.g. `588`
    - `kind` (string): e.g. `default_address`
    - `name` (string, nullable)
    - `first_name` (string, nullable)
    - `last_name` (string, nullable)
    - `company` (string): e.g. `Quinn GmbH`
    - `address1` (string): e.g. `1 Main St`
    - `address2` (string, nullable)
    - `city` (string): e.g. `Berlin`
    - `province` (string, nullable)
    - `zip` (string): e.g. `10115`
    - `country` (string): e.g. `Germany`
    - `country_code` (string): e.g. `DE`
    - `phone` (string, nullable)
    - `tax_number` (string, nullable)
    - `eori_number` (string, nullable)
  - `created_at` (string): e.g. `2026-11-10T08:50:31Z`
  - `updated_at` (string): e.g. `2026-11-10T08:50:31Z`
- `page` (object, required): Offset paging of a list (`page`, `per_page` query params).
  - `number` (integer, required): 1-based page number.
  - `size` (integer, required): Rows per page, max 100.
  - `total` (integer, required): Rows across all pages.
  - `total_pages` (integer, required): e.g. `1`

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

## Example request

```sh
curl "https://app.invoicefalcon.com/api/v3/external/customers" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

One page of rows.

```json
{
  "items": [
    {
      "id": 34,
      "shopify_customer_id": "gid://shopify/Customer/9001",
      "name": "Zoe Quinn",
      "first_name": "Zoe",
      "last_name": "Quinn",
      "email": "zoe@example.com",
      "phone": null,
      "tax_number": "DE123",
      "eori_number": null,
      "tags": [
        "vip",
        "wholesale"
      ],
      "edited_in_app": false,
      "default_address": {
        "id": 588,
        "kind": "default_address",
        "name": null,
        "first_name": null,
        "last_name": null,
        "company": "Quinn GmbH",
        "address1": "1 Main St",
        "address2": null,
        "city": "Berlin",
        "province": null,
        "zip": "10115",
        "country": "Germany",
        "country_code": "DE",
        "phone": null,
        "tax_number": null,
        "eori_number": null
      },
      "created_at": "2026-11-10T08:50:31Z",
      "updated_at": "2026-11-10T08:50:31Z"
    }
  ],
  "page": {
    "number": 1,
    "size": 25,
    "total": 1,
    "total_pages": 1
  }
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

