Обзор API Merchant Promotions

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

Когда вы добавляете рекламную акцию к своим товарам, покупатели видят ссылку на специальное предложение. Например, «Скидка 15%» или «Бесплатная доставка». Ссылки на предложения могут повысить привлекательность ваших продуктов и побудить покупателей совершить покупку. Все акции применяются на кассе или в точке продаж.

Дополнительную информацию см. в разделе Основы продвижения .

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

Google требует, чтобы вы предоставили конкретную информацию о своем бизнесе и продуктах, прежде чем показывать рекламные акции. У вас должно быть следующее:

Кроме того, вы должны зарегистрировать свой торговый аккаунт в программе «Акции». Если вы не уверены, зарегистрированы ли вы уже, проверьте Merchant Center .

Если вы не зарегистрированы, заполните форму запроса . Команда по продвижению сообщит вам, когда вы будете готовы начать реализацию.

Дополнительную информацию см. в разделе Критерии и правила участия .

Создать источник данных

Вы можете использовать метод account.dataSources.create для создания источника данных рекламного мероприятия. Если существующий источник данных рекламного мероприятия доступен, используйте метод accounts.dataSources.list для получения всех источников данных. Затем вы можете использовать поле name источника данных о рекламных акциях для создания рекламных акций .

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

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

Замените следующее:

  • {ACCOUNT_ID} : уникальный идентификатор вашей учетной записи, отображаемый в пользовательском интерфейсе Merchant Center.
  • {DISPLAY_NAME} : отображаемое имя источника данных.
  • {CONTENT_LANGUAGE} : двухбуквенный код языка ISO 639-1 продуктов в источнике данных.
  • {TARGET_COUNTRY} : код территории CLDR целевой страны, в которой вы хотите, чтобы рекламные акции были видны.

После успешного выполнения запроса вы увидите следующий ответ, содержащий сведения о вновь созданном источнике данных рекламных акций:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

Создавайте рекламные акции

Вы можете использовать метод accounts.promotions.insert для создания или обновления рекламной акции. accounts.promotions.insert принимает в качестве входных данных ресурс promotions и имя источника данных. В случае успеха возвращается новая или обновленная рекламная акция.

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

  • contentLanguage
  • redemptionChannel
  • promotionId
  • targetCountry
  • attributes.offerType
  • attributes.genericRedemptionCode
  • attributes.couponValueType
  • attributes.productApplicability
  • attributes.promotionEffectiveTimePeriod.endTime
  • attributes.promotionEffectiveTimePeriod.startTime
  • attributes.longTitle

Google проверяет и одобряет ваши промоакции перед их распространением. Дополнительную информацию см. в разделе Процесс утверждения рекламной акции .

Мы рекомендуем вам ознакомиться с правилами в отношении рекламных акций , чтобы убедиться, что создаваемые вами рекламные акции повышают ценность и соответствуют правилам в отношении товарных объявлений.

Следующий запрос демонстрирует, как создать онлайн-продвижение:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Информацию о правилах, применимых к настройке идентификатора промоакции, см. в разделе Минимальные требования к атрибуту идентификатора промоакции .

Допустимые значения обязательного поля offerType : NO_CODE и GENERIC_CODE . Если вы не укажете одно из этих значений, запрос API завершится неудачно с ответом HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type . Аналогичное сообщение об ошибке возвращается, если вы не указали ни одно из обязательных полей.

Если вы не укажете значение в поле attributes.genericRedemptionCode , запрос завершится с ошибкой HTTP 400. [genericRedemptionCode] No redemption code provided .

Значения полей promotion.attributes.promotionDisplayTimePeriod.startTime и promotion.attributes.promotionDisplayTimePeriod.endTime должны быть в формате yyyy-mm-ddThh:mm:ssZ . Обязательно замените значения этих полей датами, которые находятся в будущем.

Дополнительную информацию см. в разделе Спецификация данных рекламных акций .

Рекомендации по созданию рекламных акций см. в разделе «Рекомендации по созданию рекламных акций» .

Список атрибутов, связанных с рекламными акциями, см. в разделе Добавление атрибутов структурированных данных .

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

Вот пример, который можно использовать для асинхронной вставки нескольких рекламных акций:

