List customers
/customersCosts 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
pageintegerPage number, from 1.
per_pageintegerRows per page, 1-100 (default 25).
qstringFree text matched against name, email, phone, tax number, EORI number and tags.
Returns
itemsarray of objectsShow 14 child attributesHide child attributes
idintegerExample:34shopify_customer_idstringExample:gid://shopify/Customer/9001namestringExample:Zoe Quinnfirst_namestringExample:Zoelast_namestringExample:QuinnemailstringExample:zoe@example.comphonestring, nullabletax_numberstringExample:DE123eori_numberstring, nullabletagsarray of stringsedited_in_appbooleanExample:falsedefault_addressobjectShow 16 child attributesHide child attributes
idintegerExample:588kindstringExample:default_addressnamestring, nullablefirst_namestring, nullablelast_namestring, nullablecompanystringExample:Quinn GmbHaddress1stringExample:1 Main Staddress2string, nullablecitystringExample:Berlinprovincestring, nullablezipstringExample:10115countrystringExample:Germanycountry_codestringExample:DEphonestring, nullabletax_numberstring, nullableeori_numberstring, nullable
created_atstringExample:2026-11-10T08:50:31Zupdated_atstringExample:2026-11-10T08:50:31Z
pageobjectOffset paging of a list (
page,per_pagequery params).Show 4 child attributesHide child attributes
numberinteger1-based page number.
sizeintegerRows per page, max 100.
totalintegerRows across all pages.
total_pagesintegerExample:1
Errors
Missing or unknown X-Auth-Token, or the shop uninstalled the app.
v3_required: the shop still runs the previous dashboard. paid_plan_required: API access needs a paid plan.
The request failed validation. Nothing was saved.
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.
curl "https://app.invoicefalcon.com/api/v3/external/customers" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY"const res = await fetch("https://app.invoicefalcon.com/api/v3/external/customers", {
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.invoicefalcon.com/api/v3/external/customers",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/customers")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"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
}
}{
"errors": [
"Invalid API key"
],
"code": "unauthorized"
}{
"errors": [
"API access requires a paid plan"
],
"code": "paid_plan_required"
}{
"errors": [
"id is missing"
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited"
}