Provision a use count license

A use count license is a pay-per-use model in which access is charged based on discrete usage events. Each event, for example, launching an application feature or executing a specific operation, consumes a defined number of units from the available license balance. The use count credit is consumed according to the tracking mode defined in the license model, based on usage requests made by a user or device client.

Use count licenses are used with both B2B and B2C customers. A use count license requires that the (custom) license model associated with the license has UseCountConstraint enabled.

The following examples illustrate how you can restrict license use based on use count.

Example 1: Track usage by session

Each license consumption request that opens a new session consumes 1 unit.

You have an application that allows opening PDF files, and you want licenses that restrict its use based on how many files an end user can open during the license’s validity period.

For example, you want to grant access to a user for 1 month and allow them to open a maximum of 500 files. You set the license’s use count to 500, and each time the user opens a new file consumes 1 unit from that credit.

In this example you use the TRACK_BY_LICENSE_SESSIONS_OPENED tracking mode in UseCountConstraint.
Example 2: Metered usage (client-declared consumption)

You sell an application that relies on a file upload API, and you want to restrict usage based on how much data an end user uploads during the license’s validity period. For example, you grant a license valid for 1 year with a maximum upload quota of 1,000 GB. You set the license’s use count to 1,000, representing 1,000 GB.

In this model, the client application declares how many units to consume with each license consumption call. For instance, if the user attempts to upload 4 GB, the application reports this amount in the license consumption request, consuming 4 units from the license’s remaining quota.

This approach is ideal for metered usage, where consumption varies per action and accurate tracking is based on the count requested by the client application.

In this example you use the TRACK_BY_CALLER_CONSUMPTION_COUNT tracking mode in UseCountConstraint.

This article explains how to provision (grant) a use count license using the 10Duke Entitlement Management REST API. For background, see how license provisioning through the API uses the concept of a transaction.

The article assumes you have connected your client application to 10Duke Enterprise and implemented license consumption for it.

Your 10Duke Enterprise configuration must have the use count credit feature enabled. Contact the 10Duke Integration Support team if needed.

API operations

10Duke Entitlement Management REST API operations:

Operation	URL (relative, prepend the environment base URL)
Provision a license to an organization	POST `/organizations/{orgId}/license-transactions`
Provision a personal license to a user	POST `/users/{userId}/license-transactions`

Example

This example shows how to provision a use count license to an organization which has purchased 1 license from which their users consume the use count.

The example uses the following business case:

Product being sold: PdfPro, a B2B desktop software application which allows end users to open and edit PDF files
Quantity sold: 1 license with a use count of 15000
Product package in 10Duke Enterprise: Name PdfPro, product ID 7a195f0b-459b-4c60-ba5e-7a3d53133e28, with a licensed item configured to grant use count with a credit amount of 1
Customer: A B2B customer organization, organization ID cce56388-2c7f-4dd7-8007-b7c3fbd47901
License terms: The license allows opening a maximum of 15000 PDF files and is sold for a fixed term of 12 months

This means the license will allow users to access the software application for 12 months or until the organization has reached the use count limit.

Request example

Send a POST request to /organizations/{orgId}/license-transactions. See the API reference for details on the API path parameters, request body, and response schemas.

This example request uses curl (line breaks added for display purposes).

The request has quantity set to 15000 to grant the purchased use count, and specifies licenseValidFrom and licenseValidUntil dates to set a 12-month validity for the license.

curl --request POST
   --url <API_base_path>/organizations/cce56388-2c7f-4dd7-8007-b7c3fbd47901/license-transactions
   --header 'content-type: application/json'
   --data '{"transaction":{"type":"Order","externalId":"0000004556786","items":[{"externalId":"0001","productId":"7a195f0b-459b-4c60-ba5e-7a3d53133e28","quantity":15000,"licenseValidFrom":"2023-02-19T14:12:22.012Z","licenseValidUntil":"2024-02-19T14:12:22.012Z"}]}}'

Response example

This sample response shows information that the response body can contain:

{
   "transaction": {
      "id": "f76c1d4e-4dc3-479c-be3c-2088ed266066",
      "type": "Order",
      "externalId": "0000004556786",
      "processed": "2023-02-19T14:12:22.010Z",
      "items": [{
         "id": "4b5c0d8c-abb0-4fdb-be24-47ff06dc28c6",
         "externalId": "0001",
         "productId": "7a195f0b-459b-4c60-ba5e-7a3d53133e28",
         "quantity": 10,
         "licenseValidFrom": "2023-02-19T14:12:22.012Z",
         "licenseValidUntil": "2024-02-19T14:12:22.012Z",
         "licenses": [{
            "id": "68dbc214-fafa-47b1-a2c4-dbec78d6fbad",
            "validFrom": "2023-02-19T14:12:22.012Z",
            "validUntil": "2024-02-19T14:12:22.012Z",
            "active": true,
            "entitlementId": "6bde22fa-ecd4-4017-9b61-d661c33ba353",
            "licensedItem": {
               "id": "b4fe8835-607a-41b1-ad4a-4d17bf8b1427",
               "name": "PdfPro",
               "displayName": "PdfPro"
            },
            "licenseModelId": "11e7cb27-4643-462c-bbc0-10a278d056ee",
            "licenseModelName": "License_Model_for_Use_Count",
            "useCountConsumed": 0,
            "useCountTotal": 15000,
            "useCountCredits": [{
               "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
               "validFrom": "2023-02-19T14:12:22.012Z",
               "validUntil": "2024-02-19T14:12:22.012Z",
               "active": true,
               "licenseId": "68dbc214-fafa-47b1-a2c4-dbec78d6fbad",
               "licenseTransactionItemId": "4b5c0d8c-abb0-4fdb-be24-47ff06dc28c6",
               "useCount": 15000,
               "countUsed": 0
            }]
         }]
      }]
   }
}

Next steps

After provisioning a use count license to an organization, authorize the organization’s users or device clients to consume the license. Add the users or device clients to a user or device client group that has access to the entitlement where the licenses were placed. (This can also be done in advance.) You can do this through the 10Duke Identity Management REST API or in the [10Duke SysAdmin tool](/admin-tools/manage-organizations-users-and-devices/.

If you provisioned a use count license to a consumer customer, the user has access to the license immediately and can start using it.