Ява

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.Timestamp;
import com.google.shopping.merchant.promotions.v1beta.Attributes;
import com.google.shopping.merchant.promotions.v1beta.CouponValueType;
import com.google.shopping.merchant.promotions.v1beta.InsertPromotionRequest;
import com.google.shopping.merchant.promotions.v1beta.OfferType;
import com.google.shopping.merchant.promotions.v1beta.ProductApplicability;
import com.google.shopping.merchant.promotions.v1beta.Promotion;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceClient;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceSettings;
import com.google.shopping.merchant.promotions.v1beta.RedemptionChannel;
import com.google.shopping.type.CustomAttribute;
import com.google.shopping.type.Destination.DestinationEnum;
import com.google.type.Interval;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert multiple promotions asynchronously. */
public class InsertPromotionsAsyncSample {

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static Promotion createPromotion(String accountId) {
    String merchantPromotionId = generateRandomString();

    Attributes attributes =
        Attributes.newBuilder()
            .setProductApplicability(ProductApplicability.ALL_PRODUCTS)
            .setOfferType(OfferType.GENERIC_CODE)
            .setGenericRedemptionCode("ABCD1234")
            .setLongTitle("My promotion")
            .setCouponValueType(CouponValueType.PERCENT_OFF)
            .addPromotionDestinations(DestinationEnum.SHOPPING_ADS)
            .setPercentOff(10)
            // Note that promotions have a 6-month limit.
            // For more information, read here: https://support.google.com/merchants/answer/2906014
            // Also note that only promotions valid within the past 365 days are shown in the UI.
            .setPromotionEffectiveTimePeriod(
                Interval.newBuilder()
                    .setStartTime(Timestamp.newBuilder().setSeconds(1726842472))
                    .setEndTime(Timestamp.newBuilder().setSeconds(1726842473))
                    .build())
            .build();

    return Promotion.newBuilder()
        .setName(String.format("accounts/%s/merchantPromotions/%s", accountId, merchantPromotionId))
        .setPromotionId(merchantPromotionId)
        .setContentLanguage("fr")
        .setTargetCountry("CH")
        .addRedemptionChannel(RedemptionChannel.ONLINE)
        .setAttributes(attributes)
        // Custom attributes allow you to add additional information which is not available in
        // Attributes. For example, you might want to pilot experimental functionality.
        .addCustomAttributes(
            CustomAttribute.newBuilder()
                .setName("another example name")
                .setValue("another example value")
                .build())
        .build();
  }

  public static void asyncInsertPromotions(String accountId, String dataSourceId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    PromotionsServiceSettings merchantPromotionsServiceSettings =
        PromotionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    try (PromotionsServiceClient merchantPromotionsServiceClient =
        PromotionsServiceClient.create(merchantPromotionsServiceSettings)) {

      // Arbitrarily creates five merchant promotions with random IDs.
      List<InsertPromotionRequest> requests = new ArrayList<>();
      for (int i = 0; i < 5; i++) {
        InsertPromotionRequest request =
            InsertPromotionRequest.newBuilder()
                .setParent(String.format("accounts/%s", accountId))
                .setPromotion(createPromotion(accountId))
                .setDataSource(String.format("accounts/%s/dataSources/%s", accountId, dataSourceId))
                .build();
        requests.add(request);
      }

      // Inserts the merchant promotions.
      List<ApiFuture<Promotion>> futures =
          requests.stream()
              .map(
                  request ->
                      merchantPromotionsServiceClient.insertPromotionCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<Promotion>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<Promotion>>() {
            @Override
            public void onSuccess(List<Promotion> results) {
              System.out.println("Inserted merchant promotions below:");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());
    } catch (Exception e) {
      System.out.println(e);
    }
  }


  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    asyncInsertPromotions(config.getAccountId().toString(), "<YOUR_DATA_SOURCE_ID>");
  }
}

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

Местная акция, действующая на все товары и все магазины.

В следующем образце запроса показано, как создать местную акцию, применимую ко всем продуктам в вашей учетной записи Merchant Center и ко всем магазинам, добавленным в связанную учетную запись профиля компании .

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Поле productApplicability является обязательным. Он сигнализирует о применимости акции либо ко всем товарам, либо только к конкретным. Поддерживаемые значения: ALL_PRODUCTS и SPECIFIC_PRODUCTS . Дополнительную информацию см. в разделе Выбор продуктов для продвижения .

Поле couponValueType является обязательным. Он сигнализирует о типе рекламной акции, которую вы проводите. Список поддерживаемых значений см. в разделе Тип значения купона . В зависимости от выбранного типа купона могут потребоваться некоторые атрибуты .

Поле minimumPurchaseQuantity позволяет установить значение минимального количества покупки, которое необходимо для активации предложения по акции. Дополнительную информацию см. в разделе Минимальный объем покупки для акции .

Аналогичным образом вы можете использовать поле minimumPurchaseAmount , чтобы установить минимальную сумму покупки, необходимую для активации акции. Дополнительную информацию см. в разделе Минимальная сумма покупки .

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

Интернет-акция, распространяющаяся на выбранные продукты с кодом активации.

В следующем образце запроса показано, как создать онлайн-промоакцию, применимую к выбранным продуктам с кодом активации.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Посмотреть акции

Чтобы просмотреть рекламную акцию, используйте accounts.promotions.get . Этот запрос GET доступен только для чтения. Для этого требуется ваш merchantId и идентификатор акции. Метод GET возвращает соответствующий ресурс рекламной акции.

Например:

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

Замените следующее:

