Content API for Shopping compatibility

You can use this guide to integrate the Merchant API closed beta with your existing Content API for Shopping implementation.

Get started

See the Merchant API design for details about the Merchant API, and its sub-APIs.

To start using the Merchant API, change your request URLs to the following format:

https://merchantapi.googleapis.com/{sub-API}/{version}/{resource name}/{service}:{method}…

See the quickstart guide and the Merchant API reference for more information.

gRPC support

The Merchant API supports gRPC and REST. You can use gRPC for the Merchant API and REST for the Content API for Shopping at the same time.

The Merchant API client libraries require gRPC.

See use gRPC for more information.

Compatibility

This guide describes general changes that apply to the entire Merchant API. See the following guides for changes to specific features:

• Migrate inventories
• Migrate reporting

The Merchant API is designed to work alongside existing Content API for Shopping v2.1 features.

For example, you can use the Merchant Inventories API alongside your existing Content API for Shopping v2.1 inventories and products implementation. You might use the Content API for Shopping to upload a new local product (that you sell in a local store), then use the Merchant Inventories API LocalInventory resource to manage in-store information for that product.

Note: We can't guarantee full backwards compatibility for similar features between the Content API for Shopping and the Merchant API due to the improved design. For example, field names or method availability might differ for the same resource in the Content API for Shopping and the Merchant API.

Batch requests

The Merchant API doesn't support the customBatch method featured in the Content API for Shopping. Instead, see Send batch requests. If you use customBatch, and need this feature for the Merchant API, let us know why in your feedback.

Identifiers

To align with Google's API improvement principles, we've made some changes to the identifiers for Merchant API resources.

name replaces Id

All Merchant API resources use the name field as their unique identifier.

Here's an example of how to use the name field in your calls:

POST https://merchantapi.googleapis.com/inventories/v1beta/{parent}/regionalInventories:insert

This new name field is returned as the resource identifier for all read and write calls in the Merchant API.

The value returned in name fields uses the new ID format.

Important: We recommend using the value from the name field directly in your calls, instead of parsing or manually constructing a resource's name to avoid issues.

For example, implement a getName() method to retrieve the name from a resource, and store the output as a variable instead of constructing the name from the merchant and resource IDs yourself.

New ID format

Note: The Merchant API will return IDs without a channel value until November 13, 2023. After November 13th, all calls will return the full resource ID. You must use the full resource ID, including channel, in your calls by February 1, 2024.

In the Merchant API, resource IDs use the following format: channel~language~feedLabel~offerId

Content API resources used : instead of ~ between each value in the ID: channel:language:feedLabel:offerId

All Merchant API calls return the new format with ~ between the values of the ID. We recommend storing the new format from the response and using it in your future calls.

parent fields for child resources

In the Merchant API, all child resources have the parent field. You can use the parent field to specify the name of the resource to insert the child to, instead of passing the entire parent resource. You can also use the parent field with list methods to list the child resources of that parent.

For example, to list local inventories for a given product, specify the product's name in the parent field for the list method. In this case, the given product is the parent of the LocalInventory resources returned.

Types

Here are some common types shared across the Merchant API sub-APIs.

Price

Here's what's changed for Price in the Merchant Common package:

	Content API	Merchant API
Amount field	value:string	amountMicros:int64
Currency field	currency:string	currencyCode:string

The Price amount is now recorded in micros, where 1 million micros is equivalent to your currency's standard unit.

In the Content API for Shopping, Price was a decimal number in the form of a string.

The amount field name has changed from value to amountMicros

The currency field name has changed from currency to currencyCode. The format remains as ISO 4217.