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