Package google.shopping.merchant.promotions.v1beta

Index

PromotionsService

Service to manage promotions for products.

GetPromotion

rpc GetPromotion(GetPromotionRequest) returns (Promotion)

Retrieves the promotion from your Merchant Center account.

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

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/content

For more information, see the OAuth 2.0 Overview.
InsertPromotion

rpc InsertPromotion(InsertPromotionRequest) returns (Promotion)

Inserts a promotion for your Merchant Center account. If the promotion already exists, then it updates the promotion instead.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/content

For more information, see the OAuth 2.0 Overview.
ListPromotions

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

Lists the promotions in your Merchant Center account. The response might contain fewer items than specified by pageSize. Rely on pageToken to determine if there are more items to be requested.

After inserting or updating a promotion, it may take several minutes before the updated processed promotion can be retrieved.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/content

For more information, see the OAuth 2.0 Overview.

Attributes

Attributes.

Fields
product_applicability

ProductApplicability

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

OfferType

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

string

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

string

Required. Long title for the promotion.
coupon_value_type

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.
promotion_destinations[]

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
item_id_inclusion[]

string

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

string

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

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 [product_applicability] attribute is set to specific_products.
product_type_inclusion[]

string

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

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 product_applicability attribute is set to specific_products.
brand_exclusion[]

string

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

string

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

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 product_applicability attribute is set to specific_products.
minimum_purchase_amount

Price

Optional. Minimum purchase amount for the promotion.
minimum_purchase_quantity

int64

Optional. Minimum purchase quantity for the promotion.
limit_quantity

int64

Optional. Maximum purchase quantity for the promotion.
limit_value

Price

Optional. Maximum product price for promotion.
percent_off

int64

Optional. The percentage discount offered in the promotion.
money_off_amount

Price

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

int64

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.
free_gift_value

Price

Optional. Free gift value for the promotion.
free_gift_description

string

Optional. Free gift description for the promotion.
free_gift_item_id

string

Optional. Free gift item ID for the promotion.
promotion_effective_time_period

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.
promotion_display_time_period

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 promotion_display_time_period attribute is not specified, the promotion effective time period promotion_effective_time_period determines the date and time frame when the promotion will be live on Google.com and Shopping ads.
store_applicability

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 store_applicability is set to ALL_STORES and store_codes_inclusion or score_code_exclusion is set to a value.
store_codes_inclusion[]

string

Optional. Store codes to include for the promotion. The store filter attributes only applies when the store_applicability 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.
store_codes_exclusion[]

string

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

string

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

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. minimum_purchase_quantity and get_this_quantity_discounted must be present. money_off_amount must also be present.
BUY_M_GET_N_PERCENT_OFF Buy M quantity, get N percent off coupon value type. minimum_purchase_quantity and get_this_quantity_discounted must be present. percent_off_percentage must also be present.
BUY_M_GET_MONEY_OFF Buy M quantity, get money off. minimum_purchase_quantity and money_off_amount must be present.
BUY_M_GET_PERCENT_OFF Buy M quantity, get money off. minimum_purchase_quantity 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.

GetPromotionRequest

Request message for the GetPromotion method.

Fields
name

string

Required. The name of the promotion to retrieve. Format: accounts/{account}/promotions/{promotions}

InsertPromotionRequest

Request message for the InsertPromotion method.

Fields
parent

string

Required. The account where the promotion will be inserted. Format: accounts/{account}
promotion

Promotion

Required. The promotion to insert.
data_source

string

Required. The data source of the promotion Format: accounts/{account}/dataSources/{datasource}.

ListPromotionsRequest

Request message for the ListPromotions method.

Fields
parent

string

Required. The account to list processed promotions for. Format: accounts/{account}
page_size

int32

Output only. The maximum number of promotions to return. The service may return fewer than this value. The maximum value is 1000; values above 1000 will be coerced to 1000. If unspecified, the maximum number of promotions will be returned.
page_token

string

Output only. A page token, received from a previous ListPromotions call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListPromotions must match the call that provided the page token.

ListPromotionsResponse

Response message for the ListPromotions method.

Fields
promotions[]

Promotion

The processed promotions from the specified account.
next_page_token

string

A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

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.

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.

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.

Fields
name

string

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

string

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

string

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

Promotions is only for selected languages.
target_country

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
redemption_channel[]

RedemptionChannel

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

string

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

Attributes

Optional. A list of promotion attributes.
custom_attributes[]

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.
promotion_status

PromotionStatus

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

int64

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 version_number.

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

PromotionStatus

The status of the promotion.

Fields
destination_statuses[]

DestinationStatus

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

ItemLevelIssue

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

Timestamp

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
last_update_date

Timestamp

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.

Fields
reporting_context

ReportingContextEnum

Output only. The name of the promotion destination.
status

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.

Fields
code

string

Output only. The error code of the issue.
severity

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.
reporting_context

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.
applicable_countries[]

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.

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.

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.