Accessing Sales Reports with the REST API

This documentation describes an older version of the REST API. For the latest documentation, see the reporting resource in the Atlassian Marketplace API.

The vendor dashboard provides vendors with sales information add-ons in a visual format. To access the information in its raw format, you can use the Sales Report API.

The Sales Report API is a REST API that returns sale records in JSON format. Each sale record lists the invoice ID, the buyer, the purchase price, and so on. The data represents add-on sales only. It does not include information on evaluations.

To use the API, you send a GET HTTP request to the Atlassian Marketplace REST service, passing the username and password associated with the vendor as HTTP Basic Auth credentials.

The records in the response may be paged, that is, they may represent a subset of the results. The subset is determined by the offset and limit parameters to the query. Included in the response are "next" and "previous" elements with URL links for retrieving the next or previous set of records. You can use these elements to create an HTML page that lets users page through the results. 

An issue affects the Sales Report API that causes the service to lose the ability to link sales of an add-on to its vendor when the add-on name has been changed. 

Sales report

Request format

The request URL takes the following form:

https://marketplace.atlassian.com/rest/1.0/vendors/VENDOR_ID/sales?start-date=STARTDATE&end-date=ENDDATE&offset=OFFSET&limit=LIMIT&sort-by=SORTBY&order=ORDER&license-type=LICENSETYPE&add-on=PLUGINKEY&q=SUBSTRING 

Replace the VENDOR_ID in the URL with your numeric vendor identifier for the Marketplace website. You can find this ID in the URL for your vendor page in the Marketplace.

The service takes the following parameters:

  • STARTDATE is the beginning of the date range for the sales report request in the form YYYY-MM-DD. This parameter is optional.
  • ENDDATE is the end of the date range for the sales report request. The format for this parameter is YYYY-MM-DD. This parameter is optional.
  • OFFSET specifies the index of the beginning of this page of sales records. For example, when requesting a page of data after the first 50 sales transactions, the offset is 50. This parameter is optional and defaults to 0.
  • LIMIT specifies the maximum number of sales records to return in the page of sales data. This parameter is optional and defaults to 10. The maximum value is 50.
  • SORTBY specifies the field on which to sort the sale records in the response. The default order is ascending, but you can use the order parameter to specify either descending or ascending order. Results for requests that do not specify a sort-by parameter are sorted by reverse date order (equivalent to &sort-by=date&order=desc).  The following sort keys, corresponding to the similarly-named fields in the sale object, are valid:
    • add-on
    • customer
    • date
    • invoice
    • license-id
    • license-size
    • license-type
    • price
    • sale-type
  • ORDER specifies the order by which the records should be sorted in the response. Allowable values are asc for ascending order or desc for descending order. This parameter is optional. The default order if the request specified a sort-by field is ascending.
  • LICENSETYPE returns records associated with a specific license type. Options are academic, commercial or starter. You can specify multiple types by repeating the parameter (for example, &license-type=commercial&license-type=starter). Optional. If not specified, the response includes sales of all license types.
  • PLUGINKEY returns records for a particular add-on identified by plugin key. You can specify multiple add-ons by repeating the parameter for each add-on. This parameter is optional.
  • SUBSTRING filters sales records by a case-insensitive comparison of the query parameter value. This parameter lets you retrieve records by organization name or technical contact, for example. Fields subject to substring matching are technicalContact, organisationName, invoice, and licenseId. All applicable fields are evaluated, so a query of har would match all records with technical contacts of Charlie along with records for organisations named HarrisonStreet. Similarly, a substring value of 123 matches records with an invoice or license ID number that contains '123'.

An example of the request URL with parameters is:

https://marketplace.atlassian.com/rest/1.0/vendors/85/sales?offset=25&limit=25&sort-by=date&licenseTypes=commercial&q=har

Using curl for example, you can invoke the Sales API as follows:

$ curl -u myusername "https://marketplace.atlassian.com/rest/1.0/vendors/85/sales?start-date=2012-09-24"

Successful response

The following listing shows an example of a successful response:

{
    "links": [{
        "href": "/rest/1.0/vendors/99999/sales",
        "rel": "self"
    }, {
        "href": "/rest/1.0/vendors/99999/sales?offset=10",
        "rel": "next",
        "type": "application/json"
    }],
    "sales": [{
        "invoice": "AT-999999",
        "date": "2012-09-18",
        "licenseId": "SEN-1234567",
        "pluginKey": "org.atlassian.tutorial.example-plugin", 
        "pluginName": "Example Plugin",
        "organisationName": "Customer",
        "technicalContact": {
            "email": "sysadmin@example.com",
            "name": "Sys Admin"
        },
        "billingContact": {
            "email": "billing@example.com",
            "name": "Billing Contact"
        },
        "country": "USA",
        "licenseSize": "25 Users",
        "licenseType": "Commercial",
        "saleType": "New",
        "purchasePrice": 25.0,
        "vendorAmount": 21.25,
        "maintenanceStartDate": "2012-09-18",
        "maintenanceEndDate": "2013-09-18"
    },
    // ...
  ]
}

An HTTP 200 status response indicates a successful request.

The first object in the response is the links object. It enables you to construct links in a results page that enables users to page through sales data. The sales object contains the following data for each sale:

Data

Description

Example

