Last updated Aug 16, 2021

Parent insights and discount data

Marketplace partners can now access discounts data and parent product insights in license and transaction APIs. The discounts data can be used to get an exhaustive understanding of how much discount and the type of discount that was applied on a particular transaction. The parent product insights can be used to find out more about the parent product on which the customer has installed your app. For example, the edition of a parent product, and whether the app is installed on a sandbox site on the customer's end.

Get Licenses API

API documentation: The insights for licenses can be obtained by adding the flag withDataInsights=true as a query parameter to the license API. The details of the fields that are added and more info on them are as follows:

  • parentProductBillingCycle to know the billing cycle of an evaluation's parent product
  • parentProductName, parentProductEdition to know the edition of the parent product.
  • installedOnSandbox to know if the app is installed on a sandbox site

Sample response

1
2
{
  "licenses": [
    {
    ...
    ...
    ...
    "evaluationOpportunitySize": "NA",
    "evaluationLicense": "2205182",
    "daysToConvertEval": "-59",
    "attribution": {
      "channel": "Paid Search",
      "referrerDomain": "www.google.com",
      "campaignMedium": "cpc",
      "campaignName":
      "P:opsgenie|O:ppm|V:google|G:de|L:de|F:consider|S:brand-trademark|M:exact|A:text|D:desktop",
      "campaignSource": "google"
    },
    "evaluationStartDate": "2021-03-25",
    "evaluationEndDate": "2021-05-24",
    "evaluationSaleDate": "2021-03-26",
    "parentProductBillingCycle": "ANNUAL",
    "parentProductName": "Jira",
    "installedOnSandbox": "Yes",
    "parentProductEdition": "Premium"
  },
  ...
 ]
}

The license export reports with this additional data can be accessed via the following steps in Licenses reporting UI:

  • Open the filters dropdown
  • Change 'Type of data' from "Default" to "With additional insights"
  • Select a date range that is less than 90 days
  • Apply the filters
  • Click the CSV/JSON links at the top of the page to download the CSV/JSON respectively

Export licenses API

API documentation: The licenses export API via JSON(accept=json) has the new fields similar to the get licenses API mentioned above.

The export API via CSV(accept=csv) when requested with ?withDataInsights=true contains additional fields CSV columns:

  • parentProductBillingCycle
  • parentProductName
  • parentProductEdition
  • installedOnSandbox

Get transactions API

API documentation: The insights for transactions are appended to the earlier API response. The details of the fields that are added and more info on them are as follows:

  • changeInTier, oldTier, and tier to understand the change in users/tier of an app.
  • changeInParentProductEdition, oldParentProductEdition and parentProductEdition to understand the change in parent product edition.
  • changeInBillingPeriod, oldBillingPeriod, and billingPeriod to understand the change in the billing cycle.
  • parentProductName to understand the parent product name.
  • discounts: Array of Discount objects consisting of all the discounts that are applied to the given transaction. This object will be nested with the purchaseDetails object present for a transaction. This array will be exhaustive of all discounts and is recommended for use over existing discounts data in the transactions API. Moving ahead, Discount object within the array would be enriched to contain more data where applicable. Each Discount object will be of the structure:
1
2
{
  "type": (MANUAL|EXPERT|MARKETPLACE_PROMOTION|LOYALTY),
  "amount": Double
}

The different discount types are:

  • MARKETPLACE_PROMOTION: Discount provided via marketplace promotions by marketplace partners
  • LOYALTY: Discount provided by marketplace partner for facilitating enterprise server customer to cloud migration. Rates are based on the year a purchase was made.
  • MANUAL: Discount provided by customer advocates
  • EXPERT: Discount provided by solution partners

The fields that are populated in the CSV report to represent the above discounts are: loyaltyDiscountAmount, marketplacePromotionDiscountAmount, expertDiscountAmount, and manualDiscountAmount

Sample response

1
2
{
  "transactions": [
    {
    ...
    ...
    "licenseId": "SEN-22034XXX",
    "addonKey": "com.innovalog.jmwe.jira-misc-workflow-extensions",
    "purchaseDetails": {
    "saleDate": "2021-03-26",
    "licenseType": "COMMERCIAL",
    ...
    ...
    "tier": "10 Users",
    "parentProductName": "Jira",
    "changeInParentProductEdition": "No",
    "parentProductEdition": "Standard",
    "purchasePrice": 40.0,
    "vendorAmount": 34.0,
    "partnerDiscountAmount": 10.0,
    "discounts": [
      {
        "type": "EXPERT",
        "amount": 10.0
      }
    ],
    "saleType": "New",
    "maintenanceStartDate": "2021-04-24",
    "maintenanceEndDate": "2022-04-24"
    },
    ...
    ...
    }
  ...
  ]
}

Export transactions API

API documentation: The transactions export API via JSON(accept=json) has new fields similar to the get transactions API mentioned above.

The export API via CSV(accept=csv ) contains additional fields CSV columns:

  • changeInTier
  • oldTier
  • changeInBillingPeriod
  • oldBillingPeriod
  • parentProductName
  • parentProductEdition
  • changeInParentProductEdition
  • oldParentProductEdition
  • loyaltyDiscountAmount
  • marketplacePromotionDiscountAmount
  • expertDiscountAmount
  • manualDiscountAmount

Things to remember

  1. parentProductName and parentProductBillingCycle are available only for cloud, data-center, and server evaluations.
  2. parentProductEdition and installedOnSandbox fields are available only for cloud.
  3. changeInParentProductEdition and oldParentProductEdition are available for the cloud in licenses and transactions.
  4. The data is available approximately 48-72 hrs after an evaluation is purchased or after the evaluation is converted to a sale.
  5. Parent insights are available for evaluations created from January 2020 in the licenses API.
  6. Parent insights for cloud evaluations in licenses are more accurate compared to DC evaluations due to limited insight into Data Center instances. SEN of a cloud instance remains the same after it is converted, however it changes in Data Center. Insights would not be available in cases where an app is purchased without an evaluation.
  7. Logic to derive parent edition:
    • When an app is installed by a customer, the edition of the parent product(Jira/Confluence) as of that date is shown.
    • If a customer's site has multiple Jira instances, the edition is first filtered out according to the user count and if the user counts are also the same then prioritize the Jira according to this - Jira Software > JSM > Jira Core.
  8. Logic to derive parent product billing cycle for a sale:
    • For evaluation, we show parentProductBillingCycle field.
    • For non-evaluation, the parent billing cycle is the same as the app billing cycle. So for them, we do not show this field explicitly.
  9. Parent insights are not shown for:
    • Licenses that are owned by Atlassian
    • Test licenses or internal use licenses, which are given to partners for free
  10. In the case of refund transactions, the fields changeInTier, oldTier, changeInBillingPeriod, oldBillingPeriod,changeInParentProductEdition and oldParentProductEdition will be empty as the mapping with the previous transaction immediate to the refund is not present.
  11. The newly added discounts array is an exhaustive list of discounts applied on a transaction. The earlier available loyaltyDiscountAmount field is also captured in this array if present. The data shown by partnerDiscountAmount is faulty and incorrect. It need not coincide with the sum of the discounts amounts in the discounts array and will be removed soon.

Rate this page: