REST Resource: accounts.promotions

リソース: Promotion

プロモーションを表します。詳しくは、次の記事をご覧ください。

データ検証チェックに合格するために必要なプロモーション入力属性は、主に以下のとおりです。

プロモーション入力を挿入または更新した後、最終的なプロモーションを取得できるようになるまでに数分かかることがあります。

JSON 表現 
{
  "name": string,
  "promotionId": string,
  "contentLanguage": string,
  "targetCountry": string,
  "redemptionChannel": [
    enum (RedemptionChannel)
  ],
  "dataSource": string,
  "attributes": {
    object (Attributes)
  },
  "customAttributes": [
    {
      object (CustomAttribute)
    }
  ],
  "promotionStatus": {
    object (PromotionStatus)
  },
  "versionNumber": string
}
フィールド
name

string

ID。プロモーションの名前。形式: accounts/{account}/promotions/{promotion}
promotionId

string

必須。プロモーションを一意に識別するユーザー提供のプロモーション ID。最小要件に沿ってプロモーションを作成すると、不承認を回避できます。
contentLanguage

string

必須。プロモーションの 2 文字の ISO 639-1 言語コード。

プロモーションは一部の言語でのみご利用いただけます。
targetCountry

string

必須。一意の識別子の一部として使用されるターゲット国。CLDR 地域コードで表されます。

プロモーションは、一部の国でのみ利用できます。無料リスティングとショッピング広告 ローカル在庫広告
redemptionChannel[]

enum (RedemptionChannel)

必須。プロモーションの利用チャネル。チャネルが少なくとも 1 つ必要です。
dataSource

string

出力専用。プロモーションのメイン データソース。
attributes

object (Attributes)

省略可。プロモーション属性のリスト。
customAttributes[]

object (CustomAttribute)

省略可。カスタム（販売者提供）属性のリスト。また、データ仕様の任意の属性を汎用形式（{ "name": "size type", "value": "regular" } など）で送信する場合にも使用できます。これは、API で明示的に公開されていない属性を送信する場合に便利です。
promotionStatus

object (PromotionStatus)

出力専用。プロモーションのステータス、データ検証の問題、つまり非同期で計算されたプロモーションに関する情報。
versionNumber

string (int64 format)

省略可。プロモーションの既存のバージョン（新しさ）を表します。複数の更新が同時に行われたときに正しい順序を維持するために使用できます。

設定すると、バージョン番号が既存のプロモーションの現在のバージョン番号より小さい場合、挿入がブロックされます。再挿入（30 日後のプロモーションの更新など）は、現在の versionNumber で実行できます。

オペレーションが防止された場合、中断された例外がスローされます。

RedemptionChannel

プロモーションのチャネル。

列挙型
REDEMPTION_CHANNEL_UNSPECIFIED チャンネルが指定されていないことを示します。
IN_STORE チャンネルがストアにあることを示します。これは、products に使用される local チャネルと同じです。
ONLINE チャネルがオンラインであることを示します。

属性

属性。

JSON 表現 
{
  "productApplicability": enum (ProductApplicability),
  "offerType": enum (OfferType),
  "genericRedemptionCode": string,
  "longTitle": string,
  "couponValueType": enum (CouponValueType),
  "promotionDestinations": [
    enum (DestinationEnum)
  ],
  "itemIdInclusion": [
    string
  ],
  "brandInclusion": [
    string
  ],
  "itemGroupIdInclusion": [
    string
  ],
  "productTypeInclusion": [
    string
  ],
  "itemIdExclusion": [
    string
  ],
  "brandExclusion": [
    string
  ],
  "itemGroupIdExclusion": [
    string
  ],
  "productTypeExclusion": [
    string
  ],
  "minimumPurchaseAmount": {
    object (Price)
  },
  "minimumPurchaseQuantity": string,
  "limitQuantity": string,
  "limitValue": {
    object (Price)
  },
  "percentOff": string,
  "moneyOffAmount": {
    object (Price)
  },
  "getThisQuantityDiscounted": string,
  "freeGiftValue": {
    object (Price)
  },
  "freeGiftDescription": string,
  "freeGiftItemId": string,
  "promotionEffectiveTimePeriod": {
    object (Interval)
  },
  "promotionDisplayTimePeriod": {
    object (Interval)
  },
  "storeApplicability": enum (StoreApplicability),
  "storeCodesInclusion": [
    string
  ],
  "storeCodesExclusion": [
    string
  ],
  "promotionUrl": string
}
フィールド
productApplicability

