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.

index

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

List customers

Returns a paginated list of customers for the store. Use the search parameter to filter by name, email, phone, or card code (barcode). The response includes pagination metadata.

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, or card code (barcode)
`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.

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.

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)
`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.

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)

Error Codes

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