Обзор программ лояльности

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

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

Важно: услуга доступна только избранным продавцам. Чтобы выразить заинтересованность в участии, свяжитесь со службой поддержки, отправив запрос на добавление в список разрешенных продавцов через форму поддержки Shopping API в разделе «В чем проблема/вопрос?» > «Запрос на добавление в список разрешенных продавцов» > «Другое» .

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

Ключевые понятия

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

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

Предварительные требования

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

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

Вот пример запроса на включение надстройки «Программа лояльности» с использованием под-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, ознакомьтесь с руководством по сервису сопоставления клиентов программ лояльности .
• Чтобы включить или отключить программы покупок для вашей учетной записи, см. руководство по подAPI «Программы» .
• Подробную информацию о настройке бизнеса, редакционных правилах и отчетности см. в разделе «О программе лояльности для продавцов» в справке Merchant Center.
• Для ознакомления с методами API и определениями ресурсов см. справочник по API для продавцов .