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

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

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

Returns

Code: 200

A customer, including their enrolled loyalty cards

Name Type Required Description
id Must be a Integer Required

Unique customer ID
account_id Must be a Integer Required

Parent store ID
first_name Must be a String Required

First name
last_name Must be a String Required

Last name

(nil allowed)
email Must be a String Required

Email address, unique per store

(nil allowed)
phone Must be a String Required

Phone number, unique per store

(nil allowed)
birthday Must be a String Required

Birthday as YYYY-MM-DD

(nil allowed)
stamp_count Must be a Integer Required

Total stamps across every card
metadata Must be a Hash Required

Free form per customer data

(nil allowed)
external_references Must be an Array of nested elements Required

Links to records in other systems
external_references[source] Must be a String Required

External system slug, for example ‘square’
external_references[external_id] Must be a String Required

Identifier of the record in that system
external_references[metadata] Must be a Hash Required

Free form data stored against this reference

(nil allowed)
customer_cards Must be an Array of nested elements Required

Cards this customer is enrolled on
customer_cards[id] Must be a Integer Required

Customer card ID
customer_cards[card_id] Must be a Integer Required

Loyalty card template ID
customer_cards[card_name] Must be a String Required

Name of the loyalty card
customer_cards[stamps_count] Must be a Integer Required

Stamps collected so far
customer_cards[status] Must be a String Required

Current state of the customer card
customer_cards[uuid] Must be a String Required

Public identifier used in wallet pass URLs
customer_cards[apple_wallet_url] Must be a String Required

Link to add or view the pass in Apple Wallet
customer_cards[google_wallet_url] Must be a String Required

Link to add or view the pass in Google Wallet
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

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

Returns

Code: 201

The newly created customer. Includes a customer_card object when card_id was supplied.

Name Type Required Description
id Must be a Integer Required

Unique customer ID
account_id Must be a Integer Required

Parent store ID
first_name Must be a String Required

First name
last_name Must be a String Required

Last name

(nil allowed)
email Must be a String Required

Email address, unique per store

(nil allowed)
phone Must be a String Required

Phone number, unique per store

(nil allowed)
birthday Must be a String Required

Birthday as YYYY-MM-DD

(nil allowed)
stamp_count Must be a Integer Required

Total stamps across every card
metadata Must be a Hash Required

Free form per customer data

(nil allowed)
external_references Must be an Array of nested elements Required

Links to records in other systems
external_references[source] Must be a String Required

External system slug, for example ‘square’
external_references[external_id] Must be a String Required

Identifier of the record in that system
external_references[metadata] Must be a Hash Required

Free form data stored against this reference

(nil allowed)
customer_cards Must be an Array of nested elements Required

Cards this customer is enrolled on
customer_cards[id] Must be a Integer Required

Customer card ID
customer_cards[card_id] Must be a Integer Required

Loyalty card template ID
customer_cards[card_name] Must be a String Required

Name of the loyalty card
customer_cards[stamps_count] Must be a Integer Required

Stamps collected so far
customer_cards[status] Must be a String Required

Current state of the customer card
customer_cards[uuid] Must be a String Required

Public identifier used in wallet pass URLs
customer_cards[apple_wallet_url] Must be a String Required

Link to add or view the pass in Apple Wallet
customer_cards[google_wallet_url] Must be a String Required

Link to add or view the pass in Google Wallet
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

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

Returns

Code: 200

The updated customer

Name Type Required Description
id Must be a Integer Required

Unique customer ID
account_id Must be a Integer Required

Parent store ID
first_name Must be a String Required

First name
last_name Must be a String Required

Last name

(nil allowed)
email Must be a String Required

Email address, unique per store

(nil allowed)
phone Must be a String Required

Phone number, unique per store

(nil allowed)
birthday Must be a String Required

Birthday as YYYY-MM-DD

(nil allowed)
stamp_count Must be a Integer Required

Total stamps across every card
metadata Must be a Hash Required

Free form per customer data

(nil allowed)
external_references Must be an Array of nested elements Required

Links to records in other systems
external_references[source] Must be a String Required

External system slug, for example ‘square’
external_references[external_id] Must be a String Required

Identifier of the record in that system
external_references[metadata] Must be a Hash Required

Free form data stored against this reference

(nil allowed)
customer_cards Must be an Array of nested elements Required

Cards this customer is enrolled on
customer_cards[id] Must be a Integer Required

Customer card ID
customer_cards[card_id] Must be a Integer Required

Loyalty card template ID
customer_cards[card_name] Must be a String Required

Name of the loyalty card
customer_cards[stamps_count] Must be a Integer Required

Stamps collected so far
customer_cards[status] Must be a String Required

Current state of the customer card
customer_cards[uuid] Must be a String Required

Public identifier used in wallet pass URLs
customer_cards[apple_wallet_url] Must be a String Required

Link to add or view the pass in Apple Wallet
customer_cards[google_wallet_url] Must be a String Required

Link to add or view the pass in Google Wallet
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp