Create an Entitlement

The core functionality of the entitlement system is to create and manage entitlements. This workflow assumes the Product has been created, a purchase has been completed, and the user is associated with a Trimble Identity.

After the entitlement is created, the product must be activated, and a user assigned for the purchaser to access their product(s).

To create the entitlement:

API Call:

POST {baseurl}/entitlements

Headers:

• Accept: application/json (Note: This may be automatically added by your development tool. Postman and CURL add this header to all requests by default.)
• Authorization: Bearer {bearer token} (Include Trimble Identity OAuth Bearer token for your application. Please see Get Access Token for more information.)

Body:

Base your body on the example request code sample below. This example shows the minimum required request body. See API Definition for parameter details and additional optional parameters.

Example Request Body:

{
  "startDate": {
    "year": 2017,
    "month": 12,
    "day": 14
  },
  "source": "Sample_Test_source",
  "orderNumber": "",
  "accounts": [
    {
      "accountId": "",
      "type": "CUSTOMER",
      "name": ""
    }
  ],
  "lineItems": [
    {
      "startDate": {
        "year": 2017,
        "month": 12,
        "day": 15
      },
      "endDate": {
        "year": 2028,
        "month": 12,
        "day": 14
      },
      "totalQuantity": 5,
      "sku": "WSMFREE"
    }
  ]
}

Example Response Body:

{
  "entitlementId": "aae64080-f686-4b5f-961b-80b9c7e807b5",
  "entitlementState": "COMMITTED",
  "startDate": {
    "year": 2017,
    "month": 12,
    "day": 14
  },
  "orderNumber": "1597677751",
  "source": "Sample_Test_source",
  "entitlementAsWhole": false,
  "lineItems": [
    {
      "lineItemId": "07ab924d-4fc6-4d8d-8135-a0bed7876921",
      "startDate": {
        "year": 2017,
        "month": 12,
        "day": 15
      },
      "endDate": {
        "year": 2028,
        "month": 12,
        "day": 14
      },
      "totalQuantity": 5,
      "availableQuantity": 5,
      "product": {
        "productId": "602",
        "sku": "WSMFREE",
        "name": "WSMFREE",
        "desc": "Worksmanager Free subscription",
        "features": [
          {
            "featureId": "308",
            "name": "FEA-WRKSMNGR",
            "version": "1.0",
            "externalId": "FEA-WRKSMNGR",
            "enforcement": {
              "enforcementName": "DEMO License Generator",
              "enforcementVersion": "1.0",
              "isEntitlementAsWhole": false
            },
            "licenseModel": {
              "licenseModelId": "2",
              "licenseModelName": "Days based"
            },
            "isExternal": false
          }
        ],
        "isSAAS": false,
        "allowMultipleAssignment": true
      },
      "lineItemActivationAttributes": {
        "attributeGroups": [
          {
            "name": "LOCKING",
            "attributes": [
              {
                "name": "Locking Code",
                "value": "0",
                "readOnly": false
              }
            ]
          }
        ]
      },
      "lifeCycle": {
        "status": "NONE",
        "action": "NONE"
      },
      "fixedQuantity": 1,
      "lineItemState": "COMPLETE",
      "activationMethod": "FIXED"
    }
  ],
  "accounts": [
    {
      "accountId": "sampleId1597677750507",
      "type": "CUSTOMER",
      "name": "SampleName1597677750507",
      "isPrimary": true
    }
  ]
}

Notes:

• The startDate and endDate are provided in the request body to define the validity of the entitlement.
• SKU specifies the product that is being entitled to the customer.
• The lineItems include details such as quantity, product description, and activation attributes.
• The accounts field associates the entitlement with a customer account, where accountId is the unique identifier for the account.

Error Handling:

In case of failure or errors, check the response status and ensure that all required fields are included in the request. For more information on common errors, refer to the Common Errors section.