enum (ProductApplicability)

必須。プロモーションがすべての商品に適用されるか、特定の商品のみに適用されるか。
offerType

enum (OfferType)

必須。プロモーションのタイプ。この属性を使用して、プロモーションを利用するのにクーポンコードが必要かどうかを指定します。
genericRedemptionCode

string

省略可。プロモーションの汎用適用コード。offerType フィールドで使用し、最小要件を満たしている必要があります。
longTitle

string

必須。プロモーションの長いタイトル。
couponValueType

enum (CouponValueType)

必須。実施しているプロモーションのタイプを示すには、クーポンの値タイプ属性を使用します。選択したクーポンの値のタイプによっては、一部の属性が必須となります。
promotionDestinations[]

enum (DestinationEnum)

必須。プロモーションが適用されるデスティネーションのリスト。データソースにサポートされている値を追加して掲載先を指定していない場合、プロモーションはデフォルトでショッピング広告および無料リスティングに表示されます。

商品の掲載先として、ショッピング アクション、Google 掲載、ローカル情報 Google 掲載の値を以前に送信している場合はご注意ください。これらの値を表すには、FREE_LISTINGS、FREE_LOCAL_LISTINGS、LOCAL_INVENTORY_ADS を使用します。詳しくは、プロモーションのリンク先をご覧ください。
itemIdInclusion[]

string

省略可。プロモーションの商品アイテム ID による商品フィルタ。商品フィルタ属性は、プロモーションの対象商品 productApplicability 属性が specific_products に設定されている場合にのみ適用されます。
brandInclusion[]

string

省略可。プロモーションのブランドで商品をフィルタします。商品フィルタ属性は、プロモーションの対象商品 productApplicability 属性が specific_products に設定されている場合にのみ適用されます。
itemGroupIdInclusion[]

string

省略可。プロモーションの商品アイテム ID による商品フィルタ。商品フィルタ属性は、プロモーションの対象商品 [productApplicability] 属性が specific_products に設定されている場合にのみ適用されます。
productTypeInclusion[]

string

省略可。プロモーションの商品カテゴリで商品をフィルタします。商品フィルタ属性は、プロモーションの対象商品 productApplicability 属性が specific_products に設定されている場合にのみ適用されます。
itemIdExclusion[]

string

省略可。プロモーションの商品アイテム ID の除外による商品フィルタ。商品フィルタ属性は、プロモーションの対象商品 productApplicability 属性が specific_products に設定されている場合にのみ適用されます。
brandExclusion[]

string

省略可。プロモーションのブランド除外による商品フィルタ。商品フィルタ属性は、プロモーションの対象商品 productApplicability 属性が specific_products に設定されている場合にのみ適用されます。
itemGroupIdExclusion[]

string

省略可。商品グループ ID で商品をフィルタします。商品フィルタ属性は、プロモーションの対象商品 productApplicability 属性が specific_products に設定されている場合にのみ適用されます。
productTypeExclusion[]

string

省略可。プロモーションの商品カテゴリの除外による商品フィルタ。商品フィルタ属性は、プロモーションの対象商品 productApplicability 属性が specific_products に設定されている場合にのみ適用されます。
minimumPurchaseAmount

object (Price)

省略可。プロモーションの最小購入金額。
minimumPurchaseQuantity

string (int64 format)

省略可。プロモーションの最小購入数量。
limitQuantity

string (int64 format)

省略可。プロモーションの対象となる購入数の上限。
limitValue

object (Price)

省略可。プロモーションの商品価格の上限。
percentOff

string (int64 format)

省略可。プロモーションで提供される割引率。
moneyOffAmount

object (Price)

省略可。プロモーションで提供される割引額。
getThisQuantityDiscounted

string (int64 format)

省略可。プロモーションで割引対象となったアイテムの数。この属性は、couponValueType が buy_m_get_n_money_off または buy_m_get_n_percent_off に等しい場合に設定されます。
freeGiftValue

object (Price)

省略可。プロモーションのプレゼントの金額。
freeGiftDescription

string

