Atlassian Marketplace connection form in Accoil

The Atlassian Marketplace connection imports customer license data for one Marketplace app into Accoil. It combines commercial details from Atlassian with the product usage data already associated with each customer account.

Use this connection to segment and prioritise accounts by information such as license status, license type, app edition, tier, evaluation dates, and maintenance dates.

How the connection works

Accoil makes read-only requests to the Atlassian Marketplace API using your Atlassian account email address and API token. It does not write to your Marketplace account.

When you save the connection:

Accoil uses the vendor ID to look up the corresponding developer ID
Accoil requests the available licenses for the selected Marketplace product ID
The first sync requests all available licenses for that product
Later syncs run every six hours and request licenses updated within the previous five days
Large result sets are processed in pages of 50 licenses
Temporary rate-limit and server errors are retried automatically

The developer ID is discovered and stored automatically by Accoil. You do not enter it in the Accoil connection form, but you will use it while finding your product ID during setup.

Your connection credentials are encrypted when stored by Accoil.

How Atlassian licenses match Accoil accounts

Accoil uses the cloudId in each Atlassian license to identify the customer account. To match Marketplace license details with product activity, the group calls from your analytics implementation must send that exact Cloud ID as the group_id.

For example, if a license contains:

{
  "cloudId": "111cc111-111c-1cc1-1c1c-1111c1c1c111"
}

Your analytics group calls must therefore include:

{
  "group_id": "111cc111-111c-1cc1-1c1c-1111c1c1c111"
}

The value must match Atlassian's cloudId exactly. This shared identifier allows Accoil to attach the Marketplace license traits and your analytics activity to the same account.

For guidance on implementing product analytics in an Atlassian Forge app, see the 10 minute Forge analytics guide. When adding group calls to that implementation, use Forge's context.cloudId as the group_id.

Important: Accoil skips license records that do not contain a cloudId. Server or Data Center licenses without a Cloud ID cannot be matched through this connection.

License data imported into Accoil

Selected license values are added as account traits with an am. prefix. Depending on the data Atlassian returns for a license, these can include:

App details such as am.addonName, am.addonKey, am.productId, and am.appEdition
License details such as am.status, am.licenseType, am.hosting, and am.lastUpdated
Tier details such as am.tier and the numeric am.tier.number
Maintenance and evaluation dates
Entitlement and license identifiers
Parent product name, edition, and billing cycle
Whether the installation is on a sandbox
Site hostname, company, country, and region
Attribution and Marketplace data-insight values when provided by Atlassian

Accoil imports a selected set of useful fields rather than the entire Marketplace response. From Atlassian's contactDetails, Accoil keeps the company, country, and region rather than individual contact fields.

What you'll need

Before configuring the connection, collect these four values:

Atlassian account email address: the email address used to access your Marketplace partner account
API token: a generated Atlassian API token used as the password for Basic authentication
Vendor ID: the numeric identifier for your Marketplace vendor account
Product ID: the Marketplace product ID for the specific app whose licenses you want to import

You also need permission to manage connections for the relevant Accoil product. The Atlassian account must be able to view the vendor, app listing, and license reporting information you want to sync.

The connection supports one Marketplace product ID for each Accoil product. If you manage multiple Marketplace apps, connect each app to the corresponding product in Accoil.

Create an Atlassian API token

We recommend using a dedicated Atlassian account with only the Marketplace access required for this connection instead of a personal account.

Open Atlassian API token settings and sign in with the account Accoil will use.
Select Create API token.
Give the token a clear name, such as Accoil Marketplace sync.
Choose an expiry date and record it so the token can be rotated before it expires.
Create the token and copy it to a secure password manager.

Atlassian only displays the token once. Do not use your Atlassian account password and do not send the API token to Accoil Support or include it in screenshots.

For more information, see Manage API tokens for your Atlassian account.

Find your vendor ID

