index

GET /api/v1/accounts/:account_id/customers

List or look up customers

Returns a paginated list of customers for the store. Use the search parameter to filter by name, email, phone, card code (barcode), or external reference ID. Alternatively, pass source AND external_id together to perform an exact lookup by an external reference - the response will contain at most one customer.

Parameters

Name	Type	Required	Description
`account_id`	Must be a number.	Required	Store (account) ID
`search`	Must be a String	Optional	Search query to filter customers by name, email, phone, card code (barcode), or external reference ID
`source`	Must be a String	Optional	External system slug (e.g. `square`, `shopify`). When combined with `external_id`, performs an exact lookup.
`external_id`	Must be a String	Optional	External system’s identifier for the customer. Must be combined with `source`.
`page`	Must be a number.	Optional	Page number (defaults to 1)
`items`	Must be a number.	Optional	Number of items per page

Error Codes

Code	Description
`401`	Unauthorized – invalid or missing API token
`404`	Store not found

Returns

Code: 200

A page of customers, with pagination metadata

Name	Type	Required	Description
`customers`	Must be an Array of nested elements	Required	The customers on this page
`customers[id]`	Must be a Integer	Required	Unique customer ID
`customers[first_name]`	Must be a String	Required	First name
`customers[last_name]`	Must be a String	Required	Last name (nil allowed)
`customers[email]`	Must be a String	Required	Email address, unique per store (nil allowed)
`customers[phone]`	Must be a String	Required	Phone number, unique per store (nil allowed)
`customers[birthday]`	Must be a String	Required	Birthday as YYYY-MM-DD (nil allowed)
`customers[stamp_count]`	Must be a Integer	Required	Total stamps across every card
`customers[customer_cards_count]`	Must be a Integer	Required	Number of cards this customer is enrolled on
`customers[metadata]`	Must be a Hash	Required	Free form per customer data (nil allowed)
`customers[external_references]`	Must be an Array of nested elements	Required	Links to records in other systems
`customers[external_references][source]`	Must be a String	Required	External system slug, for example ‘square’
`customers[external_references][external_id]`	Must be a String	Required	Identifier of the record in that system
`customers[external_references][metadata]`	Must be a Hash	Required	Free form data stored against this reference (nil allowed)
`customers[created_at]`	Must be a String	Required	ISO 8601 creation timestamp
`customers[updated_at]`	Must be a String	Required	ISO 8601 last-update timestamp
`pagination`	Must be a Hash	Required	Page position and totals
`pagination[page]`	Must be a Integer	Required	Current page number
`pagination[items]`	Must be a Integer	Required	Customers per page
`pagination[count]`	Must be a Integer	Required	Total customers matching the query
`pagination[pages]`	Must be a Integer	Required	Total number of pages