Last updated Apr 24, 2025

Install operations for products and apps

Overview

This cookbook walks a you through performing the following operations to add new Enterprise product:

Provisioning a product or product instances.
Placing an order for the product(s) within 10 minutes.
Checking the status of the order placement.
Checking the status of the provisioning.

Send the provisioning request and immediately after send the place order request.

This cookbook includes two use cases and outlines two corresponding journeys:

Installing a Product

Complete the necessary prerequisites
Get offering ID
Get Enterprise entitlement details
Initiate product provisioning
Create order
Monitor provisioning status

Installing an App

Complete the necessary prerequisites
Get offering ID
Gather app key
Get product entitlement details
Initiate provision app installation
Create order
Monitor provisioning status

Prerequisites

Authorization

Org-scoped permissions

These APIs utilize an API key as a Bearer access token for authentication. To create an API key:

Go to Atlassian Administration. Select your organization if you have more than one.
Select Settings > API keys.
Select Create API key on the top right.
Enter a name that you’ll remember to identify the API key.
By default, the key expires one week from today. If you’d like to change the expiration date, pick a new date value under Expires on. You’re unable to select a date longer than a year from the date of creation.
Select Create to save the API key.
Copy the values of Organization ID and API key fields by selecting the copy button. Make sure you store these values in a safe place, as we won't show them to you again.
Select Done. The key will appear in your list of API keys.

Explore more about API keys.

Site-scoped permissions (site-admin)

You must have site admin role access for this specific site directly at the user level, not through a group.

Create an API key via https://id.atlassian.com/manage-profile/security
Construct encoded_token: create a string by concatenating email and the token created in step 1, joined by Base64 encode this string.
Use Authorization: Basic

1
2
--header 'Authorization: Basic <encoded_token>' \

Instead of:

1
2
--header 'Authorization: Bearer <access_token>' \

Site-scoped authorization can only be used for installing 2nd party apps on products.

Gather Enterprise entitlement details

You need to get product entitlement ID and use that to get entitlement details.

Get product Entitlement ID

Supports Basic authentication (e.g. for site-admins: Replace --header 'Authorization: Bearer {{APIKey}}.

Use the Get entitlement details by ID API to get the Entitlement ID.

Sample Request

1
2
curl --location 'https://api.atlassian.com/admin/installations/v2/orgs/{orgId}/products/{productAri}/entitlements' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authentication: Basic <access_token>'

Sample Response

1
2
{
    "resource_ari": "ari:cloud:platform::site/c9c33dfb-7cc6-42dc-8243-4abe82128f16",
    "entitlements": [
        {
            "entitlement_id": "edf3f6c3-22a3-3f34-a21f-8c6395ac0074",
            "provisioning_status": "ACTIVE",
            "suspension_reasons": [],
            "can_reactivate": false
        }
    ],
    "metadata": {
        "jira_family_container": "c69b31ea-ed4b-37d0-91c3-583a40c8fd9c"
    }
}

Get entitlement details

Supports Basic authentication (e.g. for site-admins: Replace --header 'Authorization: Bearer {{APIKey}}.

Use the Get entitlement details by ID API and the entitlement ID obtained in the previous step $.entitlements[].entitlement_id to get:

Transaction account (TxA)
Invoice Group ID
Entitlement Version
Next Billing Anchor Timestamp
Container Entitlement ID

These will all be important prerequisites for the next steps.

Sample Request

1
2
curl --request GET \
  --url 'https://api.atlassian.com/commerce/api/v2/entitlements/{entitlementId}/details' \
  --header 'Authorization: Bearer {{APIKey}}' \
  --header 'Accept: application/json'

Provision product instances

To provision product instances you need the following:

Contact your Enterprise Advocate to get your offeringId to use for your desired product instances.
If you wish to limit where your product data is hosted choose an Atlassian Data Residency realm and include the location parameter in the request (Optional).
Use an existing organization admin email as adminEmail parameter.

Products can either be provisioned on a new site or added to an existing site in the organization.

To create new cloud site and provision product instance

Create a new site and enter the name in the name parameter. The name will be used to construct the URL of your cloud site. for example, https://$name.atlassian.net.

Add a timezone parameter for the new site.

Sample Request

1
2
curl --request POST \
  --url 'https://api.atlassian.com/admin/installations/v2/orgs/{orgId}/products' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
 "offerings": [
   { 
     "id": "39605741-b92f-4763-8229-7bba2d16433c",
     "location": "us"
   },
   ...
 ],
 "parameters": {
   "adminEmail": "<admin-email>",
   "name": "acme-2",
   "timezone": "Australia/Sydney"
  }
}'

Sample Response

1
2
"data": {
  "statusUrl": "https://api.atlassian.com/admin/installations/v2/orgs/{orgId}/products/status/6664d179-c5e8-4f6a-9f45-8a9f0756440"
}

Save the statusUrl for use in the subsequent steps when you Get Provisioning Status

To provision product instances on existing site

Get existing site name from the Product URLs page on Atlassian Administration: https://admin.atlassian.com/o/{orgId}/product-urls. Use the name of the site preceding .atlassian.net as the name parameter. For example: existing site name of acme.atlassian.net, acme is passed is as name parameter.

Sample Request

1
2
curl --request POST \
  --url 'https://api.atlassian.com/admin/installations/v2/orgs/{orgId}/products' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
 "offerings": [
   { 
     "id": "39605741-b92f-4763-8229-7bba2d16433c",
     "location": "us"
   },
   ...
 ],
 "parameters": {
   "adminEmail": "<admin-email>",
   "name": "acme"
  }
}'

