REST Resource: promotions

Resource: Promotion

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

JSON representation 
{
  "id": string,
  "targetCountry": string,
  "contentLanguage": string,
  "promotionId": string,
  "productApplicability": enum (ProductApplicability),
  "offerType": enum (OfferType),
  "longTitle": string,
  "promotionEffectiveDates": string,
  "redemptionChannel": [
    enum (RedemptionChannel)
  ],
  "couponValueType": enum (CouponValueType),
  "promotionDestinationIds": [
    string
  ],
  "itemId": [
    string
  ],
  "brand": [
    string
  ],
  "itemGroupId": [
    string
  ],
  "productType": [
    string
  ],
  "itemIdExclusion": [
    string
  ],
  "brandExclusion": [
    string
  ],
  "itemGroupIdExclusion": [
    string
  ],
  "productTypeExclusion": [
    string
  ],
  "shippingServiceNames": [
    string
  ],
  "promotionEffectiveTimePeriod": {
    object (TimePeriod)
  },
  "storeCode": [
    string
  ],
  "storeCodeExclusion": [
    string
  ],
  "promotionStatus": {
    object (PromotionStatus)
  },
  "genericRedemptionCode": string,
  "promotionDisplayDates": string,
  "minimumPurchaseAmount": {
    object (PriceAmount)
  },
  "minimumPurchaseQuantity": integer,
  "limitQuantity": integer,
  "limitValue": {
    object (PriceAmount)
  },
  "percentOff": integer,
  "moneyOffAmount": {
    object (PriceAmount)
  },
  "getThisQuantityDiscounted": integer,
  "freeGiftValue": {
    object (PriceAmount)
  },
  "freeGiftDescription": string,
  "freeGiftItemId": string,
  "moneyBudget": {
    object (PriceAmount)
  },
  "orderLimit": integer,
  "promotionDisplayTimePeriod": {
    object (TimePeriod)
  },
  "storeApplicability": enum (StoreApplicability),
  "promotionUrl": string
}
Fields
id

string

Output only. The REST promotion ID to uniquely identify the promotion. Content API methods that operate on promotions take this as their promotionId parameter. The REST ID for a promotion is of the form

channel:contentLanguage:targetCountry:promotionId

The channel field has a value of "online", "in_store", or "online_in_store".
targetCountry

string

Required. The target country used as part of the unique identifier. Can be AU, CA, DE, FR, GB, IN, US, BR, ES, NL, JP, IT or KR.
contentLanguage

string

Required. The content language used as part of the unique identifier. en content language is available for all target countries. fr content language is available for CA and FR target countries. de content language is available for DE target country. nl content language is available for NL target country. it content language is available for IT target country. pt content language is available for BR target country. ja content language is available for JP target country. ko content language is available for KR target country.
promotionId

string

Required. The user provided promotion ID to uniquely identify the promotion.
productApplicability

enum (ProductApplicability)

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

enum (OfferType)

Required. Type of the promotion.
longTitle

string

Required. Long title for the promotion.
promotionEffectiveDates
(deprecated)

string

String representation of the promotion effective dates.

Deprecated. Use promotionEffectiveTimePeriod instead.
redemptionChannel[]

enum (RedemptionChannel)

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

enum (CouponValueType)

Required. Coupon value type for the promotion.
promotionDestinationIds[]

string

Destination ID for the promotion.
itemId[]

string

Product filter by item ID for the promotion.
brand[]

string

Product filter by brand for the promotion.
itemGroupId[]

string

Product filter by item group ID for the promotion.
productType[]

string

Product filter by product type for the promotion.
itemIdExclusion[]

string

Product filter by item ID exclusion for the promotion.
brandExclusion[]

string

Product filter by brand exclusion for the promotion.
itemGroupIdExclusion[]

string

Product filter by item group ID exclusion for the promotion.
productTypeExclusion[]

string

Product filter by product type exclusion for the promotion.
shippingServiceNames[]

string

