Merchant Promotions API の概要

プロモーションを使用して、Google で販売する商品のスペシャル オファーをアピールしましょう。プロモーションは、Google 検索、ショッピング、Chrome などのさまざまな Google サービスに表示されます。プロモーションは、承認を受けるには特定の基準を満たしている必要があります。詳細については、プロモーションの条件をご覧ください。

商品にプロモーションを追加すると、ユーザーにスペシャル オファーのリンクが表示されます。たとえば、「15% オフ」、「送料無料」などです。商品リンクを使用すると、商品の魅力を高め、買い物客に購入を促すことができます。すべてのプロモーションはご購入手続き時または POS で適用されます。

詳しくは、プロモーションの基本をご覧ください。

前提条件

プロモーションを表示するには、お客様のビジネスと商品に関して具体的な情報を提供していただく必要があります。次の要件を満たしている必要があります。

また、販売者のアカウントをプロモーション プログラムに登録する必要があります。すでに登録されているかどうか不明な場合は、Merchant Center で確認してください。

登録されていない場合は、リクエスト フォームに入力します。実装を始める準備が整うと、プロモーション チームから通知が届きます。

詳しくは、参加条件とポリシーをご覧ください。

データソースを作成する

プロモーション データソースを作成するには、accounts.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}: データソースの商品の 2 文字の 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}"
}

プロモーション ID の設定に適用されるルールについては、プロモーション 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 に表示されるまで、数分かかることがあります。

複数のプロモーションを非同期で挿入する場合は、次のサンプルを使用できます。

Java
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>");
  }
}
InsertPromotionsAsyncSample.java

以下に、すぐに使用できるプロモーションの例を示します。

すべての商品とすべての店舗に適用されるローカル プロモーション

次のリクエスト例は、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 とプロモーションの ID が必要です。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 を使用して取得できるようになるまでには数分かかることに注意してください。

ローカル プロモーションを表示する

次のサンプル リクエストは、プロモーション ID が 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 フィールドを含めないと、ローカル在庫広告プロモーションでエラーが返されます。

オンライン プロモーションを表示する

次のサンプル リクエストは、プロモーション ID が 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 フィールドには、プロモーションの対象となる商品が記載されています。詳細については、プロモーションの商品 ID をご覧ください。

プロモーションを一覧表示する

作成されたすべてのプロモーションを表示するには、promotions.list メソッドを使用します。

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

レスポンスには、アカウント内のすべてのプロモーションのリストが含まれます。プロモーションごとに、promotionId、redemptionChannel、dataSource、promotionStatus などの詳細を確認できます。

プロモーションのステータスを確認する

プロモーションのステータスを確認するには、promotions.get メソッドまたは promotions.list メソッドによって返される promotionStatus 属性を確認します。

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": []
  }

詳しくは、プロモーションのステータスに関するよくある質問をご覧ください。

その他の情報