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

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

С помощью Merchant API продавцы и сторонние поставщики программ лояльности, действующие от имени продавцов, могут настраивать и поддерживать программы лояльности программно, используя LoyaltyProgramService. Этот сервис позволяет создавать, получать, перечислять, обновлять и удалять программы лояльности.

Дополнительную информацию о требованиях к бизнесу и рекомендациях по соблюдению правил можно найти в статье О программах лояльности продавцов в Справочном центре Merchant Center.

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

При работе с программами лояльности учитывайте следующее:

• Идентификатор на уровне аккаунта. Merchant API идентифицирует программы лояльности по идентификатору аккаунта Merchant Center, которому они принадлежат.

• Ограничение на одну программу. Merchant API поддерживает только одну программу лояльности для каждого аккаунта продавца.

• Прямое владение аккаунтом. Программы лояльности должны быть настроены непосредственно в целевом аккаунте продавца (accounts/{ACCOUNT_ID}). Сервис не поддерживает управление программами лояльности на уровне расширенного аккаунта для дочерних аккаунтов. Сторонние поставщики программ лояльности, у которых есть авторизованный доступ к аккаунту продавца, могут управлять программой от его имени.

• Редакционная проверка. После создания или обновления программы лояльности она проходит проверку. Поле review_result.review_status указывает, является ли программа UNDER_REVIEW, APPROVED или REJECTED. Каждое успешное обновление отправляет программу обратно в очередь на проверку, даже если обновление не меняет ничего существенного. Во время проверки программа не будет видна покупателям. Проверка может занять до 48 часов.

• Поддерживаемые регионы. Программы лояльности продавцов доступны в поддерживаемых странах, включая Австралию, Бразилию, Великобританию, Германию, Индию, Испанию, Италию, Канаду, Мексику, Нидерланды, США, Францию, Южную Корею и Японию.

• Активные регионы. Значение атрибута "регион" regionCodes в программе лояльности должно быть подмножеством значения атрибута "регион" activeRegionCodes в атрибуте "программа лояльности" accounts/{ACCOUNT_ID}/programs/loyalty. В противном случае запросы на создание, обновление и удаление будут завершаться ошибкой LOYALTY_PROGRAM_DISABLED. Google активирует поддерживаемую страну, когда включено дополнение "Программа лояльности" и аккаунт соответствует требованиям в этой стране. Например, аккаунт соответствует требованиям, если включена программа "Бесплатные предложения" и основной источник данных о товарах настроен на таргетинг на страну для целевого сервиса FREE_LISTINGS. Чтобы узнать, почему страна неактивна, ознакомьтесь со статьей Как проверить активные регионы.

• Требования для получения уровня. Уровни могут быть бесплатными, требовать членского взноса, определенного порога расходов или наличия кредитной карты под брендом продавца. Нельзя создавать уровни на основе рода занятий, например для студентов или военнослужащих.

• Бонусы и преимущества. Программы поддерживают бесплатную доставку, бонусные баллы и цены для участников. В объявлениях цена для участников программы лояльности должна быть ниже обычной цены или цены со скидкой по крайней мере на 5 % или 5 единиц валюты.

Требования

Прежде чем начать работу с программами лояльности в Merchant API, убедитесь, что вы соответствуете следующим требованиям:

• У вас должен быть активный аккаунт Merchant Center (или авторизованный доступ к аккаунту продавца, если вы сторонний поставщик программы лояльности).

• Включите дополнение Программа лояльности в аккаунте. Вы можете включить дополнение одним из следующих способов:

  • Интерфейс Merchant Center. Следуйте инструкциям в статье Как настроить программу лояльности Справочного центра Merchant Center.
  • Дополнительный API программ. Включите программу программно, как описано в разделе Как включить программы в дополнительном API программ. Для использования метода accounts.programs.enable необходим доступ с правами администратора.

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

Ниже приведен пример запроса на включение дополнения "Программа лояльности" с помощью Programs sub-API.

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable

curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

Проверьте активные регионы

После включения дополнения "Программа лояльности" вызовите метод accounts.programs.get для accounts/{ACCOUNT_ID}/programs/loyalty. В ответе будет указано, где можно использовать программы лояльности и почему другие поддерживаемые страны неактивны.

Пример запроса:

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty

curl --request GET \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --compressed

Замените {ACCOUNT_ID} уникальным идентификатором своего аккаунта Merchant Center.

Ниже приведен пример ответа для аккаунта, в котором включено дополнение и который соответствует требованиям только в США.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty",
  "documentationUri": "https://support.google.com/merchants/answer/12827255",
  "state": "ENABLED",
  "activeRegionCodes": [
    "US"
  ],
  "unmetRequirements": [
    {
      "title": "IS_ELIGIBLE_FOR_LOYALTY",
      "documentationUri": "https://support.google.com/merchants/answer/12827255#Eligibility",
      "affectedRegionCodes": [
        "AU",
        "BR",
        "CA",
        "DE",
        "ES",
        "FR",
        "GB",
        "IN",
        "IT",
        "JP",
        "KR",
        "MX",
        "NL"
      ]
    }
  ]
}

