You are here: Entitlement Management > Entitlement > addEntitlementItem

Add a Product to an Entitlement

This interface enables you to add a product to an entitlement. Only one product is added to an entitlement at a time.

Note the following points:

Default Protocol Method Type URI




Post Parameters

Parameter Description Valid Values Optional


Identifier of the entitlement.

Note: The entId is the handle returned by the createEntitlement.xml web service. You can use the searchEntitlements.xml web service to retrieve entId for an entitlement.




Specify the identifier of the product to be added.




Number of users who can use the product. Its value should be from 1 to 999999. This parameter is applicable for enterprise named entitlements.


For Draft Entitlements:

  • If the entitlement is of type Retail, then numberOfUsers has no effect.
  • If the entitlement is of type Enterprise, note the following points:
    • In the first line item added, if numberOfUsers field is left blank, the entitlement will be marked as unnamed.
    • If some value is assigned to numberOfUsers field, the entitlement will be marked as named and can have number of users as specified.
    • For subsequent line items, the numberOfUsers field has no effect. The number of users added for first line item is taken as default for subsequent line items.

For Reconfigured Entitlements:

  • The numberOfUsers field has no effect and it inherits the value from the original entitlement.

Integer (> 0 for named entitlements, -1 for unnamed entitlements)



Number of concurrent instances (in the case of concurrent license type). The value should be between 1 - 32752.

  • If the product to be added has concurrent license type, the concurrentlimit field (if set) will update the overridable concurrent limit license model attributes of all the features inside the line item.
  • This parameter has been deprecated. You should specify concurrent limit at feature level.
Integer (>0) Yes
refId1 Information that uniquely identifies the line item in a different ERP system. String Yes
refId2 A second unique reference ID, similar to Ref ID 1. String Yes

Sample Code

import org.apache.http.params.HttpParams;
public class EMSSample {
	private static DefaultHttpClient httpclient = new DefaultHttpClient();
	private static Principal principal = null;
public static String addEntitlementItem.xml()throws Exception {
        	return "login failed";
    	HttpContext context = new BasicHttpContext();
    	context.setAttribute(ClientContext.USER_TOKEN, principal);
    	HttpPost post =  new HttpPost("https://localhost:8443/ems/addEntitlementItem.xml");
    List<NameValuePair> nvps = new ArrayList<NameValuePair>();
    	nvps.add(new BasicNameValuePair("refId2", ""));
    	nvps.add(new BasicNameValuePair("entId", ""));
    	nvps.add(new BasicNameValuePair("refId1", ""));
    	nvps.add(new BasicNameValuePair("numberOfUsers", ""));
    	nvps.add(new BasicNameValuePair("concurrentLimit", ""));
    	nvps.add(new BasicNameValuePair("productId", ""));
    	post.setEntity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8));
    HttpResponse response = httpclient.execute(post, context);
    HttpEntity entity = response.getEntity();
    byte[] b = null;
    if (entity != null) {
        long l = entity.getContentLength();
         b = new byte[(int) l];
    	return new String(b);

Sample Response

<?xml version=”1.0” encoding=”UTF-8”?>
See Also:

Output Format for Failure

Error codes

Error Code Description
100 Invalid request parameter.
101 You are not authorized to use this service.
118 {field} should be of data type integer. [Note: This error code is applicable for the fields - featureId, License modelId, entId, ftrId, customerId, lmId, templateType, lineItemId, CustomerId, stationCount, status, and granularity.]
120 {field} value is less than the minimum permitted value {value}. [Note: This error code is applicable for the fields - productd, featureId,entId, billType, lmId, lastModified, timeZoneId, customerId, and granularity.]
122 {field} is a required field and should have a not null value. [Note: This error code is applicable for the fields - Eid, namespaceName, featureName, startDate, endDate, userIds, featureId, productName, productVersion, detailsLM, lmId, templateType, customAttribute, lineItemId, customerRefId, granularity, loginId, oldPassword, and newPassword.]
123 endDate should be of dataType Date in the format yyyy-mm-dd startDate should be of dataType Date in the format yyyy-mm-dd.
128 You should log on first.
132 The URL address does not exist.
301 Unable to find product for ID ‘Id’
325 This product is already part of Entitlement!
328 product is not in lifeycle stage complete
621 Entitlement does not exist. Retry with a correct ID.
647 Cannot update entitlement with lifeCycleState=complete.
1012 UserId can not be blank.
1070 Selected License Model for feature - <featurename>, is not supported for On-Premise deployment
1074 Only Per Login counting type is allowed in concurrent license model for On-Premise(Entitlement level) entitlement.
1075 Only days between 1 and 1825 are accepted.
1076 Invalid concurrent limit.Concurrent limit between 1 - 32752 is allowed.
1077 FeatureID out of range for feature <featurename>. FeatureID can range from 1-65471 for On-premise deployment.
1081 Invalid Web service version provided
1084 No Web service version provided
1088 The EMS system is running on HTTPS. Please provide the correct Web service URL.
1116 Only "Per Identity Per Station" counting type in Concurrent license type is allowed for the Feature Level caching mode of on-premise entitlements.Please change the license model associated with this feature.
1117 The "Per Identity Per Station" Counting type in Concurrent license model is not allowed for cloud entitlements.Please change the license model associated with this feature.