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

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

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

Важно! Сервис доступен только некоторым продавцам. Чтобы принять участие в тестировании, отправьте запрос на добавление в белый список через форму поддержки Shopping API. В поле What is the issue/question? > Allowlist request (Запрос на добавление в белый список) > Other (Другое).

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

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

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

• Идентификатор на уровне аккаунта. Merchant API идентифицирует программы лояльности по идентификатору аккаунта Merchant Center, которому они принадлежат.
• Ограничение на одну программу. Merchant API поддерживает только одну программу лояльности для каждого аккаунта продавца.
• Прямое владение аккаунтом. Программы лояльности должны быть настроены непосредственно в целевом аккаунте продавца (accounts/{ACCOUNT_ID}). Сервис не поддерживает управление программами лояльности на уровне расширенного аккаунта для дочерних аккаунтов. Сторонние поставщики программ лояльности, у которых есть авторизованный доступ к аккаунту продавца, могут управлять программой от его имени.
• Редакционная проверка. После создания или обновления программы лояльности она проходит проверку. Поле review_result.review_status указывает, является ли программа UNDER_REVIEW, APPROVED или REJECTED.
• Поддерживаемые регионы. Программы лояльности доступны в Австралии, Бразилии, Великобритании, Германии, Индии, Испании, Италии, Канаде, Мексике, Нидерландах, США, Франции и Южной Корее.
• Требования для участия в уровне. Участие в уровне может быть бесплатным, требовать уплаты членского взноса, достижения определенного порога расходов или наличия кредитной карты, выпущенной продавцом. Нельзя создавать уровни на основе рода занятий, например для студентов или военнослужащих.
• Преимущества. Программы поддерживают бесплатную доставку, бонусные баллы и цены для участников. В объявлениях цена для участников программы лояльности должна быть ниже обычной цены или цены со скидкой по крайней мере на 5% или 5 единиц валюты.

Требования

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

• У вас должен быть активный аккаунт Merchant Center (или авторизованный доступ к аккаунту продавца, если вы сторонний поставщик программы лояльности).
• Включите дополнение Программа лояльности в аккаунте. Включить дополнение можно одним из следующих способов:
  • Интерфейс Merchant Center. Следуйте инструкциям в статье Как настроить программу лояльности Справочного центра Merchant Center.
  • Дополнительный API программ. Включите программу программно, как описано в разделе Как включить программы в дополнительном API программ.

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

HTTP

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

cURL

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

Методы

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

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

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

HTTP

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.

Примечание. Даже если дополнение "Программа лояльности" не включено, эта конечная точка все равно возвращает соответствующую программу лояльности без ошибки.

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

HTTP

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.

Примечание. Этот метод возвращает только программы лояльности, принадлежащие непосредственно указанному аккаунту, а не программы, связанные с дочерними аккаунтами. Даже если дополнение "Программа лояльности" отключено, эта конечная точка возвращает существующие программы без ошибки.

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

HTTP

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 или полную замену, опустив маску.

Важно! При обновлении программы лояльности повторяющиеся поля, такие как programDescriptions и tiers, нельзя обновить на месте. Любое повторяющееся поле, включенное в обновление, заменяет весь существующий список. Чтобы избежать случайной потери данных, перед обновлением повторяющихся полей отправьте запрос get, чтобы получить текущие значения.

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

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

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

HTTP

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, запрос полностью заменит конфигурацию программы лояльности.

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

HTTP

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.

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

HTTP

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

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

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

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