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)

必須。実施しているプロモーションのタイプを示す coupon value type 属性。選択したクーポンの値の種類に応じて、いくつかの属性が必須です。
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 1 つの商品または商品リストにのみ適用されます。

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 ショッピング。

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 アカウントのプロモーションが一覧表示されます。