: API контента для покупок был закрыт 18 августа 2026 года .

Начиная с 1 сентября 2026 года , запросы к Content API для покупок будут постепенно выдавать ошибки. Ознакомьтесь с руководством по прекращению поддержки Content API .

Если вам потребуется дополнительное время для перехода на Merchant API, запросите расширенный доступ к Content API для покупок .

Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Общие сведения о сервисе списков электронных адресов для программ лояльности

В этом руководстве рассказывается, как использовать сервис списков электронных адресов в Merchant API. Этот сервис позволяет продавцам и сторонним поставщикам программ лояльности, действующим от имени продавцов, управлять данными о программах лояльности, например идентификаторами пользователей и информацией об уровнях, для органической персонализации в Google Поиске без активного аккаунта Google Рекламы.

Обзор

Используйте сервис списков электронных адресов для программ лояльности, чтобы загружать данные о программах лояльности, которые затем используются для предоставления функций персонализации для программ лояльности в Google Поиске, например для показа цен, доступных только участникам программы. С помощью ManageLoyaltyCustomerMatch специального метода вы можете связывать клиентов с уровнями программы лояльности, чтобы добавлять, изменять или удалять их статус в программе на основе идентификаторов пользователей.

Основные понятия

Единый интерфейс. Уникальная конечная точка для добавления, изменения и удаления данных об уровнях программы лояльности.
Конфиденциальность. Чтобы защитить конфиденциальность пользователей и предотвратить несанкционированный доступ к аккаунтам, API не поддерживает операции GET и LIST. Это позволяет управлять данными без их извлечения или аудита.
Гибкая идентификация. Сопоставляйте пользователей, используя хотя бы один действительный идентификатор, например адрес электронной почты, почтовый адрес или номер телефона.
Обработка на основе согласия. Сервис хранит и использует данные клиента только в том случае, если конечный пользователь дал необходимое согласие Google. Чтобы защитить аккаунт от попыток узнать, существует ли он, или статус согласия, сервис возвращает сообщение об успешном выполнении, если совпадение не найдено или согласие не предоставлено.

Требования

Чтобы использовать сервис списков электронных адресов для программ лояльности, соблюдайте следующие требования:

Настройка аккаунта. Убедитесь, что у вас есть активный аккаунт Merchant Center (или авторизованный доступ к аккаунту продавца, если вы сторонний поставщик услуг по программам лояльности). Чтобы использовать сервис списков электронных адресов для программ лояльности, создавать аккаунт Google Рекламы не нужно.
Настройка программы лояльности. Включите программу лояльности в аккаунте Merchant Center и убедитесь, что вы задали уровни участия в ней.
Порядок уровней. Учитывайте порядок, в котором уровни программы лояльности определены в интерфейсе Merchant Center. API использует именно эту последовательность для сопоставления перечислений.

Метод `ManageLoyaltyCustomerMatch`

Метод ManageLoyaltyCustomerMatch – это основной интерфейс для управления связями с программами лояльности. На основе предоставленных данных сервис автоматически определяет, нужно ли добавить, изменить или удалить статус уровня программы лояльности клиента. Операция идемпотентна: повторные идентичные запросы имеют тот же эффект, что и один запрос.

В следующем запросе показано, как управлять связями с программами лояльности клиентов с помощью API:

POST https://merchantapi.googleapis.com/{API_VERSION}/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage

В этом запросе определены следующие обязательные параметры пути:

API_VERSION – версия API, например v1.
ACCOUNT_ID – идентификатор аккаунта Merchant Center.

Включите объект loyaltyCustomer в тело запроса.

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

Поля loyaltyCustomer

userIdentifier – набор идентификаторов, используемых для сопоставления клиента. В userIdentifier должно быть указано хотя бы одно действительное поле.
loyaltyTier – уровень программы лояльности, который нужно связать с клиентом. Соответствует порядку уровней в настройках Merchant Center. Подробнее о сопоставлении loyaltyTier… Используйте значение NON_MEMBER, чтобы удалить существующую связь.
pointBalance – текущий баланс баллов клиента.

Поля userIdentifier

Укажите хотя бы одно из следующих полей:

emailAddress – адрес электронной почты клиента.
address – физический адрес клиента. Требуется указать почтовый индекс.
phoneNumber – номер телефона клиента. Рекомендуется использовать формат E.164.

Как работает сопоставление `loyaltyTier`

