Overview of Merchant API

This page provides an introduction to Merchant API and explains how you can use it to automate various workflows related to managing accounts, products, and inventories on Merchant Center.

You can use Merchant API to reach more customers and showcase your products across Google. You can use Merchant API for managing large or complex Merchant Center accounts. Some typical use cases include the following:

  • Automated account management
  • Automated product management
  • Automated inventory management
  • Custom reporting

Merchant API lets you create and manage multiple data sources, enabling better organization of information about products, promotions, and reviews. With Merchant API, you can manage products in a way that complements other product data upload methods like files and autofeed. Merchant API also lets you run multiple individual requests in parallel.

The Merchant API is a redesign of the Content API for Shopping, and it comprises of multiple sub-APIs.

Retailers are responsible for complying with the Shopping ads and free listings policies. Google Shopping reserves the right to enforce these policies and respond appropriately if we find content or behavior that violates these policies.

What's new in Merchant API

Here are some reasons to upgrade to the Merchant API:

For more information, see New features introduced in Merchant API Beta.

Before you start

To run a Merchant API request, you must have the following:

  • A Merchant Center account: This is the account you will be querying, updating, and uploading data to. Make sure that you have the necessary permissions to manage products and inventories on this account.

  • A Google Cloud project: The project is used for getting API access to your account.

Authentication with Merchant API

You can use the following options for authentication:

  • You can generate an OAuth 2.0 client ID and secret for your app. The ID and secret can then be used to generate the OAuth 2.0 credentials needed in API calls to the Merchant Center account.
  • You can create a service account and download its private key to make API calls.

Account and product identifiers

Merchant API uses resource names instead of IDs for identification. An example resource name for a product can be accounts/123456/products/online~en~US~sku123, where 123456 is the unique identifier of the account and online~en~US~sku123 is the unique identifier of the product.

Request URL format

To operate on a resource, send requests to URLs in the following format:

https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}

The :{METHOD} part is omitted for standard methods like list and get.

For example, the following request deletes the regional inventory:

DELETE https://merchantapi.googleapis.com/inventories/v1beta/accounts/123456/products/online~en~US~sku123/regionalInventories/456

To create a new resource, you can use the resource name of the parent resource and the following URL:

POST https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME_OF_PARENT}/{RESOURCE}

For example, the following request shows how you can create a new region for accounts/123456:

POST https://merchantapi.googleapis.com/accounts/v1beta/accounts/123456/regions?regionId=WA HTTP/1.1

{
  "displayName": "Washington",
  "name": "Washington",
  "postalCodeArea": {
    "postalCodes": [
      {
        "begin": "98039",
        "end": "98118"
      }
    ],
    "regionCode": "US"
  }
}

For more details about specific services, see the Merchant API reference documentation.

Get started with using the Merchant API

To quickly see how Merchant API works and try uploading a sample product, see Get started with Merchant API.

Use gRPC or REST

The Merchant API supports gRPC and REST. Here are the two ways to make Merchant API calls:

gRPC (recommended) REST
  1. Create the body of the request as a protocol buffer.
  2. Send the request body to the server with HTTP/2.
  3. Deserialize the response to a protocol buffer.
  4. Interpret the results.
  1. Create the body of request as a JSON object.
  2. Send it to the server using HTTP 1.1.
  3. Deserialize the response as a JSON object.
  4. Interpret the results.

Use client libraries and code samples

Each sub-API has client libraries to help you get started. Code samples can help you get started with writing code in Java, PHP, and Python. For more information, see Samples for Merchant API.

Get help

For information about getting support, see Get help with Merchant API.

Give feedback

The beta period gives us an opportunity to collect and address your feedback before the general availability release. To provide feedback, submit one of the following:

  • API features: Submit the feedback form
  • Documentation: Use the in-page thumb ratings and Send feedback button.
  • Samples and libraries: Create an issue on the GitHub repository for the code samples.

To provide general feedback after implementing each task, use the feedback form.

What's next

Next
Design