Package google.shopping.merchant.loyaltycustomers.v1alpha

Index

LoyaltyCustomerMatchService

Manages customer loyalty program memberships for merchants.

This service allows merchants to manage the association between their customers and loyalty program tiers. This data is used to personalize the shopping experience on Google free listing surfaces.

The service is only available to selected merchants. The service follows a non-standard, imperative pattern, exposing a single ManageLoyaltyCustomerMatch method rather than conventional resource identifiers and CRUD operations. This design protects user privacy by preventing the discovery of a customer's presence or membership status through standard GET or LIST methods.

ManageLoyaltyCustomerMatch

rpc ManageLoyaltyCustomerMatch(ManageLoyaltyCustomerMatchRequest) returns (ManageLoyaltyCustomerMatchResponse)

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

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

AddressInfo

Represents a customer’s physical address.

Fields
given_name

string

Optional. The given name of the customer.
family_name

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

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

string

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

Format Rules:

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

LoyaltyCustomer

Represents a customer’s loyalty information. Represents loyalty customer data in ManageLoyaltyCustomerMatch API, but is not a resource that can be retrieved or listed by other methods. The service is only available to selected merchants.

Fields
user_identifier

UserIdentifier

Required. The identifiers for the customer.
loyalty_tier

LoyaltyTier

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

int64

Optional. The point balance of the loyalty customer.

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.

ManageLoyaltyCustomerMatchRequest

Request message for the ManageLoyaltyCustomerMatch method.

Fields
parent

string

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

LoyaltyCustomer

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

ManageLoyaltyCustomerMatchResponse

Response message for the ManageLoyaltyCustomerMatch method.

Fields
loyalty_customer

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.

UserIdentifier

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

Fields
email_address

string

Optional. The customer’s email address.
address

AddressInfo

Optional. The customer’s physical address.
phone_number

string

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