Create and install a Custom Application

Overview

The Merchant Center includes several built-in applications by default for managing entities such as Products, Categories, and Customers. While these applications offer robust functionality, you may encounter use cases that they do not cover. In such cases, you can extend the Merchant Center using a customization—either a Custom Application or a Custom View.

Custom Applications and Custom Views offer distinct user experiences and are suited for different use cases. We recommend that you read the Merchant Center Customizations overview before starting this tutorial to understand how each customization type works within the Merchant Center.

In this tutorial, we'll walk you through how to create and install a Custom Application in the Merchant Center.

Learning goal

At the end of this tutorial, you will have a Custom Application that is:

• Hosted on Vercel.
• Accessible in the Merchant Center for your specific Organization and team(s).
• Displays Channels from your Composable Commerce Project.

To get you there, we'll help you set up your development environment, deploy your Custom Application to Vercel, and configure and install it in the Merchant Center. Once installed, you will be able to access your Custom Application from the Merchant Center main menu.

Prerequisites

Before you start, make sure that you have the following:

• A Merchant Center account

• A commercetools Composable Commerce Project with a few Channels added to it

• A Vercel account

• Basic knowledge of React as well as some experience working with web applications

• Node.js installed (version 18.x, recommended >=20)

• A Node.js package manager such as yarn, pnpm, or npm

  Yarn PnP is not supported.

Instructions

Create the Custom Application

To get started, open your terminal of choice and create a Custom Application using the create-mc-app package. This package automatically sets up a pre-configured starter template.

npx @commercetools-frontend/create-mc-app@latest \
  my-new-custom-application-project \
  --template starter

You may be prompted to install the latest version of the @commercetools-frontend/create-mc-app package. If this happens, press the y key, then the Enter key to continue.

Set configuration values

Next, you will be asked to provide basic information about your Custom Application and commercetools Project. Be sure to take note of the values that you provide as you will need them later in the tutorial.

1. For entryPointUriPath, choose a unique identifier for your Custom Application, then press Enter.

   The entryPointUriPath is unique across a Composable Commerce Region. To learn more about this identifier, including formatting restrictions and other considerations, see the Custom Application Configuration documentation.

2. For the initial project key for local development, enter your unique commercetools Project key, then press Enter.

3. For cloudIdentifier, type the cloud identifier for the region where your commercetools Project is located, then press Enter.

   By default, the starter template is configured to use the Composable Commerce Project hosted in the Europe (Google Cloud, Belgium) region. If your Project is hosted in another region, you will need to set the cloudIdentifier according to the list of supported cloud identifiers.

At this point, the starter template will be downloaded and the Custom Application will be configured with the values you provided. You may also notice that the package downloads the required dependencies. This might take a minute.

After everything is installed and configured, you will see a message in your terminal letting you know that the Custom Application has been created.

Start the local development server

Now, let's start the local development server which lets you test your Custom Application locally without needing to deploy it:

1. Navigate to the folder that contains your Custom Application project:

   cd my-new-custom-application-project

2. Start the server by issuing the start command:

   yarnpnpmnpm

   yarn start

Your browser will open a new tab pointing to the local development address of the Custom Application at http://localhost:3001.

At this point, you will be redirected to the login page of the Merchant Center. When this happens, enter your Merchant Center account credentials, then click Sign in. Once you're authenticated, you will be brought back to the local development server and your Custom Application will be shown.

Here's what the local preview looks like:

Configuration

The configuration file for your application is named custom-application-config.mjs and is located in the root directory of your Custom Application project.

Inside the configuration file you can see some of the properties and values that we've previously set, along with some new ones: name, entryPointUriPath, cloudIdentifier, initialProjectKey, and oAuthScopes. Let's go over a few of these fields to better understand them.

Entry Point URI Path

The entryPointUriPath is the unique identifier for your Custom Application. In the Merchant Center, your Custom Application will be accessible through a unique URI that contains the Composable Commerce projectKey and the entryPointUriPath.

/:projectKey/:entryPointUriPath

Permissions

Permissions determine which entities within your Composable Commerce Project your Custom Application can access. In the configuration file, the oAuthScopes field uses the HTTP API scopes to define permissions. It is best practice to only give the minimum amount of permission needed to accomplish your use case(s).

For this Custom Application, we want to view and manage Channels, so we need the view_products and manage_products scopes. These two scopes are already defined in the starter template so you don't need to do anything else.

Registration

At this point, you have a Custom Application that you can interact with, but the Merchant Center doesn't know about it yet. Let's change that by configuring and adding the Custom Application to the Merchant Center.

Initial configuration

First, set the initial configuration:

1. Open the Merchant Center (not through the localhost tab) and log in using your Merchant Center credentials.

2. Click the profile icon and select Manage organizations & teams.

3. Select the Organization for which you wish to configure a Custom Application.

4. Click the Custom Applications tab.

5. Click Configure Custom Applications.

6. Add a contact email address for the developer or maintainer of the Custom Application.

   To proceed to the next step, you must first verify your email address. You only have to do this once.

Add the Custom Application

Next, add the Custom Application:

7. Click Add a Custom Application.

8. Enter the following details:

   • Application name: My Channels App
   • Application URL: enter a placeholder value like https://test.com. We'll update this later after we deploy the Custom Application.
   • Application entry point URI path: Enter the unique identifier that you previously set for the entryPointUriPath.

Set permissions and menu options

Now, let's add these same two scopes to the Merchant Center, then configure some additional settings:

9. In the Permissions > Default group section, add the scopes to the following fields:

   • OAuth Scopes for View: add the view_products scope.
   • OAuth Scopes for Manage: add the manage_products scope.

10. In the Main menu section, enter or toggle the following values:

    • Default link label: enter Channels.
    • Link permissions > Default group: toggle on both the View and Manage permissions.

11. Click Register Custom Application.

The Custom Application is now registered and is in the Draft state. Take note of the Custom Application ID which you will need in the next step when we deploy your Custom Application.

Deployment

Your Custom Application is now installed locally on your machine and registered in the Merchant Center, however, it's not yet accessible there. To see it in the Merchant Center, you need to host the Custom Application externally. In this section, we will walk you through how to deploy your Custom Application to Vercel, a popular cloud hosting platform.

Configure and deploy to Vercel

To deploy to Vercel, do the following:

1. Create a Git repository and add the files from the my-new-custom-application-project folder to the root directory.

   If you created a local repository, you need to push those changes to the remote repository before proceeding to the next step.

2. Visit your Vercel dashboard and click Add New..., then select Project.

3. Import your Git repository into Vercel and proceed to configure the project settings.

4. In the Build & Output Settings section, make the following changes:

   • Framework Preset: Create React App
   • Build Command: yarn build
   • Output Directory: public

   

5. Click Deploy.

Your Vercel project will now create a deployment. Verify the deployment has the Ready status before proceeding.

Update the configuration

Next, we need to update the configuration file with information about the Custom Application and where it is hosted.

Make the following changes to the custom-application-config.mjs file:

1. Add the Custom Application ID (that you received after adding the application to the Merchant Center) to the env.production.applicationId field.

2. Add the Vercel production URL of your deployed project to the env.production.url field. Be sure to include https:// before your URL.

   Don't use the Deployment URL from the Vercel dashboard since this value changes each time your project builds. Instead, use one of the URLs listed under Domains.

{
  "env": {
    "production": {
      "applicationId": "hxkhrl1i312sys6rjh1e6n3",
      "url": "https://<project>.vercel.app"
    }
  }
}

3. Save the file and then push the changes to your remote repository.

Since Vercel is connected to your repository, it automatically starts a new deployment. Verify that the latest deployment has the Ready status before continuing to the next section.

Install the Custom Application in the Merchant Center

Let's move the Custom Application to the Ready state and install it:

1. Open the Merchant Center (not through the localhost) and log in using your Merchant Center credentials.
2. Click the profile icon and select Manage organizations & teams.
3. Select the Organization for which you wish to configure a Custom Application.
4. Click the Custom Applications tab.
5. Click Configure Custom Applications.
6. Select your Custom Application.
7. Update the Application URL with your Vercel project URL that you previously added to your configuration file.
8. Click Save.
9. Click the State dropdown, select Ready and confirm.
10. Select the Organization where the Custom Application should be installed, then click Continue.
11. Scroll to the Projects access section, select Install for selected projects only and choose your desired Project.
12. Click Save.

At this point, you will be asked whether you want to manage team permissions. You can skip that part for now by selecting Do later.

Your Custom Application is now installed in the Merchant Center for the Project that you specified. Now let's verify that everything works.

1. Click Back to project to return to the Merchant Center homepage.
2. Select your Project from the Project dropdown.
3. In the Merchant Center main menu, locate the Channels Custom Application, then click it. The application will open and you will be shown the main page. The application consists of two parts, a main page and a child page.

To access the child page, click the Fetching channels link.

Nice work! You have successfully installed a Custom Application in the Merchant Center.

Summary

In this tutorial, you have learned how to create, deploy, and install a Custom Application in the Merchant Center.

To learn more about what you can do with Custom Applications, we recommend the following resources within the Merchant Center Customizations documentation:

• Development overview - Learn development concepts for building and working with customizations.

• Merchant Center API - Learn about the Merchant Center API and how it helps you connect to commercetools APIs.

• Integrate with your own API - Learn about integration, authentication, and local development when using your own APIs.