省略可。プロモーションのプレゼントの説明。
freeGiftItemId

string

省略可。プロモーションのプレゼント アイテム ID。
promotionEffectiveTimePeriod

object (Interval)

必須。TimePeriod プロモーションの有効期間を表します。この属性は、この期間中にオンライン ショップでプロモーションをテストできることを指定します。
promotionDisplayTimePeriod

object (Interval)

省略可。TimePeriod プロモーションの表示期間の表現。この属性では、プロモーションが Google.com とショッピング広告で公開される期間を指定します。プロモーションの表示期間 promotionDisplayTimePeriod 属性が指定されていない場合、プロモーションの有効期間 promotionEffectiveTimePeriod によって、プロモーションが Google.com とショッピング広告で公開される期間が決まります。
storeApplicability

enum (StoreApplicability)

省略可。プロモーションがすべての店舗に適用されるか、特定の店舗のみに適用されるか。店舗の適用性が指定されていない場合、ローカル在庫広告のプロモーションでエラーが発生します。storeApplicability が ALL_STORES に設定され、storeCodesInclusion または score_code_exclusion が値に設定されている場合、INVALID_ARGUMENT エラーがスローされます。
storeCodesInclusion[]

string

省略可。プロモーションに含めるストアコード。店舗フィルタ属性は、storeApplicability 属性が specific_stores に設定されている場合にのみ適用されます。

商品が販売されている実店舗の店舗コード（ビジネス プロフィールの店舗 ID）。詳しくは、ローカル商品在庫データ仕様をご覧ください。
storeCodesExclusion[]

string

省略可。プロモーションの除外する店舗コード。店舗フィルタ属性は、storeApplicability 属性が specific_stores に設定されている場合にのみ適用されます。
promotionUrl

string

省略可。プロモーションが表示される販売者のサイトのページの URL。promotionUrl が含まれていない場合、ローカル在庫広告のプロモーションでエラーが発生します。URL は、プロモーションが有効で利用可能であることを確認するために使用されます。

ProductApplicability

プロモーションが適用される商品または商品リスト。

列挙型
PRODUCT_APPLICABILITY_UNSPECIFIED プロモーションが適用される商品が不明です。
ALL_PRODUCTS すべてのプロダクトが対象です。
SPECIFIC_PRODUCTS 単一の商品または商品リストにのみ適用されます。

OfferType

プロモーションのオファーの種類。

列挙型
OFFER_TYPE_UNSPECIFIED 不明なオファーの種類。
NO_CODE コードなしのオファータイプ。
GENERIC_CODE コード付きのオファーの種類。offerType = GENERIC_CODE の場合、プロモーションの汎用適用コードが必要です。

CouponValueType

プロモーションのクーポンの値タイプ。

列挙型
COUPON_VALUE_TYPE_UNSPECIFIED クーポンの値タイプが指定されていないことを示します。
MONEY_OFF 割引クーポンの値タイプ。
PERCENT_OFF 割引率のクーポンの値タイプ。
BUY_M_GET_N_MONEY_OFF m 個購入で n 円割引のクーポンの値タイプ。minimumPurchaseQuantity と getThisQuantityDiscounted が存在している必要があります。moneyOffAmount も存在している必要があります。
BUY_M_GET_N_PERCENT_OFF m 個購入で n% 割引のクーポン値タイプの値。minimumPurchaseQuantity と getThisQuantityDiscounted が存在している必要があります。percent_off_percentage も存在している必要があります。
BUY_M_GET_MONEY_OFF m 個購入で一定額割引。minimumPurchaseQuantity と moneyOffAmount が存在している必要があります。
BUY_M_GET_PERCENT_OFF m 個購入で一定額割引。minimumPurchaseQuantity と percent_off_percentage が存在している必要があります。
FREE_GIFT 説明のみのプレゼント。
FREE_GIFT_WITH_VALUE 金額が対象のプレゼント。
FREE_GIFT_WITH_ITEM_ID 商品アイテム ID が対象のプレゼント。
FREE_SHIPPING_STANDARD 標準の送料無料クーポンの値タイプ。オンライン プロモーションにのみ使用できます。
FREE_SHIPPING_OVERNIGHT 翌日配達無料クーポンの値タイプ。オンライン プロモーションにのみ使用できます。
FREE_SHIPPING_TWO_DAY 2 日間送料無料クーポンの値タイプ。オンライン プロモーションにのみ使用できます。