API не использует пользовательские имена. Значения перечисления loyaltyTier (от TIER1 до TIER7) – это семантические ярлыки. В них не используются специальные названия (например, "Золотые бонусы") или метки (например, "золотой уровень"), которые вы задали в интерфейсе Merchant Center. Они строго соответствуют порядку, в котором вы задали уровни в настройках программы лояльности в Merchant Center:

TIER1 – первый уровень, указанный в настройках программы лояльности в Merchant Center.
TIER2 – соответствует второму уровню, указанному в настройках программы лояльности в Merchant Center.
TIER3–TIER7 – соответствуют третьему–седьмому уровням, указанным в настройках программы лояльности в Merchant Center.

Пример

Если в вашей программе лояльности в Merchant Center уровни заданы в следующем порядке:

Название уровня: "Серебряный статус", ярлык уровня: "silver".
Название уровня: "Золотой участник", метка уровня: "gold".
Название уровня: "Platinum Elite", метка уровня: "platinum".

Затем в accounts.loyaltyCustomers.manage вызовах API:

Чтобы назначить клиенту статус Silver, необходимо использовать loyaltyTier: TIER1.
Чтобы назначить клиенту статус Золотой участник, необходимо использовать loyaltyTier: TIER2.
Чтобы назначить клиенту уровень Platinum Elite, необходимо использовать loyaltyTier: TIER3.

Значения перечисления LoyaltyTier

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER (используется для удаления связи с программой лояльности клиента)

Как устроен ответ ManageLoyaltyCustomerMatch

Метод ManageLoyaltyCustomerMatch возвращает объект ManageLoyaltyCustomerMatchResponse:

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

Важные примечания об ответах

Успешное обновление или добавление данных. Чтобы успешно сохранить или обновить данные о связи уровня лояльности с клиентом, должны быть выполнены следующие условия:
- вы сопоставляете пользователя Google с предоставленным значением userIdentifier;
- вы задали для параметра loyaltyTier в запросе действительное значение, отличное от NON_MEMBER;
- пользователь, с которым было установлено соответствие, дал согласие на использование данных о программе лояльности;

Ответ содержит объект loyaltyCustomer из вашего запроса, указывающий на то, что сервис успешно обработал и сохранил данные:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}

Успешное удаление. Чтобы удалить связь с программой лояльности для клиента, должны быть выполнены следующие условия:
- вы сопоставляете пользователя Google с предоставленным значением userIdentifier;
- вы задали для параметра loyaltyTier в запросе значение NON_MEMBER;

Ответ представляет собой пустой объект JSON:

{}

Нет совпадений или согласия (успешное выполнение без уведомления). Если предоставленный userIdentifier не соответствует аккаунту Google или если пользователь, с которым найдено совпадение, не дал согласия на использование данных о программе лояльности, API возвращает статус HTTP 200 OK с пустым объектом JSON: {}. Это происходит как при попытке вставить или обновить данные, так и при попытке удалить их.

Примеры

TIER1 соответствует первому уровню (например, Basic), а TIER2 – второму (например, Premium).

Чтобы добавить клиента в группу TIER2 или изменить его статус, используя адрес электронной почты, отправьте следующий запрос:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

Если пользователь успешно сопоставлен и дал согласие, API возвращает следующий ответ:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

Если совпадений нет или пользователь не дал согласия, API возвращает следующий ответ:

{}

Чтобы удалить связь с программой лояльности по номеру телефона, отправьте следующий запрос:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

Независимо от того, существовала ли запись, API возвращает следующий успешный ответ:

{}

Чтобы добавить или обновить клиента, используя несколько идентификаторов, отправьте следующий запрос:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

Ответ похож на первый пример, но зависит от соответствия и согласия.

Обработка ошибок

В API используются стандартные коды HTTP. Вот несколько распространенных строк ошибок:

Код HTTP	Строка ошибки	Описание
400	INVALID_ARGUMENT	Отсутствует user_identifier или loyalty_tier, либо идентификатор пуст.
401	UNAUTHENTICATED	Неверные или отсутствующие учетные данные.
403	PERMISSION_DENIED	У аутентифицированного пользователя нет доступа к указанному аккаунту Merchant Center.
404	NOT_FOUND	Указанная метка уровня программы лояльности не существует в вашей конфигурации.
412	FAILED_PRECONDITION	В вашем аккаунте не настроена программа лояльности.
429	RESOURCE_EXHAUSTED	Достигнуто ограничение по квоте.