You can use the Merchant Promotions API to create and manage promotions on
Google. The
[`accounts.promotions`](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions)
resource lets you showcase special offers for the products you sell on Google.
For more information, see [Overview of Merchant Promotions
API](https://developers.google.com/merchant/api/guides/promotions/overview).

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

## Overview of changes from Content API for Shopping to Merchant API

A significant difference is that Content API for Shopping automatically
creates the data source upon the first promotion insertion, which doesn't
occur with Merchant API. To insert a promotion using Merchant API, you first
need to [create a promotions data source](https://developers.google.com/merchant/api/guides/promotions/overview#create-data-source).

> [!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).

For information about the fields in the `promotionDataSource` object in
`accounts.dataSources` resource, see [PromotionDataSource](https://developers.google.com/merchant/api/reference/rest/datasources_v1/accounts.dataSources#promotiondatasource).

### Existing data sources

For existing data sources, if you don't know your
[`accounts.dataSources.name`](https://developers.google.com/merchant/api/reference/rest/datasources_v1/accounts.dataSources#DataSource.FIELDS.name),
use
[`dataSources.list`](https://developers.google.com/merchant/api/reference/rest/datasources_v1/accounts.dataSources/list)
to retrieve it.

Alternatively, you can identify the data source for each of your promotions by
using the
[`accounts.promotions.get`](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions/get)
method and inspecting the
[`dataSource`](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions#Promotion.FIELDS.data_source)
field in the response of any existing promotions within your account.

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.

## Requests

To make requests, use the following URL.

    POST https://merchantapi.googleapis.com/promotions/v1/{ACCOUNT_NAME}/promotions

## Migrate from Content API for Shopping

The following compares the Content API for Shopping to the Merchant Promotions
API for promotions-related requests.

### URL

In the Content API for Shopping:

    https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/promotions

in Merchant API becomes:

    https://merchantapi.googleapis.com/promotions/v1/{parent=accounts/*}/promotions

### Identifiers

In the Content API for Shopping:

    {MERCHANT_ID}/promotions/{PROMOTION_ID}

in Merchant API becomes:

    {NAME}

### Methods

The Merchant API supports the following methods for promotions:

- Insert promotions
- Get promotions
- List promotions

Here's a comparison of promotion methods availability in the Content API for
Shopping and the Merchant API:

| Feature | Content API for Shopping | Merchant API |
|---|---|---|
| **URL** | `https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/promotions` | `https://merchantapi.googleapis.com/promotions/v1/{parent=accounts/*}/promotions` |
| **Identifiers** | `{MERCHANT_ID}/promotions/{PROMOTION_ID}` | `{NAME}` |
| **Methods** | - `insert` - `get` - `list` - `customBatch` - `delete` | - `insert` - `get` - `list` |

### Field Changes

The table shows what changes for Promotions in the Merchant Promotions API.

To see an example for reference, see
[accounts.promotions](https://developers.google.com/merchant/api/reference/rest/promotions_v1/accounts.promotions).

| Content API for Shopping | Merchant API | Description |
|---|---|---|
| (not supported) | **custom_attributes** | A list of custom (user-provided) attributes. You can also use it to submit any attribute of the feed specification in its generic form. For example: ``` { "name": "size type", "value": "regular" } ``` This is useful for submitting attributes not explicitly exposed by the API. |
| Not supported | **data_source** | Creating a promotion requires an existing data source. |
| Not supported | **attributes** | Promotion specific attributes, for example, **long_tile** , **promotion_effective_timeperiod** , and others, are part of the attribute message. |
| **item_id** | **item_id_inclusion** | The list of item IDs that a promotion applies to is renamed. |
| **store_id** | **store_id_inclusion** | The list of store IDs that a promotion applies to is renamed. |
| **product_type** | **product_type_inclusion** | The list of product types that a promotion applies to is renamed. |
| **item_group_id** | **item_group_id_inclusion** | The list of item group IDs that a promotion applies to is renamed. |
| **brand** | **brand_inclusion** | The list of brands that a promotion applies to is renamed. |
| **store_code** | **store_codes_inclusion** | The list of store codes that a promotion applies to is renamed. |
| ``` price: { object (Price) } ``` | ``` price: { object (Price) } ``` | The definition of [**Price**](https://developers.google.com/merchant/api/guides/compatibility/overview#price) has changed. In the Content API for Shopping, **Price** was a decimal number in the form of a string. The **Price** amount is now recorded in micros, where 1 million micros is equivalent to your currency's standard unit. The **amount** field name has changed from value to **amountMicros.** The **currency** field name has changed to **currencyCode** . The format remains as [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217). (Wikipedia) |
| **order_limit** | (not supported) | The **order_limit** attribute is not supported. |
| **shippingServiceNames\[\]** | (not supported) | **shippingServiceNames\[\]** is not supported. |
| **money_budget** | (not supported) | **money_budget** is not supported. |
| **promotion_destination_ids** | **promotion_destinations** | **promotionDestinationIds** is renamed. |
| **Promotion Status** ``` { "destinationStatuses": [ { "destination": string, "status": enum (State) } ], "promotionIssue": [ { "code": string, "detail": string } ], "creationDate": string, "lastUpdateDate": string } ``` | [**Promotion Status**](https://developers.google.com/shopping-content/reference/rest/v2.1/promotions#promotionstatus) has changed. More granular-level details are available in the issues. ``` promotionStatus = { destinationStatuses = [ { reportingContext = Enum status = Enum }, ], itemLevelIssues = [ { code = String severity = Enum resolution = String reportingContext = Enum description = String detail = String documentation = String applicableCountries = [ String, ] } ] } ``` ||