DestinationEnum

リンク先の値。

列挙型
DESTINATION_ENUM_UNSPECIFIED 指定されていません。
SHOPPING_ADS ショッピング広告。
DISPLAY_ADS ディスプレイ広告。
LOCAL_INVENTORY_ADS ローカル在庫広告。
FREE_LISTINGS 無料リスティング。
FREE_LOCAL_LISTINGS 無料ローカル商品リスティング。
YOUTUBE_SHOPPING YouTube ショッピング。
YOUTUBE_SHOPPING_CHECKOUT YouTube ショッピングの購入手続き。
YOUTUBE_AFFILIATE YouTube アフィリエイト。
FREE_VEHICLE_LISTINGS 無料車両リスティング。
VEHICLE_ADS 車両広告。
CLOUD_RETAIL クラウド小売。
LOCAL_CLOUD_RETAIL ローカル Cloud Retail。

StoreApplicability

プロモーションが適用される店舗コードまたは店舗コードのリスト。ローカル在庫広告のプロモーションにのみ使用できます。

列挙型
STORE_APPLICABILITY_UNSPECIFIED プロモーションが適用される店舗コードが不明です。
ALL_STORES プロモーションはすべての店舗に適用されます。
SPECIFIC_STORES プロモーションは指定した店舗にのみ適用されます。

PromotionStatus

プロモーションのステータス。

JSON 表現 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
フィールド
destinationStatuses[]

object (DestinationStatus)

出力専用。プロモーションの掲載先。
itemLevelIssues[]

object (ItemLevelIssue)

出力専用。プロモーションに関連する問題のリスト。
creationDate

string (Timestamp format)

出力専用。プロモーションが作成された日付（ISO 8601 形式: 日付、時刻、オフセット。例: 2020-01-02T09:00:00+01:00、2020-01-02T09:00:00Z）。
lastUpdateDate

string (Timestamp format)

出力専用。プロモーション ステータスが最後に更新された日付（ISO 8601 形式の日付、時刻、オフセット。例: 2020-01-02T09:00:00+01:00、2020-01-02T09:00:00Z）。

DestinationStatus

指定された宛先のステータス。

JSON 表現 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
フィールド
reportingContext

enum (ReportingContextEnum)

出力専用。プロモーションのリンク先の名前。
status

enum (State)

出力専用。指定された宛先のステータス。

州

プロモーションの現在のステータス。

列挙型
STATE_UNSPECIFIED プロモーションの状態が不明です。
IN_REVIEW プロモーションは審査中です。
REJECTED プロモーションが不承認です。
LIVE プロモーションが承認され、有効になっている。
STOPPED 販売者によってプロモーションが停止されています。
EXPIRED プロモーションは終了しています。
PENDING プロモーションは停止されておらず、すべての審査が承認されていますが、有効日が将来の日付になっています。

ItemLevelIssue

プロモーションに関連する問題。

JSON 表現 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
フィールド
code

string

出力専用。問題のエラーコード。
severity

enum (Severity)

出力専用。この問題によるプロモーションの配信への影響。
resolution

string

出力専用。販売者側で問題が解決可能かどうか。
attribute

string

出力専用。属性名（問題の原因が単一属性の場合）。
reportingContext

enum (ReportingContextEnum)

出力専用。問題の適用先。
description

string

出力専用。問題の簡単な説明（英語）。
detail

string

出力専用。問題の詳しい説明（英語）。
documentation

string

出力専用。この問題の解決に役立つウェブページの URL。
applicableCountries[]

string

出力専用。問題が商品に適用される国コード（ISO 3166-1 alpha-2）のリスト。

重大度

問題の重大度。

列挙型
SEVERITY_UNSPECIFIED 指定されていません。
NOT_IMPACTED この問題は警告であり、プロモーションには直接影響しません。
DEMOTED プロモーションが降格され、検索結果でのパフォーマンスが制限される可能性が高い
DISAPPROVED 問題によりプロモーションが不承認になる。

メソッド

get

 Merchant Center アカウントからプロモーションを取得します。

insert

 Merchant Center アカウントのプロモーションを挿入します。

list

 Merchant Center アカウントのプロモーションを一覧表示します。