Loyalty API
Write CallUpdateCustomerDetails1
Edit one customer's profile the way the customer would: first and last name, phone, birthday, special dates, and loyalty opt-in or opt-out (enroll in or leave the program). Returns a result per field. Cannot change email or tags.
| Kind | Write API call |
|---|---|
| Method | POST |
| URL | https://app.bubblehouse.com/api/v2023061/<shop>/UpdateCustomerDetails1 |
| Authentication | Customer TokenShop Token |
This function runs in real time, and is meant to give an immediate feedback to the customer. It is for strictly customer-initiated updates happening right now.
Good usage examples: self-service customer portals, customer support portals, data collection forms and popups.
Bad usage examples: batch updates, importing data from other systems. Use UpdateCustomersV call for those.
Note that the function call itself will succeed even if some field updates fail (either due to invalid data or external system failures). You are expected to check the result property for each updated field, and to display validation errors accordingly.
With await_all_effects set to true, the call definitely waits for the opt-in backdate points described under optin_status before it returns. It will wait for more effects of this call over time.
Input
-
A customer to operate upon, when using a shop token.
If you're using a customer token and decide to pass this field (which we do not recommend), it must match the customer from the token.
-
first_namestring | null optionalThe new first name to use.
Set to empty string to remove the value. Omit or set to null to keep the current value.
-
last_namestring | null optionalThe new last name to use.
Set to empty string to remove the value. Omit or set to null to keep the current value.
-
phonestring | null optionalThe new phone number to use.
Set to empty string to remove the value. Omit or set to null to keep the current value.
Updating a phone number is a long-running operation that involves talking to external systems; the call might take a few seconds or even a minute to complete.
Updating a phone number can fail, or can report that the provided number is invalid.
The resulting phone number might not match the input exactly, for example, if the input is missing a country code, the resulting phone number might have a country code added.
-
marketstring optionalMarket key for determining the phone number's country code.
When
phoneis provided without a country code, the specified market's default phone country code is used.If this field is omitted, empty, or contains an unknown market key, the store's default market is used.
This field only affects phone number updates and is ignored for Shopify stores.
-
The new birthday to use (YYYY-MM-DD format).
Set to an empty string (or 0-0-0) to remove the value. Omit or set to null to keep the current value.
Use 0-MM-DD format if the year is unknown.
Updating a birthday can report an invalid value if the day is invalid. Shop-specific rules might affect which exact dates are acceptable.
-
The complete list of special dates to keep. Add-date points are limited by the merchant’s configured allowance; additional dates can still be saved.
Include bhid for existing dates; dates left out of the list are removed. Omit the field or send null to leave it unchanged; send [] to remove all dates.
If any date is invalid, the list remains unchanged.
Editing or removing dates does not reset the add-date reward allowance.
Updating a date replaces its person_name and note entirely: resending a date without these fields clears them. The image_choice field is optional and may be omitted.
-
optin_statusboolean | null optionalLoyalty opt-in. true opts in, false opts out.
Omit this field or set it to null to leave the stored status unchanged.
This call cannot set the status back to unknown.
falseis an explicit opt-out. An opted-out customer is not a member even when the store does not require loyalty opt-in.This is loyalty opt-in, not email or SMS marketing consent.
Read the stored value from CustomerDetails1 as
optin(true,false, ornull).When the store backdates points on opt-in, opting in awards points for recent orders placed before the customer joined. Normally these points arrive in the background shortly after the call. With
await_all_effectsset to true, the call definitely waits for this award. -
await_all_effectsboolean optionalTrue to return only after all effects of this change are fully processed.
Normally, some effects of a change are processed in the background after the call returns, so data you read right after the call might not include them yet. Pass
"await_all_effects": trueto wait until all effects caused by this change are fully processed before the call returns.The call's description names the effects it definitely waits for today. More effects will be awaited over time, so the call may also wait for other related processing before it returns.
Waiting makes the call slower. If processing an effect fails, the call still reports the change itself as usual, and the effect may still complete in the background.
Output
-
okboolean requiredTrue if all updates have succeeded, false otherwise.
This is a convenience property, a result of ANDing together the
okproperties of each field's result. -
The result of updating the first name.
This update always succeeds, so
okis always true. The only relevant field isoutcome, indicating if the field has been updated or remained unchanged. -
The result of updating the last name.
This update always succeeds, so
okis always true. The only relevant field isoutcome, indicating if the field has been updated or remained unchanged. -
The result of updating the birthday.
All outcomes are possible, except
failed. -
The result of updating the phone number.
All outcomes are possible.
-
The result of updating special dates, including any points credited.
-
The result of updating loyalty opt-in.
okis always true.outcomeisunchangedwhen the customer already had that status, andupdatedwhen it changed. This result does not include points. Opt-in backdate points, when the store awards them, arrive later, unlessawait_all_effectsis true. Rewards granted in this same request because membership changed are not inpts.
API-wide Errors
| Status | Error | Reason & Examples |
|---|---|---|
| 404 | no_customers_match_customer_identity |
The customer identity ('customer' input parameter) does not match a known customer. |
| 404 | empty_customer_identity |
All fields of the customer identity ('customer' input parameter) have been empty when using a shop token. You need to either specify a non-empty value for one of the customer identity fields, or use a customer token. |
| 404 | customer_identity_partially_mismatches_matched_customer |
A customer has been matched by one of the fields of the customer identity ('customer' input parameter), but some non-empty fields do not match Bubblehouse data on that customer. |
| 400 | missing_customer_identity |
The customer identity ('customer' input parameter) has not been specified when using a shop token. You need to either specify a non-empty value for one of the customer identity fields, or use a customer token. |
| 403 | customer_identity_does_not_match_token |
API call is using a customer token, but the customer identity in API params does not match the customer from the token. |
Global Errors
| Status | Error | Reason & Examples |
|---|---|---|
| 429 | rate_limit_exceeded |
Your usage is over the rate limit. Ensure that you're not making duplicate calls, and contact our team for a rate limit increase. For example: |
| 400 | invalid_global_api_version |
The global API version you are trying to use has never existed. |
| 401 | invalid_token |
The provided authentication token is invalid or has expired. For example: |
| 400 | inaccessible_global_api_version |
The global API version you are trying to use is not enabled on your account. |
| 400 | obsolete_global_api_version |
The global API version you are trying to use is no longer supported. |