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