Direct API calls

In this approach to interacting with Merchant API make raw requests to the API endpoints directly, typically over HTTP(S). You manually handle aspects like forming the request body, setting headers (including authentication), and parsing the response.

Step 1. Register as a developer

To use Merchant API, you must register your developer contact information.

Registration accomplishes the following:

Creates a technical contact for your Merchant Center account by assigning the API developer role to a user. This lets Google send important updates specifically about the API and the features the developer is using, such as service announcements and information about new features, that might be of less interest to non-developers.
Lets you work with multiple merchant accounts without having to register multiple times. When you register, the Google Cloud project ID used to authenticate to the Merchant API is associated with your Merchant Center account, which has the technical contacts (the API developers). This way, you can get important updates for all the merchant accounts you manage as long as the authentication is done with the registered Google Cloud project.

When registering, observe the prerequisites and restrictions detailed at Registration.

To register using the developerRegistration.registerGcp method, you can start with this example, replacing {DEVELOPER_EMAIL} with the appropriate email address in the request body.

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

{
  "developerEmail": "{DEVELOPER_EMAIL}"
}

A successful call returns a DeveloperRegistration resource, which confirms the link between your project and your account.

{
  "name": "accounts/{ACCOUNT_ID}/developerRegistration",
  "gcpIds": [
    "123456789012345"
  ]
}

Step 2. Manage developer contacts and permissions

When you register:

If the email address belongs to a user in the Merchant Center account, that user is granted the API_DEVELOPER role.
If the email address doesn't belong to an existing user, an invitation is sent to that address. The recipient must accept the invitation to be added as a new user with the API_DEVELOPER role.

After the initial registration, we recommend that you add multiple developers and grant them additional access rights.

Step 2a. Grant additional permissions

The API_DEVELOPER role is required to receive important notifications, but it has minimal permissions within Merchant Center. To allow this user to make other API calls or manage settings in the Merchant Center UI, you need to grant them additional roles, such as STANDARD or ADMIN. For more information, see Access types.

You can update a user's access rights with the accounts.users.patch method.

The following example shows how to update a user to grant them both ADMIN and API_DEVELOPER roles. This lets them fully manage the account and they will also receive API-related communications.

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/users/{DEVELOPER_EMAIL}?update_mask=access_rights

{
  "access_rights": [
    "ADMIN",
    "API_DEVELOPER"
  ]
}

Step 2b. Add backup developers

To prevent your API access from being disrupted if your primary developer contact leaves your organization, you should add at least one backup developer.

You can add a user with the accounts.users.create method or update one with accounts.users.patch. We recommend giving this user both the ADMIN and API_DEVELOPER roles.

Step 3. Create a primary products data source

To insert a product, you need a primary products data source. The following request shows how to create a data source you can use to insert a product to your account:

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

{
  "primaryProductDataSource": {
    "contentLanguage": "en",
    "countries": [
      "US"
    ],
    "feedLabel": "US"
  },
  "name": "primary-data-source",
  "displayName": "Primary Products Data Source"
}

Replace {ACCOUNT_ID} with the ID of the Merchant Center account you created.

After you run this request successfully, you should see the following response:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "Primary Products Data Source",
  "primaryProductDataSource": {
    "feedLabel": "US",
    "contentLanguage": "en",
    "countries": [
      "US"
    ],
    "defaultRule": {
      "takeFromDataSources": [
        {
          "self": true
        }
      ]
    }
  },
  "input": "API"
}

Copy the value of the name field. You will need it to insert a product.

You can view this data source in the Merchant Center UI. For more information, see How to find the Data sources tab.

Step 4. Insert a product

Once you create the data source, try to insert a product into it. Run the following, supplying the correct ACCOUNT_ID. Replace {DATASOURCE_NAME} with the value you copied earlier.

POST https://merchantapi.googleapis.com/products/v1/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource={DATASOURCE_NAME}
{
  "contentLanguage": "en",
  "feedLabel": "US",
  "name": "Red T-shirt",
  "productAttributes": {
    "gender": "MALE",
    "brand": "New brand"
  },
  "offerId": "tshirt-123"
}

After you run this request successfully, you should see the following response:

{
  "name": "accounts/{ACCOUNT_ID}/productInputs/en~US~tshirt-123",
  "product": "accounts/{ACCOUNT_ID}/products/en~US~tshirt-123",
  "offerId": "tshirt-123",
  "contentLanguage": "en",
  "feedLabel": "US",
  "productAttributes": {
    "brand": "New brand",
    "gender": "MALE"
  }
}

The product ID for the newly created product is en~US~tshirt-123. You can use the accounts.products.get method to retrieve details about this product. You can also use the Merchant Center UI to view this product. See View your product data.

Overview

Client libraries