Shipping service names for the promotion.
promotionEffectiveTimePeriod

object (TimePeriod)

Required. TimePeriod representation of the promotion's effective dates.
storeCode[]

string

Store codes to include for the promotion.
storeCodeExclusion[]

string

Store codes to exclude for the promotion.
promotionStatus

object (PromotionStatus)

Output only. The current status of the promotion.
genericRedemptionCode

string

Generic redemption code for the promotion. To be used with the offerType field.
promotionDisplayDates
(deprecated)

string

String representation of the promotion display dates.

Deprecated. Use promotionDisplayTimePeriod instead.
minimumPurchaseAmount

object (PriceAmount)

Minimum purchase amount for the promotion.
minimumPurchaseQuantity

integer

Minimum purchase quantity for the promotion.
limitQuantity

integer

Maximum purchase quantity for the promotion.
limitValue

object (PriceAmount)

Maximum purchase value for the promotion.
percentOff

integer

The percentage discount offered in the promotion.
moneyOffAmount

object (PriceAmount)

The money off amount offered in the promotion.
getThisQuantityDiscounted

integer

The number of items discounted in the promotion.
freeGiftValue

object (PriceAmount)

Free gift value for the promotion.
freeGiftDescription

string

Free gift description for the promotion.
freeGiftItemId

string

Free gift item ID for the promotion.
moneyBudget

object (PriceAmount)

Cost cap for the promotion.
orderLimit

integer

Order limit for the promotion.
promotionDisplayTimePeriod

object (TimePeriod)

TimePeriod representation of the promotion's display dates.
storeApplicability

enum (StoreApplicability)

Whether the promotion applies to all stores, or only specified stores. Local pos.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 storeCode or score_code_exclusion is set to a value.
promotionUrl

string

URL to the page on the merchant's site where the promotion shows. Local pos.inventory ads promotions throw an error if no promo url 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.

RedemptionChannel

Channel of a promotion.

Enums
REDEMPTION_CHANNEL_UNSPECIFIED Indicates that the channel is unspecified.
IN_STORE Indicates that the channel is in store.
ONLINE Indicates that the channel is online.

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. buy_this_quantity and get_this_quantity must be present. moneyOffAmount must also be present.
BUY_M_GET_N_PERCENT_OFF Buy M quantity, get N percent off coupon value type. buy_this_quantity and get_this_quantity must be present. percent_off_percentage must also be present.
BUY_M_GET_MONEY_OFF Buy M quantity, get money off. buy_this_quantity and moneyOffAmount must be present.
BUY_M_GET_PERCENT_OFF Buy M quantity, get money off. buy_this_quantity and percent_off_percentage must be present.
FREE_GIFT Free gift with description only.
FREE_GIFT_WITH_VALUE Free gift with value (description is optional).
FREE_GIFT_WITH_ITEM_ID Free gift with item ID (description is optional).
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.

TimePeriod

A message that represents a time period.

JSON representation 
{
  "startTime": string,
  "endTime": string
}
Fields
startTime

string (Timestamp format)

The starting timestamp.
endTime

string (Timestamp format)

The ending timestamp.

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)
    }
  ],
  "promotionIssue": [
    {
      object (PromotionIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
Fields
destinationStatuses[]

object (DestinationStatus)

The intended destinations for the promotion.
promotionIssue[]

object (PromotionIssue)

A list of issues associated with the promotion.
creationDate

string

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

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 destination status of the promotion.

JSON representation 
{
  "destination": string,
  "status": enum (State)
}
Fields
destination

string

The name of the destination.
status

enum (State)

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.

PromotionIssue

The issue associated with the promotion.

JSON representation 
{
  "code": string,
  "detail": string
}
Fields
code

string

Code of the issue.
detail

string

Explanation of the issue.

Methods

create

 Inserts a promotion for your Merchant Center account.

get

 Retrieves a promotion from your Merchant Center account.

list

 List all promotions from your Merchant Center account.