update
/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 |