Provision a subscription license

A subscription-based license means that the customer pays, for example, a monthly or annual fee to use the software instead of making a one-time purchase.

By using 10Duke Enterprise integrated with your e-commerce or payment provider platform, you can monetize and leverage the power of recurring billing and deliver subscriptions effectively. Subscription licenses are used with both B2B and B2C customers.

In 10Duke Enterprise, a subscription license has a fixed validity start and end date defined, and you enable customers to renew their license through the e-commerce or payment provider platform. In 10Duke Enterprise, renewing the license in practice means either extending the customer’s existing license period or granting them a new fixed-term license.

This article provides an overview of the integration and configurations needed for providing subscription licenses, and explains how to provision (grant) a subscription 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.

Integration with e-commerce or payment provider platform

You can integrate your e-commerce or Payment provider platform with 10Duke Enterprise to accept online payments and issue and manage recurring licenses.

It’s important to understand the role of each system:

10Duke Enterprise provides both customer identity management and entitlement management APIs, enabling you to both authenticate an end user when they sign into your application and allow them to access your application if they have a valid license. 10Duke Enterprise is not concerned with any aspect of the e-commerce or payment provider.
The e-commerce or payment provider platform is primarily set up to receive and manage payments from customers online.

Configurations required

The following configurations are typically required for provisioning subscription licenses:

Configure and connect the e-commerce or payment provider platform as a client application to 10Duke Enterprise.
Make sure the product mapping on the e-commerce or payment provider platform reflects the product packages defined in 10Duke Enterprise.
Configure the prices and set up the subscription billing cycles, tax rates, and so on on the e-commerce or payment provider platform.
Configure and customize the e-commerce or payment provider hosted payment pages and customer portal as needed.
Design and agree on the e-commerce user flow and identify the 10Duke API operations required to support it.
- 10Duke Identity Management REST API allows you to make CRUD interactions with 10Duke Enterprise on organizations, users, and user groups and more.
- 10Duke Entitlement Management REST API allows you to make CRUD operations with 10Duke Enterprise on licenses and the entitlements that hold those licenses.
Set up the e-commerce or payment provider API integration (for example, configure webhook endpoints) to 10Duke Enterprise and other business systems (for example, a CRM).

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 subscription license to a consumer customer.

The example uses the following business case:

Product being sold: CutXPro, a B2C desktop software application that allows end users to crop elements from photographs
Quantity sold: 1 license
Product package in 10Duke Enterprise: Name CutXPro, product ID 0aa228a2-d3bc-4934-9069-658333c03780
Customer: A B2C customer
License terms: The license is sold as a monthly subscription

This example provisions a seat-based license, so the product package has a licensed item configured to grant 1 seat, and the associated license model has SeatCountConstraint enabled.

Request example

Send a POST request to users/{userId}/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 specifies licenseValidFrom and licenseValidUntil dates to set a 1-month validity for the license.

curl --request POST
   --url <API_base_path>/users/me/license-transactions
   --header 'content-type: application/json'
   --data '{"transaction":{"type":"Order","externalId":"0000004556786","items":[{"externalId":"0001","productId":"0aa228a2-d3bc-4934-9069-658333c03780","quantity":1,"licenseValidFrom":"2023-02-19T14:12:22.012Z","licenseValidUntil":"2023-03-19T14:12:22.012Z"}]}}'

Response example

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

{
   "transaction": {
      "id": "8ec39f9d-f739-4bc1-aa55-8cb712e50adb",
      "type": "Order",
      "externalId": "0000004556786",
      "processed": "2023-02-19T14:12:22.010Z",
      "items": [{
         "id": "e0588c33-7055-4b28-8ec6-9e92c6f3b94f",
         "externalId": "0001",
         "productId": "0aa228a2-d3bc-4934-9069-658333c03780",
         "quantity": 1,
         "licenseValidFrom": "2023-02-19T14:12:22.012Z",
         "licenseValidUntil": "2023-03-19T14:12:22.012Z",
         "licenses": [{
            "id": "48e04c21-1fae-4ddf-ab5a-e0644039c81e",
            "validFrom": "2023-02-19T14:12:22.012Z",
            "validUntil": "2024-02-19T14:12:22.012Z",
            "active": true,
            "entitlementId": "6bde22fa-ecd4-4017-9b61-d661c33ba353",
            "licensedItem": {
               "id": "75151a68-fee2-436e-bfa7-3d9e5b94668d",
               "name": "CutXPro",
               "displayName": "CutXPro"
            },
            "licenseModelId": "1db0c182-70c4-4a51-8326-54ce29138303",
            "licenseModelName": "License_Model_for_Personal_License",
            "seatsTaken": 0,
            "seatsReserved": 0,
            "seatsTotal": 1,
            "seatCountCredits": [{
               "id": "0841fc18-3220-4816-a12f-9cf125c7d489",
               "validFrom": "2023-02-19T14:12:22.012Z",
               "validUntil": "2023-03-19T14:12:22.012Z",
               "active": true,
               "licenseId": "48e04c21-1fae-4ddf-ab5a-e0644039c81e",
               "licenseTransactionItemId": "e0588c33-7055-4b28-8ec6-9e92c6f3b94f",
               "seatCount": 1,
               "seatsConsumed": 0
            }]
         }]
      }]
   }
}

Next steps

In the above example case, the consumer user now has a valid subscription and is allowed to consume the license and run the application for 1 month.

When the next billing date is reached, your e-commerce or payment provider charges the end user’s credit card for the next billing cycle.

If the subscription is renewed successfully, use one of the following options:

Recommended: Update the validity of the existing license for another month using PUT /users/{userId}/license-transactions.
Leave the existing license to expire as scheduled, and provision a new license for the new month in the same way as the first license.

If you provisioned a subscription license to an organization, also 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.