invoice A unique transaction ID. Note that credit memos do not have the "AT-" prefix. AT-123456
date The date the sales transaction completed. The format for this field is YYYY-MM-DD. 2012-02-04

licenseId

A unique value in Atlassian SEN format. Note that in Atlassian Cloud, the same license ID will be used for all products licensed for a given Atlassian Cloud instance.

SEN-205346

pluginKey The plugin key that identifies the plugin. If the sale is for a plugin in Atlassian Cloud, the key will end with .ondemand. com.pyxis.greenhopper.jira

pluginName

The name of the purchased plugin.

GreenHopper for JIRA

organisationName

A string representing the add-on customer's organisation name. This field is optional.

Example Company, Inc

technicalContact

The technical contact information configured for this plugin. 
name A string representing the name of the contact. This field is optional. Alice Adams
email A valid email address. This field is required and functions as a unique customer ID. alice.adams@example.com
billingContact


The billing contact information configured for this plugin.

name

A string representing the name of the contact. This field is optional.

Joe Blatt

email

A valid email address. This field is optional.

joe.blatt@example.com

country

A string. This field is optional.

USA

licenseSize

A string describing the number of users.

25 Users, Enterprise 500 users

licenseType

An enumeration that describes the customer's license for the Atlassian product. This value is one of:

  • Commercial
  • Academic

Commercial

saleType

A string representing the type of sale. This is one of:

  • New
  • Renewal
  • Upgrade

New

maintenanceStartDate

The start of the maintenance period associated with this sale. The customer may purchase the add-on before this. The format for this field is YYYY-MM-DD.

2012-02-04

maintenanceEndDate

The end of the maintenance period associated with this sale. The customer may renew before this date. The format for this field is YYYY-MM-DD.

2013-02-04

purchasePrice

This is before tax (GST) and includes discounts. This value is negative for refunds.

100.00

vendorAmount The amount from the sale due to the vendor. This value is negative for refunds. 75.00

discount

Occurs if sale was by an Atlassian expert. This value is negative for refunds.

25.00

expertName The name of the expert involved in the sale, if applicable. AtlassianExperts, Inc.

Error response

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

HTTP Status Code Description

401 Unauthorized

Returned for unauthenticated requests, including requests with incorrect credentials or missing credentials.
403 Forbidden The credentials aren't associated with a user who has permission to access the specified vendor.

License report

Request format

Your license report details user information for those that have started an evaluation or purchased a license for your paid-via-Atlassian add-on. This report is available via the REST API.

The request URL takes the following form:

https://marketplace.atlassian.com/rest/1.0/vendors/VENDOR_ID/license/report

A successful response yields a file titled licenseReport.csv, which includes the 10,000 most recent licenses for your vendor account. It is not possible to filter the results returned by this API.

Data included in the license report

The license report includes the following fields and columns: 

Data

Description

Example

Add-on license ID

licenseId

A unique value in Atlassian SEN format. Note that in Atlassian Cloud, the same license ID will be used for all products licensed for a given Atlassian Cloud instance. Evaluations have a license ID beginning with SEN-L, and that license ID will change once the customer purchases a license.

SEN-205346

Organization name

organisationName

A string. This field is optional.

BMW AG

Add-on name

addOnName

A string representing the name of your add-on. This field is populated by the Marketplace.

GreenHopper for JIRA

Add-on key

addOnKey

Your add-on key. If the sale is for a plugin in Atlassian Cloud, the key will end with .ondemand. com.atlassian.plugins.jira.greenhopper

Technical contact name

technicalContactName

A string representing the contact name. This field is optional.

Alice Adams

Technical contact email

technicalContactEmail

A valid email address. This field functions as a unique customer ID.

alice.adams@supercompany.com

Technical contact phone number

technicalContactPhone

A phone number. This field is optional.

+61294811111

Technical contact address 1

technicalContactAddress1

A string representing the address. This field is optional.

1 Spam Street

Technical contact address 2

technicalContactAddress2

A string representing the address. This field is optional.

Suite 210

Technical contact city

technicalContactCity

A string representing an city. This field is optional.

San Francisco

Technical contact state

technicalContactState

A string representing a state. This field is optional.

CA

Technical contact postal code/zip code

technicalContactPostcode

A string representing a postal code. This field is optional.

94103

Technical contact country

technicalContactCountry

A string representing a country. This field is optional.

US

Billing contact name

billingContactName

A string representing the contact name. This field is optional.

Steve Peters

Billing contact email

billingContactEmail

A valid email address. This field is optional.

steven.peters@company.com

Billing contact phone

billingContactPhone

A string representing the phone number. This field is optional.

+61294811111

Edition

edition

A string representing the user tier of the license. 10 Users

Application license type

licenseType

The value of the Atlassian product license. This value is one of:

  • Evaluation
  • Commercial
  • Academic
  • Open Source
  • Community

Commercial

Add-one license start date

startDate

When the product was originally purchased. The format for this field is YYYY-MM-DD.

2013-02-04

Add-on license end date

endDate

When the license is schedule to expire. The format for this field is YYYY-MM-DD.

2013-02-04

Renewal action

renewalAction

When the license expires, the sales system does one of the following:

  • AUTO_QUOTE : automatically quoted 90 days prior to expiration
  • AUTO_RENEW : automatically renewed using the saved CC on the license expiration date.
  • NONE : a reminder is not sent to the customer

AUTO_QUOTE

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport