Content API for Shopping compatibility

You can use this guide to integrate Merchant API 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 accounts management
• Migrate shipping settings
• Migrate products management
• Migrate data sources management
• Migrate inventories management
• Migrate promotions management
• Migrate reporting management
• Migrate conversion sources management
• Migrate local feeds partnership management

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.

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.

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

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:

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.