Skip to content

List customers

GET/customers

Costs 1 rate-limit point · Rate limits

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.

Also searched aslist customersfind customersearch customers by emailcustomers with a VAT numberwho is this customercustomer list

Query parameters

  • pageinteger

    Page number, from 1.

  • per_pageinteger

    Rows per page, 1-100 (default 25).

  • qstring

    Free text matched against name, email, phone, tax number, EORI number and tags.

Returns

  • itemsarray of objects
    Show 14 child attributesHide child attributes
    • idinteger
      Example: 34
    • shopify_customer_idstring
      Example: gid://shopify/Customer/9001
    • namestring
      Example: Zoe Quinn
    • first_namestring
      Example: Zoe
    • last_namestring
      Example: Quinn
    • emailstring
      Example: zoe@example.com
    • phonestring, nullable
    • tax_numberstring
      Example: DE123
    • eori_numberstring, nullable
    • tagsarray of strings
    • edited_in_appboolean
      Example: false
    • default_addressobject
      Show 16 child attributesHide child attributes
      • idinteger
        Example: 588
      • kindstring
        Example: default_address
      • namestring, nullable
      • first_namestring, nullable
      • last_namestring, nullable
      • companystring
        Example: Quinn GmbH
      • address1string
        Example: 1 Main St
      • address2string, nullable
      • citystring
        Example: Berlin
      • provincestring, nullable
      • zipstring
        Example: 10115
      • countrystring
        Example: Germany
      • country_codestring
        Example: DE
      • phonestring, nullable
      • tax_numberstring, nullable
      • eori_numberstring, nullable
    • created_atstring
      Example: 2026-11-10T08:50:31Z
    • updated_atstring
      Example: 2026-11-10T08:50:31Z
  • pageobject

    Offset paging of a list (page, per_page query params).

    Show 4 child attributesHide child attributes
    • numberinteger

      1-based page number.

    • sizeinteger

      Rows per page, max 100.

    • totalinteger

      Rows across all pages.

    • total_pagesinteger
      Example: 1

Errors

401

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

403

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

422

The request failed validation. Nothing was saved.

429

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

Every error has the same shape: see Errors.

GET/customers
curl "https://app.invoicefalcon.com/api/v3/external/customers" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
Response
{
  "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
  }
}