REST Resource: accounts.promotions

Resource: Promotion

Represents a promotion. See the following articles for more details.

Required promotion input attributes to pass data validation checks are primarily defined below:

After inserting, updating a promotion input, it may take several minutes before the final promotion can be retrieved.

JSON representation 
{
  "name": string,
  "promotionId": string,
  "contentLanguage": string,
  "targetCountry": string,
  "redemptionChannel": [
    enum (RedemptionChannel)
  ],
  "dataSource": string,
  "attributes": {
    object (Attributes)
  },
  "customAttributes": [
    {
      object (CustomAttribute)
    }
  ],
  "promotionStatus": {
    object (PromotionStatus)
  },
  "versionNumber": string
}
Fields
name

string

Identifier. The name of the promotion. Format: accounts/{account}/promotions/{promotion}
promotionId

string

Required. The user provided promotion ID to uniquely identify the promotion. Follow minimum requirements to prevent promotion disapprovals.
contentLanguage

string

Required. The two-letter ISO 639-1 language code for the promotion.

Promotions is only for selected languages.
targetCountry

string

Required. The target country used as part of the unique identifier. Represented as a CLDR territory code.

Promotions are only available in selected countries, Free Listings and Shopping ads Local Inventory ads
redemptionChannel[]

enum (RedemptionChannel)

Required. Redemption channel for the promotion. At least one channel is required.
dataSource

string

Output only. The primary data source of the promotion.
attributes

object (Attributes)

Optional. A list of promotion attributes.
customAttributes[]

object (CustomAttribute)

Optional. A list of custom (merchant-provided) attributes. It can also be used for submitting any attribute of the data specification in its generic form (for example, { "name": "size type", "value": "regular" }). This is useful for submitting attributes not explicitly exposed by the API.
promotionStatus

object (PromotionStatus)

Output only. The status of a promotion, data validation issues, that is, information about a promotion computed asynchronously.
versionNumber

string (int64 format)

Optional. Represents the existing version (freshness) of the promotion, which can be used to preserve the right order when multiple updates are done at the same time.

If set, the insertion is prevented when version number is lower than the current version number of the existing promotion. Re-insertion (for example, promotion refresh after 30 days) can be performed with the current versionNumber.

If the operation is prevented, the aborted exception will be thrown.

RedemptionChannel

Channel of a promotion.

Enums
REDEMPTION_CHANNEL_UNSPECIFIED Indicates that the channel is unspecified.
IN_STORE Indicates that the channel is in store. This is same as local channel used for products.
ONLINE Indicates that the channel is online.

Attributes

Attributes.

JSON representation 
{
  "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
}
Fields
productApplicability

enum (ProductApplicability)

Required. Applicability of the promotion to either all products or only specific products.
offerType

enum (OfferType)

Required. Type of the promotion. Use this attribute to indicate whether or not customers need a coupon code to redeem your promotion.
genericRedemptionCode

string

Optional. Generic redemption code for the promotion. To be used with the offerType field and must meet the minimum requirements.
longTitle

string

Required. Long title for the promotion.
couponValueType

enum (CouponValueType)

Required. The coupon value type attribute to signal the type of promotion that you are running. Depending on type of the selected coupon value some attributes are required.
promotionDestinations[]

enum (DestinationEnum)

Required. The list of destinations where the promotion applies to. If you don't specify a destination by including a supported value in your data source, your promotion will display in Shopping ads and free listings by default.

You may have previously submitted the following values as destinations for your products: Shopping Actions, Surfaces across Google, Local surfaces across Google. To represent these values use FREE_LISTINGS, FREE_LOCAL_LISTINGS, LOCAL_INVENTORY_ADS. For more details see Promotion destination
itemIdInclusion[]

string

Optional. Product filter by item ID for the promotion. The product filter attributes only applies when the products eligible for promotion product applicability productApplicability attribute is set to specific_products.
brandInclusion[]

string

Optional. Product filter by brand for the promotion. The product filter attributes only applies when the products eligible for promotion product applicability productApplicability attribute is set to specific_products.
itemGroupIdInclusion[]

string

Optional. Product filter by item group ID for the promotion. The product filter attributes only applies when the products eligible for promotion product applicability [productApplicability] attribute is set to specific_products.
productTypeInclusion[]

string

Optional. Product filter by product type for the promotion. The product filter attributes only applies when the products eligible for promotion product applicability productApplicability attribute is set to specific_products.
itemIdExclusion[]

