Converting proprietary licenses into Marketplace licenses

If your add-on used a non-Atlassian licensing system before becoming a paid via Atlassian add-on, you can convert your proprietary license keys into new Marketplace license keys. To convert an existing license into a Marketplace license, you use the Atlassian License Service API, as described here.

Before starting

Before you can use the Atlassian License Service API, you need to be approved for access by the Atlassian Marketplace team. This is necessary because the Atlassian Marketplace team audits usage and monitors the performance of the API very closely, subject to the Atlassian Marketplace Vendor Agreement

To be approved for access, file an issue in the Marketplace Vendor Support Portal. Keep an eye on the issue (or watch for notifications) to find out when you are ready to go.

Using the License Service API

After getting the go-ahead from the Marketplace team, use the Atlassian License Service API as described here. The service accepts JSON data via HTTP POST and returns a JSON response.

The URL for the service is: 

https://marketplace.atlassian.com/rest/1.0/plugins/KEY/license

In your request:

  • Replace KEY with the plugin key of your add-on. This is the same key you supplied when submitting your add-on to the Marketplace. It also appears in the plugin descriptor (atlassian-plugin.xml) for your add-on.
  • Ensure the Content-Type is application/json.
  • Provide credentials via HTTP basic authentication. You can use the same username and password that you do to access your vendor account on the Atlassian Marketplace.

In request body, provide details about the license to be migrated. For example, for a 2000-user commercial license, the body would look like this: 

{
  "id": "1000",
  "email": "customer@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "organisationName": "Example Customer",
  "isoCountryCode": "US",
  "startDate": "2011-05-01",
  "endDate": "2012-05-01",
  "licenseType": "COMMERCIAL",
  "users": 2000
}

And a successful response would look like this:

{
  "id": "1000",
  "sen": "SEN-4839484",
  "licenseKey": "888BKQ0OD8oPeNpVj11Lwz8U08GytI1qJ8Z2I=X02eu"
}

Request format

The service accepts the following values in the request. 

Make sure that the data you submit in your request is formatted as indicated in the table. For example, dates must be in yyyy-MM-dd format. Submitting incorrectly formatted data does not necessarily generate a service error and can lead to faulty or invalid licenses.

Field

Required?

Type

Description

id

yes

String

A unique license identifier. The identifier prevents accidentally importing the same license twice. This can be any non-empty string; it only must be unique within the set of all licenses for this particular add-on.

email

yes

String

The licensee's (end customer's) email address. If there is not already an account on my.atlassian.com with this email, the service creates one.

firstName, lastName, organisationName

yes

String

The licensee's (end customer's) identifying information. Used to create the new account on my.atlassian.com. This is only done if the account did not previously exist. If the account exists, the service ignores these fields.

address1, address2, city, state, postcode

no

String

Address information. Used for licensees (end customers) without an account on my.atlassian.com. The service creates the new account with this data. Otherwise, if the account exists, the system ignores this information.

isoCountryCode

yes

String

The ISO code for the licensee's (end customer's) country. The service can only import a licenses for Marketplace-authorised countries.

startDate

yes

String

The date on which support for this license started. This value must have a format of: yyyy-MM-dd

endDate

yes

String

The date on which support for this license ends. This value must have a format of: yyyy-MM-dd

licenseType

yes

String

Must be COMMERCIAL or ACADEMIC

users

yes

Integer

The maximum number of users (or, for Bamboo, the maximum number of remote agents) supported by this license, or -1 for no maximum. This should match one of the user tiers for the host product.

expertEmail

no

String

If set, the imported license will be associated with the Atlassian Expert organization associated to this email address.

Notes:

  1. The times you specify will be set to midnight Sydney time on that day. This might be as much as a day ahead relative to the location of your customer.
  2. In light of the discontinuation of the legacy Enterprise licensing program, this service generates add-on licenses that are compatible with both enterprise and non-enterprise host licenses.

Successful response

An HTTP 200 status indicates the license was converted successfully. The JSON response body contains the following:

id

The same unique identifier specified in the request.

sen

The new Support Entitlement Number for this license.

licenseKey

The encoded Marketplace-license key.

Error responses

If the call fails, the service returns one of the following HTTP statuses:

400 (Bad Request)

Reasons for this error include: the request did not contain a valid JSON object, the startDate of the imported license is within the last 30 days, the expertEmail is not a valid Atlassian Expert email address, or a required field was omitted.

If available, the response returns additional detail about the error.

401 (Unauthorized)

You did not provide valid basic authentication credentials.

403 (Forbidden)

The credentials you provided were not associated with the vendor of the specified add-on or the vendor is not authorized to use the API.

404 (Not Found)

The plugin key you specified in the URL does not correspond to any add-on listed on the Atlassian Marketplace.

409 (Conflict)

A license with the same id already exists. The response body contains the same JSON information as it would for a successful import. This allows you to view the license key and SEN for an existing license.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport