{ "rootUrl": "https://merchantapi.googleapis.com/", "discoveryVersion": "v1", "resources": { "accounts": { "resources": { "promotions": { "methods": { "list": { "httpMethod": "GET", "id": "merchantapi.accounts.promotions.list", "parameterOrder": [ "parent" ], "path": "promotions/v1/{+parent}/promotions", "parameters": { "pageSize": { "description": "Optional. The maximum number of promotions to return. The service may return fewer than this value. The maximum value is 250; values above 250 will be coerced to 250. If unspecified, the maximum number of promotions will be returned.", "format": "int32", "location": "query", "type": "integer" }, "pageToken": { "location": "query", "type": "string", "description": "Optional. 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." }, "parent": { "description": "Required. The account to list processed promotions for. Format: `accounts/{account}`", "required": true, "type": "string", "pattern": "^accounts/[^/]+$", "location": "path" } }, "flatPath": "promotions/v1/accounts/{accountsId}/promotions", "description": "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.", "scopes": [ "https://www.googleapis.com/auth/content" ], "response": { "$ref": "ListPromotionsResponse" } }, "insert": { "description": "Inserts a promotion for your Merchant Center account. If the promotion already exists, then it updates the promotion instead.", "scopes": [ "https://www.googleapis.com/auth/content" ], "response": { "$ref": "Promotion" }, "httpMethod": "POST", "request": { "$ref": "InsertPromotionRequest" }, "id": "merchantapi.accounts.promotions.insert", "parameterOrder": [ "parent" ], "path": "promotions/v1/{+parent}/promotions:insert", "parameters": { "parent": { "location": "path", "pattern": "^accounts/[^/]+$", "required": true, "type": "string", "description": "Required. The account where the promotion will be inserted. Format: accounts/{account}" } }, "flatPath": "promotions/v1/accounts/{accountsId}/promotions:insert" }, "get": { "httpMethod": "GET", "id": "merchantapi.accounts.promotions.get", "parameterOrder": [ "name" ], "path": "promotions/v1/{+name}", "parameters": { "name": { "pattern": "^accounts/[^/]+/promotions/[^/]+$", "location": "path", "description": "Required. The name of the promotion to retrieve. Format: `accounts/{account}/promotions/{promotions}`", "required": true, "type": "string" } }, "flatPath": "promotions/v1/accounts/{accountsId}/promotions/{promotionsId}", "description": "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.", "scopes": [ "https://www.googleapis.com/auth/content" ], "response": { "$ref": "Promotion" } } } } } } }, "schemas": { "Price": { "id": "Price", "type": "object", "description": "The price represented as a number and currency.", "properties": { "amountMicros": { "description": "The price represented as a number in micros (1 million micros is an equivalent to one's currency standard unit, for example, 1 USD = 1000000 micros).", "format": "int64", "type": "string" }, "currencyCode": { "description": "The currency of the price using three-letter acronyms according to [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217).", "type": "string" } } }, "PromotionStatus": { "id": "PromotionStatus", "type": "object", "properties": { "destinationStatuses": { "description": "Output only. The intended destinations for the promotion.", "items": { "$ref": "DestinationStatus" }, "readOnly": true, "type": "array" }, "itemLevelIssues": { "type": "array", "readOnly": true, "description": "Output only. A list of issues associated with the promotion.", "items": { "$ref": "ItemLevelIssue" } }, "lastUpdateDate": { "type": "string", "description": "Output only. Date on which the promotion status has been last updated in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format: Date, time, and offset, for example `2020-01-02T09:00:00+01:00` or `2020-01-02T09:00:00Z`", "format": "google-datetime", "readOnly": true }, "creationDate": { "readOnly": true, "description": "Output only. Date on which the promotion has been created in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format: Date, time, and offset, for example `2020-01-02T09:00:00+01:00` or `2020-01-02T09:00:00Z`", "format": "google-datetime", "type": "string" } }, "description": "The status of the promotion." }, "ProductStatusChangeMessage": { "id": "ProductStatusChangeMessage", "type": "object", "description": "The message that the merchant will receive to notify about product status change event", "properties": { "eventTime": { "type": "string", "description": "The time at which the event was generated. If you want to order the notification messages you receive you should rely on this field not on the order of receiving the notifications.", "format": "google-datetime" }, "attribute": { "type": "string", "description": "The attribute in the resource that changed, in this case it will be always `Status`.", "enumDescriptions": [ "Unspecified attribute", "Status of the changed entity" ], "enum": [ "ATTRIBUTE_UNSPECIFIED", "STATUS" ] }, "changes": { "type": "array", "description": "A message to describe the change that happened to the product", "items": { "$ref": "ProductChange" } }, "managingAccount": { "type": "string", "description": "The account that manages the merchant's account. can be the same as merchant id if it is standalone account. Format : `accounts/{service_provider_id}`" }, "expirationTime": { "type": "string", "description": "Optional. The product expiration time. This field will not be set if the notification is sent for a product deletion event.", "format": "google-datetime" }, "resource": { "description": "The product name. Format: `accounts/{account}/products/{product}`", "type": "string" }, "account": { "type": "string", "description": "The target account that owns the entity that changed. Format : `accounts/{merchant_id}`" }, "resourceType": { "description": "The resource that changed, in this case it will always be `Product`.", "enumDescriptions": [ "Unspecified resource", "Resource type : product", "Account service" ], "enum": [ "RESOURCE_UNSPECIFIED", "PRODUCT", "ACCOUNT_SERVICE" ], "type": "string" }, "resourceId": { "description": "The product id.", "type": "string" } } }, "ProductChange": { "properties": { "regionCode": { "description": "Countries that have the change (if applicable). Represented in the ISO 3166 format.", "type": "string" }, "oldValue": { "type": "string", "description": "The old value of the changed resource or attribute. If empty, it means that the product was created. Will have one of these values : (`approved`, `pending`, `disapproved`, ``)" }, "reportingContext": { "enum": [ "REPORTING_CONTEXT_ENUM_UNSPECIFIED", "SHOPPING_ADS", "DISCOVERY_ADS", "DEMAND_GEN_ADS", "DEMAND_GEN_ADS_DISCOVER_SURFACE", "VIDEO_ADS", "DISPLAY_ADS", "LOCAL_INVENTORY_ADS", "VEHICLE_INVENTORY_ADS", "FREE_LISTINGS", "FREE_LISTINGS_UCP_CHECKOUT", "FREE_LOCAL_LISTINGS", "FREE_LOCAL_VEHICLE_LISTINGS", "YOUTUBE_AFFILIATE", "YOUTUBE_SHOPPING", "CLOUD_RETAIL", "LOCAL_CLOUD_RETAIL", "PRODUCT_REVIEWS", "MERCHANT_REVIEWS", "YOUTUBE_CHECKOUT" ], "enumDeprecated": [ false, false, true, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false ], "description": "Reporting contexts that have the change (if applicable). Currently this field supports only (`SHOPPING_ADS`, `LOCAL_INVENTORY_ADS`, `YOUTUBE_SHOPPING`, `YOUTUBE_CHECKOUT`, `YOUTUBE_AFFILIATE`) from the enum value [ReportingContextEnum](/merchant/api/reference/rest/Shared.Types/ReportingContextEnum)", "enumDescriptions": [ "Not specified.", "[Shopping ads](https://support.google.com/merchants/answer/6149970).", "Deprecated: Use `DEMAND_GEN_ADS` instead. [Discovery and Demand Gen ads](https://support.google.com/merchants/answer/13389785).", "[Demand Gen ads](https://support.google.com/merchants/answer/13389785).", "[Demand Gen ads on Discover surface](https://support.google.com/merchants/answer/13389785).", "[Video ads](https://support.google.com/google-ads/answer/6340491).", "[Display ads](https://support.google.com/merchants/answer/6069387).", "[Local inventory ads](https://support.google.com/merchants/answer/3271956).", "[Vehicle inventory ads](https://support.google.com/merchants/answer/11544533).", "[Free product listings](https://support.google.com/merchants/answer/9199328).", "[Free product listings on UCP checkout](https://developers.google.com/merchant/ucp).", "[Free local product listings](https://support.google.com/merchants/answer/9825611).", "[Free local vehicle listings](https://support.google.com/merchants/answer/11544533).", "[Youtube Affiliate](https://support.google.com/youtube/answer/13376398).", "[YouTube Shopping](https://support.google.com/merchants/answer/13478370).", "[Cloud retail](https://cloud.google.com/solutions/retail).", "[Local cloud retail](https://cloud.google.com/solutions/retail).", "[Product Reviews](https://support.google.com/merchants/answer/14620732).", "[Merchant Reviews](https://developers.google.com/merchant-review-feeds).", "YouTube Checkout ." ], "type": "string" }, "newValue": { "type": "string", "description": "The new value of the changed resource or attribute. If empty, it means that the product was deleted. Will have one of these values : (`approved`, `pending`, `disapproved`, ``)" } }, "description": "The change that happened to the product including old value, new value, country code as the region code and reporting context.", "id": "ProductChange", "type": "object" }, "Attributes": { "id": "Attributes", "type": "object", "properties": { "limitValue": { "$ref": "Price", "description": "Optional. [Maximum product price](https://support.google.com/merchants/answer/2906014) for promotion." }, "minPercentOff": { "description": "Optional. Minimum percent off for a promotion with `PERCENT_OFF_RANGE` coupon value type. At least one of `min_percent_off` or `max_percent_off` must be present when the coupon value type is `PERCENT_OFF_RANGE`. If neither is provided an `INVALID_PROMOTION_MISSING_BENEFIT_OR_RESTRICTION` error is returned.", "format": "int64", "type": "string" }, "productTypeInclusion": { "type": "array", "description": "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](https://support.google.com/merchants/answer/13837299?ref_topic=13773355).", "items": { "type": "string" } }, "minimumPurchaseAmount": { "description": "Optional. [Minimum purchase amount](https://support.google.com/merchants/answer/13837705?ref_topic=13773355) for the promotion.", "$ref": "Price" }, "brandExclusion": { "description": "Optional. Product filter by [brand exclusion](https://support.google.com/merchants/answer/13861679?ref_topic=13773355) 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](https://support.google.com/merchants/answer/13837299?ref_topic=13773355).", "items": { "type": "string" }, "type": "array" }, "redemptionRestriction": { "description": "Optional. A restriction customers must meet before they can redeem the promotion.", "enumDescriptions": [ "Indicates that the redemption restriction is unspecified.", "The promotion can only be redeemed by signing up for a subscription.", "The promotion can only be redeemed on the first order.", "The promotion can only be redeemed by signing up for email.", "The promotion can only be redeemed by signing up for text message alerts.", "The promotion can only be redeemed with a custom redemption restriction. In this case, the `custom_redemption_restriction` field must be set." ], "enum": [ "REDEMPTION_RESTRICTION_UNSPECIFIED", "SUBSCRIBE", "FIRST_ORDER", "SIGNUP_FOR_EMAIL", "SIGNUP_FOR_TEXT", "CUSTOM" ], "type": "string" }, "googleProductCategories": { "type": "array", "description": "Optional. A list of Google product categories for this promotion. Set if `EventApplicability` is `SPECIFIC_CATEGORIES`. Up to 5 product categories can be specified. For more details on eligible values for product categories, checkout the `google_product_category` attribute in the [Promotion data specification](https://support.google.com/merchants/answer/2906014).", "items": { "type": "string" } }, "percentOff": { "description": "Optional. The [percentage discount](https://support.google.com/merchants/answer/13837404?sjid=17642868584668136159-NC) offered in the promotion.", "format": "int64", "type": "string" }, "productApplicability": { "type": "string", "description": "Optional. Applicability of the promotion to either all products or [only specific products](https://support.google.com/merchants/answer/6396257). Exactly one of `product_applicability` or `event_applicability` must be set.", "enumDescriptions": [ "Which products the promotion applies to is unknown.", "Applicable to all products.", "Applicable to only a single product or list of products." ], "enum": [ "PRODUCT_APPLICABILITY_UNSPECIFIED", "ALL_PRODUCTS", "SPECIFIC_PRODUCTS" ] }, "freeGiftValue": { "description": "Optional. [Free gift value](https://support.google.com/merchants/answer/13844477?ref_topic=13773355) for the promotion.", "$ref": "Price" }, "moneyOffAmount": { "$ref": "Price", "description": "Optional. The [money off amount](https://support.google.com/merchants/answer/13838101?ref_topic=13773355) offered in the promotion." }, "getThisQuantityDiscounted": { "description": "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`.", "format": "int64", "type": "string" }, "minimumPurchaseQuantity": { "type": "string", "format": "int64" }, "freeGiftItemId": { "description": "Optional. [Free gift item ID](https://support.google.com/merchants/answer/13857152?ref_topic=13773355) for the promotion.", "type": "string" }, "productTypeExclusion": { "description": "Optional. Product filter by [product type exclusion](https://support.google.com/merchants/answer/13863746?ref_topic=13773355) 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](https://support.google.com/merchants/answer/13837299?ref_topic=13773355).", "items": { "type": "string" }, "type": "array" }, "offerType": { "description": "Required. [Type](https://support.google.com/merchants/answer/13837405?ref_topic=13773355) of the promotion. Use this attribute to indicate whether or not customers need a coupon code to redeem your promotion.", "enumDescriptions": [ "Unknown offer type.", "Offer type without a code.", "Offer type with a code. Generic redemption code for the promotion is required when `offerType` = `GENERIC_CODE`." ], "enum": [ "OFFER_TYPE_UNSPECIFIED", "NO_CODE", "GENERIC_CODE" ], "type": "string" }, "customRedemptionRestriction": { "description": "Optional. The custom redemption restriction for the promotion. If the `redemption_restriction` field is set to `CUSTOM`, this field must be set.", "type": "string" }, "maxDiscountAmount": { "$ref": "Price", "description": "Optional. The maximum monetary discount a customer can receive for the promotion. This field is only supported with the `Percent off` coupon value type." }, "promotionEffectiveTimePeriod": { "description": "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.", "$ref": "Interval" }, "maxPercentOff": { "description": "Optional. Maximum percent off for a promotion with `PERCENT_OFF_RANGE` coupon value type. At least one of `min_percent_off` or `max_percent_off` must be present when the coupon value type is `PERCENT_OFF_RANGE`. If neither is provided an `INVALID_PROMOTION_MISSING_BENEFIT_OR_RESTRICTION` error is returned.", "format": "int64", "type": "string" }, "limitQuantity": { "type": "string", "description": "Optional. [Maximum purchase quantity](https://support.google.com/merchants/answer/13861564?ref_topic=13773355) for the promotion.", "format": "int64" }, "itemIdInclusion": { "description": "Optional. Product filter by [item ID](https://support.google.com/merchants/answer/13861565?ref_topic=13773355) 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](https://support.google.com/merchants/answer/13837299?ref_topic=13773355).", "items": { "type": "string" }, "type": "array" }, "itemGroupIdInclusion": { "type": "array", "description": "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](https://support.google.com/merchants/answer/13837299?ref_topic=13773355).", "items": { "type": "string" } }, "minMoneyOffAmount": { "$ref": "Price", "description": "Optional. Minimum money off amount for a promotion with `MONEY_OFF_RANGE` coupon value type. At least one of `min_money_off_amount` or `max_money_off_amount` must be present when the coupon value type is `MONEY_OFF_RANGE`. If neither is provided an `INVALID_PROMOTION_MISSING_BENEFIT_OR_RESTRICTION` error is returned." }, "promotionUrl": { "type": "string", "description": "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." }, "maxMoneyOffAmount": { "$ref": "Price", "description": "Optional. Maximum money off amount for a promotion with `MONEY_OFF_RANGE` coupon value type. At least one of `min_money_off_amount` or `max_money_off_amount` must be present when the coupon value type is `MONEY_OFF_RANGE`. If neither is provided an `INVALID_PROMOTION_MISSING_BENEFIT_OR_RESTRICTION` error is returned." }, "couponValueType": { "type": "string", "description": "Required. The [coupon value type] (https://support.google.com/merchants/answer/13861986?ref_topic=13773355) attribute to signal the type of promotion that you are running. Depending on type of the selected coupon value [some attributes are required](https://support.google.com/merchants/answer/6393006?ref_topic=7322920).", "enumDescriptions": [ "Indicates that the coupon value type is unspecified.", "Money off coupon value type.", "Percent off coupon value type.", "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 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 quantity, get money off. `minimum_purchase_quantity` and `money_off_amount` must be present.", "Buy M quantity, get money off. `minimum_purchase_quantity` and `percent_off_percentage` must be present.", "Free gift with description only.", "Free gift with monetary value.", "Free gift with item ID.", "Standard free shipping coupon value type. Only available for online promotions.", "Overnight free shipping coupon value type. Only available for online promotions.", "Two day free shipping coupon value type. Only available for online promotions.", "Money off range coupon value type. This coupon value type is used exclusively for US-based sales events. At least one of `min_money_off_amount` or `max_money_off_amount` must be present.", "Percent off range coupon value type. This coupon value type is exclusively used for US-based sale events. At least one of `min_percent_off` or `max_percent_off` must be present." ], "enum": [ "COUPON_VALUE_TYPE_UNSPECIFIED", "MONEY_OFF", "PERCENT_OFF", "BUY_M_GET_N_MONEY_OFF", "BUY_M_GET_N_PERCENT_OFF", "BUY_M_GET_MONEY_OFF", "BUY_M_GET_PERCENT_OFF", "FREE_GIFT", "FREE_GIFT_WITH_VALUE", "FREE_GIFT_WITH_ITEM_ID", "FREE_SHIPPING_STANDARD", "FREE_SHIPPING_OVERNIGHT", "FREE_SHIPPING_TWO_DAY", "MONEY_OFF_RANGE", "PERCENT_OFF_RANGE" ] }, "freeGiftDescription": { "description": "Optional. [Free gift description](https://support.google.com/merchants/answer/13847245?ref_topic=13773355) for the promotion.", "type": "string" }, "regionIdInclusion": { "description": "Optional. A list of [regions](https://support.google.com/merchants/answer/15406457?#howregionswork) where the promotion is applicable. Must be set if `audience` is set to `LOCATION`.", "items": { "type": "string" }, "type": "array" }, "longTitle": { "type": "string", "description": "Required. [Long title](https://support.google.com/merchants/answer/13838102?ref_topic=13773355) for the promotion." }, "itemGroupIdExclusion": { "description": "Optional. Product filter by [item group ID](https://support.google.com/merchants/answer/13837298?ref_topic=13773355). The product filter attributes only applies when the products eligible for promotion product applicability `product_applicability` attribute is set to [specific_products](https://support.google.com/merchants/answer/13837299?ref_topic=13773355). exclusion for the promotion.", "items": { "type": "string" }, "type": "array" }, "genericRedemptionCode": { "type": "string", "description": "Optional. Generic redemption code for the promotion. To be used with the `offerType` field and must meet the [minimum requirements](https://support.google.com/merchants/answer/13837405?ref_topic=13773355)." }, "brandInclusion": { "description": "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](https://support.google.com/merchants/answer/13837299?ref_topic=13773355).", "items": { "type": "string" }, "type": "array" }, "eventApplicability": { "type": "string", "description": "Optional. Event applicability for this promotion. When present, this field indicates you are creating a [sales event](https://support.google.com/merchants/answer/15523289) and not a product promotion. Exactly one of `product_applicability` or `event_applicability` must be set.", "enumDescriptions": [ "Indicates that the event applicability is unspecified.", "Indicates that the promotion applies to the entire site.", "Indicates that the promotion applies to specific categories. When this is set, the GoogleProductCategory field is required." ], "enum": [ "EVENT_APPLICABILITY_UNSPECIFIED", "SITEWIDE", "SPECIFIC_CATEGORIES" ] }, "promotionDestinations": { "description": "Required. The list of destinations (also known as [Marketing methods](https://support.google.com/merchants/answer/15130232)) 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](https://support.google.com/merchants/answer/13837465)", "items": { "enumDescriptions": [ "Not specified.", "[Shopping ads](https://support.google.com/google-ads/answer/2454022).", "[Display ads](https://support.google.com/merchants/answer/6069387).", "[Local inventory ads](https://support.google.com/merchants/answer/3057972).", "[Free listings](https://support.google.com/merchants/answer/9199328).", "[Free local product listings](https://support.google.com/merchants/answer/9825611).", "[YouTube Shopping](https://support.google.com/merchants/answer/12362804).", "Youtube shopping checkout.", "[Youtube Affiliate](https://support.google.com/youtube/answer/13376398).", "[Free vehicle listings](https://support.google.com/merchants/answer/11189169).", "[Vehicle ads](https://support.google.com/merchants/answer/11189169).", "[Cloud retail](https://cloud.google.com/solutions/retail).", "[Local cloud retail](https://cloud.google.com/solutions/retail)." ], "enum": [ "DESTINATION_ENUM_UNSPECIFIED", "SHOPPING_ADS", "DISPLAY_ADS", "LOCAL_INVENTORY_ADS", "FREE_LISTINGS", "FREE_LOCAL_LISTINGS", "YOUTUBE_SHOPPING", "YOUTUBE_SHOPPING_CHECKOUT", "YOUTUBE_AFFILIATE", "FREE_VEHICLE_LISTINGS", "VEHICLE_ADS", "CLOUD_RETAIL", "LOCAL_CLOUD_RETAIL" ], "type": "string" }, "type": "array" }, "promotionDisplayTimePeriod": { "$ref": "Interval", "description": "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." }, "audience": { "type": "string", "description": "Optional. This field defines the audience a promotion will be visible to.", "enumDescriptions": [ "The promotion is not restricted to any audience and will be shown to all users. Default value.", "The Promotion will be shown to new customers only. If this value is set, the `promotion_destinations` field in `Attributes` must include `SHOPPING_ADS`. Requests that do not satisfy this condition will be rejected. For more details, see [First order promotions](https://support.google.com/merchants/answer/16310477)", "The Promotion will be shown to customer within a certain location. Applicable locations must be specified in the `region_id_inclusion` field and the `promotion_destinations` field must contain `FREE_LISTINGS`. For more details, see [Regional Promotions](https://support.google.com/merchants/answer/16700435)." ], "enum": [ "AUDIENCE_UNSPECIFIED", "NEW_CUSTOMERS", "LOCATION" ] }, "storeApplicability": { "description": "Optional. Whether the promotion applies to [all stores, or only specified stores](https://support.google.com/merchants/answer/13857563?sjid=17642868584668136159-NC). 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.", "enumDescriptions": [ "Which store codes the promotion applies to is unknown.", "Promotion applies to all stores.", "Promotion applies to only the specified stores." ], "enum": [ "STORE_APPLICABILITY_UNSPECIFIED", "ALL_STORES", "SPECIFIC_STORES" ], "type": "string" }, "storeCodesExclusion": { "description": "Optional. [Store codes to exclude](https://support.google.com/merchants/answer/13859586?ref_topic=13773355) for the promotion. The store filter attributes only applies when the `store_applicability` attribute is set to [specific_stores](https://support.google.com/merchants/answer/13857563?ref_topic=13773355).", "items": { "type": "string" }, "type": "array" }, "itemIdExclusion": { "description": "Optional. Product filter by [item ID exclusion](https://support.google.com/merchants/answer/13863524?ref_topic=13773355) 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](https://support.google.com/merchants/answer/13837299?ref_topic=13773355).", "items": { "type": "string" }, "type": "array" }, "storeCodesInclusion": { "description": "Optional. [Store codes to include](https://support.google.com/merchants/answer/13857470?ref_topic=13773355) for the promotion. The store filter attributes only applies when the `store_applicability` attribute is set to [specific_stores](https://support.google.com/merchants/answer/13857563?ref_topic=13773355). 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](https://support.google.com/merchants/answer/3061342) for more information.", "items": { "type": "string" }, "type": "array" } }, "description": "Attributes." }, "DestinationStatus": { "id": "DestinationStatus", "type": "object", "description": "The status for the specified destination.", "properties": { "status": { "description": "Output only. The status for the specified destination.", "enumDescriptions": [ "Unknown promotion state.", "The promotion is under review.", "The promotion is disapproved.", "The promotion is approved and active.", "The promotion is stopped by merchant.", "The promotion is no longer active.", "The promotion is not stopped, and all reviews are approved, but the active date is in the future." ], "type": "string", "enum": [ "STATE_UNSPECIFIED", "IN_REVIEW", "REJECTED", "LIVE", "STOPPED", "EXPIRED", "PENDING" ], "readOnly": true }, "reportingContext": { "type": "string", "description": "Output only. The name of the promotion destination.", "enumDescriptions": [ "Not specified.", "[Shopping ads](https://support.google.com/merchants/answer/6149970).", "Deprecated: Use `DEMAND_GEN_ADS` instead. [Discovery and Demand Gen ads](https://support.google.com/merchants/answer/13389785).", "[Demand Gen ads](https://support.google.com/merchants/answer/13389785).", "[Demand Gen ads on Discover surface](https://support.google.com/merchants/answer/13389785).", "[Video ads](https://support.google.com/google-ads/answer/6340491).", "[Display ads](https://support.google.com/merchants/answer/6069387).", "[Local inventory ads](https://support.google.com/merchants/answer/3271956).", "[Vehicle inventory ads](https://support.google.com/merchants/answer/11544533).", "[Free product listings](https://support.google.com/merchants/answer/9199328).", "[Free product listings on UCP checkout](https://developers.google.com/merchant/ucp).", "[Free local product listings](https://support.google.com/merchants/answer/9825611).", "[Free local vehicle listings](https://support.google.com/merchants/answer/11544533).", "[Youtube Affiliate](https://support.google.com/youtube/answer/13376398).", "[YouTube Shopping](https://support.google.com/merchants/answer/13478370).", "[Cloud retail](https://cloud.google.com/solutions/retail).", "[Local cloud retail](https://cloud.google.com/solutions/retail).", "[Product Reviews](https://support.google.com/merchants/answer/14620732).", "[Merchant Reviews](https://developers.google.com/merchant-review-feeds).", "YouTube Checkout ." ], "enumDeprecated": [ false, false, true, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false ], "readOnly": true, "enum": [ "REPORTING_CONTEXT_ENUM_UNSPECIFIED", "SHOPPING_ADS", "DISCOVERY_ADS", "DEMAND_GEN_ADS", "DEMAND_GEN_ADS_DISCOVER_SURFACE", "VIDEO_ADS", "DISPLAY_ADS", "LOCAL_INVENTORY_ADS", "VEHICLE_INVENTORY_ADS", "FREE_LISTINGS", "FREE_LISTINGS_UCP_CHECKOUT", "FREE_LOCAL_LISTINGS", "FREE_LOCAL_VEHICLE_LISTINGS", "YOUTUBE_AFFILIATE", "YOUTUBE_SHOPPING", "CLOUD_RETAIL", "LOCAL_CLOUD_RETAIL", "PRODUCT_REVIEWS", "MERCHANT_REVIEWS", "YOUTUBE_CHECKOUT" ] } } }, "Promotion": { "id": "Promotion", "type": "object", "description": "Represents a promotion. See the following articles for more details. Required promotion input attributes to pass data validation checks are primarily defined below: * [Promotions data specification](https://support.google.com/merchants/answer/2906014) * [Local promotions data specification](https://support.google.com/merchants/answer/10146130) After inserting, updating a promotion input, it may take several minutes before the final promotion can be retrieved.", "properties": { "attributes": { "$ref": "Attributes", "description": "Optional. A list of promotion attributes." }, "promotionStatus": { "readOnly": true, "$ref": "PromotionStatus", "description": "Output only. The [status of a promotion](https://support.google.com/merchants/answer/3398326?ref_topic=7322924&sjid=5155774230887277618-NC), data validation issues, that is, information about a promotion computed asynchronously." }, "targetCountry": { "type": "string", "description": "Required. The target country used as part of the unique identifier. Represented as a [CLDR territory code](https://github.com/unicode-org/cldr/blob/latest/common/main/en.xml). Promotions are only available in selected countries, [Free Listings and Shopping ads](https://support.google.com/merchants/answer/4588460) [Local Inventory ads](https://support.google.com/merchants/answer/10146326)" }, "contentLanguage": { "type": "string", "description": "Required. The two-letter [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) language code for the promotion. Promotions is only for [selected languages](https://support.google.com/merchants/answer/4588281?ref_topic=6396150&sjid=18314938579342094533-NC#option3&zippy=)." }, "versionNumber": { "type": "string", "description": "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.", "format": "int64" }, "redemptionChannel": { "type": "array", "description": "Required. [Redemption channel](https://support.google.com/merchants/answer/13837674?ref_topic=13773355&sjid=17642868584668136159-NC) for the promotion. At least one channel is required.", "items": { "enumDescriptions": [ "Indicates that the channel is unspecified.", "Indicates that the channel is in store. This is same as `local` channel used for `products`.", "Indicates that the channel is online." ], "enum": [ "REDEMPTION_CHANNEL_UNSPECIFIED", "IN_STORE", "ONLINE" ], "type": "string" } }, "customAttributes": { "description": "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.", "items": { "$ref": "CustomAttribute" }, "type": "array" }, "promotionId": { "description": "Required. The user provided promotion ID to uniquely identify the promotion. Follow [minimum requirements](https://support.google.com/merchants/answer/7050148?ref_topic=7322920&sjid=871860036916537104-NC#minimum_requirements) to prevent promotion disapprovals.", "type": "string" }, "dataSource": { "type": "string", "readOnly": true, "description": "Output only. The primary data source of the promotion." }, "name": { "description": "Identifier. The name of the promotion. Format: `accounts/{account}/promotions/{promotion}`", "type": "string" } } }, "ItemLevelIssue": { "description": "The issue associated with the promotion.", "properties": { "severity": { "description": "Output only. How this issue affects serving of the promotion.", "enumDescriptions": [ "Not specified.", "This issue represents a warning and does not have a direct affect on the promotion.", "The promotion is demoted and most likely have limited performance in search results", "Issue disapproves the promotion." ], "type": "string", "enum": [ "SEVERITY_UNSPECIFIED", "NOT_IMPACTED", "DEMOTED", "DISAPPROVED" ], "readOnly": true }, "resolution": { "type": "string", "readOnly": true, "description": "Output only. Whether the issue can be resolved by the merchant." }, "applicableCountries": { "type": "array", "description": "Output only. List of country codes (ISO 3166-1 alpha-2) where issue applies to the offer.", "items": { "type": "string" }, "readOnly": true }, "description": { "description": "Output only. A short issue description in English.", "readOnly": true, "type": "string" }, "detail": { "type": "string", "readOnly": true, "description": "Output only. A detailed issue description in English." }, "attribute": { "type": "string", "readOnly": true, "description": "Output only. The attribute's name, if the issue is caused by a single attribute." }, "documentation": { "type": "string", "description": "Output only. The URL of a web page to help with resolving this issue.", "readOnly": true }, "code": { "description": "Output only. The error code of the issue.", "readOnly": true, "type": "string" }, "reportingContext": { "description": "Output only. The destination the issue applies to.", "enumDescriptions": [ "Not specified.", "[Shopping ads](https://support.google.com/merchants/answer/6149970).", "Deprecated: Use `DEMAND_GEN_ADS` instead. [Discovery and Demand Gen ads](https://support.google.com/merchants/answer/13389785).", "[Demand Gen ads](https://support.google.com/merchants/answer/13389785).", "[Demand Gen ads on Discover surface](https://support.google.com/merchants/answer/13389785).", "[Video ads](https://support.google.com/google-ads/answer/6340491).", "[Display ads](https://support.google.com/merchants/answer/6069387).", "[Local inventory ads](https://support.google.com/merchants/answer/3271956).", "[Vehicle inventory ads](https://support.google.com/merchants/answer/11544533).", "[Free product listings](https://support.google.com/merchants/answer/9199328).", "[Free product listings on UCP checkout](https://developers.google.com/merchant/ucp).", "[Free local product listings](https://support.google.com/merchants/answer/9825611).", "[Free local vehicle listings](https://support.google.com/merchants/answer/11544533).", "[Youtube Affiliate](https://support.google.com/youtube/answer/13376398).", "[YouTube Shopping](https://support.google.com/merchants/answer/13478370).", "[Cloud retail](https://cloud.google.com/solutions/retail).", "[Local cloud retail](https://cloud.google.com/solutions/retail).", "[Product Reviews](https://support.google.com/merchants/answer/14620732).", "[Merchant Reviews](https://developers.google.com/merchant-review-feeds).", "YouTube Checkout ." ], "type": "string", "readOnly": true, "enum": [ "REPORTING_CONTEXT_ENUM_UNSPECIFIED", "SHOPPING_ADS", "DISCOVERY_ADS", "DEMAND_GEN_ADS", "DEMAND_GEN_ADS_DISCOVER_SURFACE", "VIDEO_ADS", "DISPLAY_ADS", "LOCAL_INVENTORY_ADS", "VEHICLE_INVENTORY_ADS", "FREE_LISTINGS", "FREE_LISTINGS_UCP_CHECKOUT", "FREE_LOCAL_LISTINGS", "FREE_LOCAL_VEHICLE_LISTINGS", "YOUTUBE_AFFILIATE", "YOUTUBE_SHOPPING", "CLOUD_RETAIL", "LOCAL_CLOUD_RETAIL", "PRODUCT_REVIEWS", "MERCHANT_REVIEWS", "YOUTUBE_CHECKOUT" ], "enumDeprecated": [ false, false, true, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false ] } }, "id": "ItemLevelIssue", "type": "object" }, "CustomAttribute": { "properties": { "name": { "type": "string", "description": "The name of the attribute." }, "groupValues": { "description": "Subattributes within this attribute group. If `group_values` is not empty, `value` must be empty.", "items": { "$ref": "CustomAttribute" }, "type": "array" }, "value": { "description": "The value of the attribute. If `value` is not empty, `group_values` must be empty.", "type": "string" } }, "description": "A message that represents custom attributes. Exactly one of `value` or `group_values` must not be empty.", "id": "CustomAttribute", "type": "object" }, "InsertPromotionRequest": { "id": "InsertPromotionRequest", "type": "object", "description": "Request message for the `InsertPromotion` method.", "properties": { "dataSource": { "type": "string", "description": "Required. The data source of the [promotion](https://support.google.com/merchants/answer/6396268?sjid=5155774230887277618-NC) Format: `accounts/{account}/dataSources/{datasource}`." }, "promotion": { "$ref": "Promotion", "description": "Required. The promotion to insert." } } }, "ListPromotionsResponse": { "id": "ListPromotionsResponse", "type": "object", "description": "Response message for the `ListPromotions` method.", "properties": { "promotions": { "description": "The processed promotions from the specified account.", "items": { "$ref": "Promotion" }, "type": "array" }, "nextPageToken": { "type": "string", "description": "A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages." } } }, "Interval": { "description": "Represents a time interval, encoded as a Timestamp start (inclusive) and a Timestamp end (exclusive). The start must be less than or equal to the end. When the start equals the end, the interval is empty (matches no time). When both start and end are unspecified, the interval matches any time.", "properties": { "startTime": { "description": "Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.", "format": "google-datetime", "type": "string" }, "endTime": { "type": "string", "description": "Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.", "format": "google-datetime" } }, "id": "Interval", "type": "object" } }, "ownerDomain": "google.com", "name": "merchantapi", "documentationLink": "https://developers.google.com/merchant/api", "version": "promotions_v1", "protocol": "rest", "version_module": true, "fullyEncodeReservedExpansion": true, "mtlsRootUrl": "https://merchantapi.mtls.googleapis.com/", "title": "Merchant API", "auth": { "oauth2": { "scopes": { "https://www.googleapis.com/auth/content": { "description": "Manage your product listings and accounts for Google Shopping" } } } }, "batchPath": "batch", "baseUrl": "https://merchantapi.googleapis.com/", "description": "Programmatically manage your Merchant Center Accounts.", "servicePath": "", "revision": "20260627", "ownerName": "Google", "parameters": { "access_token": { "type": "string", "location": "query", "description": "OAuth access token." }, "uploadType": { "type": "string", "location": "query", "description": "Legacy upload protocol for media (e.g. \"media\", \"multipart\")." }, "oauth_token": { "description": "OAuth 2.0 token for the current user.", "type": "string", "location": "query" }, "fields": { "type": "string", "location": "query", "description": "Selector specifying which fields to include in a partial response." }, "$.xgafv": { "location": "query", "enum": [ "1", "2" ], "type": "string", "description": "V1 error format.", "enumDescriptions": [ "v1 error format", "v2 error format" ] }, "key": { "description": "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.", "type": "string", "location": "query" }, "prettyPrint": { "type": "boolean", "location": "query", "description": "Returns response with indentations and line breaks.", "default": "true" }, "quotaUser": { "description": "Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.", "type": "string", "location": "query" }, "alt": { "type": "string", "description": "Data format for response.", "enumDescriptions": [ "Responses with Content-Type of application/json", "Media download with context-dependent Content-Type", "Responses with Content-Type of application/x-protobuf" ], "location": "query", "default": "json", "enum": [ "json", "media", "proto" ] }, "callback": { "type": "string", "location": "query", "description": "JSONP" }, "upload_protocol": { "description": "Upload protocol for media (e.g. \"raw\", \"multipart\").", "type": "string", "location": "query" } }, "basePath": "", "id": "merchantapi:promotions_v1", "icons": { "x16": "http://www.google.com/images/icons/product/search-16.gif", "x32": "http://www.google.com/images/icons/product/search-32.gif" }, "canonicalName": "Merchant", "kind": "discovery#restDescription" }