Manage and transition Google Cloud projects

To use the Merchant API, you must link your Google Cloud project to your primary Merchant Center account through developer registration. Over the lifecycle of your integration, you might need to change the Google Cloud project ID associated with your Merchant Center account, manage multiple projects across environments, or transition projects when migrating from the Content API for Shopping.

This guide explains how to:

  • Change or rotate the Google Cloud project ID for an existing Merchant API integration without downtime.
  • Unregister a Google Cloud project from one Merchant Center account and register it with a different Merchant Center account.
  • Choose and execute the right Google Cloud project transition strategy if you are migrating from the Content API for Shopping to the Merchant API.

Prerequisites

Before managing or transitioning Google Cloud projects, verify that you meet the developer registration prerequisites. For more details, see the Prerequisites section of the Register as a developer guide.

Key rules and limitations

When planning changes to your Google Cloud projects, keep the following rules in mind:

  • One-to-many project registration: A single primary Merchant Center account can have multiple Google Cloud projects registered to it simultaneously. However, each Google Cloud project can be registered to only one primary Merchant Center account at any given time. Attempting to register a project that is already linked to another Merchant Center account returns an ALREADY_EXISTS (409 Conflict) error with reason DUPLICATE_PROJECT_REGISTRATION.
  • Project ownership privacy: For security and privacy reasons, Google Shopping and Merchant API support cannot disclose the owner or administrator email addresses of a Google Cloud project. If you lose access to a project, contact Google Cloud Support.
  • Content API for Shopping shutdown extensions are project-specific: If you received an extended access approval for the Content API for Shopping, that extension applies only to the specific Google Cloud project ID submitted in your request. Extensions don't transfer automatically to new Google Cloud projects.

Change the Google Cloud project ID for a Merchant API account

If you already use the Merchant API and need to switch your integration to a new Google Cloud project—for example, due to organizational restructuring, credential rotation policies, or lost administrative access to an older project—you can transition projects without downtime. Because a Merchant Center account supports multiple registered Google Cloud projects simultaneously, you can register the new project before retiring the old one.

Step 1: Create and configure your new Google Cloud project

  1. Create a new project in the Google Cloud console. For detailed instructions, see Create a Google Cloud project.
  2. Enable the Merchant API (merchantapi.googleapis.com) in the new project. See Enable Merchant API section from Create a Google Cloud project.
  3. Create authentication credentials (a service account or an OAuth 2.0 client ID) in the new Google Cloud project.
  4. Add the authenticating email address (such as the new service account email) as a user with the ADMIN role in your primary Merchant Center account.

Step 2: Register the new Google Cloud project

Authenticate using credentials from your new Google Cloud project and call the accounts.developerRegistration.registerGcp method to link the new project to your primary Merchant Center account. For detailed instructions, see Make the registration call section from Register as a developer.

Step 3: Verify your registered Google Cloud projects

To confirm that both your existing and new Google Cloud projects are linked to your Merchant Center account, call the accounts.developerRegistration.getDeveloperRegistration method:

GET https://merchantapi.googleapis.com/accounts/v1/accounts/ACCOUNT_ID/developerRegistration
Authorization: Bearer ACCESS_TOKEN

Replace the following:

  • ACCOUNT_ID: your Merchant Center ID
  • ACCESS_TOKEN: the authorization token to make the API call

The response returns the DeveloperRegistration resource with the numeric Google Cloud project numbers of all linked projects in the gcpIds field:

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

You can also verify which Merchant Center account the calling Google Cloud project is registered with by calling the accounts.developerRegistration.getAccountForGcpRegistration method:

GET https://merchantapi.googleapis.com/accounts/v1/accounts:getAccountForGcpRegistration
Authorization: Bearer ACCESS_TOKEN

Replace the following:

  • ACCESS_TOKEN: the authorization token generated using credentials from the Google Cloud project you want to check

Step 4: Switch traffic and unregister the old Google Cloud project

  1. Update your application configuration to use the credentials from your new Google Cloud project. Because both projects are registered, your workloads transition without interruption.
  2. Once all traffic uses the new project, you can optionally remove the old project link by authenticating with the old Google Cloud project credentials and calling the accounts.developerRegistration.unregisterGcp method:
POST https://merchantapi.googleapis.com/accounts/v1/accounts/ACCOUNT_ID/developerRegistration:unregisterGcp
Content-Type: application/json
Authorization: Bearer OLD_PROJECT_ACCESS_TOKEN

Replace the following:

  • ACCOUNT_ID: your Merchant Center ID

  • OLD_PROJECT_ACCESS_TOKEN: the authorization token from the old Google Cloud project to make the API Call

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.DeveloperRegistrationName;
import com.google.shopping.merchant.accounts.v1.DeveloperRegistrationServiceClient;
import com.google.shopping.merchant.accounts.v1.DeveloperRegistrationServiceSettings;
import com.google.shopping.merchant.accounts.v1.UnregisterGcpRequest;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/**
 * This class demonstrates how to unregister the GCP project currently used to call the Merchant API
 * for a specific account.
 */
public class UnregisterGcpSample {

  public static void unregisterGcp(Config config) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    DeveloperRegistrationServiceSettings developerRegistrationServiceSettings =
        DeveloperRegistrationServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates DeveloperRegistration name to identify the DeveloperRegistration.
    // The name has the format: accounts/{account}/developerRegistration
    String name =
        DeveloperRegistrationName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .build()
            .toString();

