# Configure and manage Custom Applications

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

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 customizations for the Merchant Center](/merchant-center-customizations).

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.

## Configure Custom Applications

### Add 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. Click the **Custom Applications** tab.

4. Click **Configure Custom Applications**.

   At this point, you can add a contact email address of the Custom Application's developer or maintainer. Refer to [Verify contact email address](/merchant-center/managing-custom-applications.md#verify-contact-email-address) for more details.

5. Click **Add a Custom Application**.

6. 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](/merchant-center-customizations/tooling-and-configuration/custom-application-config.md#configuration-properties).

7. 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.

![A Custom Application in the Draft state.](https://docs.commercetools.com/merchant-center/images/customizations/custom-application-draft-state.png)

A Custom Application has two states:

- [**Draft**](/merchant-center/managing-custom-applications.md#move-a-custom-application-to-the-draft-state): the Custom Application is not ready to be installed. Administrators can still apply changes.
- [**Ready**](/merchant-center/managing-custom-applications.md#move-a-custom-application-to-the-ready-state): the Custom Application is ready to be installed in one or more Projects of an Organization where you have administrator rights. Once installed, the Organization's users can access the application according to their Team's permissions.

Before proceeding with the installation step, you need to perform the following actions:

- [Verify contact email address](/merchant-center/managing-custom-applications.md#verify-contact-email-address)
- [Assign the Application ID](/merchant-center/managing-custom-applications.md#assign-the-application-id)
- [Move a Custom Application to the Ready state](/merchant-center/managing-custom-applications.md#move-a-custom-application-to-the-ready-state)

### Verify 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, do the following:

1. In the [Configure Custom Applications](/merchant-center/managing-custom-applications.md#configure-custom-applications) screen, click **Add new email address**.
2. Specify a valid email address.
3. Click **Save**.

To update an existing email address, do the following:

1. In the [Configure Custom Applications](/merchant-center/managing-custom-applications.md#configure-custom-applications) screen, 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**.

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

If you don't receive an email, verify that you've provided the correct email address.
If you've provided an incorrect email address, update the address and click **Resend verification email**.

The previously validated email address remains valid until the new email address is verified.

### Assign the Application ID

Once you add a new Custom Application, a unique ID is generated for the Custom Application.
Copy the **Application ID** and add it to the [Custom Application Config](/merchant-center-customizations/tooling-and-configuration/custom-application-config.md#envproductionapplicationid), then redeploy your Custom Application.

### Move a Custom Application to the Ready state

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

To [install a Custom Application](/merchant-center/managing-custom-applications.md#install-a-custom-application) in an Organization, you must first move it to the **Ready** state.

- Add and [verify a contact email](/merchant-center/managing-custom-applications.md#verify-contact-email-address) address before moving a Custom Application to the **Ready** state.
- A Custom Application cannot be deleted in the **Ready** state. Refer to [Delete a Custom Application](/merchant-center/managing-custom-applications.md#delete-a-custom-application) for more details.

In the configuration details page of your Custom Application:

1. Click the **State** drop-down menu, choose **Ready**.
2. Click **Confirm** in the confirmation dialog. The Custom Application is now **Ready for installation**.

### Move a Custom Application to the Draft state

- A Custom Application cannot be installed in an Organization while in the **Draft** state.
- Changing the state from **Ready** to **Draft** results in the Custom Application being uninstalled from all Organizations and Projects.

In the configuration details page of your Custom Application:

Click the **State** drop-down menu, choose **Draft**. The Custom Application is now in the **Draft** state. While in this state, you can update the configuration or delete the Custom Application.

### Update Custom Application permissions

You can modify the permissions of a Custom Application in both **Draft** and **Ready** states. This is useful in cases where a Custom Application needs to make additional API requests (thus requiring more OAuth scopes) or if you want to configure additional permission groups or remove unused OAuth scopes.

Administrators receive email notifications about any permission updates to their installed Custom Applications.

Use caution when editing permissions of a Custom Application in the **Ready** state. A confirmation prompt will appear to ensure awareness of the changes.

Ensure your Custom Application's code can adapt to these changes to maintain its functionality.

### Delete a Custom Application

To delete a Custom Application, it must be in the [Draft](/merchant-center/managing-custom-applications.md#move-a-custom-application-to-the-draft-state) state.

To delete a Custom Application, click the delete icon, then click **Confirm** in the **Delete Custom Applications** dialog. The Custom Application is then removed from the **Configured Custom Applications: Draft** section.

## Manage Custom Applications

### Install a Custom Application

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

A Custom Application can be installed in multiple Organizations where you have administrator rights.

1. Click the profile icon and select **Manage organizations & teams**.

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

3. Click the **Custom Applications** tab.

4. Click **Install Custom Applications**.
   This page shows the Custom Applications that have been **Installed** in the current Organization.
   In addition, you can see the list of Custom Applications that are **Ready for installation** and have not been installed yet in the current Organization. The list might include Custom Applications defined in other Organizations where you have administrator rights.

   ![A Custom Application ready for installation.](https://docs.commercetools.com/merchant-center/images/customizations/custom-application-ready-for-installation.png)

5. Choose a Custom Application from the **Ready for installation** section. Refer to [Move a Custom Application to the Ready state](/merchant-center/managing-custom-applications.md#move-a-custom-application-to-the-ready-state) for more details.

The installation process can also be triggered by clicking on the **Install application** 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. Click the **Custom Applications** tab.
4. Click **Configure Custom Applications**.
5. Select a Custom Application from the **Configured Custom Applications: Ready** section.
6. Click **Install application**.
7. Select an Organization to install the Custom Application. Only Organizations where you have administrator rights can be selected.

6) 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.

7) In the **Projects access** section, grant Projects access by selecting one of the following options:

   - **Install for all projects of this organization**: grants access to all projects of an Organization.
   - **Install for selected projects only**: grants access only to selected projects of an Organization. To do so, select the Projects from the **Select projects** drop-down list.

8) 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](/merchant-center/managing-custom-applications.md#assign-team-permissions) to your Teams.

By default, the Administrators Team can access and modify the installed Custom Views.

### Update Projects access

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

1. Click the profile icon and select **Manage organizations & teams**.

2. Select the Organization.

3. Click the **Custom Applications** tab.

4. Click **Install Custom Applications**.

5. Choose a Custom Application from the **Ready for installation** section.

6. In the **Projects access** section, select one of the following options:

   - **Install for all projects of this organization**: grants access to all projects of an Organization.
   - **Install for selected projects only**: grants access only to selected projects of an Organization. To do so, select the Projects from the **Select projects** drop-down list.

     To revoke access for selected Projects of the Organization, click the **Revoke access** button next to the desired Project in the selected projects list.

7. Click **Save**.

### Assign Team permissions

To grant access to Custom Applications to individual Teams, you must configure each Team's permissions. Members of the Team can view and access the Custom Application in the Merchant Center, based on the given permissions.

1. Click the profile icon and select **Manage organizations & teams**.

2. Select your Organization.

3. Choose a Team, then click 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. A Custom Application always has a default permission group. At the very minimum, you need to assign **View only** to allow users to access the Custom Application. Additionally, you can use more granular permission groups to cover specific business requirements.

- **View only**: view resources in a Custom Application.
- **View and edit**: view, create, modify, and delete resources in a Custom Application.

### Reorder submenu items

To customize the navigation experience, you can update the display order of the submenu items:

1. Click the profile icon and select **Manage organizations & teams**.
2. Select the Organization for the Custom Application.
3. Click the **Custom Applications** tab.
4. Click **Configure Custom Applications**.
5. Select the Custom Application.
6. In the **Submenu** section, click **Reorder links**.
7. Drag the submenu items into the desired order.
8. Click **Confirm** in the **Reorder submenu links** dialog.
9. Click **Save**.

You can also manage the submenu items through the config file using the [config:sync](/merchant-center-customizations/tooling-and-configuration/cli.md#configsync) command. For more information, see the `submenuLinks` property in the [Custom Application Config](/merchant-center-customizations/tooling-and-configuration/custom-application-config.md#submenulinks).

### Uninstall 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. Click the **Custom Applications** tab.
4. Click **Install Custom Applications**.
5. Choose a Custom Application from the **Installed** section.
6. Click **Uninstall**.
7. Click **Confirm** in the **Uninstall the Custom Application** dialog.

## Manage Custom Applications deployment previews

Deployment previews let you preview changes to your Custom Applications using a unique URL. For more information, see [Deployment previews](/merchant-center-customizations/concepts/deployment-previews.md).

![Custom Application deployment previews tab](https://docs.commercetools.com/merchant-center/images/customizations/deployment-preview-page.png)

### Add a deployment preview

To add a deployment preview, do the following:

1. Click the profile icon and select **Manage organizations & teams**.
2. Select the Organization for which you wish to add a Custom Application deployment preview.
3. Click the **Custom Applications** tab.
4. Click **Configure Custom Applications**.
5. Select a Custom Application from the **Configured Custom Applications: Ready** section.
6. Select **Deployment Previews**.
7. Click **Add deployment preview**.
8. Fill out the form with a unique **Alias** and **Application URL**.
9. Click **Save**.

To access the deployment preview, click the link under the Preview URL heading. A new browser tab opens to the `mc-preview` domain at the deployment preview alias location. Then, navigate to the Custom Application using the Merchant Center main navigation.

### Update a deployment preview

To update a Custom Application deployment preview, do the following:

1. Click the profile icon and select **Manage organizations & teams**.
2. Select the Organization for which you wish to update a Custom Application deployment preview.
3. Click the **Custom Applications** tab.
4. Click **Configure Custom Applications**.
5. Select a Custom Application from the **Configured Custom Applications: Ready** section.
6. Select **Deployment Previews**.
7. Click **Edit deployment preview** on the deployment preview you want to update.
8. Fill out the form with new values.
9. Click **Save**.

You can't update a deployment preview's alias. To use a different alias, create a new deployment preview with the desired alias and delete the old one.

### Delete a deployment preview

To delete a Custom Application deployment preview:

1. Click the profile icon and select **Manage organizations & teams**.
2. Select the Organization for which you wish to delete a Custom Application deployment preview.
3. Click the **Custom Applications** tab.
4. Click **Configure Custom Applications**.
5. Select a Custom Application from the **Configured Custom Applications: Ready** section.
6. Select **Deployment Previews**.
7. Click **Delete deployment preview** on the deployment preview you want to delete.
8. Click **Confirm** in the **Delete Deployment Preview** dialog.

## Related pages

- [Area overview page with navigation](/merchant-center.md)
- [Next page: Custom Views](/merchant-center/managing-custom-views.md)
- [Search documentation and API specs](/search.md)