  • {ACCOUNT_ID} : уникальный идентификатор вашего аккаунта Merchant Center.
  • {PROMOTION_ID} : уникальный идентификатор рекламной акции, которую вы хотите получить. Формат: {CHANNEL} ~ {CONTENT_LANGUAGE} ~ {TARGET_COUNTRY} ~ {PROMOTION_ID} .

Обратите внимание, что для получения новой рекламной акции с помощью API требуется несколько минут.

Посмотреть местную акцию

Следующий пример запроса извлекает местную рекламную акцию, идентификатор которой — in_store~en~US~buy_2_get_10_off .

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

После успешного запроса вы увидите следующий ответ:

{
 "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Поле moneyOffAmount в этом примере указывает скидку, предлагаемую в рамках рекламной акции. Дополнительную информацию см. в разделе Сумма денежной скидки для рекламной акции .

Поле promotionUrl в этом примере предоставляет ссылку на веб-сайт магазина, где покупатели могут найти дополнительную информацию о рекламной акции. Промоакции с рекламой местного ассортимента возвращают ошибку, если вы не укажете поле promotionUrl .

Посмотреть онлайн-акцию

Следующий пример запроса извлекает онлайн-промоакцию, идентификатор которой — online~en~US~25_pct_off .

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
}

В поле itemIdInclusion , используемом в этом примере, упоминаются продукты, подпадающие под действие акции. Дополнительную информацию см. в разделе «Идентификатор продукта для продвижения» .

Список рекламных акций

Вы можете использовать метод promotions.list для просмотра всех созданных промоакций.

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

В ответе содержится список всех акций вашего аккаунта. Для каждой рекламной акции вы можете просмотреть такие сведения, как promotionId , redemptionChannel , dataSource , promotionStatus и т. д.

Посмотреть статус акции

Чтобы просмотреть статус рекламной акции, просмотрите атрибут promotionStatus возвращаемый методом promotions.get или promotions.list .

Поле promotionStatus может иметь следующие значения:

  • IN_REVIEW : Промоакция все еще находится на рассмотрении.
  • REJECTED : Продвижение отклонено.
  • LIVE : Акция одобрена и активна.
  • STOPPED : продвижение остановлено на аккаунте.
  • EXPIRED : Акция больше не активна.
  • PENDING : акция не остановлена, все отзывы одобрены, но дата активации наступает в будущем.
  • STATE_UNSPECIFIED : Неизвестный статус продвижения.

Чтобы понять процесс утверждения созданной вами рекламной акции, см. раздел Процесс утверждения рекламной акции .

Пример статуса промоакции

Следующие примеры демонстрируют разницу между успешными и неудачными запросами.

Отсутствует сопоставление продуктов

В следующем тексте ответа показано онлайн-продвижение, которое отклонено из-за отсутствия сопоставления продуктов.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

Информацию об устранении неполадок с отклоненными рекламными акциями и о том, как избежать отклонений в будущем, см. в разделе Устранение проблем с отклоненными рекламными акциями .

Если созданное вами продвижение не будет одобрено, вы получите электронное письмо с указанием причины отклонения и инструкциями по устранению проблем.

Продвижение на стадии оценки

В следующем тексте ответа показано продвижение, которое все еще оценивается.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

Одобренная и действующая акция

В следующем тексте ответа показана рекламная акция, видимая покупателям.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

Дополнительную информацию см. в разделе Часто задаваемые вопросы о статусе промоакции .

Узнать больше

,

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

Когда вы добавляете рекламную акцию к своим товарам, покупатели видят ссылку на специальное предложение. Например, «Скидка 15%» или «Бесплатная доставка». Ссылки на предложения могут повысить привлекательность ваших продуктов и побудить покупателей совершить покупку. Все акции применяются на кассе или в точке продаж.

Дополнительную информацию см. в разделе Основы продвижения .

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

Google требует, чтобы вы предоставили конкретную информацию о своем бизнесе и продуктах, прежде чем показывать рекламные акции. У вас должно быть следующее:

Кроме того, вы должны зарегистрировать свой торговый аккаунт в программе «Акции». Если вы не уверены, зарегистрированы ли вы уже, проверьте Merchant Center .

Если вы не зарегистрированы, заполните форму запроса . Команда по продвижению сообщит вам, когда вы будете готовы начать реализацию.

Дополнительную информацию см. в разделе Критерии и правила участия .

Создать источник данных

Вы можете использовать метод account.dataSources.create для создания источника данных рекламного мероприятия. Если существующий источник данных рекламного мероприятия доступен, используйте метод accounts.dataSources.list для получения всех источников данных. Затем вы можете использовать поле name источника данных о рекламных акциях для создания рекламных акций .

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

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

Замените следующее:

  • {ACCOUNT_ID} – уникальный идентификатор вашей учетной записи, отображаемый в пользовательском интерфейсе Merchant Center.
  • {DISPLAY_NAME} : отображаемое имя источника данных.
  • {CONTENT_LANGUAGE} : двухбуквенный код языка ISO 639-1 продуктов в источнике данных.
  • {TARGET_COUNTRY} : код территории CLDR целевой страны, в которой вы хотите, чтобы рекламные акции были видны.

После успешного выполнения запроса вы увидите следующий ответ, содержащий сведения о вновь созданном источнике данных рекламных акций:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

Создавайте рекламные акции

Вы можете использовать метод accounts.promotions.insert для создания или обновления рекламной акции. accounts.promotions.insert принимает в качестве входных данных ресурс promotions и имя источника данных. В случае успеха возвращается новая или обновленная рекламная акция.

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

  • contentLanguage
  • redemptionChannel
  • promotionId
  • targetCountry
  • attributes.offerType
  • attributes.genericRedemptionCode
  • attributes.couponValueType
  • attributes.productApplicability
  • attributes.promotionEffectiveTimePeriod.endTime
  • attributes.promotionEffectiveTimePeriod.startTime
  • attributes.longTitle

Google проверяет и одобряет ваши промоакции перед их распространением. Дополнительную информацию см. в разделе Процесс утверждения рекламной акции .

Мы рекомендуем вам ознакомиться с правилами в отношении рекламных акций , чтобы убедиться, что создаваемые вами рекламные акции повышают ценность и соответствуют правилам в отношении товарных объявлений.

Следующий запрос демонстрирует, как создать онлайн-продвижение:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Информацию о правилах, применимых к настройке идентификатора промоакции, см. в разделе Минимальные требования к атрибуту идентификатора промоакции .

Допустимые значения обязательного поля offerType : NO_CODE и GENERIC_CODE . Если вы не укажете одно из этих значений, запрос API завершится неудачно с ответом HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type . Аналогичное сообщение об ошибке возвращается, если вы не указали ни одно из обязательных полей.

Если вы не укажете значение в поле attributes.genericRedemptionCode , запрос завершится с ошибкой HTTP 400. [genericRedemptionCode] No redemption code provided .

Значения полей promotion.attributes.promotionDisplayTimePeriod.startTime и promotion.attributes.promotionDisplayTimePeriod.endTime должны быть в формате yyyy-mm-ddThh:mm:ssZ . Обязательно замените значения этих полей датами, которые находятся в будущем.

Дополнительную информацию см. в разделе Спецификация данных рекламных акций .

Рекомендации по созданию рекламных акций см. в разделе «Рекомендации по созданию рекламных акций» .

Список атрибутов, связанных с рекламными акциями, см. в разделе Добавление атрибутов структурированных данных .

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

Вот пример, который можно использовать для асинхронной вставки нескольких рекламных акций:

Ява

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.Timestamp;
import com.google.shopping.merchant.promotions.v1beta.Attributes;
import com.google.shopping.merchant.promotions.v1beta.CouponValueType;
import com.google.shopping.merchant.promotions.v1beta.InsertPromotionRequest;
import com.google.shopping.merchant.promotions.v1beta.OfferType;
import com.google.shopping.merchant.promotions.v1beta.ProductApplicability;
import com.google.shopping.merchant.promotions.v1beta.Promotion;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceClient;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceSettings;
import com.google.shopping.merchant.promotions.v1beta.RedemptionChannel;
import com.google.shopping.type.CustomAttribute;
import com.google.shopping.type.Destination.DestinationEnum;
import com.google.type.Interval;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert multiple promotions asynchronously. */
public class InsertPromotionsAsyncSample {

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static Promotion createPromotion(String accountId) {
    String merchantPromotionId = generateRandomString();

    Attributes attributes =
        Attributes.newBuilder()
            .setProductApplicability(ProductApplicability.ALL_PRODUCTS)
            .setOfferType(OfferType.GENERIC_CODE)
            .setGenericRedemptionCode("ABCD1234")
            .setLongTitle("My promotion")
            .setCouponValueType(CouponValueType.PERCENT_OFF)
            .addPromotionDestinations(DestinationEnum.SHOPPING_ADS)
            .setPercentOff(10)
            // Note that promotions have a 6-month limit.
            // For more information, read here: https://support.google.com/merchants/answer/2906014
            // Also note that only promotions valid within the past 365 days are shown in the UI.
            .setPromotionEffectiveTimePeriod(
                Interval.newBuilder()
                    .setStartTime(Timestamp.newBuilder().setSeconds(1726842472))
                    .setEndTime(Timestamp.newBuilder().setSeconds(1726842473))
                    .build())
            .build();

    return Promotion.newBuilder()
        .setName(String.format("accounts/%s/merchantPromotions/%s", accountId, merchantPromotionId))
        .setPromotionId(merchantPromotionId)
        .setContentLanguage("fr")
        .setTargetCountry("CH")
        .addRedemptionChannel(RedemptionChannel.ONLINE)
        .setAttributes(attributes)
        // Custom attributes allow you to add additional information which is not available in
        // Attributes. For example, you might want to pilot experimental functionality.
        .addCustomAttributes(
            CustomAttribute.newBuilder()
                .setName("another example name")
                .setValue("another example value")
                .build())
        .build();
  }