    // Calls the API and propagates any network failures/errors.
    try (DeveloperRegistrationServiceClient developerRegistrationServiceClient =
        DeveloperRegistrationServiceClient.create(developerRegistrationServiceSettings)) {

      // Creates a request to unregister the GCP project.
      UnregisterGcpRequest request = UnregisterGcpRequest.newBuilder().setName(name).build();

      System.out.println("Sending UnregisterGcp request for: " + name);
      developerRegistrationServiceClient.unregisterGcp(request);
      System.out.println("Unregister GCP successful.");
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    unregisterGcp(config);
  }
}

cURL

curl -X POST \
  "https://merchantapi.googleapis.com/accounts/v1/accounts/ACCOUNT_ID/developerRegistration:unregisterGcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OLD_PROJECT_ACCESS_TOKEN"

Reassign a registered Google Cloud project to a different Merchant Center account

Because a Google Cloud project can be registered to only one primary Merchant Center account at a time, follow these steps to reassign an existing project from one Merchant Center account (OLD_ACCOUNT_ID) to another (NEW_ACCOUNT_ID). For guidelines on choosing which Merchant Center account to register your project with, see Important considerations:

  1. Authenticate using credentials from the Google Cloud project that have access to OLD_ACCOUNT_ID and call unregisterGcp on accounts/OLD_ACCOUNT_ID/developerRegistration.
  2. Verify that the authenticating identity has the ADMIN role on NEW_ACCOUNT_ID and that NEW_ACCOUNT_ID has a verified website.
  3. Call registerGcp on accounts/NEW_ACCOUNT_ID/developerRegistration using credentials from the same Google Cloud project. If NEW_ACCOUNT_ID doesn't yet have a user with the API_DEVELOPER role, pass a valid user email in the developerEmail request field. Service account emails ending in .gserviceaccount.com can't be used as the developerEmail.

Transition Google Cloud projects when migrating from Content API for Shopping

When migrating from the Content API for Shopping to the Merchant API, you might encounter access limitations on your legacy Google Cloud project—for instance, if your original API keys were configured directly through the legacy Merchant Center authentication workflow or if the original project owner left your organization.

Depending on whether you want to keep your existing project or use a new project for Merchant API while keeping Content API for Shopping on your old project, choose one of the following two options.

Choose your migration project strategy

Scenario Admin access to old project required? APIs to enable Content API for Shopping extension required on new project?
Option 1: Keep your existing project Yes (or recover through Google Cloud Support) Enable Merchant API on the existing project (Content API for Shopping is already enabled) No (existing extension on old project ID remains valid)
Option 2: Keep old project for Content API for Shopping and use a new project for Merchant API No Enable Merchant API on the new project (keep Content API for Shopping enabled on the old project) No (the old project retains its extension; the new project calls only Merchant API)

Option 1: Keep your existing Google Cloud project

Choose this option if you want to use your existing Google Cloud project for both the Content API for Shopping and the Merchant API.

Before beginning, verify or recover access to your existing project. Sign in to the Google Cloud console and confirm that your account holds any of the following roles on your existing project:

  • Owner (roles/owner),
  • Editor (roles/editor)
  • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
  1. Enable the Merchant API: Enable merchantapi.googleapis.com in the Google Cloud API Library or with the gcloud command. For step-by-step instructions, see Configure API authentication from Merchant Center.
  2. Register the Google Cloud project with Merchant Center: Follow the steps in the Register as a developer guide to authorize requests from your existing project and call the registerGcp method to link your existing Google Cloud project to your primary Merchant Center account. Your existing service account keys and approved Content API for Shopping extension continue to work without changes.

Option 2: Use the old Google Cloud project for Content API for Shopping and a new project for Merchant API

Choose this option if your legacy Content API for Shopping integration is already running with valid credentials and an approved extension on your old Google Cloud project, and you want to build your new Merchant API integration in a separate, dedicated Google Cloud project:

  1. Keep your Content API for Shopping integration on the old project: Leave your existing Content API for Shopping workflows and credentials running on the old Google Cloud project. If your extension request for the old project ID was approved, your current Content API for Shopping integration continues working through the extended deadline.
  2. Create a new Google Cloud project exclusively for Merchant API: Create a new Google Cloud project, enable merchantapi.googleapis.com, and create credentials (a service account or OAuth 2.0 client ID) for your new Merchant API workloads.
  3. Register the new project: Follow the steps in Register as a developer to authorize requests from your new project and call the registerGcp method with a valid developer contact email. Service account emails (ending in .gserviceaccount.com) can't be used as the developerEmail.
  4. Migrate workloads incrementally: Shift API calls from your old Content API for Shopping project to your new Merchant API project gradually, before the Content API for Shopping scheduled sunset date (or before your approved extension expires), and retire the old project once your migration is complete.

Special case: Lost access to your old Google Cloud project before completing migration

Because the Content API for Shopping is deprecated, it is no longer listed in the Google Cloud API Library and cannot be enabled on newly created Google Cloud projects. As a result, you cannot move existing Content API for Shopping workloads to a new Google Cloud project on your own.

If you can no longer make Content API for Shopping calls from your old project (for example, due to revoked credentials or unrecoverable project access):

  1. Contact Google Cloud Support to recover access to your existing Google Cloud project (Option 1), or
  2. Follow Option 2 to create and register a new Google Cloud project and migrate the affected workflows directly to the Merchant API. If you encounter a critical migration blocker, contact Merchant API support.

Next steps

Previous
Verify your account's connection to Merchant API