# Marketplace App Distribution Type

> Below is a developer-facing guide covering both the new, simplified Marketplace distribution model and the OAuth flow you’ll need to implement to obtain…

- Source: https://docs.ghlcustomercare.com/docs/developer-resources/developer-resources-2/marketplace-app-distribution-type
- Section: Developer Resources / Developer Resources
- Reading time: 5 min
- Images: 9, each explained below
- Modified on Mon, 30 Mar at 5:43 AM

---
Below is a developer-facing guide covering both the new, simplified Marketplace distribution model and the OAuth flow you’ll need to implement to obtain the correct access tokens.

---

**TABLE OF CONTENTS**

-   [App Distribution Model](#app-distribution-model)
-   [Distribution scenarios](#distribution-scenarios)
-   [Article elaborating pricing models supported for each distribution model](#article-elaborating-pricing-models-supported-for-each-distribution-model)
-   [Backward compatibility](#backward-compatibility)
-   [Target User: Agency](#target-user-agency)
-   [Target User: Sub-account - Both Can Install](#target-user-sub-account-both-can-install)
-   [Target User: Sub-account - Only Agency Can Install](#target-user-sub-account-only-agency-can-install)

---

## App Distribution Model

To configure your desired app distribution model, you have three fields:

<table style="width: 100%"><colgroup><col width="112"><col width="139"><col width="373"></colgroup><tbody><tr><td><p dir="ltr" style="text-align: center"><span style="font-weight: 700">Field</span></p></td><td style="width: 17.416%"><p dir="ltr" style="text-align: center"><span style="font-weight: 700">Values</span></p></td><td style="width: 64.6174%"><p dir="ltr" style="text-align: center"><span style="font-weight: 700">Description</span></p></td></tr><tr><td><span style="font-weight: 700">Who is the target user of the app?</span></td><td style="width: 17.416%"><p dir="ltr"><span style="font-weight: 400">‘Agency’ / ‘Sub-account’</span></p></td><td style="width: 64.6174%"><ul><li dir="ltr" style="list-style-type: disc; font-weight: 400"><p dir="ltr"><span style="font-weight: 400">Who is going to interact with the app?&nbsp;</span></p></li><li dir="ltr" style="list-style-type: disc; font-weight: 400"><p dir="ltr"><span style="font-weight: 400">In other words, whose access token does the app ultimately need?</span></p></li><li dir="ltr" style="list-style-type: disc; font-weight: 400"><p dir="ltr"><span dir="ltr" style="font-weight: 400">For 95% of the apps, this would be <strong dir="ltr">“Sub-account” (Recommended)</strong></span></p></li><li dir="ltr" style="list-style-type: disc; font-weight: 400"><p dir="ltr"><span dir="ltr">This field cannot be modified once set.</span></p></li></ul></td></tr><tr><td><span dir="ltr" style="font-weight: 700">Who can install the app?</span></td><td style="width: 17.416%"><p dir="ltr"><span style="font-weight: 400">‘Both Agency and Sub-account’ / ‘Agency Only’</span></p></td><td style="width: 64.6174%"><ul><li dir="ltr" style="list-style-type: disc; font-weight: 400"><p dir="ltr"><span style="font-weight: 400">Which user(s) may see and install the app from the Marketplace UI?</span></p></li><li dir="ltr" style="list-style-type: disc; font-weight: 400"><p dir="ltr"><span style="font-weight: 400">The <strong>recommended option is “Both Agency &amp; Sub-account”</strong>, to ensure your app has the maximum reach</span></p></li><li dir="ltr" style="list-style-type: disc; font-weight: 400"><p dir="ltr"><span dir="ltr" style="font-weight: 400">Use "Agency Only" If you’re build an app exclusively as a fully white-labelled SaaS feature that only agencies can discover and install to their sub-accounts.&nbsp;</span></p></li></ul></td></tr><tr><td><span style="font-weight: 700">Can this app be bulk-installed by agencies?</span></td><td style="width: 17.416%"><p dir="ltr"><span style="font-weight: 400">‘Yes’ / ‘No’</span></p></td><td style="width: 64.6174%"><ul><li><p dir="ltr"><span dir="ltr">This is <strong>purely for backwards compatibility</strong> of apps already in the Marketplace. All apps added to the Marketplace going forward will be set to "Yes" (mandatory).</span></p></li><li dir="ltr" style="list-style-type: disc; font-weight: 400"><p dir="ltr"><span dir="ltr">If ‘Yes’, an agency owner/admin can install your app to multiple subaccounts in one operation.</span></p></li><li dir="ltr" style="list-style-type: disc; font-weight: 400"><p dir="ltr"><span dir="ltr" style="font-weight: 400">Once set to 'Yes', this field cannot be reverted back to 'No'.</span></p></li></ul></td></tr></tbody></table>

## **Private App Install Limits (Policy)**

If your Marketplace app is set to App type = Private, installs are limited to a small pilot:

**Cap:** A Private app can be installed in up to 5 Agencies.

**Block:** When the app reaches 6+ Agencies, new installs are blocked until the developer either:

1.  Publishes the app as Public (listed).
2.  Passes Security Review (if approved, the app can remain Private and installs can continue).

**Counting Rules**

Each unique Agency counts as 1, no matter how many sub-accounts (locations) the app is installed in.

Bulk installs still count as 1 per Agency.

Counts update in real time when an app is fully uninstalled from an Agency.

---

## Distribution scenarios

<table style="width: 100%"><colgroup><col width="103"><col width="99"><col width="89"><col width="142"><col width="148"><col width="165"></colgroup><tbody><tr><td colspan="3"><p dir="ltr" style="text-align: center"><span style="font-weight: 700">Developer’s distribution config scenarios</span></p></td><td rowspan="2" style="width: 19.6378%"><p dir="ltr"><span style="font-weight: 700">User Installation Scenarios</span></p></td><td colspan="2" style="width: 41.365%"><p dir="ltr" style="text-align: center"><span dir="ltr" style="font-weight: 700">Getting the right access token</span></p></td></tr><tr><td style="width: 12.1311%"><p dir="ltr"><span style="font-weight: 700">Who is the target user?</span></p></td><td style="width: 12.2356%"><p dir="ltr"><span style="font-weight: 700">Who can install the app?</span></p></td><td style="width: 14.6446%"><p dir="ltr"><span dir="ltr" style="font-weight: 700">Can the app be bulk-installed by agencies?</span></p></td><td style="width: 20.1951%"><p dir="ltr"><span style="font-weight: 700">Step 1: Identifying the type of installation from&nbsp;</span><span style="font-weight: 700">Get Access Token API</span></p></td><td><p dir="ltr"><span style="font-weight: 700">Step 2:&nbsp;</span></p></td></tr><tr><td style="width: 12.1311%"><p dir="ltr"><span style="font-weight: 400">Agency</span></p></td><td style="width: 12.2356%"><p dir="ltr"><span style="font-weight: 400">NA</span></p></td><td style="width: 14.6446%"><p dir="ltr"><span style="font-weight: 400">NA</span></p></td><td style="width: 19.6378%"><p dir="ltr"><span style="font-weight: 400">Agency user installs the app</span></p></td><td style="width: 20.1951%"><p dir="ltr"><span dir="ltr" style="font-weight: 400">“isBulkInstallation” : false,</span></p><p dir="ltr"><span style="font-weight: 400">“userType” : ”Company”</span></p></td><td><p dir="ltr"><span style="font-weight: 400">NA</span></p></td></tr><tr><td rowspan="5" style="width: 12.1311%"><p dir="ltr"><span style="font-weight: 400">Sub-account&nbsp;</span></p></td><td rowspan="4" style="width: 12.2356%"><p dir="ltr"><span style="font-weight: 400">Agency &amp; sub-account</span></p></td><td rowspan="2" style="width: 14.6446%"><p dir="ltr"><span style="font-weight: 400">No</span></p></td><td style="width: 19.6378%"><p dir="ltr"><span style="font-weight: 400">Sub-account user installs the app</span></p></td><td style="width: 20.1951%"><p dir="ltr"><span dir="ltr" style="font-weight: 400">“isBulkInstallation” : false,</span></p><p dir="ltr"><span style="font-weight: 400">“userType” : ”Location”</span></p></td><td><p dir="ltr"><span style="font-weight: 400">NA</span></p></td></tr><tr><td style="width: 19.6378%"><p dir="ltr"><span style="font-weight: 400">Agency user installs the app</span></p></td><td style="width: 20.1951%"><p dir="ltr"><span style="font-weight: 400">“isBulkInstallation” : <span dir="ltr" style="font-weight: 400; text-align: start">false</span>,</span></p><p dir="ltr"><span style="font-weight: 400">“userType" : "Location”</span></p></td><td><p dir="ltr"><span style="font-weight: 400">NA</span></p></td></tr><tr><td rowspan="2" style="width: 14.6446%"><p dir="ltr"><span style="font-weight: 400">Yes</span></p></td><td style="width: 19.6378%"><p dir="ltr"><span style="font-weight: 400">Sub-account user installs the app</span></p></td><td style="width: 20.1951%"><p dir="ltr"><span style="font-weight: 400">“isBulkInstallation” : <span dir="ltr" style="font-weight: 400; text-align: start">false</span>,</span></p><p dir="ltr"><span style="font-weight: 400">“userType" : "Location”</span></p></td><td><p dir="ltr"><span style="font-weight: 400">NA</span></p></td></tr><tr><td style="width: 19.6378%"><p dir="ltr"><span style="font-weight: 700">[NEW and RECOMMENDED]</span></p><p dir="ltr"><span style="font-weight: 400">Agency user installs the app</span></p></td><td style="width: 20.1951%"><p dir="ltr"><span style="font-weight: 400">“isBulkInstallation” : true,</span></p><p dir="ltr"><span style="font-weight: 400">“userType" : "Company”</span></p></td><td rowspan="2" style="width: 21.1699%"><p dir="ltr"><span class="doc-step-num">1</span><span dir="ltr" style="font-weight: 400">Get sub-accounts where app is installed</span></p><p dir="ltr"><span class="doc-step-num">2</span><span dir="ltr" style="font-weight: 400">Get Location Token using Agency Token</span><span dir="ltr" style="font-weight: 400">&nbsp;for every location where app is installed</span></p><p dir="ltr"><span dir="ltr" style="font-weight: 400">3. Listen to AppInstall webhook event for automatic future installations or installs done as part of a SaaS plan, and <span dir="ltr" style="font-weight: 400">Get Location Token using Agency Token</span> for the newly installed locations.</span></p></td></tr><tr><td style="width: 12.2356%"><p dir="ltr"><span style="font-weight: 400">Agency Only</span></p></td><td style="width: 14.6446%"><p dir="ltr"><span style="font-weight: 400">Yes</span></p></td><td style="width: 19.6378%"><p dir="ltr"><span style="font-weight: 400">Agency user installs the app</span></p></td><td style="width: 20.1951%"><p dir="ltr"><span style="font-weight: 400">“isBulkInstallation” : true,</span></p><p dir="ltr"><span style="font-weight: 400">“userType" : "Company”</span></p></td></tr></tbody></table>

## **[](https://docs.ghlcustomercare.com/docs/developer-resources/developer-resources-2/set-up-your-marketplacapp-pricing)[](https://docs.ghlcustomercare.com/docs/developer-resources/developer-resources-2/set-up-your-marketplacapp-pricing)**  
**[Article elaborating pricing models supported for each distribution model](https://docs.ghlcustomercare.com/docs/developer-resources/developer-resources-2/set-up-your-marketplacapp-pricing)**

---

## Backward compatibility

For all existing apps, to ensure the existing installation flow and token exchange mechanism is maintained, we have configured the fields as follows for the existing/legacy distribution types:

| Legacy Distribution Type  
 | Developer’s distribution config mapping to ensure backward compatibility  
 | Recommendation on how you can maximise the reach for your app  
 |
| --- | --- | --- |
| Who is the target user?  
 | Who can install the app?  
 | Can the app be bulk-installed by agencies?  
 |
| --- | --- | --- |
| Agency Only | Agency | NA | NA | NA |
| Sub-account Only | Sub-account  | Agency & sub-account | No | 1\. Develop the token exchange mechanism for bulk-installation flow as mentioned above.  
2\. Once done, set "Can the app be bulk-installed by agencies?" to "Yes" |
| Agency & Sub-account | Sub-account  | Agency Only | Yes | To make the app accessible to sub-accounts, you must ensure the app does not require any agency-level access such as:
-   Agency Level Scopes - companies.readonly, companies.write, location.write, saas/location.write, snapshots.readonly, snapshots.write, custom-menu-link.readonly, custom-menu-link.write
-   Module > Snapshots
-   Module > CustomJS

If your app does not require any of the above:  
1\. Develop the OAuth flow for installation by sub-account admins, which would generate a **userType: Location** token, as mentioned above.  
2\. Once done, change "Who can install the app?" **to** "**Agency & sub-account"** |

---

## **Target User: Agency**

Choose the Agency distribution type if your app's functionalities are applicable only to agency-level accounts.

![Target User: Agency (image 1 of 9)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155048583581/original/w4Mv3eWxtc7ky1cU_fU1FfLuBdg8fYAt_w.png)

**Target User: Agency (image 1 of 9)**

This screenshot appears in the "Target User: Agency" section of "Marketplace App Distribution Type". The text alongside this image reads: Choose the Agency distribution type if your app's functionalities are applicable only to agency-level accounts. Immediately after, the guide continues: App Listing: Apps will be listed solely in the agency level app marketplace.
- What to fill in: Choose the Agency distribution type if your app's functionalities are applicable only to agency-level accounts.
- Controls: App Listing, Installation and Uninstallation, Payments, Re-selling
- Next: App Listing: Apps will be listed solely in the agency level app marketplace.

**App Listing**: Apps will be listed solely in the agency level app marketplace.

![Target User: Agency (image 2 of 9)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155048583594/original/f4TxfrBHaJTtETQV7pYDWWQ4nI5z7bz-vw.png)

**Target User: Agency (image 2 of 9)**

This screenshot appears in the "Target User: Agency" section of "Marketplace App Distribution Type". The text alongside this image reads: App Listing: Apps will be listed solely in the agency level app marketplace. Immediately after, the guide continues: Installation and Uninstallation: Only agency administrators or owners have the authority to install or uninstall the app at the agency account level.
- What this covers: App Listing: Apps will be listed solely in the agency level app marketplace.
- Controls: App Listing, Installation and Uninstallation, Payments, Re-selling
- Next: Installation and Uninstallation: Only agency administrators or owners have the authority to install or uninstall the app at the agency account level.

**Installation and Uninstallation**:  Only agency administrators or owners have the authority to install or uninstall the app at the agency account level.

**Payments**: For paid applications, the installing agency is responsible for the app's cost.

**Re-selling**: Agencies cannot re-sell these apps, as they are not available for installation at the sub-account level.

---

## **Target User: Sub-account - Both Can Install**

Select the Sub-account (both can install) type if your app's functionalities are intended for sub-account level accounts.

![Target User: Sub-account - Both Can Install (image 3 of 9)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155048583624/original/kJtU4fEgullilWG0fxoAnDDRM-hJdD-cdg.png)

**Target User: Sub-account - Both Can Install (image 3 of 9)**

This screenshot appears in the "Target User: Sub-account - Both Can Install" section of "Marketplace App Distribution Type". The text alongside this image reads: Select the Sub-account (both can install) type if your app's functionalities are intended for sub-account level accounts. Immediately after, the guide continues: App Listing: These apps are available to both agency owners/admins and sub-account admins to install. These apps are listed in both Marketplaces.
- What to fill in: Select the Sub-account (both can install) type if your app's functionalities are intended for sub-account level accounts.
- Controls: App Listing, Installation and Uninstallation
- Next: App Listing: These apps are available to both agency owners/admins and sub-account admins to install. These apps are listed in both Marketplaces.

**App Listing**: These apps are available to both agency owners/admins and sub-account admins to install. These apps are listed in both Marketplaces.

![Target User: Sub-account - Both Can Install (image 4 of 9)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155048583635/original/eYRbavl9kxE3dTmJWUzJ26BuxrtACE9o4g.png)

**Target User: Sub-account - Both Can Install (image 4 of 9)**

This screenshot appears in the "Target User: Sub-account - Both Can Install" section of "Marketplace App Distribution Type". The text alongside this image reads: App Listing: These apps are available to both agency owners/admins and sub-account admins to install. These apps are listed in both Marketplaces. Immediately after, the guide continues: Installation and Uninstallation: Both Sub-account admins and agency admins can install the app.
- What this covers: App Listing: These apps are available to both agency owners/admins and sub-account admins to install. These apps are listed in both Marketplaces.
- Controls: App Listing, Installation and Uninstallation
- Next: Installation and Uninstallation: Both Sub-account admins and agency admins can install the app.

**Installation and Uninstallation**:  Both Sub-account admins and agency admins can install the app. 

Sub-account admins can discover and install these apps to their respective sub-accounts.

### 

![Target User: Sub-account - Both Can Install (image 5 of 9)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155023404538/original/lQxf69LOM8uFEPOdE9MQ6M8gYq-b4GDkoA.png)

**Target User: Sub-account - Both Can Install (image 5 of 9)**

This screenshot appears in the "Target User: Sub-account - Both Can Install" section of "Marketplace App Distribution Type". The text alongside this image reads: Sub-account admins can discover and install these apps to their respective sub-accounts. Immediately after, the guide continues: Bulk Installation: If bulk-installation is supported by the app developer, agency admins can bulk-install such apps. If not, agency admins can install the app one sub-account at a time. Agencies can automatically install these apps for….
- What this covers: Sub-account admins can discover and install these apps to their respective sub-accounts.
- Controls: Bulk Installation, Payments, Re-selling
- Next: Bulk Installation: If bulk-installation is supported by the app developer, agency admins can bulk-install such apps. If not, agency admins can install the app one sub-account at a time. Agencies can automatically install these apps for future sub-accounts if they choose the 'all sub-accounts' option during the initial installation.

**Bulk Installation**: If bulk-installation is supported by the app developer, agency admins can bulk-install such apps. If not, agency admins can install the app one sub-account at a time. Agencies can automatically install these apps for future sub-accounts if they choose the 'all sub-accounts' option during the initial installation.  
  

![Target User: Sub-account - Both Can Install (image 6 of 9)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155023404499/original/MqHiBlSiuQlJPZxBKZ49b7ZdsXzUeYZ6tw.png)

**Target User: Sub-account - Both Can Install (image 6 of 9)**

This screenshot appears in the "Target User: Sub-account - Both Can Install" section of "Marketplace App Distribution Type". The text alongside this image reads: Bulk Installation: If bulk-installation is supported by the app developer, agency admins can bulk-install such apps. If not, agency admins can install the app one sub-account at a time. Agencies can automatically install these apps for future sub-accounts if they choose the 'all sub-accounts'…. Immediately after, the guide continues: Payments: The sub-account installing a paid app will bear its cost.
- What to choose: Bulk Installation: If bulk-installation is supported by the app developer, agency admins can bulk-install such apps. If not, agency admins can install the app one sub-account at a time. Agencies can automatically install these apps for future sub-accounts if they choose the 'all sub-accounts' option during the initial installation.
- Controls: Bulk Installation, Payments, Re-selling
- Next: Payments: The sub-account installing a paid app will bear its cost.

**Payments**:  The sub-account installing a paid app will bear its cost.

**Re-selling**:  These apps can be re-sold by agencies.

---

## **Target User: Sub-account - Only Agency Can Install**

Opt for type Sub-account (only agency can install) distribution if your app is designed such a way that agency owners are the only relevant installers.  
  

![Target User: Sub-account - Only Agency Can Install (image 7 of 9)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155048584235/original/ifH_YbCWG2-uY5wxZFLw6jeWGAm3Ma0PpQ.png)

**Target User: Sub-account - Only Agency Can Install (image 7 of 9)**

This screenshot appears in the "Target User: Sub-account - Only Agency Can Install" section of "Marketplace App Distribution Type". The text alongside this image reads: Opt for type Sub-account (only agency can install) distribution if your app is designed such a way that agency owners are the only relevant installers. Immediately after, the guide continues: App Listing: These apps will only show up in the agency view of the Marketplace.
- What to fill in: Opt for type Sub-account (only agency can install) distribution if your app is designed such a way that agency owners are the only relevant installers.
- Controls: App Listing, Installation and Uninstallation, Bulk Installation, Re-selling
- Next: App Listing: These apps will only show up in the agency view of the Marketplace.

**App Listing**: These apps will only show up in the agency view of the Marketplace.  
  

![Target User: Sub-account - Only Agency Can Install (image 8 of 9)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155023404478/original/ZaZlYBRJIocjPL0AfUJkH_yXBSpC_BEoWg.png)

**Target User: Sub-account - Only Agency Can Install (image 8 of 9)**

This screenshot appears in the "Target User: Sub-account - Only Agency Can Install" section of "Marketplace App Distribution Type". The text alongside this image reads: App Listing: These apps will only show up in the agency view of the Marketplace. Immediately after, the guide continues: Installation and Uninstallation: Installation and uninstallation of these apps at the sub-account level must be carried out by agency admins or owners only.
- What this covers: App Listing: These apps will only show up in the agency view of the Marketplace.
- Controls: App Listing, Installation and Uninstallation, Bulk Installation, Re-selling
- Next: Installation and Uninstallation: Installation and uninstallation of these apps at the sub-account level must be carried out by agency admins or owners only.

**Installation and Uninstallation**: Installation and uninstallation of these apps at the sub-account level must be carried out by agency admins or owners only.

**Bulk Installation**: If enabled, Agency admins can bulk-install such apps. If not, agency admins can install the app one sub-account at a time. Agencies can automatically install these apps for future sub-accounts if they choose the 'all sub-accounts' option during the initial installation.

![Target User: Sub-account - Only Agency Can Install (image 9 of 9)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155023404499/original/MqHiBlSiuQlJPZxBKZ49b7ZdsXzUeYZ6tw.png)

**Target User: Sub-account - Only Agency Can Install (image 9 of 9)**

This screenshot appears in the "Target User: Sub-account - Only Agency Can Install" section of "Marketplace App Distribution Type". The text alongside this image reads: Bulk Installation: If enabled, Agency admins can bulk-install such apps. If not, agency admins can install the app one sub-account at a time. Agencies can automatically install these apps for future sub-accounts if they choose the 'all sub-accounts' option during the initial installation. Immediately after, the guide continues: Re-selling: Agencies can re-sell these apps to their sub-accounts, with the agency paying the base price set by the developer and sub-accounts paying a marked-up price set by the agency.
- What to choose: Bulk Installation: If enabled, Agency admins can bulk-install such apps. If not, agency admins can install the app one sub-account at a time. Agencies can automatically install these apps for future sub-accounts if they choose the 'all sub-accounts' option during the initial installation.
- Controls: App Listing, Installation and Uninstallation, Bulk Installation, Re-selling
- Next: Re-selling: Agencies can re-sell these apps to their sub-accounts, with the agency paying the base price set by the developer and sub-accounts paying a marked-up price set by the agency.

**Re-selling**: Agencies can re-sell these apps to their sub-accounts, with the agency paying the base price set by the developer and sub-accounts paying a marked-up price set by the agency.[](https://docs.ghlcustomercare.com/docs/app-marketplace/view-install-and-uninstallation-apps/how-to-resell-marketplace-apps)[](https://docs.ghlcustomercare.com/docs/app-marketplace/view-install-and-uninstallation-apps/how-to-resell-marketplace-apps)

---

Documentation for GHL Customer Care. Support: support@ghlcustomercare.com