  public static void asyncInsertPromotions(String accountId, String dataSourceId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    PromotionsServiceSettings merchantPromotionsServiceSettings =
        PromotionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    try (PromotionsServiceClient merchantPromotionsServiceClient =
        PromotionsServiceClient.create(merchantPromotionsServiceSettings)) {

      // Arbitrarily creates five merchant promotions with random IDs.
      List<InsertPromotionRequest> requests = new ArrayList<>();
      for (int i = 0; i < 5; i++) {
        InsertPromotionRequest request =
            InsertPromotionRequest.newBuilder()
                .setParent(String.format("accounts/%s", accountId))
                .setPromotion(createPromotion(accountId))
                .setDataSource(String.format("accounts/%s/dataSources/%s", accountId, dataSourceId))
                .build();
        requests.add(request);
      }

      // Inserts the merchant promotions.
      List<ApiFuture<Promotion>> futures =
          requests.stream()
              .map(
                  request ->
                      merchantPromotionsServiceClient.insertPromotionCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<Promotion>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<Promotion>>() {
            @Override
            public void onSuccess(List<Promotion> results) {
              System.out.println("Inserted merchant promotions below:");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());
    } catch (Exception e) {
      System.out.println(e);
    }
  }


  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    asyncInsertPromotions(config.getAccountId().toString(), "<YOUR_DATA_SOURCE_ID>");
  }
}

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

Местная акция, действующая на все товары и все магазины.

В следующем образце запроса показано, как создать местную акцию, применимую ко всем продуктам в вашей учетной записи Merchant Center и ко всем магазинам, добавленным в связанную учетную запись профиля компании .

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Поле productApplicability является обязательным. Он сигнализирует о применимости акции либо ко всем товарам, либо только к конкретным. Поддерживаемые значения: ALL_PRODUCTS и SPECIFIC_PRODUCTS . Дополнительную информацию см. в разделе Выбор продуктов для продвижения .

Поле couponValueType является обязательным. Он сигнализирует о типе рекламной акции, которую вы проводите. Список поддерживаемых значений см. в разделе Тип значения купона . В зависимости от выбранного типа купона могут потребоваться некоторые атрибуты .

Поле minimumPurchaseQuantity позволяет установить значение минимального количества покупки, которое необходимо для активации предложения по акции. Дополнительную информацию см. в разделе Минимальный объем покупки для акции .

Аналогичным образом вы можете использовать поле minimumPurchaseAmount , чтобы установить минимальную сумму покупки, необходимую для активации акции. Дополнительную информацию см. в разделе Минимальная сумма покупки .

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

Интернет-акция, распространяющаяся на выбранные продукты с кодом активации.

В следующем образце запроса показано, как создать онлайн-промоакцию, применимую к выбранным продуктам с кодом активации.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Посмотреть акции

Чтобы просмотреть рекламную акцию, используйте accounts.promotions.get . Этот запрос GET доступен только для чтения. Для этого требуется ваш merchantId и идентификатор акции. Метод GET возвращает соответствующий ресурс рекламной акции.

Например:

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

Замените следующее:

