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…
5 min read1,137 words9 explained imagesUpdated Mon, 30 Mar at 5:43 AM
Assistants need to reach this page over the internet. While it is only running on your machine, these two buttons will not be able to load it.
Each image has a one line explanation. Switch to full detail for the step it belongs to, the fields and buttons involved, examples and the whole procedure.
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.
To configure your desired app distribution model, you have three fields:
Field
Values
Description
Who is the target user of the app?
‘Agency’ / ‘Sub-account’
Who is going to interact with the app?
In other words, whose access token does the app ultimately need?
For 95% of the apps, this would be “Sub-account” (Recommended)
This field cannot be modified once set.
Who can install the app?
‘Both Agency and Sub-account’ / ‘Agency Only’
Which user(s) may see and install the app from the Marketplace UI?
The recommended option is “Both Agency & Sub-account”, to ensure your app has the maximum reach
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.
Can this app be bulk-installed by agencies?
‘Yes’ / ‘No’
This is purely for backwards compatibility of apps already in the Marketplace. All apps added to the Marketplace going forward will be set to "Yes" (mandatory).
If ‘Yes’, an agency owner/admin can install your app to multiple subaccounts in one operation.
Once set to 'Yes', this field cannot be reverted back to 'No'.
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:
Publishes the app as Public (listed).
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
Developer’s distribution config scenarios
User Installation Scenarios
Getting the right access token
Who is the target user?
Who can install the app?
Can the app be bulk-installed by agencies?
Step 1: Identifying the type of installation from Get Access Token API
Step 2:
Agency
NA
NA
Agency user installs the app
“isBulkInstallation” : false,
“userType” : ”Company”
NA
Sub-account
Agency & sub-account
No
Sub-account user installs the app
“isBulkInstallation” : false,
“userType” : ”Location”
NA
Agency user installs the app
“isBulkInstallation” : false,
“userType" : "Location”
NA
Yes
Sub-account user installs the app
“isBulkInstallation” : false,
“userType" : "Location”
NA
[NEW and RECOMMENDED]
Agency user installs the app
“isBulkInstallation” : true,
“userType" : "Company”
1Get sub-accounts where app is installed
2Get Location Token using Agency Token for every location where app is installed
3. Listen to AppInstall webhook event for automatic future installations or installs done as part of a SaaS plan, and Get Location Token using Agency Token for the newly installed locations.
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:
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)What this shows Choose the Agency distribution type if your app's functionalities are applicable only to agency-level accounts.What this showsIllustrates the "Target User: Agency" section of "Marketplace App Distribution Type".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.Image 1 of 9What to fill inChoose the Agency distribution type if your app's functionalities are applicable only to agency-level accounts.
Buttons and menus referencedApp ListingInstallation and UninstallationPaymentsRe-selling
Next stepApp 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)What this shows App Listing: Apps will be listed solely in the agency level app marketplace.What this showsIllustrates the "Target User: Agency" section of "Marketplace App Distribution Type".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.Image 2 of 9What this coversApp Listing: Apps will be listed solely in the agency level app marketplace.
Buttons and menus referencedApp ListingInstallation and UninstallationPaymentsRe-selling
Next stepInstallation 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)What this shows Select the Sub-account (both can install) type if your app's functionalities are intended for sub-account level accounts.What this showsIllustrates the "Target User: Sub-account - Both Can Install" section of "Marketplace App Distribution Type".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.Image 3 of 9What to fill inSelect the Sub-account (both can install) type if your app's functionalities are intended for sub-account level accounts.
Buttons and menus referencedApp ListingInstallation and Uninstallation
Next stepApp 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)What this shows App Listing: These apps are available to both agency owners/admins and sub-account admins to install.What this showsIllustrates the "Target User: Sub-account - Both Can Install" section of "Marketplace App Distribution Type".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.Image 4 of 9What this coversApp Listing: These apps are available to both agency owners/admins and sub-account admins to install. These apps are listed in both Marketplaces.
Buttons and menus referencedApp ListingInstallation and Uninstallation
Next stepInstallation 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)What this shows Sub-account admins can discover and install these apps to their respective sub-accounts.What this showsIllustrates the "Target User: Sub-account - Both Can Install" section of "Marketplace App Distribution Type".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….Image 5 of 9What this coversSub-account admins can discover and install these apps to their respective sub-accounts.
Buttons and menus referencedBulk InstallationPaymentsRe-selling
Next stepBulk 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)What this shows Bulk Installation: If bulk-installation is supported by the app developer, agency admins can bulk-install such apps.What this showsIllustrates the "Target User: Sub-account - Both Can Install" section of "Marketplace App Distribution Type".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.Image 6 of 9What to chooseBulk 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.
Buttons and menus referencedBulk InstallationPaymentsRe-selling
Next stepPayments: 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)What this shows 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.What this showsIllustrates the "Target User: Sub-account - Only Agency Can Install" section of "Marketplace App Distribution Type".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.Image 7 of 9What to fill inOpt 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.
Buttons and menus referencedApp ListingInstallation and UninstallationBulk InstallationRe-selling
Next stepApp 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)What this shows App Listing: These apps will only show up in the agency view of the Marketplace.What this showsIllustrates the "Target User: Sub-account - Only Agency Can Install" section of "Marketplace App Distribution Type".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.Image 8 of 9What this coversApp Listing: These apps will only show up in the agency view of the Marketplace.
Buttons and menus referencedApp ListingInstallation and UninstallationBulk InstallationRe-selling
Next stepInstallation 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)What this shows Bulk Installation: If enabled, Agency admins can bulk-install such apps.What this showsIllustrates the "Target User: Sub-account - Only Agency Can Install" section of "Marketplace App Distribution Type".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.Image 9 of 9What to chooseBulk 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.
Buttons and menus referencedApp ListingInstallation and UninstallationBulk InstallationRe-selling
Next stepRe-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.