В ответе обратите внимание на следующие поля:

• activeRegionCodes – страны, которые можно указать в атрибуте regionCodes для программы лояльности. В приведенном выше примере активен только US.
• unmetRequirements – причина, по которой другие поддерживаемые страны неактивны. Для программ лояльности это требование IS_ELIGIBLE_FOR_LOYALTY.
  • affectedRegionCodes – поддерживаемые страны, в которых аккаунт не соответствует требованиям.
  • documentationUri – ссылка на требования.

В приведенном выше примере вы пока не можете использовать страны из affectedRegionCodes. Если в поле regionCodes вашей программы лояльности указано одно из этих значений, запросы на создание, обновление и удаление будут отклоняться с ошибкой LOYALTY_PROGRAM_DISABLED. Чтобы активировать страну, выполните следующие действия:

1. Сделайте аккаунт доступным в этой стране. Например, включите программу "Бесплатные предложения" и настройте основной источник данных о товарах для таргетинга на страну для целевого сервиса FREE_LISTINGS. Ознакомьтесь со всеми требованиями к участникам.
2. Позвоните по номеру accounts.programs.get ещё раз и убедитесь, что страна находится в activeRegionCodes.

affectedRegionCodes может включать страны, в которых вы не продаете товары. В этих странах никаких действий с вашей стороны не требуется. Они не влияют на страны, указанные в поле activeRegionCodes.

Методы

Управлять программами лояльности можно следующими способами:

• loyaltyPrograms.create
• loyaltyPrograms.get
• loyaltyPrograms.list
• loyaltyPrograms.update
• loyaltyPrograms.delete

Как создать программу лояльности

Чтобы создать новую программу лояльности для аккаунта, используйте метод loyaltyPrograms.create. Укажите подробные сведения, такие как описание программы, URL страницы регистрации и уровни программы с их уникальными преимуществами и требованиями.

Обязательный атрибут program_label задает уникальный идентификатор программы лояльности. Например, если указать ярлык my-rewards, то для ресурса name будет задано значение accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

Пример запроса:

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}

Замените {ACCOUNT_ID} уникальным идентификатором своего аккаунта Merchant Center.

Ниже приведен пример ответа на успешный запрос.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Как получить программу лояльности

Чтобы получить сведения о собственной программе лояльности, используйте метод loyaltyPrograms.get.

Пример запроса:

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Замените {ACCOUNT_ID} на идентификатор аккаунта, а {PROGRAM_LABEL} – на уникальный ярлык программы лояльности (например, my-rewards).

Ниже приведен пример ответа на успешный запрос.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Список программ лояльности

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

Пример запроса:

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

Ниже приведен пример ответа на успешный запрос.

{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}

Как изменить программу лояльности

Чтобы обновить существующую программу лояльности, используйте метод loyaltyPrograms.update. Выполните частичное обновление с помощью update_mask или полную замену, опустив маску. Каждое успешное обновление запускает новую редакционную проверку, поэтому отправляйте обновления только при изменении значения.

Частичное обновление с маской обновления

update_mask позволяет указать, какие именно поля нужно обновить. Изменяются только поля, перечисленные в маске, а остальные остаются без изменений. Любое поле, не указанное в маске обновления, игнорируется, даже если оно присутствует в теле запроса.

В примере запроса ниже обновляются только поля programDescriptions и advancedSettings:

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}

В этом примере сервис игнорирует signupUrl, поскольку он не включен в update_mask. Поле programDescriptions полностью заменяет все ранее настроенные описания.

Ниже приведен пример ответа на успешный запрос.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}

Полная замена без маски обновления

Если параметр update_mask не указан, запрос полностью заменяет конфигурацию программы лояльности.

Пример запроса:

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}

Ниже приведен пример ответа на успешный запрос.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Как удалить программу лояльности

Чтобы удалить программу лояльности из аккаунта, используйте метод loyaltyPrograms.delete.

Пример запроса:

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Если запрос выполнен успешно, тело ответа будет пустым.

Дальнейшие действия

• Чтобы связать отдельных покупателей с уровнями программы лояльности для бесплатной персонализации в Google Поиске, ознакомьтесь с руководством по использованию сервиса списков электронных адресов для программ лояльности.
• Чтобы включить или отключить программы в аккаунте, ознакомьтесь с руководством по работе с Programs sub-API.
• Подробную информацию о настройке, редакционных правилах и отчетах вы найдете в статье О программе лояльности продавца Справочного центра Merchant Center.
• Чтобы узнать больше о методах API и определениях ресурсов, ознакомьтесь с документацией по Merchant API.