Provision a use count license

A use count license means that access to the software application is restricted by the use count defined in the license. The use count credit is consumed each time that a user or a device client uses the software application.

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: Each license consumption request consumes 1 unit.

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

    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 file consumes 1 unit from that credit.

  • Example 2: Each license consumption request declares how many units are consumed.

    You have a file upload API, and you want licenses that restrict its use based on the amount of data that an end user can upload during the license validity time.

    For example, you want to grant access to a user for 1 month and allow them to upload a maximum of 1,000 Gb. You set the license’s use count to 1,000, and the API client declares in each license consumption call the number of Gb to upload (for example, 4 Gb), which then consumes units from the credit accordingly.

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:

Item 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",
            "seatsTaken": 0,
            "seatsReserved": 0,
            "seatsTotal": 0,
            "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. The license was created in the organization’s default entitlement, so add the users or device clients to a user or device client group that has access to that entitlement. (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.

On this page