Save the statusUrl for use in the subsequent steps when you Get Provisioning Status

Provision app on product

Supports Basic authentication (e.g. for site-admins: replace '--header 'Authorization: Bearer {{APIKey}}' as per instruction of site-admin authentication.

To provision app on product you need the following:

Contact your Enterprise Advocate to get your offeringId for the app that you want to install.
Contact your Enterprise Advocate to find out the appKey for the app that you want to install. This requires agreeing to the app partners' EULA and privacy policies as per https://privacy.atlassian.net/servicedesk/customer/portal/1/group/1/create/54
Get the product ARI of the product where the app will be installed by querying the Workspaces API. Then URL encode the product ARI using the UTF-8 character set before passing it into the path. ari:cloud:confluence::site/123 → ari%3Acloud%3Aconfluence%3A%3Asite%2F123%0A

Get product ARI

Query the Workspaces API to find the product ARI for the product instance to install apps on. This API returns a list of workspaces within the organization where the id of each workspace returned corresponds to the product ARI. You can filter the response by querying on the site name.

Sample Request

1
2
curl --request POST \
  --url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/workspaces' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{APIKey}}' \
  --data '{
      "query": {
          "field": {
              "name": "attributes.name",
              "values": ["acme"]
          }
      }
  }'

Sample response

1
2
{
  "data": [
    {
      "id": "<string>",
      "type": "<string>",
      "attributes": {
        "name": "acme",
        "typeKey": "<string>",
        "type": "<string>",
        "owner": "<string>",
        "status": "online",
        "statusDetails": [
          "<string>"
        ],
        "icons": {},
        "avatars": {},
        "labels": [
          "<string>"
        ],
        "sandbox": {
          "type": "CHILD"
        },
        "usage": 2154,
        "capacity": 2154,
        "createdAt": "<string>",
        "createdBy": "<string>",
        "updatedAt": "<string>",
        "hostUrl": "<string>",
        "realm": "<string>",
        "regions": [
          "<string>"
        ]
      },
      "links": {
        "self": "<string>"
      },
      "relationships": {}
    }
  ],
  "links": {
    "self": "<string>",
    "prev": "<string>",
    "next": "<string>"
  },
  "meta": {
    "pageSize": 2154,
    "startIndex": 2154,
    "endIndex": 2154,
    "total": 2154
  }
}

Provision app on your product:

1
2
curl --request POST \
  --url 'https://api.atlassian.com/admin/installations/v2/orgs/{orgId}/products/{productAri}/apps' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
 "offerings": [
   { 
     "id": "39605741-b92f-4763-8229-7bba2d16433c"
   },
   ...
 ],
 "parameters": {
   "adminEmail": "<admin-email>",
   "appKey": "<app-key>"
  }
}'

Sample response

1
2
"data": {
  "statusUrl": "https://api.atlassian.com/admin/installations/v2/orgs/{orgId}/products/status/6664d179-c5e8-4f6a-9f45-8a9f0756440"
}

Save the statusUrl for use in the subsequent steps when you Get Provisioning Status

Place order for provisioned product(s) within 10 minutes

To proceed with your order for this product, first check the provisioning status. Once you have that information, you can place an order for either a new site or an existing one.

Get provisioning status

Use the statusUrl returned from provisioning the product instances to check the status of the provisioning operation of the products.

Sample Request

1
2
curl --request GET \
  --url 'https://api.atlassian.com/admin/installations/v2/orgs/{orgId}/products/status/6664d179-c5e8-4f6a-9f45-8a9f0756440' \
  --header 'Accept: application/json'

Sample response

1
2
{
  "data": {
    "requestId": "6664d179-c5e8-4f6a-9f45-8a9f07564400",
    "status": "IN_PROGRESS"
  }
}

Place order for provisioned product(s) within 10 minutes