string

Optional. Product filter by item ID exclusion for the promotion. The product filter attributes only applies when the products eligible for promotion product applicability productApplicability attribute is set to specific_products.
brandExclusion[]

string

Optional. Product filter by brand exclusion for the promotion. The product filter attributes only applies when the products eligible for promotion product applicability productApplicability attribute is set to specific_products.
itemGroupIdExclusion[]

string

Optional. Product filter by item group ID. The product filter attributes only applies when the products eligible for promotion product applicability productApplicability attribute is set to specific_products. exclusion for the promotion.
productTypeExclusion[]

string

Optional. Product filter by product type exclusion for the promotion. The product filter attributes only applies when the products eligible for promotion product applicability productApplicability attribute is set to specific_products.
minimumPurchaseAmount

object (Price)

Optional. Minimum purchase amount for the promotion.
minimumPurchaseQuantity

string (int64 format)

Optional. Minimum purchase quantity for the promotion.
limitQuantity

string (int64 format)

Optional. Maximum purchase quantity for the promotion.
limitValue

object (Price)

Optional. Maximum product price for promotion.
percentOff

string (int64 format)

Optional. The percentage discount offered in the promotion.
moneyOffAmount

object (Price)

Optional. The money off amount offered in the promotion.
getThisQuantityDiscounted

string (int64 format)

Optional. The number of items discounted in the promotion. The attribute is set when couponValueType is equal to buy_m_get_n_money_off or buy_m_get_n_percent_off.
freeGiftValue

object (Price)

Optional. Free gift value for the promotion.
freeGiftDescription

string

Optional. Free gift description for the promotion.
freeGiftItemId

string

Optional. Free gift item ID for the promotion.
promotionEffectiveTimePeriod

object (Interval)

Required. TimePeriod representation of the promotion's effective dates. This attribute specifies that the promotion can be tested on your online store during this time period.
promotionDisplayTimePeriod

object (Interval)

Optional. TimePeriod representation of the promotion's display dates. This attribute specifies the date and time frame when the promotion will be live on Google.com and Shopping ads. If the display time period for promotion promotionDisplayTimePeriod attribute is not specified, the promotion effective time period promotionEffectiveTimePeriod determines the date and time frame when the promotion will be live on Google.com and Shopping ads.
storeApplicability

enum (StoreApplicability)

Optional. Whether the promotion applies to all stores, or only specified stores. Local Inventory ads promotions throw an error if no store applicability is included. An INVALID_ARGUMENT error is thrown if storeApplicability is set to ALL_STORES and storeCodesInclusion or score_code_exclusion is set to a value.
storeCodesInclusion[]

string

Optional. Store codes to include for the promotion. The store filter attributes only applies when the storeApplicability attribute is set to specific_stores.

Store code (the store ID from your Business Profile) of the physical store the product is sold in. See the Local product inventory data specification for more information.
storeCodesExclusion[]

string

Optional. Store codes to exclude for the promotion. The store filter attributes only applies when the storeApplicability attribute is set to specific_stores.
promotionUrl

string

Optional. URL to the page on the merchant's site where the promotion shows. Local Inventory ads promotions throw an error if no promotionUrl is included. URL is used to confirm that the promotion is valid and can be redeemed.

ProductApplicability

Which product or list of products the promotion applies to.

Enums
PRODUCT_APPLICABILITY_UNSPECIFIED Which products the promotion applies to is unknown.
ALL_PRODUCTS Applicable to all products.
SPECIFIC_PRODUCTS Applicable to only a single product or list of products.

OfferType

Offer type of a promotion.

Enums
OFFER_TYPE_UNSPECIFIED Unknown offer type.
NO_CODE Offer type without a code.
GENERIC_CODE Offer type with a code. Generic redemption code for the promotion is required when offerType = GENERIC_CODE.

CouponValueType

Coupon value type of a promotion.

Enums
COUPON_VALUE_TYPE_UNSPECIFIED Indicates that the coupon value type is unspecified.
MONEY_OFF Money off coupon value type.
PERCENT_OFF Percent off coupon value type.
BUY_M_GET_N_MONEY_OFF Buy M quantity, get N money off coupon value type. minimumPurchaseQuantity and getThisQuantityDiscounted must be present. moneyOffAmount must also be present.
BUY_M_GET_N_PERCENT_OFF Buy M quantity, get N percent off coupon value type. minimumPurchaseQuantity and getThisQuantityDiscounted must be present. percent_off_percentage must also be present.
BUY_M_GET_MONEY_OFF Buy M quantity, get money off. minimumPurchaseQuantity and moneyOffAmount must be present.
BUY_M_GET_PERCENT_OFF Buy M quantity, get money off. minimumPurchaseQuantity and percent_off_percentage must be present.
FREE_GIFT Free gift with description only.
FREE_GIFT_WITH_VALUE Free gift with monetary value.
FREE_GIFT_WITH_ITEM_ID Free gift with item ID.
FREE_SHIPPING_STANDARD Standard free shipping coupon value type.
FREE_SHIPPING_OVERNIGHT Overnight free shipping coupon value type.
FREE_SHIPPING_TWO_DAY Two day free shipping coupon value type.

DestinationEnum

Destination values.

Enums
DESTINATION_ENUM_UNSPECIFIED Not specified.
SHOPPING_ADS Shopping ads.
DISPLAY_ADS Display ads.
LOCAL_INVENTORY_ADS Local inventory ads.
FREE_LISTINGS Free listings.
FREE_LOCAL_LISTINGS Free local product listings.
YOUTUBE_SHOPPING YouTube Shopping.
YOUTUBE_SHOPPING_CHECKOUT Youtube shopping checkout.
YOUTUBE_AFFILIATE Youtube affiliate.
FREE_VEHICLE_LISTINGS Free vehicle listings.
VEHICLE_ADS Vehicle ads.
CLOUD_RETAIL Cloud retail.
LOCAL_CLOUD_RETAIL Local cloud retail.

StoreApplicability

Store codes or list of store codes the promotion applies to. Only for Local inventory ads promotions.

Enums
STORE_APPLICABILITY_UNSPECIFIED Which store codes the promotion applies to is unknown.
ALL_STORES Promotion applies to all stores.
SPECIFIC_STORES Promotion applies to only the specified stores.

PromotionStatus

The status of the promotion.

JSON representation 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
Fields
destinationStatuses[]

object (DestinationStatus)

Output only. The intended destinations for the promotion.
itemLevelIssues[]

object (ItemLevelIssue)

Output only. A list of issues associated with the promotion.
creationDate

string (Timestamp format)

Output only. Date on which the promotion has been created in ISO 8601 format: Date, time, and offset, for example 2020-01-02T09:00:00+01:00 or 2020-01-02T09:00:00Z
lastUpdateDate

string (Timestamp format)

Output only. Date on which the promotion status has been last updated in ISO 8601 format: Date, time, and offset, for example 2020-01-02T09:00:00+01:00 or 2020-01-02T09:00:00Z

DestinationStatus

The status for the specified destination.

JSON representation 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
Fields
reportingContext

enum (ReportingContextEnum)

Output only. The name of the promotion destination.
status

enum (State)

Output only. The status for the specified destination.

State

The current state of the promotion.

Enums
STATE_UNSPECIFIED Unknown promotion state.
IN_REVIEW The promotion is under review.
REJECTED The promotion is disapproved.
LIVE The promotion is approved and active.
STOPPED The promotion is stopped by merchant.
EXPIRED The promotion is no longer active.
PENDING The promotion is not stopped, and all reviews are approved, but the active date is in the future.

ItemLevelIssue

The issue associated with the promotion.

JSON representation 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
Fields
code

string

Output only. The error code of the issue.
severity

enum (Severity)

Output only. How this issue affects serving of the promotion.
resolution

string

Output only. Whether the issue can be resolved by the merchant.
attribute

string

Output only. The attribute's name, if the issue is caused by a single attribute.
reportingContext

enum (ReportingContextEnum)

Output only. The destination the issue applies to.
description

string

Output only. A short issue description in English.
detail

string

Output only. A detailed issue description in English.
documentation

string

Output only. The URL of a web page to help with resolving this issue.
applicableCountries[]

string

Output only. List of country codes (ISO 3166-1 alpha-2) where issue applies to the offer.

Severity

The severity of the issue.

Enums
SEVERITY_UNSPECIFIED Not specified.
NOT_IMPACTED This issue represents a warning and does not have a direct affect on the promotion.
DEMOTED The promotion is demoted and most likely have limited performance in search results
DISAPPROVED Issue disapproves the promotion.

Methods

get

 Retrieves the promotion from your Merchant Center account.

insert

 Inserts a promotion for your Merchant Center account.

list

 Lists the promotions in your Merchant Center account.