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](https://developers.google.com/merchant/api/guides/quickstart/registration#prerequisites)
of the [Register as a developer](https://developers.google.com/merchant/api/guides/quickstart/registration)
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](https://cloud.google.com/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](https://console.cloud.google.com/). For detailed instructions, see [Create a Google Cloud project](https://developers.google.com/merchant/api/guides/quickstart/create-project).
2. Enable the **Merchant API** (`merchantapi.googleapis.com`) in the new project. See [Enable Merchant API](https://developers.google.com/merchant/api/guides/quickstart/create-project#merchant-api) section from [Create a Google Cloud project](https://developers.google.com/merchant/api/guides/quickstart/create-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`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.developerRegistration/registerGcp)
method to link the new project to your primary Merchant Center account. For
detailed instructions, see
[Make the registration call](https://developers.google.com/merchant/api/guides/quickstart/registration#make-registration)
section from
[Register as a developer](https://developers.google.com/merchant/api/guides/quickstart/registration).

### 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`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.developerRegistration/getDeveloperRegistration)
method:

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

Replace the following:

- <var translate="no">`ACCOUNT_ID`</var>: your Merchant Center ID
- <var translate="no">`ACCESS_TOKEN`</var>: the authorization token to make the API call

The response returns the
[`DeveloperRegistration`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/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`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.developerRegistration/getAccountForGcpRegistration)
method:

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

Replace the following:

- <var translate="no">`ACCESS_TOKEN`</var>: 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`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/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:

- <var translate="no">`ACCOUNT_ID`</var>: your Merchant Center ID
- <var translate="no">`OLD_PROJECT_ACCESS_TOKEN`</var>: 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"

> [!NOTE]
> **Note:** After you call `unregisterGcp`, the unregistered Google Cloud project can continue to access the Merchant API for up to 1 day before requests are blocked. If you lost access to the old Google Cloud project and cannot call `unregisterGcp`, leaving the old project ID in `gcpIds` does not affect your new project.

### 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](https://developers.google.com/merchant/api/guides/quickstart/registration#important-considerations):

1. Authenticate using credentials from the Google Cloud project that have access to `OLD_ACCOUNT_ID` and call [`unregisterGcp`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.developerRegistration/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`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.developerRegistration/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](https://console.cloud.google.com/)
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`)

> [!NOTE]
> **Note:** If your engineering team has lost owner or administrative access to the project, contact [Google Cloud Support](https://cloud.google.com/support) directly for assistance with recovering project access.

1. **Enable the Merchant API:** Enable `merchantapi.googleapis.com` in the [Google Cloud API Library](https://console.cloud.google.com/apis/library/merchantapi.googleapis.com) or with the `gcloud` command. For step-by-step instructions, see [Configure API authentication from Merchant Center](https://developers.google.com/merchant/api/guides/compatibility/configure-api-authentication).
2. **Register the Google Cloud project with Merchant Center:** Follow the steps in the [Register as a developer](https://developers.google.com/merchant/api/guides/quickstart/registration) guide to authorize requests from your existing project and call the [`registerGcp`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.developerRegistration/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](https://developers.google.com/merchant/api/guides/quickstart/registration) to authorize requests from your new project and call the [`registerGcp`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.developerRegistration/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](https://developers.google.com/shopping-content/guides/deprecation-and-sunset#sunset_timetable) (or before your approved extension expires), and retire the old project once your migration is complete.

> [!NOTE]
> **Note:** Because your new Google Cloud project is used **exclusively** for the Merchant API, you **don't** need to enable the Content API for Shopping or request a shutdown extension for the new project ID.

### 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](https://cloud.google.com/support) to recover access to your existing Google Cloud project ([Option 1](https://developers.google.com/merchant/api/guides/accounts/manage-transition-gcp-projects#option-1-keep-existing-project)), or
2. Follow [Option 2](https://developers.google.com/merchant/api/guides/accounts/manage-transition-gcp-projects#option-2-split-projects) 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](https://developers.google.com/merchant/api/support/get-help#merchant_api_support_team).

## Next steps

- Learn more about developer registration requirements in [Register as a developer](https://developers.google.com/merchant/api/guides/quickstart/registration) and the [Developer registration FAQ](https://developers.google.com/merchant/api/guides/quickstart/faq).
- Review how legacy credentials behave in [Configure API authentication from Merchant Center](https://developers.google.com/merchant/api/guides/compatibility/configure-api-authentication).
- Plan your sub-API rollout with [Start your migration](https://developers.google.com/merchant/api/guides/compatibility/start-migration).
- Find details on Content API for Shopping extended access in [Request a migration extension](https://developers.google.com/merchant/api/support/get-help#request-extension).