Loyalty API

Write Call

UpdateCustomerDetails1

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
You have a choice of making this call from your server using a shop token and specifying a customer ID, or making this call from a web browser/app using a customer token you have generated on the server.

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

  • customer CustomerIdentity1 required if using a shop token

    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_name string | null optional

    The new first name to use.

    Set to empty string to remove the value. Omit or set to null to keep the current value.

  • last_name string | null optional

    The new last name to use.

    Set to empty string to remove the value. Omit or set to null to keep the current value.

  • phone string | null optional

    The 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.

  • market string optional

    Market key for determining the phone number's country code.

    When phone is 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.

  • birthday date | null optional

    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.

  • special_dates array of SpecialDate1 | null optional

    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_status boolean | null optional

    Loyalty 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. false is 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, or null).

    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_effects set to true, the call definitely waits for this award.

  • await_all_effects boolean optional

    True 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": true to 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

  • ok boolean required

    True if all updates have succeeded, false otherwise.

    This is a convenience property, a result of ANDing together the ok properties of each field's result.

  • first_name UpdateResult1 required if corresponding input field provided

    The result of updating the first name.

    This update always succeeds, so ok is always true. The only relevant field is outcome, indicating if the field has been updated or remained unchanged.

  • last_name UpdateResult1 required if corresponding input field provided

    The result of updating the last name.

    This update always succeeds, so ok is always true. The only relevant field is outcome, indicating if the field has been updated or remained unchanged.

  • birthday UpdateResult1 required if corresponding input field provided

    The result of updating the birthday.

    All outcomes are possible, except failed.

  • phone UpdateResult1 required if corresponding input field provided

    The result of updating the phone number.

    All outcomes are possible.

  • special_dates UpdateResult1 required if non-null corresponding input field provided

    The result of updating special dates, including any points credited.

  • optin_status UpdateResult1 required if corresponding input field provided

    The result of updating loyalty opt-in.

    ok is always true. outcome is unchanged when the customer already had that status, and updated when it changed. This result does not include points. Opt-in backdate points, when the store awards them, arrive later, unless await_all_effects is true. Rewards granted in this same request because membership changed are not in pts.

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: You are over the read limit per second for this customer

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: The token has expired

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.

Previous
Unredeem1