Sign in to the Atlassian Marketplace partner portal and open your vendor management page. The vendor ID is the number at the end of its URL:

https://marketplace.atlassian.com/manage/vendors/<vendor-id>

For example, if the URL is:

https://marketplace.atlassian.com/manage/vendors/123456

Your vendor ID is 123456.

Get your developer ID

Atlassian's newer Marketplace APIs use a developer ID. Run the following request after replacing {vendorId}, {your-email}, and {api_token} with your own values:

curl --request GET \
  --url 'https://api.atlassian.com/marketplace/rest/3/developer-space/vendor/{vendorId}' \
  --user '{your-email}:{api_token}' \
  --header 'Accept: application/json'

The API token is the password portion of the Basic authentication value. Use the email address belonging to the same Atlassian account that created the token.

You should receive a response similar to:

{
  "developerId": "e33e3aca-c9fc-11ed-afa1-0242ac"
}

Copy the developerId value for the next request. You do not enter the developer ID in Accoil.

Find the product ID for your app

Replace {developerId}, {your-email}, and {api_token} in the following request:

curl --request GET \
  --url 'https://api.atlassian.com/marketplace/rest/3/product-listing/developer-space/{developerId}?limit=50' \
  --user '{your-email}:{api_token}' \
  --header 'Accept: application/json'

You should receive a response similar to this abbreviated example:

{
  "links": {
    "self": "/rest/3/product-listing/developer-space/87654321-4321-4321-4321-210987654321?limit=50",
    "next": "/rest/3/product-listing/developer-space/87654321-4321-4321-4321-210987654321?limit=50&cursor=..."
  },
  "items": [
    {
      "productId": "12345678-1234-1234-1234-123456789abc",
      "appKey": "com.example.app.addon",
      "developerId": "87654321-4321-4321-4321-210987654321",
      "appName": "Example App for Platform"
    }
  ]
}

Find the item whose appKey or appName matches the app you want to connect, then copy its productId.

Be sure to copy productId, not appKey or developerId. These values identify different things in Atlassian Marketplace.

If your developer account contains more than 50 apps, use the path in links.next to request the next page. Add that path after https://api.atlassian.com/marketplace and use the same email address and API token for authentication.

Connect Atlassian Marketplace in Accoil

Open the Atlassian Marketplace connection to enter the credentials and IDs collected in the previous steps.

In Accoil, open Settings.
Under Product Settings, select Connections.
Under Tracking & Ingestion, open Atlassian Marketplace.
Enter your Atlassian connection details.
Select Update connection.

Enter the values as follows:

Atlassian User Name: your Atlassian account email address
Atlassian API Token: the API token created by that account
Vendor ID: the numeric vendor ID from the Marketplace vendor URL
Product ID: the productId returned for the app you want to connect

The first license sync starts automatically after the connection is saved. A large license set can take longer to appear because it is processed in pages in the background.

Check that the connection is working

After the first sync has had time to complete:

Open an Accoil account that you know has a license for the selected app.
Confirm that your analytics group calls send the Atlassian Cloud ID as group_id.
Check the account traits for values beginning with am..
Confirm that traits such as am.addonName, am.status, and am.tier contain the expected Marketplace values.

If the license traits appear on a separate account from the product activity, the group_id in your analytics group calls does not match Atlassian's cloudId exactly.

Rotate or replace an API token

Atlassian API tokens can expire or be revoked. To replace a token:

Create a new token in Atlassian.
Open Settings > Connections > Atlassian Marketplace in Accoil.
Select Show config if the configuration fields are hidden.
Re-enter all four connection values, including the new API token.
Select Update connection.

If Atlassian previously returned 401 Unauthorized, Accoil marks the connection as requiring authentication and pauses further syncs. Saving valid connection details reactivates it and starts another sync.

Disconnecting Atlassian Marketplace stops future license syncs. Account traits already imported with the am. prefix are not automatically removed.

Connect Atlassian Marketplace to Accoil