Customers

Manage store customers

Customers represent the people who visit your store and participate in your loyalty program. Each customer requires a first_name and at least one of email or phone. Both email and phone are unique within a store. Customers can be enrolled in loyalty cards and have their stamp counts managed through this API.

External references and metadata

Every customer can carry two kinds of integration-friendly data so you can match them up with records in other systems (Square, Shopify, Mailchimp, your own POS, etc.) without depending on email or phone:

external_references: a list of source/external_id pairs. source is a free-form lowercase slug that identifies the foreign system (e.g. square, shopify, mailchimp, hubspot, or anything custom like my_pos). Each source/external_id pair is unique per store, indexed for fast lookups, and can be used to find or upsert a customer.

metadata: a free-form JSON object for any other per-customer data you want to attach (preferred drink, segment tags, “last seen at counter”, etc.). Not indexed; not unique; merged on update.

Use ‘GET /customers?source=…&external_id=…` to look up a customer by an external reference.

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

show

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

Show a customer

Returns detailed information about a single customer, including all of their enrolled loyalty cards with stamp progress and wallet pass URLs (apple_wallet_url and google_wallet_url) for each card. Also includes metadata and external_references so you can sync state with external systems.

Parameters

Name	Type	Required	Description
`account_id`	Must be a number.	Required	Store (account) ID
`id`	Must be a number.	Required	Customer ID

Error Codes

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

create

POST /api/v1/accounts/:account_id/customers

Create a customer

Creates a new customer for the store. Requires first_name and at least one of email or phone. Optionally enroll the customer in a loyalty card by passing card_id, and trigger delivery of card links (email/SMS) by passing send_card_links. When a card with initial stamps is assigned, those stamps are automatically applied as a welcome bonus.

Pass metadata to attach arbitrary key/value data, and external_references to link the customer to records in other systems (e.g. Square, Shopify). External references are upserted by ‘(source, external_id)` so this endpoint is safe to call with the same references twice.

Parameters

Name	Type	Required	Description
`account_id`	Must be a number.	Required	Store (account) ID
`customer`	Must be a Hash	Required	Customer attributes
`customer[first_name]`	Must be a String	Required	Customer’s first name
`customer[last_name]`	Must be a String	Optional	Customer’s last name
`customer[email]`	Must be a String	Optional	Customer’s email address (unique per store; required if phone is blank)
`customer[phone]`	Must be a String	Optional	Customer’s phone number (unique per store; required if email is blank)
`customer[birthday]`	Must be a String	Optional	Customer’s birthday (YYYY-MM-DD)
`customer[metadata]`	Must be a Hash	Optional	Free-form JSON object of additional per-customer attributes
`customer[external_references]`	Must be an Array of nested elements	Optional	Array of ‘{source, external_id, metadata}` objects linking this customer to records in external systems
`customer[external_references][source]`	Must be a String	Required	Lowercase slug for the external system (e.g. `square`, `shopify`, `mailchimp`)
`customer[external_references][external_id]`	Must be a String	Required	External system’s identifier for this customer
`customer[external_references][metadata]`	Must be a Hash	Optional	Optional per-reference metadata
`card_id`	Must be a number.	Optional	Loyalty card ID to auto-enroll the customer in
`send_card_links`	Must be one of: `true`, `false`, `1`, `0`.	Optional	When true, sends the card links to the customer via email/SMS after enrollment. Note: even without this flag, the response includes `apple_wallet_url` and `google_wallet_url` in each customer card object so you can deliver them yourself.

Error Codes

Code	Description
`401`	Unauthorized – invalid or missing API token
`404`	Store not found
`422`	Validation failed – check `errors` for details

update

PATCH /api/v1/accounts/:account_id/customers/:id

Update a customer

Updates an existing customer’s details. To add stamps or redeem rewards, use the customer cards endpoints instead.

metadata is shallow-merged into the existing metadata. external_references are upserted by ‘(source, external_id)` - to remove a reference, omit it from subsequent calls and use a separate DELETE workflow (not yet exposed via API; manage in dashboard for now).

Parameters

Name	Type	Required	Description
`account_id`	Must be a number.	Required	Store (account) ID
`id`	Must be a number.	Required	Customer ID
`customer`	Must be a Hash	Required	Customer attributes to update
`customer[first_name]`	Must be a String	Optional	Customer’s first name
`customer[last_name]`	Must be a String	Optional	Customer’s last name
`customer[email]`	Must be a String	Optional	Customer’s email address (unique per store)
`customer[phone]`	Must be a String	Optional	Customer’s phone number (unique per store)
`customer[birthday]`	Must be a String	Optional	Customer’s birthday (YYYY-MM-DD)
`customer[metadata]`	Must be a Hash	Optional	Shallow-merged into existing metadata
`customer[external_references]`	Must be an Array of nested elements	Optional	Array of ‘{source, external_id, metadata}` objects to upsert
`customer[external_references][source]`	Must be a String	Required	Lowercase slug for the external system
`customer[external_references][external_id]`	Must be a String	Required	External system’s identifier for this customer
`customer[external_references][metadata]`	Must be a Hash	Optional	Optional per-reference metadata

Error Codes

Code	Description
`401`	Unauthorized – invalid or missing API token
`404`	Store or customer not found
`422`	Validation failed – check `errors` for details