--- title: "POST /{merchantId}/promotions" method: POST path: "/{merchantId}/promotions" tags: ["promotions"] --- # POST /{merchantId}/promotions `POST /{merchantId}/promotions` Inserts a promotion for your Merchant Center account. If the promotion already exists, then it updates the promotion instead. To [end or delete] (https://developers.google.com/shopping-content/guides/promotions#end_a_promotion) a promotion update the time period of the promotion to a time that has already passed. ## Path parameters - `merchantId` string, required ## Request body - Promotion — Represents a promotion. See the following articles for more details. * [Promotions feed specification](https://support.google.com/merchants/answer/2906014) * [Local promotions feed specification](https://support.google.com/merchants/answer/10146130) * [Promotions on Buy on Google product data specification](https://support.google.com/merchants/answer/9173673) - `productApplicability` 'PRODUCT_APPLICABILITY_UNSPECIFIED' | 'ALL_PRODUCTS' | 'SPECIFIC_PRODUCTS' — Required. Applicability of the promotion to either all products or only specific products. - `itemIdExclusion` string[] — Product filter by item ID exclusion for the promotion. - `brandExclusion` string[] — Product filter by brand exclusion for the promotion. - `longTitle` string — Required. Long title for the promotion. - `limitQuantity` integer — Maximum purchase quantity for the promotion. - `storeApplicability` 'STORE_APPLICABILITY_UNSPECIFIED' | 'ALL_STORES' | 'SPECIFIC_STORES' — 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_code or score_code_exclusion is set to a value. - `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. - `itemGroupId` string[] — Product filter by item group ID for the promotion. - `itemGroupIdExclusion` string[] — Product filter by item group ID exclusion for the promotion. - `moneyBudget` PriceAmount — The price represented as a number and currency. - `value` string — The price represented as a number. - `currency` string — The currency of the price. - `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`. - `promotionEffectiveDates` string — String representation of the promotion effective dates. Deprecated. Use `promotion_effective_time_period` instead. - `promotionUrl` string — URL to the page on the merchant's site where the promotion shows. Local 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. - `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"`. - `shippingServiceNames` string[] — Shipping service names for the promotion. - `productType` string[] — Product filter by product type for the promotion. - `brand` string[] — Product filter by brand for the promotion. - `moneyOffAmount` PriceAmount — The price represented as a number and currency. - `value` string — The price represented as a number. - `currency` string — The currency of the price. - `percentOff` integer — The percentage discount offered in the promotion. - `promotionDisplayDates` string — String representation of the promotion display dates. Deprecated. Use `promotion_display_time_period` instead. - `promotionDestinationIds` string[] — Destination ID for the promotion. - `freeGiftItemId` string — Free gift item ID for the promotion. - `storeCode` string[] — Store codes to include for the promotion. - `itemId` string[] — Product filter by item ID for the promotion. - `minimumPurchaseAmount` PriceAmount — The price represented as a number and currency. - `value` string — The price represented as a number. - `currency` string — The currency of the price. - `promotionDisplayTimePeriod` TimePeriod — A message that represents a time period. - `endTime` string, google-datetime — The ending timestamp. - `startTime` string, google-datetime — The starting timestamp. - `genericRedemptionCode` string — Generic redemption code for the promotion. To be used with the `offerType` field. - `redemptionChannel` string[] — Required. Redemption channel for the promotion. At least one channel is required. - `minimumPurchaseQuantity` integer — Minimum purchase quantity for the promotion. - `orderLimit` integer — Order limit for the promotion. - `customRedemptionRestriction` string — The custom redemption restriction for the promotion. If the `redemption_restriction` field is set to `CUSTOM`, this field must be set. - `maxDiscountAmount` PriceAmount — The price represented as a number and currency. - `value` string — The price represented as a number. - `currency` string — The currency of the price. - `getThisQuantityDiscounted` integer — The number of items discounted in the promotion. - `storeCodeExclusion` string[] — Store codes to exclude for the promotion. - `redemptionRestriction` 'REDEMPTION_RESTRICTION_UNSPECIFIED' | 'SUBSCRIBE_AND_SAVE' | 'FIRST_ORDER' | 'SIGN_UP_FOR_EMAIL' | 'SIGN_UP_FOR_TEXT' | 'FORMS_OF_PAYMENT' | 'CUSTOM' — The redemption restriction for the promotion. - `freeGiftValue` PriceAmount — The price represented as a number and currency. - `value` string — The price represented as a number. - `currency` string — The currency of the price. - `freeGiftDescription` string — Free gift description for the promotion. - `promotionEffectiveTimePeriod` TimePeriod — A message that represents a time period. - `endTime` string, google-datetime — The ending timestamp. - `startTime` string, google-datetime — The starting timestamp. - `offerType` 'OFFER_TYPE_UNSPECIFIED' | 'NO_CODE' | 'GENERIC_CODE' — Required. Type of the promotion. - `productTypeExclusion` string[] — Product filter by product type exclusion for the promotion. - `couponValueType` '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' — Required. Coupon value type for the promotion. - `limitValue` PriceAmount — The price represented as a number and currency. - `value` string — The price represented as a number. - `currency` string — The currency of the price. - `promotionId` string — Required. The user provided promotion ID to uniquely identify the promotion. - `promotionStatus` PromotionPromotionStatus — The status of the promotion. - `creationDate` string — 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" - `promotionIssue` PromotionPromotionStatusPromotionIssue[] — A list of issues associated with the promotion. - `code` string — Code of the issue. - `detail` string — Explanation of the issue. - `lastUpdateDate` string — 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" - `destinationStatuses` PromotionPromotionStatusDestinationStatus[] — The intended destinations for the promotion. - `destination` string — The name of the destination. - `status` 'STATE_UNSPECIFIED' | 'IN_REVIEW' | 'REJECTED' | 'LIVE' | 'STOPPED' | 'EXPIRED' | 'PENDING' — The status for the specified destination. ## Response `200` Successful response --- [API](https://skmtc.net/google/apis/content.md) · [All operations](https://skmtc.net/google/apis/content/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/content/revisions/1033388fc86f/schema)