Method: accounts.loyaltyCustomers.manage

Manages (inserts, updates, or removes) a customer's loyalty tier information.

This method serves as a single interface for all changes to a customer's loyalty status. The specific action (insert, update, or remove) is determined by the current state of the merchant-to-customer association and the loyaltyTier value provided in the request.

Operation Logic:

  • Upsert (Insert/Update): Providing any valid tier other than NON_MEMBER will associate the customer with that tier. If an association already exists, it will be updated; otherwise, a new one will be created.
  • Removal: Setting loyaltyTier to NON_MEMBER will remove any existing loyalty association for the customer.

Privacy Note: To protect user privacy, this method consistently returns a 200 OK status with a default LoyaltyCustomer response if the customer's identifier cannot be matched to a Google account or if the user has not opted into loyalty personalization.

HTTP request

POST https://merchantapi.googleapis.com/loyaltyCustomers/v1/{parent=accounts/*}/loyaltyCustomers:manage

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The parent account where this loyalty customer will be handled. Format: accounts/{account}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "loyaltyCustomer": {
    object (LoyaltyCustomer)
  }
}
Fields
loyaltyCustomer

object (LoyaltyCustomer)

Required. The loyalty customer to insert, update, or remove.

Response body

Response message for the loyaltyCustomers.manage method.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "loyaltyCustomer": {
    object (LoyaltyCustomer)
  }
}
Fields
loyaltyCustomer

object (LoyaltyCustomer)

The loyalty customer that was inserted, updated, or removed. If the customer's identifier cannot be matched to a Google account or if the user has not opted into loyalty personalization, this field will contain a default LoyaltyCustomer instance.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/content

For more information, see the OAuth 2.0 Overview.

LoyaltyCustomer

Represents a customer’s loyalty information. Represents loyalty customer data in loyaltyCustomers.manage API, but is not a resource that can be retrieved or listed by other methods.

JSON representation 
{
  "userIdentifier": {
    object (UserIdentifier)
  },
  "loyaltyTier": enum (LoyaltyTier),
  "pointBalance": string
}
Fields
userIdentifier

object (UserIdentifier)

Required. The identifiers for the customer.
loyaltyTier

enum (LoyaltyTier)

Required. The tier label of the loyalty tier the customer belongs to.
pointBalance

string (int64 format)

Optional. The point balance of the loyalty customer.

UserIdentifier

The user identifiers associated with the customer. At least one of the fields within this message must be provided.

JSON representation 
{
  "emailAddress": string,
  "address": {
    object (AddressInfo)
  },
  "phoneNumber": string
}
Fields
emailAddress

string

Optional. The customer’s email address.
address

object (AddressInfo)

Optional. The customer’s physical address.
phoneNumber

string

Optional. The customer's phone number, in E.164 format (e.g., "+16502530000").

AddressInfo

Represents a customer’s physical address.

JSON representation 
{
  "givenName": string,
  "familyName": string,
  "city": string,
  "state": string,
  "regionCode": string,
  "postalCode": string
}
Fields
givenName

string

Optional. The given name of the customer.
familyName

string

Optional. The family name of the customer.
city

string

Optional. The city of the customer.
state

string

Optional. The state or province of the customer.
regionCode

string

Optional. The Unicode country/region code (CLDR) of the customer, such as "US" or "CH". This field is case-insensitive. For more information, see https://cldr.unicode.org/ and https://www.unicode.org/cldr/charts/latest/supplemental/territory_containment_un_m_49.html.
postalCode

string

Optional. The postal code (zip code) of the customer.

Format Rules:

  • United States: 5-digit zip codes (e.g., "94108").

LoyaltyTier

The tier label of the loyalty tier the customer belongs to.

Enums
LOYALTY_TIER_UNSPECIFIED Loyalty tier unspecified.
TIER1 Loyalty tier 1.
TIER2 Loyalty tier 2.
TIER3 Loyalty tier 3.
TIER4 Loyalty tier 4.
TIER5 Loyalty tier 5.
TIER6 Loyalty tier 6.
TIER7 Loyalty tier 7.
NON_MEMBER Disassociates the user from any loyalty tier. Only set to “NON_MEMBER” when the intent is to remove the user association from Google organic loyalty customer match experience.