Use promotions to showcase special offers for products you sell on Google.
Promotions display across different Google properties, including Google Search,
Shopping, and Chrome. Promotions must meet certain criteria to be approved. For
more information, see
[Promotion criteria](https://support.google.com/merchants/answer/13422697#criteria).

When you add a promotion to your products, shoppers see a special offer link.
For example, "15% off" or "Free shipping". Offer links can increase the appeal
of your products and encourage shoppers to make a purchase. All promotions are
applied at checkout or point of sale.

For more information, see
[Promotion basics](https://support.google.com/merchants/answer/7322422).

## Prerequisites

Google needs you to provide specific information about your business and
products prior to displaying your promotions. You must have the following:

- A [product data source](https://support.google.com/merchants/answer/7439882) in the [Google Merchant Center](https://merchants.google.com/).
- A [promotions data source](https://support.google.com/merchants/answer/7439058) in the [Google Merchant Center](https://merchants.google.com/).
- A [Google Ads](https://support.google.com/google-ads/topic/3119073) account for [Shopping campaigns](https://support.google.com/google-ads/answer/2454022).

In addition, you must enroll your Merchant Center account in the
Promotions program. If you are unsure whether you are already enrolled, check
the [Merchant Center](https://merchants.google.com/Google).

If you are not enrolled, complete the [request
form](https://support.google.com/merchants/contact/promos_contact). The
promotions team will let you know when you are ready to start implementation.

For more information, see [Participation criteria and
policies](https://support.google.com/merchants/answer/4588460).

## Create a data source

You can use the
[accounts.dataSources.create](https://developers.google.com/merchant/api/reference/rest/datasources_v1/accounts.dataSources/create)
method to create a promotion data source. If an existing promotion data source
is available, use the
[`accounts.dataSources.list`](https://developers.google.com/merchant/api/reference/rest/datasources_v1/accounts.dataSources/list)
method to retrieve all the data sources. You can then use the`name` field of
the promotion data source to [create promotions](https://developers.google.com/merchant/api/guides/promotions/overview#create-promotions).

To refer to them directly in future API calls, we strongly recommend to store
the `accounts.dataSources.name` in your local database for each promotion. You
can perform a one-off backfill of your local database.

> [!NOTE]
> **Note:** A data source is also required for promotions used at the Advanced Account level. Access to Advanced Account promotions is restricted to users in an allowlist. To request access, contact the [Merchant API support team](https://developers.google.com/merchant/api/support/get-help#merchant_api_support_team).

The following request shows how to create a data source for adding promotions:

    POST https://merchantapi.googleapis.com/datasources/v1/accounts/{ACCOUNT_ID}/dataSources

    {
      "displayName": "{DISPLAY_NAME}",
      "promotionDataSource": {
        "contentLanguage": "{CONTENT_LANGUAGE}",
        "targetCountry": "{TARGET_COUNTRY}"
      }
    }

Replace the following:

- <var translate="no">{ACCOUNT_ID}</var>: The unique identifier of your account as it appears in the Merchant Center UI.
- <var translate="no">{DISPLAY_NAME}</var>: The display name of the data source.
- <var translate="no">{CONTENT_LANGUAGE}</var>: The two-letter [ISO
  639-1](https://wikipedia.org/wiki/ISO_639-1) language code of the products in the data source.
- <var translate="no">{TARGET_COUNTRY}</var>: The CLDR territory code of the target country where you want the promotions to be visible.

After the request runs successfully, you see the following response that
contains details about the newly created promotions data source:

    {
      "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
      "dataSourceId": "{DATASOURCE_ID}",
      "displayName": "{DISPLAY_NAME}",
      "promotionDataSource": {
        "targetCountry": "{TARGET_COUNTRY}",
        "contentLanguage": "{CONTENT_LANGUAGE}"
      },
      "input": "API"
    }

> [!NOTE]
> **Note:** The data source is immediately available after creation so you don't have to wait for any processing.

## Create promotions

You can use the
[`accounts.promotions.insert`](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions/insert)
method to create or update a promotion. The `accounts.promotions.insert` method
takes a
[`promotions`](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions)
resource and a data source name as input. It returns the new or updated
promotion, if successful.

Creating a promotion requires the name of the [data
source](https://developers.google.com/merchant/api/reference/rest/datasources_v1/accounts.dataSources#resource:-datasource).
You must also provide values for the following fields in your request:

- `contentLanguage`
- `redemptionChannel`
- `promotionId`
- `targetCountry`
- `attributes.offerType`
- `attributes.genericRedemptionCode`
- `attributes.couponValueType`
- `attributes.productApplicability`
- `attributes.promotionEffectiveTimePeriod.endTime`
- `attributes.promotionEffectiveTimePeriod.startTime`
- `attributes.longTitle`

> [!IMPORTANT]
> **Important:** This request overwrites the entire promotions resource, so the request needs to include all the promotions details to avoid losing information.

Google reviews and approves your promotions before distributing them. For more
information, see
[Promotion approval process](https://support.google.com/merchants/answer/4588464).

We recommend that you go through the
[Promotions policies](https://support.google.com/merchants/answer/2877565)
to make sure that the promotions you create add value and adhere to Shopping
ads policies.

The following request demonstrates how to create an online promotion:

### HTTP

    POST https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert

    {
    "promotion": {
      "name": "{PROMOTION_NAME}",
      "promotionId": "{PROMOTION_ID}",
      "targetCountry": "{TARGET_COUNTRY}",
      "redemptionChannel": [
        "ONLINE"
      ],
      "contentLanguage": "{CONTENT_LANGUAGE}",
      "attributes": {
        "promotionDisplayTimePeriod": {
          "endTime": "{PROMOTION_END_TIME}",
          "startTime": "{PROMOTION_START_TIME}"
        },
        "offerType": "{OFFER_TYPE}",
        "longTitle": "{LONG_TITLE}"
      }
    },
    "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
    }

### cURL

      curl --request POST \
    'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert?key=[YOUR_API_KEY]' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"dataSource":"{DATASOURCE_ID}","promotion":{"name":"accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}y","promotionId":"abc","contentLanguage":"en","targetCountry":"US","redemptionChannel":["ONLINE"]}}' \
    --compressed

For information about the rules applicable to setting your promotion ID, see
[Minimum requirements for promotion ID attribute](https://support.google.com/merchants/answer/7050148#minimum_requirements).

The valid values for the mandatory `offerType` field are `NO_CODE` and
`GENERIC_CODE`. If you don't provide one of these values, the API request fails
with the HTTP 400 response `[offer_type] validation/missing_required: Invalid or
missing required attribute: offer_type`. A similar error message is returned if
you don't provide any of the mandatory fields.

If you don't provide a value for the `attributes.genericRedemptionCode` field,
the request fails with the HTTP 400 response `[genericRedemptionCode] No
redemption code provided`.

The values for the `promotion.attributes.promotionDisplayTimePeriod.startTime`
and `promotion.attributes.promotionDisplayTimePeriod.endTime` fields must be in
the format `yyyy-mm-ddThh:mm:ssZ`. Make sure to replace the values for these
fields with dates that are in the future.

For more information, see
[Promotions data specification](https://support.google.com/merchants/answer/2906014).

For best practices about creating a promotion, see
[Promotions best practices](https://support.google.com/merchants/answer/10146235).

For a list of promotions-related attributes, see
[Add structured data attributes](https://support.google.com/merchants/answer/6393006).

After promotion creation request runs successfully, it can take a few minutes
for the promotion to be retrievable using the API or to appear in the
Merchant Center.

Here's a sample you can use to insert multiple promotions asynchronously:

### Java

    import com.google.api.core.ApiFuture;
    import com.google.api.core.ApiFutureCallback;
    import com.google.api.core.ApiFutures;
    import com.google.api.gax.core.FixedCredentialsProvider;
    import com.google.api.gax.grpc.ChannelPoolSettings;
    import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
    import com.google.auth.oauth2.GoogleCredentials;
    import com.google.common.util.concurrent.MoreExecutors;
    import com.google.protobuf.Timestamp;
    import com.google.shopping.merchant.promotions.v1.Attributes;
    import com.google.shopping.merchant.promotions.v1.CouponValueType;
    import com.google.shopping.merchant.promotions.v1.InsertPromotionRequest;
    import com.google.shopping.merchant.promotions.v1.OfferType;
    import com.google.shopping.merchant.promotions.v1.ProductApplicability;
    import com.google.shopping.merchant.promotions.v1.Promotion;
    import com.google.shopping.merchant.promotions.v1.PromotionsServiceClient;
    import com.google.shopping.merchant.promotions.v1.PromotionsServiceSettings;
    import com.google.shopping.merchant.promotions.v1.RedemptionChannel;
    import com.google.shopping.type.CustomAttribute;
    import com.google.shopping.type.Destination.DestinationEnum;
    import com.google.type.Interval;
    import java.util.ArrayList;
    import java.util.List;
    import java.util.Random;
    import java.util.stream.Collectors;
    import shopping.merchant.samples.utils.Authenticator;
    import shopping.merchant.samples.utils.Config;

    /** This class demonstrates how to insert multiple promotions asynchronously. */
    public class InsertPromotionsAsyncSample {

      private static String generateRandomString() {
        String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
        Random random = new Random();
        StringBuilder sb = new StringBuilder(8);
        for (int i = 0; i < 8; i++) {
          sb.append(characters.charAt(random.nextInt(characters.length())));
        }
        return sb.toString();
      }

      private static Promotion createPromotion(String accountId) {
        String merchantPromotionId = generateRandomString();

        Attributes attributes =
            Attributes.newBuilder()
                .setProductApplicability(ProductApplicability.ALL_PRODUCTS)
                .setOfferType(OfferType.GENERIC_CODE)
                .setGenericRedemptionCode("ABCD1234")
                .setLongTitle("My promotion")
                .setCouponValueType(CouponValueType.PERCENT_OFF)
                .addPromotionDestinations(DestinationEnum.SHOPPING_ADS)
                .setPercentOff(10)
                // Note that promotions have a 6-month limit.
                // For more information, read here: https://support.google.com/merchants/answer/2906014
                // Also note that only promotions valid within the past 365 days are shown in the UI.
                .setPromotionEffectiveTimePeriod(
                    Interval.newBuilder()
                        .setStartTime(Timestamp.newBuilder().setSeconds(1726842472))
                        .setEndTime(Timestamp.newBuilder().setSeconds(1726842473))
                        .build())
                .build();

        return Promotion.newBuilder()
            .setName(String.format("accounts/%s/merchantPromotions/%s", accountId, merchantPromotionId))
            .setPromotionId(merchantPromotionId)
            .setContentLanguage("fr")
            .setTargetCountry("CH")
            .addRedemptionChannel(RedemptionChannel.ONLINE)
            .setAttributes(attributes)
            // Custom attributes allow you to add additional information which is not available in
            // Attributes. For example, you might want to pilot experimental functionality.
            .addCustomAttributes(
                CustomAttribute.newBuilder()
                    .setName("another example name")
                    .setValue("another example value")
                    .build())
            .build();
      }

      public static void asyncInsertPromotions(String accountId, String dataSourceId) throws Exception {
        GoogleCredentials credential = new Authenticator().authenticate();

        // Creates a channel provider. This provider manages a pool of gRPC channels
        // to enhance throughput for bulk operations. Each individual channel in the pool
        // can handle up to approximately 100 concurrent requests.
        //
        // Channel: A single connection pathway to the service.
        // Pool: A collection of multiple channels managed by this provider.
        //   Requests are distributed across the channels in the pool.
        //
        // We recommend estimating the number of concurrent requests you'll make, divide by 50 (50%
        // utilization of channel capacity), and set the pool size to that number.
        InstantiatingGrpcChannelProvider channelProvider =
            InstantiatingGrpcChannelProvider.newBuilder()
                .setChannelPoolSettings(ChannelPoolSettings.staticallySized(30))
                .build();

        PromotionsServiceSettings merchantPromotionsServiceSettings =
            PromotionsServiceSettings.newBuilder()
                .setCredentialsProvider(FixedCredentialsProvider.create(credential))
                .setTransportChannelProvider(channelProvider)
                .build();

        try (PromotionsServiceClient merchantPromotionsServiceClient =
            PromotionsServiceClient.create(merchantPromotionsServiceSettings)) {

          // Arbitrarily creates five merchant promotions with random IDs.
          List<InsertPromotionRequest> requests = new ArrayList<>();
          for (int i = 0; i < 5; i++) {
            InsertPromotionRequest request =
                InsertPromotionRequest.newBuilder()
                    .setParent(String.format("accounts/%s", accountId))
                    .setPromotion(createPromotion(accountId))
                    .setDataSource(String.format("accounts/%s/dataSources/%s", accountId, dataSourceId))
                    .build();
            requests.add(request);
          }

          // Inserts the merchant promotions.
          List<ApiFuture<Promotion>> futures =
              requests.stream()
                  .map(
                      request ->
                          merchantPromotionsServiceClient.insertPromotionCallable().futureCall(request))
                  .collect(Collectors.toList());

          // Creates callback to handle the responses when all are ready.
          ApiFuture<List<Promotion>> responses = ApiFutures.allAsList(futures);
          ApiFutures.addCallback(
              responses,
              new ApiFutureCallback<List<Promotion>>() {
                @Override
                public void onSuccess(List<Promotion> results) {
                  System.out.println("Inserted merchant promotions below:");
                  System.out.println(results);
                }

                @Override
                public void onFailure(Throwable throwable) {
                  System.out.println(throwable);
                }
              },
              MoreExecutors.directExecutor());
        } catch (Exception e) {
          System.out.println(e);
        }
      }


      public static void main(String[] args) throws Exception {
        Config config = Config.load();
        asyncInsertPromotions(config.getAccountId().toString(), "<YOUR_DATA_SOURCE_ID>");
      }
    }

The following are some sample promotions that you can use to get started.

### A local promotion applicable for all products and all stores

The following sample request shows how to create a local promotion that is
applicable for all the products in your Merchant Center account and all
the stores added in your linked
[Business Profile](https://www.google.com/business/) account.

    POST https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert

    {
      "promotion": {
        "promotionId": "buy_2_get_10_off",
        "contentLanguage": "en",
        "targetCountry": "US",
        "redemptionChannel": [
          "IN_STORE"
        ],
        "attributes": {
          "longTitle": "Buy 2 and get 10$ OFF purchase",
          "productApplicability": "ALL_PRODUCTS",
          "offerType": "NO_CODE",
          "couponValueType": "BUY_M_GET_MONEY_OFF",
          "promotionDisplayTimePeriod": {
            "startTime": "2024-2-06T00:47:44Z",
            "endTime": "2024-5-06T00:47:44Z"
          },
          "promotionEffectiveTimePeriod": {
            "startTime": "2024-2-06T00:47:44Z",
            "endTime": "2024-5-06T00:47:44Z"
          },
          "moneyOffAmount": {
            "amountMicros": "1000000",
            "currencyCode": "USD"
          },
          "minimumPurchaseQuantity": 2,
          "storeApplicability": "ALL_STORES",
          "promotionUrl": "http://promotionnew4url.com/",
          "promotionDestinations": [
            "LOCAL_INVENTORY_ADS"
          ],
        }
      },
      "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
    }

The `productApplicability` field is required. It signals the applicability of
the promotion to either all products or only specific ones. The supported values
are `ALL_PRODUCTS` and `SPECIFIC_PRODUCTS`. For more information, see [Choose
products for your promotion](https://support.google.com/merchants/answer/13421476).

The `couponValueType` field is required. It signals the type of promotion that
you are running. For the list of support values, see
[Coupon value type](https://support.google.com/merchants/answer/13861986).
Depending on the type of coupon value you selected,
[some attributes are required](https://support.google.com/merchants/answer/6393006).

The `minimumPurchaseQuantity` field lets you set the value for the minimum
purchase quantity that is required to redeem the promotion offering. For more
information, see
[Minimum purchase quantity for promotion](https://support.google.com/merchants/answer/13838182).

Similarly, you can use the `minimumPurchaseAmount` field to set the minimum
purchase amount that is required to redeem the promotion. For more information,
see [Minimum purchase amount](https://support.google.com/merchants/answer/13837705).

For more information about the values you need to provide for creating a local
promotion, see
[Data source specifications for local promotions](https://support.google.com/merchants/answer/10146130).

### An online promotion applying to selected products with a redemption code

The following sample request shows how to create an online promotion that
applies to selected products with a redemption code.

    POST https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert

    {
     "promotion": {
       "promotionId": "25_pct_off",
       "contentLanguage": "en",
       "targetCountry": "US",
       "redemptionChannel": [
         "ONLINE"
       ],
       "attributes": {
         "longTitle": "10% off on selected items",
         "productApplicability": "SPECIFIC_PRODUCTS",
         "offerType": "GENERIC_CODE",
         "genericRedemptionCode": "SPRINGSALE",
         "couponValueType": "PERCENT_OFF",
         "promotionDisplayTimePeriod": {
           "startTime": "2024-2-06T00:47:44Z",
           "endTime": "2024-5-06T00:47:44Z"
         },
         "promotionEffectiveTimePeriod": {
           "startTime": "2024-2-06T00:47:44Z",
           "endTime": "2024-5-06T00:47:44Z"
         },
         "percentOff": 25,
         "promotionDestinations": [
           "FREE_LISTINGS"
         ],
         "itemIdInclusion": [
           "1499860100",
           "1499860101",
           "1499860102",
           "1499860103",
           "1499860104"
         ],
       }
     },
     "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
    }

## View promotions

To view a promotion, use
[`accounts.promotions.get`](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions/get).
This `GET` request is read-only. It requires your `merchantId` and the ID of the
promotion. The `GET` method returns the corresponding promotions resource.

For example:

### HTTP

    GET https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

### cURL

      curl \
       'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}?key=[YOUR_API_KEY]' \
       --header 'Authorization: Bearer {ACCESS_TOKEN}' \
       --header 'Accept: application/json' \
       --compressed

Replace the following:

- <var translate="no">{ACCOUNT_ID}</var>: The unique identifier of your Merchant Center account.
- <var translate="no">{PROMOTION_ID}</var>: The unique identifier of the promotion you want to retrieve. The format is <var translate="no">{CHANNEL} </var>\~<var translate="no">{CONTENT_LANGUAGE}</var>\~ <var translate="no">{TARGET_COUNTRY}</var>\~<var translate="no">{PROMOTION_ID} </var>.

Note that it takes a few minutes for a newly created promotion to be retrievable
using the API.

### View a local promotion

The following sample request retrieves a local promotion whose promotion ID is
`in_store~en~US~buy_2_get_10_off`.

    GET https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

After the request is successful, you see the following response:

    {
     "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
     "promotionId": "buy_2_get_10_off",
     "contentLanguage": "en",
     "targetCountry": "US",
     "redemptionChannel": [
       "IN_STORE"
     ],
     "attributes": {
       "longTitle": "Buy 2 and get 10$ OFF purchase",
       "productApplicability": "ALL_PRODUCTS",
       "offerType": "NO_CODE",
       "couponValueType": "BUY_M_GET_MONEY_OFF",
       "promotionDisplayTimePeriod": {
         "startTime": "2024-2-06T00:47:44Z",
         "endTime": "2024-5-06T00:47:44Z"
       },
       "promotionEffectiveTimePeriod": {
         "startTime": "2024-2-06T00:47:44Z",
         "endTime": "2024-5-06T00:47:44Z"
       },
       "moneyOffAmount": {
         "amountMicros": "1000000",
         "currencyCode": "USD"
       },
       "minimumPurchaseQuantity": 2,
       "storeApplicability": "ALL_STORES",
       "promotionUrl": "http://promotionnew4url.com/",
       "promotionDestinations": [
         "LOCAL_INVENTORY_ADS"
       ],
     }
     "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
    }

The `moneyOffAmount` field in this sample provides the discount that is offered
in the promotion. For more information, see [Monetary discount amount of a
promotion](https://support.google.com/merchants/answer/13838101).

The `promotionUrl` field in this sample provides the link to the store's website
where shoppers can find more information about the promotion. Local inventory
ads promotions return an error if you don't include the `promotionUrl` field.

### View an online promotion

The following sample request retrieves an online promotion whose promotion ID is
`online~en~US~25_pct_off`.

    GET https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
    {
     "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
     "promotionId": "25_pct_off",
     "contentLanguage": "en",
     "targetCountry": "US",
     "redemptionChannel": [
       "ONLINE"
     ],
     "attributes": {
       "longTitle": "10% off on selected items",
       "productApplicability": "SPECIFIC_PRODUCTS",
       "offerType": "GENERIC_CODE",
       "genericRedemptionCode": "WINTERGIFT",
       "couponValueType": "PERCENT_OFF",
       "promotionDisplayTimePeriod": {
         "startTime": "2024-2-06T00:47:44Z",
         "endTime": "2024-5-06T00:47:44Z"
       },
       "promotionEffectiveTimePeriod": {
         "startTime": "2024-2-06T00:47:44Z",
         "endTime": "2024-5-06T00:47:44Z"
       },
       "percentOff": 25,
       "promotionDestinations": [
         "FREE_LISTINGS"
       ],
       "itemIdInclusion": [
         "1499860100",
         "1499860101",
         "1499860102",
         "1499860103",
         "1499860104"
       ],
     }
     "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
    }

The `itemIdInclusion` field used in this sample mentions the products that are
eligible for the promotion. For more information, see [Product ID for
promotion](https://support.google.com/merchants/answer/13861565).

## List promotions

You can use the
[`promotions.list`](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions/list)
method to view all the created promotions.

Here'a a sample request:

### HTTP

    GET https://merchantapi.googleapis.com/promotions/v1/{ACCOUNT_ID}/promotions

### cURL

      curl \
       'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions?key=[YOUR_API_KEY]' \
       --header 'Authorization: Bearer {ACCESS_TOKEN}' \
       --header 'Accept: application/json' \
       --compressed

The response contains the list of all the promotions in your account. For each
promotion, you can see details like the `promotionId`, `redemptionChannel`,
`dataSource`, `promotionStatus`, and more.

## View the status of a promotion

To see a promotion's status, see the `promotionStatus` attribute returned by the
[`promotions.get`](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions/get)
or
[`promotions.list`](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions/list)
method.

The `promotionStatus` field can have the following values:

- `IN_REVIEW`: The promotion is still in review.
- `REJECTED`: The promotion is disapproved.
- `LIVE`: The promotion is approved and active.
- `STOPPED`: The promotion is stopped by the account.
- `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.
- `STATE_UNSPECIFIED`: Unknown promotion state.

To understand the approval process for a promotion that you created, see
[Promotion approval
process](https://support.google.com/merchants/answer/4588464).

### Sample promotion status

The following samples demonstrate the difference between successful and failing
requests.

**Missing product mapping**

The following response body shows an online promotion that is disapproved due to
missing product mapping.

      "promotionStatus": {
        "destinationStatuses": [
          {
            "reportingContext": "FREE_LISTINGS",
            "status": "REJECTED"
          }
        ],
        "itemLevelIssues": [
          {
            "code": "promotion_sku_unmapped",
            "severity": "DISAPPROVED",
            "resolution": "merchant_action",
            "reportingContext": "FREE_LISTINGS",
            "description": "Unmapped",
            "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
            "documentation": "https://support.google.com/merchants/answer/2906014",
            "applicableCountries": [
              "US"
            ]
          },
          {
            "code": "promotion_sku_additional_requirements",
            "severity": "DISAPPROVED",
            "resolution": "merchant_action",
            "reportingContext": "FREE_LISTINGS",
            "description": "Promotion conditions not allowed",
            "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
            "documentation": "https://support.google.com/merchants/answer/2906014",
            "applicableCountries": [
              "US"
            ]
          }
        ]
      }

For troubleshooting disapproved promotions and to learn how to avoid future
disapprovals, see [Fix issues with disapproved
promotions](https://support.google.com/merchants/answer/13511381).

If a promotion you created isn't approved, you receive an email mentioning the
reason of rejection and instructions to fix the issues.

**Promotion under evaluation**

The following response body shows a promotion that is still being evaluated.

      "promotionStatus": {
        "destinationStatuses": [
          {
            "reportingContext": "FREE_LISTINGS",
            "status": "PENDING"
          },
          {
            "destination": "SHOPPING_ADS",
            "status": "PENDING"
          }
        ],
        "itemLevelIssues": []
      }

**An approved and live promotion**

The following response body shows a promotion that is visible to shoppers.

      "promotionStatus": {
        "destinationStatuses": [
          {
            "reportingContext": "FREE_LISTINGS",
            "status": "LIVE"
          },
          {
            "destination": "SHOPPING_ADS",
            "status": "LIVE"
     }  ],
        "itemLevelIssues": []
      }

For more information, see
[Promotion status FAQs](https://support.google.com/merchants/answer/13509015).

## Delete promotions

It isn't possible to delete a promotion using the API. To delete a promotion,
you will need to access the Merchant Center UI. For more
information, see
[Edit a promotion or change promotion status](https://support.google.com/merchants/answer/13506134).

To end an existing promotion, you can use the
[accounts.promotions.insert](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions/insert)
method to update the `attributes.promotionEffectiveTimePeriod.endTime` field to
a time in the past.

## Learn more

- For more details, see the [Promotions Help
  Center](https://support.google.com/merchants/topic/7299375).
- To troubleshoot common issues, see [Troubleshoot issues related to
  Promotions sub-API](https://developers.google.com/merchant/api/guides/promotions/troubleshooting).
- To learn about migrating from Content API for Shopping, see [Migrate
  promotions management](https://developers.google.com/merchant/api/guides/compatibility/promotions).