Supports Basic authentication (e.g. for site-admins: replace '--header 'Authorization: Bearer {{APIKey}}' as per instruction of site-admin authentication.

Once a statusUrl is successfully returned from the previous step, immediately place an order for the desired product instance using the parent entitlement. The place order action must happen in quick succession (within 10 minutes) or the provisioning process will time out while waiting for information from commerce.

Use provisioning request ID returned in the status URL https://api.atlassian.com/admin/installations/v2/orgs/{orgId}/products/status/{provisioningRequestId} as the metadata.provisionRequestId to associate the provisioning and place order operations together.

New Sites

Sample request

Jira Premium (Open Source) instance:

1
2
curl --location --request POST 'https://api.atlassian.com/commerce/api/v2/orders' \
--header 'Authorization: Bearer {{APIKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "orderId": "{{$randomUUID}}",
    "transactionAccountId": "6d9cfcbc-0103-4c21-aa8b-462e1ef2d74e",
    "invoiceGroupId": "63f48e7a-3da6-47af-87c6-724cca25096f",
    "items": [
        {
            "type": "CREATION_ORDER",
            "itemId": "O1",
            "offeringId": "009f8789-c10c-4366-9420-f712d02a6499"
        },
        {
            "type": "CREATION_ORDER",
            "itemId": "O2",
            "offeringId": "6dd805b4-da75-4374-a7a7-cf0b12f7ea07",
            "optedUsageOptions": {
                "effectiveTime": {
                    "endsAt": {
                        "type": "TIMESTAMP",
                        "endTimestamp": 1765520321000
                    }
                },
                "chargingDetails": {
                    "pricingPlanId": "8c1ffdde-3c1d-41a1-a43d-26bd81079e9e",
                    "chargeQuantities": [
                        {
                            "chargeElement": "user",
                            "quantity": 100
                        }
                    ]
                }
            },
            "relatesFromEntitlements": [
                {
                    "relationshipType": "FAMILY_CONTAINER",
                    "referenceType": "ORDER_ITEM",
                    "itemId": "O1"
                }
            ],
            "nextBillingAnchorTimestamp": 1765520321000
        }
    ],
    "metadata": {
        "provisionRequestId": "e532857e-4c27-49d3-8e03-ac032043e76b"
    }
}'

Confluence Enterprise instance:

1
2
curl --location --request POST 'https://api.atlassian.com/commerce/api/v2/orders' \
--header 'Authorization: Bearer {{APIKey}}' \
--header 'Content-Type: application/json' \
--header 'X-transaction-account': {{transactionAccountId}} \
--data-raw '{
  "orderId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
  "transactionAccountId": "2666852d-2296-4c24-a999-8949db3bbf1f",
  "invoiceGroupId": "f5b07603-1330-4235-bbba-1b9d54f04882",
  "items": [
      {
          "type": "CREATION_ORDER",
          "itemId": "O1",
          "offeringId": "39605741-b92f-4763-8229-7bba2d16433c", // Confluence instance
          "optedUsageOptions": {
              "chargingDetails": {
                  "chargeQuantities": [
                      {
                          "chargeElement": "user",
                          "quantity": 100
                      }
                  ]
              }
          },
          "relatesFromEntitlements": [
              {
                  "relationshipType": "ENTERPRISE",
                  "referenceType": "ENTITLEMENT",
                  "entitlementId": "1036832a-8660-4293-9178-3a12b19bc67c" // Confluence parent entitlement
              }
          ]
      }
  ],
  "metadata": {
        "provisionRequestId": "07fb4851-986a-438d-8749-e2c07851c6ca"
    }
}'

Jira Enterprise instance:

1
2
curl --location --request POST 'https://api.atlassian.com/commerce/api/v2/orders' \
--header 'Authorization: Bearer {{APIKey}}' \
--header 'Content-Type: application/json' \
--header 'X-transaction-account': {{transactionAccountId}} \
--data-raw '{
  "orderId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
  "transactionAccountId": "2666852d-2296-4c24-a999-8949db3bbf1f",
  "invoiceGroupId": "f5b07603-1330-4235-bbba-1b9d54f04882",
  "items": [
      {
          "type": "CREATION_ORDER",
          "itemId": "O1",
          "offeringId": "009f8789-c10c-4366-9420-f712d02a6499" // Jira family container
      },
      {
          "type": "CREATION_ORDER",
          "itemId": "O2",
          "offeringId": "799958b5-36bb-4a3d-9289-9fd2986352a7", // Jira instance
          "optedUsageOptions": {
              "chargingDetails": {
                  "chargeQuantities": [
                      {
                          "chargeElement": "user",
                          "quantity": 100
                      }
                  ]
              }
          },
          "relatesFromEntitlements": [
              {
                  "relationshipType": "FAMILY_CONTAINER",
                  "referenceType": "ORDER_ITEM",
                  "itemId": "O1"
              },
              {
                  "relationshipType": "ENTERPRISE",
                  "referenceType": "ENTITLEMENT",
                  "entitlementId": "58146793-4749-4db3-8c36-0cd59aa10b50" // Jira parent entitlement
              }
          ]
      }
  ],
  "metadata": {
        "provisionRequestId": "bb8c5447-c7d3-4aaf-8897-ab28370a753b"
    }
}'

JSM Enterprise instance:

1
2
curl --location --request POST 'https://api.atlassian.com/commerce/api/v2/orders' \
--header 'Authorization: Bearer {{APIKey}}' \
--header 'Content-Type: application/json' \
--header 'X-transaction-account': {{transactionAccountId}} \
--data-raw '{
  "orderId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
  "transactionAccountId": "2666852d-2296-4c24-a999-8949db3bbf1f",
  "invoiceGroupId": "f5b07603-1330-4235-bbba-1b9d54f04882",
  "items": [
      {
          "type": "CREATION_ORDER",
          "itemId": "O1",
          "offeringId": "009f8789-c10c-4366-9420-f712d02a6499" // Jira family container
      },
      {
          "type": "CREATION_ORDER",
          "itemId": "O2",
          "offeringId": "4021727f-e6d1-47ad-be64-2367755f5c51", // JSM instance id
          "optedUsageOptions": {
              "chargingDetails": {
                  "chargeQuantities": [
                      {
                          "chargeElement": "agent",
                          "quantity": 100
                      }
                  ]
              }
          },
          "relatesFromEntitlements": [
              {
                  "relationshipType": "FAMILY_CONTAINER",
                  "referenceType": "ORDER_ITEM",
                  "itemId": "O1"
              },
              {
                  "relationshipType": "ENTERPRISE",
                  "referenceType": "ENTITLEMENT",
                  "entitlementId": "a4c95dd2-eb2d-46a8-b9a4-7076fb8e7548" // JSM parent entitlement
              }
          ]
      }
  ],
  "metadata": {
        "provisionRequestId": "bb8c5447-c7d3-4aaf-8897-ab28370a753b"
    }
}'

All Enterprise products together:

There is only one order item for the Jira family container, which is referenced in both Jira and JSM.

1
2
curl --location --request POST 'https://api.atlassian.com/commerce/api/v2/orders' \
--header 'Authorization: Bearer {{APIKey}}' \
--header 'Content-Type: application/json' \
--header 'X-transaction-account': {{transactionAccountId}} \
--data-raw '{
  "orderId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
  "transactionAccountId": "2666852d-2296-4c24-a999-8949db3bbf1f",
  "invoiceGroupId": "f5b07603-1330-4235-bbba-1b9d54f04882",
  "items": [
  // ------ Confluence
      {
          "type": "CREATION_ORDER",
          "itemId": "O1",
          "offeringId": "39605741-b92f-4763-8229-7bba2d16433c", // Confluence instance
          "optedUsageOptions": {
              "chargingDetails": {
                  "chargeQuantities": [
                      {
                          "chargeElement": "user",
                          "quantity": 100
                      }
                  ]
              }
          },
          "relatesFromEntitlements": [
              {
                  "relationshipType": "ENTERPRISE",
                  "referenceType": "ENTITLEMENT",
                  "entitlementId": "1036832a-8660-4293-9178-3a12b19bc67c" // Confluence parent entitlement
              }
          ]
      },
  // ------- Jira
      {
          "type": "CREATION_ORDER",
          "itemId": "O2",
          "offeringId": "009f8789-c10c-4366-9420-f712d02a6499" // Jira family container
      },
      {
          "type": "CREATION_ORDER",
          "itemId": "O3",
          "offeringId": "799958b5-36bb-4a3d-9289-9fd2986352a7", // Jira instance
          "optedUsageOptions": {
              "chargingDetails": {
                  "chargeQuantities": [
                      {
                          "chargeElement": "user",
                          "quantity": 100
                      }
                  ]
              }
          },
          "relatesFromEntitlements": [
              {
                  "relationshipType": "FAMILY_CONTAINER",
                  "referenceType": "ORDER_ITEM",
                  "itemId": "O2"    // reference to Jira family container order item
              },
              {
                  "relationshipType": "ENTERPRISE",
                  "referenceType": "ENTITLEMENT",
                  "entitlementId": "58146793-4749-4db3-8c36-0cd59aa10b50" // Jira parent entitlement
              }
          ]
      },
  // ------- JSM
      {
          "type": "CREATION_ORDER",
          "itemId": "O4",
          "offeringId": "4021727f-e6d1-47ad-be64-2367755f5c51", // JSM instance id
          "optedUsageOptions": {
              "chargingDetails": {
                  "chargeQuantities": [
                      {
                          "chargeElement": "agent",
                          "quantity": 100
                      }
                  ]
              }
          },
          "relatesFromEntitlements": [
              {
                  "relationshipType": "FAMILY_CONTAINER",
                  "referenceType": "ORDER_ITEM",
                  "itemId": "O2"   // reference to Jira family container order item
              },
              {
                  "relationshipType": "ENTERPRISE",
                  "referenceType": "ENTITLEMENT",
                  "entitlementId": "a4c95dd2-eb2d-46a8-b9a4-7076fb8e7548" // JSM parent entitlement
              }
          ]
      }
  ],
  "metadata": {
        "provisionRequestId": "bb8c5447-c7d3-4aaf-8897-ab28370a753b"
    }
}'