  • {ACCOUNT_ID} : уникальный идентификатор вашего аккаунта Merchant Center.
  • {PROMOTION_ID} : уникальный идентификатор рекламной акции, которую вы хотите получить. Формат: {CHANNEL} ~ {CONTENT_LANGUAGE} ~ {TARGET_COUNTRY} ~ {PROMOTION_ID} .

Обратите внимание, что для получения новой рекламной акции с помощью API требуется несколько минут.

Посмотреть местную акцию

Следующий пример запроса извлекает местную рекламную акцию, идентификатор которой — in_store~en~US~buy_2_get_10_off .

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

После успешного запроса вы увидите следующий ответ:

{
 "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Поле moneyOffAmount в этом примере указывает скидку, предлагаемую в рамках рекламной акции. Дополнительные сведения см. в разделе Сумма денежной скидки для рекламной акции .

Поле promotionUrl в этом примере предоставляет ссылку на веб-сайт магазина, где покупатели могут найти дополнительную информацию о рекламной акции. Промоакции с рекламой местного ассортимента возвращают ошибку, если вы не укажете поле promotionUrl .

Посмотреть онлайн-акцию

Следующий пример запроса извлекает онлайн-промоакцию, идентификатор которой — online~en~US~25_pct_off .

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
}

В поле itemIdInclusion , используемом в этом примере, упоминаются продукты, подпадающие под действие акции. Дополнительную информацию см. в разделе «Идентификатор продукта для продвижения» .

Список рекламных акций

Вы можете использовать метод promotions.list для просмотра всех созданных промоакций.

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

В ответе содержится список всех акций вашего аккаунта. Для каждой рекламной акции вы можете просмотреть такие сведения, как promotionId , redemptionChannel , dataSource , promotionStatus и т. д.

Посмотреть статус акции

Чтобы просмотреть статус рекламной акции, просмотрите атрибут promotionStatus возвращаемый методом promotions.get или promotions.list .

Поле promotionStatus может иметь следующие значения:

  • IN_REVIEW : Промоакция все еще находится на рассмотрении.
  • REJECTED : Продвижение отклонено.
  • LIVE : Акция одобрена и активна.
  • STOPPED : продвижение остановлено на аккаунте.
  • EXPIRED : Акция больше не активна.
  • PENDING : акция не остановлена, все отзывы одобрены, но дата активации наступает в будущем.
  • STATE_UNSPECIFIED : Неизвестный статус продвижения.

Чтобы понять процесс утверждения созданной вами рекламной акции, см. раздел Процесс утверждения рекламной акции .

Пример статуса промоакции

Следующие примеры демонстрируют разницу между успешными и неудачными запросами.

Отсутствует сопоставление продуктов

В следующем тексте ответа показано онлайн-продвижение, которое отклонено из-за отсутствия сопоставления продуктов.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

Информацию об устранении неполадок с отклоненными рекламными акциями и о том, как избежать отклонений в будущем, см. в разделе Устранение проблем с отклоненными рекламными акциями .

Если созданное вами продвижение не будет одобрено, вы получите электронное письмо с указанием причины отклонения и инструкциями по устранению проблем.

Продвижение на стадии оценки

В следующем тексте ответа показано продвижение, которое все еще оценивается.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

Одобренная и действующая акция

В следующем тексте ответа показана рекламная акция, видимая покупателям.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

Дополнительную информацию см. в разделе Часто задаваемые вопросы о статусе промоакции .

Узнать больше