Configuring and Managing Custom Applications

Learn how to configure and manage Custom Applications in your Organization.

This document refers to the new Organization-level Custom Applications. If you have existing Custom Applications configured in Settings > Custom Applications, you must migrate them. To know more about migrating Custom Applications, refer to the migration document.

Working with Custom Applications involves two phases: development and production usage.

As a developer, you begin with the local development of your Custom Application. For more information, refer to Develop applications for the Merchant Center.

This document describes the necessary steps to configure and install your Custom Application in the Merchant Center. The process involves:

  1. Configuring the Custom Application for your Organization.
  2. Installing the Custom Application to make it accessible in the Projects of your Organization.

Configuring Custom Applications

Adding a Custom Application

  1. Click the profile icon and select Manage Organizations & Teams.
  2. Select the Organization for which you wish to configure a Custom Application.
  3. Navigate to the Custom Applications tab.
  4. Click Configure Custom Applications. configure-custom-applications

At this point, you can add a contact email address of the Custom Application's developer or maintainers. Refer to Verifying contact email address for more details.

  1. Click Add a Custom Application. add-a-custom-application

  2. Fill out the form to configure a new Custom Application. Specify the same information that you have previously defined in the local Custom Application config file.

  3. Click Add Custom Application.

Now, the configuration is stored in the Merchant Center and a Custom Application entity is created. The Custom Application is currently in the Draft state.

custom-application-states

A Custom Application has two states:

  • Draft: The Custom Application is not ready to be installed. Administrators can still apply changes.
  • Ready: The Custom Application is ready to be installed in one or more Projects of the Organization. Once installed, users of the Organization can access the application according to their Team's permissions.

Before being able to proceed with the installation step, you need to perform the following actions:

Verifying contact email address

Working on Custom Applications requires commercetools to contact the developers or owners of Custom Applications from time to time, primarily for updates and support purposes. Hence, we require that every Organization using Custom Applications provides a valid and verified contact email address.

To add a new email address:

  1. In the Configure Custom Applications screen click Add new email address.
  2. Put in a valid email address.

To update an existing email address:

  1. Click the edit icon in the Contact email address for support section.
  2. Specify the email address in the Edit contact email address dialog.
  3. Click Save. edit-contact-email

You will receive an email to the provided address. Click the verification link.

In case you don't receive an email, please check if you've provided a valid address. If incorrect, update the address and click Resend verification email.

The previously validated email address will remain valid till the new email address is verified.

Assigning the Application ID

Once you add a new Custom Application, a unique ID is generated for the Custom Application. Copy the Application ID and define it in the Custom Application Config.
Make sure that the Custom Application then is (re)deployed with the application ID.

Moving the Custom Applications to the Ready state

By default, a Custom Application is in the Draft state. It signifies that the owners or developers are finalizing the development and configuration of the Custom Application.

After adding a Custom Application, you must move it to the Ready state so that it can be installed in an Organization. See Installing a Custom Application.

Click the State drop-down menu, choose Ready. ready-state

Click Confirm in the confirmation dialog. The Custom Application is now Ready for installation.

Moving the Custom Applications to the Draft state

  • The Custom Application cannot be installed in any Organization while in the Draft state.
  • Changing state from Ready to Draft results in the Custom Application being uninstalled from all Organizations and Projects.

Click the State drop-down menu, choose Draft. ready-state

The Custom Application is now in the Draft state. While in this state, you can update the configurations or delete the Custom Application.

Deleting a Custom Application

You can delete a Custom Application only when it is in the Draft state. Refer to Moving the Custom Applications to the Draft state for more details.

Click the delete icon.

delete-custom-application

Further, click Confirm in the Delete Custom Applications dialog.

The Custom Application will then be removed from the Configured Custom Applications: Draft section.

Managing Custom Applications

Installing a Custom Application

Install the Custom Application to make it accessible in the Projects of your Organization.

  1. Click the profile icon and select Manage Organizations & Teams.

  2. Select the Organization for which you wish to install a Custom Application.

  3. Navigate to the Custom Applications tab.

  4. Click Manage project access.

    This page displays the current Organization's Custom Applications that are:

    • Ready for installation: not installed in the Organization yet.
    • Installed: already installed in one or more Projects of the Organization. ready-for-installation
  5. Choose a Custom Application from the Ready for installation section. Refer to Moving the Custom Application to the Ready state for more details.

The installation process can also be triggered by clicking on the Manage project access button in the configuration details page:

  1. Click the profile icon and select Manage Organizations & Teams.
  2. Select the Organization for which you wish to install a Custom Application.
  3. Navigate to the Custom Applications tab.
  4. Click Configure Custom Applications.
  5. Select a Custom Application from the Configured Custom Applications: Ready section.
  6. Click Manage project access. manage-projects-access
  1. Review the permissions listed in the Requested permissions section. A user must have at least View permission to access the Custom Application in the Merchant Center.

  2. In the Projects access section, you can either choose to grant Projects access for:

    • all the current Projects of the Organization. To do so, choose Install for all projects of this organization.
    • selected Projects of the Organization. To do so, choose Install for selected projects only and then select the Projects from the Select projects drop-down list.

    select-projects

  3. Click Save.

You can now access the Custom Application within the respective Merchant Center Projects.

Depending on the setup of your Organization, you can assign Team permissions to your Teams.

By default, the administrators Team has access to the installed Custom Applications.

Updating Projects access

You can either grant or revoke Projects access for a Custom Application.

  1. Click the profile icon and select Manage Organizations & Teams.

  2. Select the Organization.

  3. Navigate to the Custom Applications tab.

  4. Click Manage project access.

  5. Choose the Custom Application.

  6. In the Projects access section of the Custom Application, choose:

    • Install for all projects of this organization to grant access for all the current Projects of the Organization.
    • Install for selected projects only to grant Projects access for selected Projects of the Organization and then select the Projects from the Select projects drop-down list. To revoke access for selected Projects of the Organization, click the close icon (Revoke access) next to the desired Project in the projects selected list. revoke-access
  7. Click Save.

Assigning Team permissions

To grant access to Custom Applications to individual Teams, you must configure each Team's permissions.

  1. Click the profile icon and select Manage Organizations & Teams.

  2. Select your Organization.

  3. Choose a Team and navigate to the Permissions tab.

  4. Select the desired Project from the Select project drop-down.

    Make sure to select Projects that have been granted access to the Custom Application.

  5. In the Custom Applications section, choose the desired Custom Application and configure the permissions for the Team:

  • View all: view resources in a Custom Application.
  • View and edit all: view, create, modify, and delete resources in a Custom Application.

Based on the permissions, members of the Team can view and access the Custom Application in the Merchant Center.

Uninstalling a Custom Application

To remove a Custom Application from all the Projects in an Organization:

  1. Click the profile icon and select Manage Organizations & Teams.

  2. Select the Organization for which you wish to uninstall a Custom Application.

  3. Navigate to the Custom Applications tab.

  4. Click Manage project access.

  5. Choose a Custom Application from the Installed section.

  6. Click Uninstall. uninstall

  7. Click Confirm in the Uninstall the Custom Application dialog.

The Custom Application is then moved back to the Ready for installation section.

Developer Center
HTTP APIGraphQL APIPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & ExportSUNRISE Starter FrontendsTutorialsFAQ
Merchant Center
DocumentationRelease Notes
Sign upLog inTech BlogIntegrationsStatusSupportUser Research Program
Copyright © 2022 commercetools
Privacy PolicyImprint