Sample Response

Confluence Enterprise instance:

1
2
{
    "orderId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
    "slug": "R-42K-N76-CYQ-ZT6",
    "items": [
        {
            "itemId": "O1",
            "orderItemId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        }
    ],
    "transactionAccountId": "2666852d-2296-4c24-a999-8949db3bbf1f",
    "invoiceGroupId": "f5b07603-1330-4235-bbba-1b9d54f04882",
    "additionalTriggeredOrders": null,
    "metadata": {
        "provisionRequestId": "07fb4851-986a-438d-8749-e2c07851c6ca"
    }
}

Jira Enterprise instance:

1
2
{
    "orderId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
    "slug": "R-42K-N76-CYQ-ZT6",
    "items": [
        {
            "itemId": "O1",
            "orderItemId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        },
        {
            "itemId": "O2",
            "orderItemId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        }
    ],
    "transactionAccountId": "2666852d-2296-4c24-a999-8949db3bbf1f",
    "invoiceGroupId": "f5b07603-1330-4235-bbba-1b9d54f04882",
    "additionalTriggeredOrders": null,
    "metadata": {
        "provisionRequestId": "07fb4851-986a-438d-8749-e2c07851c6ca"
    }
}

JSM Enterprise instance:

1
2
{
    "orderId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
    "slug": "R-42K-N7A-YVZ-BE7",
    "items": [
        {
            "itemId": "O1",
            "orderItemId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        },
        {
            "itemId": "O2",
            "orderItemId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        }
    ],
    "transactionAccountId": "2666852d-2296-4c24-a999-8949db3bbf1f",
    "invoiceGroupId": "f5b07603-1330-4235-bbba-1b9d54f04882",
    "additionalTriggeredOrders": null,
    "metadata": {
        "provisionRequestId": "07fb4851-986a-438d-8749-e2c07851c6ca"
    }
}

All Enterprise products together:

1
2
{
    "orderId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
    "slug": "R-42K-N7A-YVZ-BE7",
    "items": [
        {
            "itemId": "O1",
            "orderItemId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        },
        {
            "itemId": "O2",
            "orderItemId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        },
        {
            "itemId": "O3",
            "orderItemId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        },
        {
            "itemId": "O4",
            "orderItemId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        }
    ],
    "transactionAccountId": "2666852d-2296-4c24-a999-8949db3bbf1f",
    "invoiceGroupId": "f5b07603-1330-4235-bbba-1b9d54f04882",
    "additionalTriggeredOrders": null,
    "metadata": {
        "provisionRequestId": "07fb4851-986a-438d-8749-e2c07851c6ca"
    }
}

Existing Sites

Supports Basic authentication (e.g. for site-admins: replace '--header 'Authorization: Bearer {{APIKey}}' as per instruction of site-admin authentication.

If your site already has one Jira family product (Jira, JSM), and you want to place an order for the other, you will need to get the entitlementId of the Jira family container.

Query the Workspaces API on your site name to retrieve the entitlementId of the existing Jira product. Look for $.relationships.entitlement[0].id in the response.

Sample Request

1
2
curl --request POST \
  --url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/workspaces' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{APIKey}}' \
  --data '{
      "query": {
          "field": {
              "name": "attributes.name",
              "values": ["acme"]
          }
      }
  }'

Sample Response

1
2
{
    "data": [
        {...},
        {
            "id": "ari:cloud:jira-software::site/4745a76c-290c-49d4-aa23-04d5ccb3c52d",
            "type": "Jira Software",
            "links": {
                "self": "https://api.atlassian.com/admin/v1/workspaces/ari%3Acloud%3Ajira-software%3A%3Asite%2F4745a76c-290c-49d4-aa23-04d5ccb3c52d"
            },
            "attributes": {
                "name": "acme",
                "typeKey": "jira-software",
                "type": "Jira Software",
                "icons": {},
                "avatars": {},
                "labels": [
                    "sandbox"
                ],
                "status": "online",
                "statusDetails": [],
                "sandbox": {
                    "type": "NONE",
                    "parentId": null
                },
                "hostUrl": "https://acme.atlassian.net",
                "realm": "us",
                "regions": [
                    "us-east-1",
                    "us-west-2"
                ]
            },
            "relationships": {
                "entitlement": [
                    {
                        "id": "f5050916-617d-49d5-9aa8-382185a0c0b3",   // this is what we're looking for in this step
                        "links": {
                            "self": "https://api.atlassian.com/admin/v1/workspaces/ari%3Acloud%3Ajira-software%3A%3Asite%2F4745a76c-290c-49d4-aa23-04d5ccb3c52d/entitlements/f5050916-617d-49d5-9aa8-382185a0c0b3"
                        },
                        "type": "entitlements",
                        "attributes": {
                            "planKey": "enterprise",
                            "plan": "Enterprise",
                            "key": "jira-software.ondemand"
                        }
                    }
                ],
                ...
            }
        }
    ],
    "links": {
        "self": "eyJxdWVyeSI6eyJwcmltaXRgdhrtherthdfhdfghyY2hEaXJlY3Rpb24iOm51bGwsImxpbWl0IjoyMH0=",
        "next": null,
        "prev": null
    },
    "meta": {
        "attributes": null,
        "pageSize": 20,
        "startIndex": 1,
        "endIndex": 4,
        "total": 4
    }
}

Use the entitlementId obtained above on the Get entitlement details API to find the entitlementId of the Jira family container for this site. Look for $.relatesFromEntitlements[].entitlementId for type FAMILY_CONTAINER in the response.

Sample Request

1
2
curl --request GET \
  --url 'https://api.atlassian.com/commerce/api/v2/entitlements/{entitlementId}/details' \
  --header 'Authorization: Bearer {{APIKey}}' \
  --header 'Accept: application/json'

Sample Response

1
2
{
    "entitlementId": "73a8edb7-a48f-3a03-8609-5a616930f01c",
    ...,
    "relatesFromEntitlements": [
        {
            "entitlementId": "96a551eb-b8e2-3217-a11f-5e5670b10a3e",
            "relationshipType": "ENTERPRISE",
            "relationshipId": "b68b68ec-8b54-4baa-9886-c11a549d4cd6"
        },
        {
            "entitlementId": "92ee1d1d-9f6c-3288-b1d9-12dbf5086ef6",   // we want this
            "relationshipType": "FAMILY_CONTAINER",
            "relationshipId": "c3758d24-c5ec-42f3-81f6-eec7a3cd9420"
        }
    ],
    ...
}

Use the container’s entitlementId to place the order.

Sample Request

Add JSM to a site with Jira

1
2
curl --location --request POST 'https://api.atlassian.com/commerce/api/v1/orders' \
--header 'Authorization: Bearer {{APIKey}}' \
--header 'Content-Type: application/json' \
--header 'X-transaction-account': {{transactionAccountId}} \
--data-raw '{
  "orderId": "78e519c2-2277-40dd-82b2-efb08d6290ad",
  "transactionAccountId": "2666852d-2296-4c24-a999-8949db3bbf1f",
  "invoiceGroupId": "f5b07603-1330-4235-bbba-1b9d54f04882",
  "items": [
      {
          "type": "CREATION_ORDER",
          "itemId": "O1",
          "offeringId": "4021727f-e6d1-47ad-be64-2367755f5c51", // JSM instance id
          "optedUsageOptions": {
              "chargingDetails": {
                  "chargeQuantities": [
                      {
                          "chargeElement": "agent",
                          "quantity": 100
                      }
                  ]
              }
          },
          "relatesFromEntitlements": [
              {
                  "relationshipType": "FAMILY_CONTAINER",
                  "referenceType": "ENTITLEMENT",
                  "entitlementId": "{{jiraFamilyContainerEntitlementId}}"
              },
              {
                  "relationshipType": "ENTERPRISE",
                  "referenceType": "ENTITLEMENT",
                  "entitlementId": "a4c95dd2-eb2d-46a8-b9a4-7076fb8e7548" // JSM parent entitlement
              }
          ]
      }
  ],
  "metadata": {
        "provisionRequestId": "99352caa-8e29-4947-9826-e9af789e8242"
    }
}

If you have provisioned apps on products, proceed to place an order for those apps.

Supports Basic authentication (e.g. for site-admins: Replace '--header 'Authorization: Bearer {{APIKey}}' as per instruction of site-admin authentication.

Sample request

$.orderId - a UUID generated by the caller. It is used as an idempotent key as well
$.transactionAccountId - the ID assigned to you can be obtained from Atlassian Support
$.invoiceGroupId - the ID assigned to you can be obtained from Atlassian Support
$.items[].itemId - a unique id for each order item generated by the client
$.items[].type is CREATION_ORDER
$.items[].offeringId can be obtained from List products API and Get offerings by product API
$.items[].optedUsageOptions.chargingDetails.pricingPlanId can be obtained from Get Priving plan API
$.items[].promotions[].promotionDefinition.promotionCode the app promo code you have received from the app vendor
$.items[].relatesFromEntitlements[].entitlementId

For Jira installations: This is the containerId derived from the Entitlement Details query (add link) $.relatesFromEntitlements.entitlementId.
For Confluence installations: This is the confluence entitlement_id derived from Entitlement ID Query (add link).

$.items[].nextBillingAchorTimestamp This is the timestampderived from the Entitlement Details query (add link) $.subscriptionv2.billingPeriodDetails.billingAnchorTimestamp.
In the array chargeQuantities, set $.chargeElement to '?' and $.quantity to the anticipated maximum number of users of your site. This limit is is relevant for annually billed Jira Cloud sites of Standard and Premium Tiers being the maximum number of users you can add to the site. For Enterprise instances, this limit is not enforced.

Sample request

1
2
curl --location --request POST 'https://api.atlassian.com/commerce/api/v2/orders' \
--header 'Authorization: Bearer {{APIKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "orderId": "ff34629f-cc52-4fae-a8e3-364257229805",
    "transactionAccountId": "78e855e6-731e-4819-b23e-7854aad854c8",
    "invoiceGroupId": "2f100e51-b40a-4d9a-8809-63b1ffdde012",
    "items": [
        {
            "type": "CREATION_ORDER",
            "itemId": "O1",
            "offeringId": "3198373c-f623-445a-be6d-da924f4161d2",
            "optedUsageOptions": {
                "chargingDetails": {
                    "pricingPlanId": "99eb1387-befd-47bc-a2e6-9e66eb086281",
                    "chargeQuantities": [
                        {
                            "chargeElement": "agent",
                            "quantity": 100
                        }
                    ]
                },
                "trial": {
                    "skipTrial": true
                },
                "effectiveTime": {
                  "endsAt": {
                      "type": "TIMESTAMP",
                      "endTimestamp": 1752745039000
                  }
                }
            },
            "promotions": [{
                "promotionDefinition": {
                    "promotionCode": "PROMO_CODE"
                }
            }],
            "relatesFromEntitlements": [
                {
                    "relationshipType": "APP_DEPENDENCE",
                    "referenceType": "ENTITLEMENT",
                    "entitlementId": "d71ec13e-301b-35bf-9808-653f5be6c256"
                }
            ],
            "nextBillingAnchorTimestamp": 1752745039000
        }
    ],
    "metadata": {
        "provisionRequestId": "6664d179-c5e8-4f6a-9f45-8a9f0756440"
    }
}'

Sample response

1
2
{
    "orderId": "ff34629f-cc52-4fae-a8e3-364257229805",
    "slug": "R-42K-N7M-D5T-4XD",
    "items": [
        {
            "itemId": "O1",
            "orderItemId": "ff34629f-cc52-4fae-a8e3-364257229805-1",
            "triggeredByOrderItem": null,
            "processingInfo": null,
            "metadata": null
        }
    ],
    "transactionAccountId": "78e855e6-731e-4819-b23e-7854aad854c8",
    "invoiceGroupId": "2f100e51-b40a-4d9a-8809-63b1ffdde012",
    "additionalTriggeredOrders": null,
    "metadata": null
}

Get status of order

Supports Basic authentication (e.g. for site-admins: replace '--header 'Authorization: Bearer {{APIKey}}' as per instruction of site-admin authentication.

Track the status of the order using the orderId. The status of the order item can be found in $.items[].processingInfo.status. Each item must reach the SUCCESS state for the entire order to be successful. Some of the order item fields will be populated only after the item reaches SUCCESS status. For example, $.items[].processingInfo.entitlement.id for a CREATION_ORDER item type will be populated after reaching SUCCESS status.

Sample Request

1
2
curl --request GET \
  --url 'https://api.atlassian.com/commerce/api/v2/orders/{id}' \
  --header 'Authorization: Bearer {{APIKey}}' \
  --header 'X-transaction-account: {{transactionAccountId}}'
  --header 'Accept: application/json'

Sample response

1
2
{
    "orderId": "0aed15e5-3d09-4319-800d-d65a5e73f783",
    "slug": "R-42K-N76-CYQ-ZT6",
    "transactionAccountId": "78e855e6-731e-4819-b23e-7854aad854c8",
    "transactionAccount": {
        "id": "78e855e6-731e-4819-b23e-7854aad854c8",
        "partitionKey": "atlassian-commercial"
    },
    "invoiceGroupId": "2f100e51-b40a-4d9a-8809-63b1ffdde012",
    "items": [
        {
            "orderItemId": "0aed15e5-3d09-4319-800d-d65a5e73f783-1",
            "offeringId": "009f8789-c10c-4366-9420-f712d02a6499",
            "type": "CREATION_ORDER",
            "parentEntitlementId": null,
            "optedUsageOptions": null,
            "billingOptions": null,
            "resetOptions": null,
            "processingInfo": {
                "entitlement": {
                    "id": "d71ec13e-301b-35bf-9808-653f5be6c256",
                    "version": "1"
                },
                "status": "SUCCESS",
                "transitionTime": "IMMEDIATE",
                "transitionTimestamp": null,
                "saleTransitionType": "NA",
                "saleTransitionDetails": {
                    "glpForLastPaidPlan": -1,
                    "glpForCurrentPlan": -1,
                    "glpForNextPlan": -1,
                    "glpForNextPlanLegacyPricing": null,
                    "currentOfferingLevel": null,
                    "nextOfferingLevel": 1,
                    "saleTransitionType": "NA",
                    "lastPaidOfferingLevel": null,
                    "saleTransitionTime": null,
                    "glpForAllPhases": null
                },
                "accountModification": null,
                "computedDetails": {
                    "offeringId": null,
                    "computedEndTimestamp": null,
                    "computedBillUntilTimestamp": null,
                    "usageOptions": null,
                    "removedPromotions": null,
                    "orderedPromotions": null,
                    "pricingPlanTransition": null
                },
                "impactedEntitlements": null,
                "additionalTriggeredOrderItems": null,
                "prorationBehaviour": "ALWAYS_INVOICE"
            },
            "triggeredByOrderItem": null,
            "reasonCode": null,
            "featureOverrides": null,
            "metadata": null,
            "isImmediate": null,
            "promotions": null,
            "quoteLineItemDetailsReference": null,
            "originalOrderItemId": null,
            "updatedDate": 1721418339443,
            "prorationBehaviour": null,
            "relatesFromEntitlements": []
        },
        {
            "orderItemId": "0aed15e5-3d09-4319-800d-d65a5e73f783-2",
            "offeringId": "799958b5-36bb-4a3d-9289-9fd2986352a7",
            "type": "CREATION_ORDER",
            "parentEntitlementId": null,
            "optedUsageOptions": {
                "trial": null,
                "chargingDetails": {
                    "pricingPlanId": null,
                    "chargeQuantities": [
                        {
                            "chargeElement": "user",
                            "quantity": 100
                        }
                    ]
                },
                "purchaseMetadata": null,
                "effectiveTime": null,
                "billingBehaviour": null
            },
            "billingOptions": null,
            "resetOptions": null,
            "processingInfo": {
                "entitlement": {
                    "id": "3e54ef62-8c14-33ab-9625-5de436e5625b",
                    "version": "2"
                },
                "status": "SUCCESS",
                "transitionTime": "IMMEDIATE",
                "transitionTimestamp": null,
                "saleTransitionType": "NA",
                "saleTransitionDetails": {
                    "glpForLastPaidPlan": -1,
                    "glpForCurrentPlan": -1,
                    "glpForNextPlan": 0,
                    "glpForNextPlanLegacyPricing": null,
                    "currentOfferingLevel": null,
                    "nextOfferingLevel": 700,
                    "saleTransitionType": "NA",
                    "lastPaidOfferingLevel": null,
                    "saleTransitionTime": null,
                    "glpForAllPhases": null
                },
                "accountModification": null,
                "computedDetails": {
                    "offeringId": null,
                    "computedEndTimestamp": null,
                    "computedBillUntilTimestamp": null,
                    "usageOptions": null,
                    "removedPromotions": null,
                    "orderedPromotions": null,
                    "pricingPlanTransition": null
                },
                "impactedEntitlements": null,
                "additionalTriggeredOrderItems": null,
                "prorationBehaviour": "ALWAYS_INVOICE"
            },
            "triggeredByOrderItem": null,
            "reasonCode": null,
            "featureOverrides": null,
            "metadata": null,
            "isImmediate": null,
            "promotions": null,
            "quoteLineItemDetailsReference": null,
            "originalOrderItemId": null,
            "updatedDate": 1721418339400,
            "prorationBehaviour": null,
            "relatesFromEntitlements": [
                {
                    "relationshipType": "FAMILY_CONTAINER",
                    "referenceType": "ORDER_ITEM",
                    "orderItemId": "0aed15e5-3d09-4319-800d-d65a5e73f783-1"
                },
                {
                    "relationshipType": "ENTERPRISE",
                    "referenceType": "ENTITLEMENT",
                    "entitlementId": "1dd82d6d-13cd-3e10-a8bd-1fac14fa3f6e"
                }
            ]
        }
    ],
    "additionalTriggeredOrders": null,
    "metadata": null,
    "createdDate": 1721418338715
}