- [HTTP request](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#body.HTTP_TEMPLATE)
- [Path parameters](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#body.PATH_PARAMETERS)
- [Request body](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#body.request_body)
  - [JSON representation](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#body.response_body)
  - [JSON representation](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#body.ManageLoyaltyCustomerMatchResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#body.aspect)
- [LoyaltyCustomer](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#LoyaltyCustomer)
  - [JSON representation](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#LoyaltyCustomer.SCHEMA_REPRESENTATION)
- [UserIdentifier](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#UserIdentifier)
  - [JSON representation](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#UserIdentifier.SCHEMA_REPRESENTATION)
- [AddressInfo](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#AddressInfo)
  - [JSON representation](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#AddressInfo.SCHEMA_REPRESENTATION)
- [LoyaltyTier](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#LoyaltyTier)
- [Try it!](https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#try-it)

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.

For more information on how to use this method, see [Overview of the loyalty customer match service](https://developers.google.com/merchant/api/guides/loyalty/customer-match-service).

**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](https://google.aip.dev/127) 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 (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#LoyaltyCustomer`) } } ``` |

| Fields ||
|---|---|
| `loyaltyCustomer` | ``object (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#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 (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#LoyaltyCustomer`) } } ``` |

| Fields ||
|---|---|
| `loyaltyCustomer` | ``object (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#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](https://developers.google.com/identity/protocols/OAuth2).

## 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 (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#UserIdentifier`) }, "loyaltyTier": enum (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#LoyaltyTier`), "pointBalance": string } ``` |

| Fields ||
|---|---|
| `userIdentifier` | ``object (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#UserIdentifier`)`` Required. The identifiers for the customer. |
| `loyaltyTier` | ``enum (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#LoyaltyTier`)`` Required. The tier label of the loyalty tier the customer belongs to. |
| `pointBalance` | `string (https://developers.google.com/discovery/v1/type-format 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 (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#AddressInfo`) }, "phoneNumber": string } ``` |

| Fields ||
|---|---|
| `emailAddress` | `string` Optional. The customer's email address. |
| `address` | ``object (`https://developers.google.com/merchant/api/reference/rest/loyaltycustomers_v1/accounts.loyaltyCustomers/manage#AddressInfo`)`` Optional. The customer's physical address. |
| `phoneNumber` | `string` Optional. The customer's phone number, in [E.164 format](https://support.google.com/google-ads/answer/16355235) (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. |