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

必須。固有 ID の一部として使用される対象国。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 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

出力専用。属性の名前（問題の原因が 1 つの属性の場合）。
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 アカウントのプロモーションが一覧表示されます。