{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":510,"path":"api-reference/rest-apis/entitlement-api.md","title":"Entitlement API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Entitlement API\n\nThe Entitlement API provides endpoints to create and retrieve entitlement records from an instance.\n\nEntitlement checks occur as part of post-sales support services for customers that purchase a product, such as an appliance or computer. Entitlement checks are made by agents to determine what services customers are eligible to receive for the products they've purchased. Use the Entitlement API to define and retrieve entitlements.\n\nThis API accesses and stores data in the following tables:\n\n- Account \\[customer\\_account\\]\n- Consumer \\[csm\\_consumer\\]\n- Household \\[csm\\_household\\]\n- Install Base \\[sn\\_install\\_base\\_item\\]\n- Product Model \\[cmdb\\_model\\]\n- Product Offering \\[sn\\_prd\\_pm\\_product\\_offering\\]\n- Sold Product \\[sn\\_install\\_base\\_sold\\_product\\]\n\nTo access this API, the following plugins must be activated on the associated instance:\n\n- Customer Contracts and Entitlements \\(com.sn\\_pss\\_core\\) \n- Customer Service Install Base Management \\(com.snc.install\\_base\\)\n- Product Catalog Management Core \\(com.sn\\_prd\\_pm\\)\n\nIn addition, to successfully call this API you must have the sn\\_pss\\_core.pss\\_integrator role. This API runs in the `sn_pss_core` namespace.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Entitlement - GET /sn\\_pss\\_core/entitlement/\\{id\\}\n\nReturns the specified entitlement record, its associated coverage, and its latest usage details.\n\nThe following is the list of tables in which the entitlement data is stored:\n\n- Characteristics \\[sn\\_pss\\_core\\_entitlement\\_characteristic\\]\n- Entitlement \\[service\\_entitlement\\]\n- Entitlement Usage \\[sn\\_pss\\_core\\_entitlement\\_usage\\]\n- Sold Product Covered \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\] - This table contains information for both sold products covered and install base items covered.\n\n### URL format\n\nVersioned URL: `/api/sn_pss_core/{api_version}/entitlement/{id}`\n\nDefault URL: `/api/sn_pss_core/entitlement/{id}`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\n\nOptional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String\n\n
\n\nid\n\n\n\nSys\\_id of the entitlement record to retrieve.Data type: String\n\nTable: Entitlement \\[service\\_entitlement\\]\n\n
\n
\n\nName\n\n\n\nDescription\n\n
\n\ndisplay\\_value\n\n\n\nType of data to return.Valid values:\n\n- false: Return the `value` for all fields. For example, `\"state\":\"draft\"`.\n- true: Return the `display_value` for all fields. For example, `\"state\":\"Draft\"`\n- all: Return all information for all fields.\n\nData type: String\n\nDefault: false\n\n
|Name|Description|\n|----|-----------|\n|None| |\n\n### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nAccept\n\n\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|403|Forbidden. The user doesn't have access rights to the specified record.|\n|404|Not found. The requested item wasn't found.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\naccount\n\n\n\nSys\\_id of the account record to which the entitlement belongs.\n\nData type: String\n\nTable: Account \\[customer\\_account\\]\n\n
\n\nconsumer\n\n\n\nSys\\_id of the consumer record to which the entitlement belongs.\n\nData type: String\n\nTable: Consumer \\[csm\\_consumer\\]\n\n
\n\ncontract\n\n\n\nSys\\_id of the contract record to which the entitlement belongs.Data type: String\n\nTable: Service Contract \\[sn\\_pss\\_core\\_service\\_contract\\]\n\n
\n\nend\\_date\n\n\n\nEnd date of the entitlement.Data type: String\n\nFormat: yyyy-mm-dd\n\nDefault: Never ends until manually removed.\n\n
\n\nentitlement\\_characteristics\n\n\n\nList of characteristics associated with the entitlement.Data type: Array of Objects\n\n```\n\"entitlement_characteristics\" [\n {\n \"characteristic\": \"String\",\n \"characteristic_option\": \"String\",\n \"entitlement\": \"String\",\n \"entitlement_usage\": [Array],\n \"service_contract_line\": \"String\",\n \"sys_created_by\": \"String\",\n \"sys_created_on\": \"String\",\n \"sys_id\": \"String\",\n \"sys_updated_by\": \"String\",\n \"sys_updated_on\": \"String\",\n \"type\": \"String\",\n \"value\": \"String\"\n }\n]\n```\n\nStored in: Characteristic \\[sn\\_pss\\_core\\_entitlement\\_characteristic\\]\n\n
\n\nentitlement\\_characteristics.​characteristic\n\n\n\nSys\\_id of the characteristic record associated with the entitlement.\n\nData type: String\n\nTable: Characteristic \\[sn\\_prd\\_pm\\_characteristic\\]\n\n
\n\nentitlement\\_characteristics.​characteristic\\_option\n\n\n\nSys\\_id of the characteristic option record associated with the entitlement.Data type: String\n\nTable: Characteristic Option \\[sn\\_prd\\_pm\\_characteristic\\_option\\]\n\n
\n\nentitlement\\_characteristics.​entitlement\n\n\n\nSys\\_id of the associated entitlement record.Data type: String\n\nTable: Entitlement \\[service\\_entitlement\\]\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage\n\n\n\nList of entitlement usages associated with the entitlement characteristic.Data type: Array of Objects\n\n```\n\"entitlement_usage\": [\n {\n \"entitlement\": \"String\",\n \"entitlement_characteristic\": \"String\",\n \"period_end\": \"String\",\n \"period_start\": \"String\",\n \"service_contract_line\": \"String\",\n \"sys_created_by\": \"String\",\n \"sys_created_on\": \"String\",\n \"sys_id\": \"String\",\n \"sys_updated_by\": \"String\",\n \"sys_updated_on\": \"String\",\n \"total_units\": \"String\",\n \"used_units\": \"String\"\n }\n]\n```\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​entitlement\n\n\n\nSys\\_id of the entitlement record associated with the entitlement usage.Data type: String\n\nTable: Entitlement \\[service\\_entitlement\\]\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​entitlement\\_characteristic\n\n\n\nSys\\_id of the entitlement characteristic record associated with the entitlement usage.Data type: String\n\nTable: Characteristic \\[sn\\_pss\\_core\\_entitlement\\_characteristic\\]\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​period\\_end\n\n\n\nEnd date when the entitlement usage is no longer tracked.Data type: String\n\nFormat: yyyy-mm-dd\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​period\\_start\n\n\n\nStarting date of when the entitlement usage is tracked.Data type: String\n\nFormat: yyyy-mm-dd\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​service\\_contract\\_line\n\n\n\nSys\\_id of the service contract line to which the current entitlement usage belongs. Data type: String\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​sys\\_created\\_by\n\n\n\nName of the user that created the entitlement usage record.Data type: String\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​sys\\_created\\_on\n\n\n\nDate and time that the entitlement usage record was created.Data type: String\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​sys\\_id\n\n\n\nSys\\_id of the entitlement usage record.Data type: String\n\nTable: Entitlement Usage \\[sn\\_pss\\_core\\_entitlement\\_usage\\]\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​sys\\_updated\\_by\n\n\n\nName of the user that last updated the entitlement usage record.Data type: String\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​sys\\_updated\\_on\n\n\n\nDate and time that the entitlement usage record was last updated.Data type: String\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​total\\_units\n\n\n\nTotal coverage value of the associated entitlement characteristic.Data type: String\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​used\\_units\n\n\n\nNumber of units used by the account or consumer between the **period\\_start** and the **period\\_end**.Data type: String\n\n
\n\nentitlement\\_characteristics.​type\n\n\n\nType of entitlement characteristic. Valid values:\n\n- coverage\n- coverage\\_and\\_usage\n\nData type: String\n\n
\n\nentitlement\\_characteristics.​value\n\n\n\nValue of the characteristic.\n\nData type: String\n\n
\n\nentitlement\\_name\n\n\n\nName of the entitlement.\n\nData type: String\n\n
\n\nhousehold\n\n\n\nSys\\_id of the household record associated with the entitlement.\n\nData type: String\n\nTable: Household \\[csm\\_household\\]\n\n
\n\ninstall\\_base\\_items\\_covered\n\n\n\nList of install base items covered under the  entitlement.Data type: Array of Objects\n\n```\n \"install_base_items_covered\": [ \n {\n \"added\": \"String\",\n \"contract\": \"String\",\n \"entitlement\": \"String\",\n \"install_base\": \"String\",\n \"removed\": \"String\",\n \"service_contract_line\": \"String\",\n \"sys_created_by\": \"String\",\n \"sys_created_on\": \"String\",\n \"sys_id\": \"String\",\n \"sys_updated_by\": \"String\",\n \"sys_updated_on\": \"String\"\n }\n]\n```\n\nTable: Sold Product Covered  \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\]\n\n
\n\ninstall\\_base\\_items\\_covered.​added\n\n\n\nDate that the associated install base item was added to the entitlement.Data type: String\n\n
\n\ninstall\\_base\\_items\\_covered.​contract\n\n\n\nSys\\_id of the service contract record associated with the install base item.Data type: String\n\nTable: Service Contract \\[sn\\_pss\\_core\\_service\\_contract\\]\n\n
\n\ninstall\\_base\\_items\\_covered.​install\\_base\n\n\n\nSys\\_id of the install base item covered by the service contract line.Data type: String\n\nTable: Install Base Item \\[sn\\_install\\_base\\_item\\]\n\n
\n\ninstall\\_base\\_items\\_covered.​removed\n\n\n\nDate that the associated install base item was removed from the entitlement.Data type: String\n\n
\n\ninstall\\_base\\_items\\_covered.​entitlement\n\n\n\nSys\\_id of the entitlement record associated with the install base item.Data type: String\n\nTable: Entitlement \\[service\\_entitlement\\]\n\n
\n\ninstall\\_base\\_items\\_covered.​service\\_contract\\_line\n\n\n\nSys\\_id of the associated service contract line record.Data type: String\n\nTable: Service Contract Line \\[sn\\_pss\\_core\\_service\\_contract\\_line\\]\n\n
\n\ninstall\\_base\\_items\\_covered.​sys\\_created\\_by\n\n\n\nName of the user that created the install base item record.Data type: String\n\n
\n\ninstall\\_base\\_items\\_covered.​sys\\_created\\_on\n\n\n\nDate and time that the install base item record was created.Data type: String\n\n
\n\ninstall\\_base\\_items\\_covered.​sys\\_id\n\n\n\nSys\\_id of the install base item covered.Data type: String\n\nTable: Sold Product Covered \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\]\n\n
\n\ninstall\\_base\\_items\\_covered.​sys\\_updated\\_by\n\n\n\nName of the user that last updated the install base item record.Data type: String\n\n
\n\ninstall\\_base\\_items\\_covered.​sys\\_updated\\_on\n\n\n\nDate and time that the install base item record was last updated.Data type: String\n\n
\n\nproduct\n\n\n\nSys\\_id of the product model record associated with the entitlement.Data type: String\n\nTable: Product Model \\[cmdb\\_model\\]\n\n
\n\nproduct\\_offering\n\n\n\nSys\\_id of the product offering record associated with the entitlement.Data type: String\n\nTable: Product Offering \\[sn\\_prd\\_pm\\_product\\_offering\\]\n\n
\n\nsold\\_entitlement\n\n\n\nSys\\_id of the sold product record associated with the entitlement.Data type: String\n\nTable: Sold Product \\[sn\\_install\\_base\\_sold\\_product\\]\n\n
\n\nsold\\_products\\_covered\n\n\n\nList of products covered.Data type: Array of Objects\n\n```\n\"sold_products_covered\": [ \n {\n \"added\": \"String\",\n \"contract\": \"String\",\n \"entitlement\": \"String\",\n \"removed\": \"String\",\n \"service_contract_line\": \"String\",\n \"sold_product\": \"String\",\n \"sys_created_by\": \"String\",\n \"sys_created_on\": \"String\",\n \"sys_id\": \"String\",\n \"sys_updated_by\": \"String\",\n \"sys_updated_on\": \"String\"\n }\n]\n```\n\nTable: Sold Product Covered \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\]\n\n
\n\nsold\\_products\\_covered.​added\n\n\n\nDate that the associated sold product was added to the entitlement.Data type: String\n\nFormat: yyyy-mm-dd\n\nDefault: Current date\n\n
\n\nsold\\_products\\_covered.​contract\n\n\n\nSys\\_id of the service contract record associated with the sold product covered.Data type: String\n\nTable: Service Contract \\[sn\\_pss\\_core\\_service\\_contract\\]\n\n
\n\nsold\\_products\\_covered.​entitlement\n\n\n\nSys\\_id of the entitlement record associated with the sold product covered.Data type: String\n\nTable: Entitlement \\[service\\_entitlement\\]\n\n
\n\nsold\\_products\\_covered.removed\n\n\n\nDate that the associated sold product was removed from the entitlement.Data type: String\n\nFormat: yyyy-mm-dd\n\nDefault: No end date\n\n
\n\nsold\\_products\\_covered.​service\\_contract\\_line\n\n\n\nSys\\_id of the service contract line record associated with the sold product covered.Data type: String\n\nTable: Service Contract Line \\[sn\\_pss\\_core\\_service\\_contract\\_line\\]\n\n
\n\nsold\\_products\\_covered.​sold\\_product\n\n\n\nSys\\_id of the product covered by the entitlement.Data type: String\n\nTable: Sold Product \\[sn\\_install\\_base\\_sold\\_product\\]\n\n
\n\nsold\\_products\\_covered.​sys\\_created\\_by\n\n\n\nName of the user that created the sold product covered record.Data type: String\n\n
\n\nsold\\_products\\_covered.​sys\\_created\\_on\n\n\n\nDate and time that the sold product covered record was created.Data type: String\n\n
\n\nsold\\_products\\_covered.​sys\\_id\n\n\n\nSys\\_id of the product covered by this service contract.Data type: String\n\nTable: Sold Product Covered \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\]\n\n
\n\nsold\\_products\\_covered.​sys\\_updated\\_by\n\n\n\nName of the user that last updated the sold product covered record.Data type: String\n\n
\n\nsold\\_products\\_covered.​sys\\_updated\\_on\n\n\n\nDate and time that the sold product covered record was last updated.Data type: String\n\n
\n\nstart\\_date\n\n\n\nStart date of the entitlement.\n\nData type: String\n\nFormat: yyyy-mm-dd\n\n
\n\nstate\n\n\n\nCurrent state of the entitlement.\n\nValid values: \\(case-sensitive\\)\n\n- active\n- cancelled\n- draft\n- expired\n- suspended\n\nData type: String\n\n
\n\nsys\\_created\\_by\n\n\n\nName of the user that created the entitlement record.Data type: String\n\n
\n\nsys\\_created\\_on\n\n\n\nDate and time that the entitlement record was created.Data type: String\n\n
\n\nsys\\_id\n\n\n\nSys\\_id of the associated entitlement record.Data type: String\n\nTable: Entitlement \\[service\\_entitlement\\]\n\n
\n\nsys\\_updated\\_by\n\n\n\nName of the user that last updated the entitlement record.Data type: String\n\n
\n\nsys\\_updated\\_on\n\n\n\nDate and time that the entitlement record was created.Data type: String\n\n
### cURL request\n\nThe following example shows how to call this endpoint to retrieve an entitlement template.\n\n```\ncurl \"https://instance.servicenow.com/api/sn_pss_core/entitlement/fc73d2de89226110f877430a4e008\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user \"username\":\"password\"\n```\n\nResponse:\n\n```\n{\n \"result\": {\n \"sys_id\": \"5a651515d1f53110f8776589fa411f7b\",\n \"sys_created_by\": \"admin\",\n \"sys_updated_by\": \"admin\",\n \"sys_created_on\": \"2023-10-09 11:31:59\",\n \"sys_updated_on\": \"2023-10-09 11:31:59\",\n \"entitlement_name\": \"indep entl\",\n \"account\": \"4c325111d1f53110f8776589fa411f3d\",\n \"consumer\": null,\n \"household\": null,\n \"contract\": null,\n \"service_contract_line\": null,\n \"state\": \"active\",\n \"product_offering\": null,\n \"sold_entitlement\": null,\n \"product\": null,\n \"start_date\": \"2023-10-03\",\n \"end_date\": \"2024-12-03\",\n \"sold_products_covered\": [\n {\n \"sys_id\": \"d6651515d1f53110f8776589fa411f7c\",\n \"sys_created_by\": \"admin\",\n \"sys_updated_by\": \"admin\",\n \"sys_created_on\": \"2023-10-09 11:31:59\",\n \"sys_updated_on\": \"2023-10-09 11:31:59\",\n \"contract\": null,\n \"service_contract_line\": null,\n \"entitlement\": \"5a651515d1f53110f8776589fa411f7b\",\n \"sold_product\": \"0df21151d1f53110f8776589fa411f1b\",\n \"added\": \"\",\n \"removed\": \"\"\n }\n ],\n \"install_base_items_covered\": [\n {\n \"sys_id\": \"12651515d1f53110f8776589fa411f7d\",\n \"sys_created_by\": \"admin\",\n \"sys_updated_by\": \"admin\",\n \"sys_created_on\": \"2023-10-09 11:31:59\",\n \"sys_updated_on\": \"2023-10-09 11:31:59\",\n \"contract\": null,\n \"service_contract_line\": null,\n \"entitlement\": \"5a651515d1f53110f8776589fa411f7b\",\n \"install_base\": \"e2639951d1f53110f8776589fa411f2b\",\n \"added\": \"\",\n \"removed\": \"\"\n }\n ],\n \"entitlement_characteristics\": [\n {\n \"sys_id\": \"12651515d1f53110f8776589fa411f7e\",\n \"sys_created_by\": \"admin\",\n \"sys_updated_by\": \"admin\",\n \"sys_created_on\": \"2023-10-09 11:31:59\",\n \"sys_updated_on\": \"2023-10-09 11:31:59\",\n \"service_contract_line\": null,\n \"entitlement\": \"5a651515d1f53110f8776589fa411f7b\",\n \"characteristic_option\": \"495149b7539e61106bfcddeeff7b1262\",\n \"value\": \"5\",\n \"characteristic\": \"63418db7539e61106bfcddeeff7b1238\",\n \"type\": \"coverage_and_usage\",\n \"entitlement_usage\": [\n {\n \"sys_id\": \"de651515d1f53110f8776589fa411f7e\",\n \"sys_created_by\": \"admin\",\n \"sys_updated_by\": \"admin\",\n \"sys_created_on\": \"2023-10-09 11:31:59\",\n \"sys_updated_on\": \"2023-10-09 11:31:59\",\n \"entitlement\": \"5a651515d1f53110f8776589fa411f7b\",\n \"service_contract_line\": null,\n \"entitlement_characteristic\": \"12651515d1f53110f8776589fa411f7e\",\n \"period_start\": \"2023-10-03\",\n \"period_end\": \"2024-12-03\",\n \"total_units\": \"5\",\n \"used_units\": \"25\"\n }\n ]\n }\n ]\n }\n}\n```\n\n## Entitlement - POST /sn\\_pss\\_core/entitlement\n\nCreates an entitlement record and all its related detail records.\n\nThe following is the list of tables in which the entitlement data is stored:\n\n- Characteristic \\[sn\\_pss\\_core\\_entitlement\\_characteristic\\]\n- Entitlement \\[service\\_entitlement\\]\n- Entitlement Usage \\[sn\\_pss\\_core\\_entitlement\\_usage\\]\n- Sold Products Covered \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\] - This table contains information for both sold products covered and install base items covered.\n\n### URL format\n\nVersioned URL: `/api/sn_pss_core/{api_version}/entitlement`\n\nDefault URL: `/api/sn_pss_core/entitlement`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\n\nOptional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String\n\n
|Name|Description|\n|----|-----------|\n|None| |\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\naccount\n\n\n\nRequired if the **consumer** parameter is not passed.Sys\\_id of the account record to which the entitlement belongs.\n\nData type: String\n\nTable: Account \\[customer\\_account\\]\n\n
\n\nconsumer\n\n\n\nRequired if the **account** parameter is not passed. Sys\\_id of the consumer record to which the entitlement belongs.\n\nData type: String\n\nTable: Consumer \\[csm\\_consumer\\]\n\n
\n\nend\\_date\n\n\n\nEnd date of the entitlement.Data type: String\n\nFormat: yyyy-mm-dd\n\nDefault: Never ends until manually removed.\n\n
\n\nentitlement\\_characteristics\n\n\n\nList of characteristics associated with the entitlement.Data type: Array of Objects\n\n```\n\"entitlement_characteristics\": [\n {\n \"characteristic\": \"String\",\n \"characteristic_option\": \"String\",\n \"entitlement_usage\": {Object},\n \"type\": \"String\",\n \"value\": \"String\"\n }\n]\n```\n\nStored in: Characteristic \\[sn\\_pss\\_core\\_entitlement\\_characteristic\\]\n\n
\n\nentitlement\\_characteristics.​characteristic\n\n\n\nRequired. Sys\\_id of the characteristic record associated with the entitlement.\n\nData type: String\n\nTable: Characteristic \\[sn\\_prd\\_pm\\_characteristic\\]\n\n
\n\nentitlement\\_characteristics.​characteristic\\_option\n\n\n\nSys\\_id of the characteristic option record associated with the entitlement.Data type: String\n\nTable: Characteristic Option \\[sn\\_prd\\_pm\\_characteristic\\_option\\]\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage\n\n\n\nUsed unit value for the associated entitlement characteristic.Only pass this parameter if the entitlement\\_characteristics are under the entitlement.\n\nData type: Object\n\n```\n\"entitlement_usage\": {\n \"used_units\": \"String\"\n}\n```\n\nStored in: Entitlement Usage \\[sn\\_pss\\_core\\_entitlement\\_usage\\]\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​usage\\_units\n\n\n\nUsage of the associated entitlement characteristic.Data type: String\n\n
\n\nentitlement\\_characteristics.​type\n\n\n\nType of entitlement characteristic. Valid values:\n\n- coverage\n- coverage\\_and\\_usage\n\nData type: String\n\n
\n\nentitlement\\_characteristics.​value\n\n\n\nRequired if the **input\\_type** parameter contained in the record specified in the **entitlement\\_characteristics.characteristic** parameter, is not `choice`.Value of the characteristic.\n\nData type: String\n\n
\n\nentitlement\\_name\n\n\n\nRequired. Name of the entitlement.\n\nData type: String\n\n
\n\nhousehold\n\n\n\nOnly passed when the household plugins are active and the **consumer** parameter is passed. Sys\\_id of the household record associated with the entitlement.\n\nData type: String\n\nTable: Household \\[csm\\_household\\]\n\n
\n\ninstall\\_base\\_items\\_covered\n\n\n\nList of install base items covered under the entitlement. The information in this array is inserted in the Sold Product Covered  \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\] table.\n\nData type: Array of Objects\n\n ```\n\"install_base_items_covered\": [ \n {\n \"added\": \"String\",\n \"install_base\": \"String\",\n \"removed\": \"String\"\n }\n]\n```\n\n For more information on Install Base Items [Configure install base](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/customer-service-management/configure-install-base.md).\n\n
\n\ninstall\\_base\\_items\\_covered.added\n\n\n\nDate that the associated install base item was added to the entitlement.Data type: String\n\nFormat: yyyy-mm-dd\n\nDefault: Current date\n\n
\n\ninstall\\_base\\_items\\_covered.​install\\_base\n\n\n\nSys\\_id of the associated install base item record.Data type: String\n\nTable: Install Base Item \\[sn\\_install\\_base\\_item\\]\n\n
\n\ninstall\\_base\\_items\\_covered.​removed\n\n\n\nDate that the associated install base item was removed from the entitlement.Data type: String\n\nFormat: yyyy-mm-dd\n\nDefault: No end date\n\n
\n\nproduct\n\n\n\nSys\\_id of the product model record associated with the entitlement.Data type: String\n\nTable: Product Model \\[cmdb\\_model\\]\n\n
\n\nproduct\\_offering\n\n\n\nSys\\_id of the product offering record associated with the entitlement.Data type: String\n\nTable: Product Offering \\[sn\\_prd\\_pm\\_product\\_offering\\]\n\n
\n\nsold\\_entitlement\n\n\n\nSys\\_id of the sold product record associated with the entitlement.Data type: String\n\nTable: Sold Product \\[sn\\_install\\_base\\_sold\\_product\\]\n\n
\n\nsold\\_products\\_covered\n\n\n\nList of products covered under the entitlement.Data type: Array of Objects\n\n```\n\"sold_products_covered\": [ \n {\n \"added\": \"String\",\n \"removed\": \"String\",\n \"sold_product\": \"String\"\n }\n]\n```\n\nStored in: Sold Product Covered \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\]\n\n
\n\nsold\\_products\\_covered.added\n\n\n\nDate that the associated sold product was added to the entitlement.Data type: String\n\nFormat: yyyy-mm-dd\n\nDefault: Current date\n\n
\n\nsold\\_products\\_covered.removed\n\n\n\nDate that the associated sold product was removed from the entitlement.Data type: String\n\nFormat: yyyy-mm-dd\n\nDefault: No end date\n\n
\n\nsold\\_products\\_covered.sold\\_product\n\n\n\nSys\\_id of the product covered by the entitlement.Data type: String\n\nTable: Sold Product \\[sn\\_install\\_base\\_sold\\_product\\]\n\n
\n\nstart\\_date\n\n\n\nRequired. Start date of the entitlement.\n\nData type: String\n\nFormat: yyyy-mm-dd\n\n
\n\nstate\n\n\n\nRequired.Current state of the entitlement.\n\nValid values: \\(case-sensitive\\)\n\n- active\n- cancelled\n- draft\n- expired\n- suspended\n\nData type: String\n\n
### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nAccept\n\n\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
\n\nContent-Type\n\n\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|201|Successful. The request was successfully processed and the records were created.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|403|Forbidden. The user doesn't have permission to access the API.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON\\)\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nentitlement\\_characteristics\n\n\n\nList of the entitlement characteristic objects  created under the entitlement. Data type: Array of Objects\n\n```\n\"entitlement_characteristics\" [\n {\n \"entitlement_usage\": {Object},\n \"sys_id\": \"String\"\n }\n]\n```\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage\n\n\n\nEntitlement usage object inserted under the entitlement\\_characteristic.Data type: Object\n\n```\n\"entitlement_usage\": {\n \"sys_id\": \"String\"\n}\n```\n\n
\n\nentitlement\\_characteristics.​entitlement\\_usage.​sys\\_id\n\n\n\nSys\\_id of the entitlement usage record.Data type: String\n\nTable: Entitlement Usage \\[sn\\_pss\\_core\\_entitlement\\_usage\\]\n\n
\n\nentitlement\\_characteristics.​sys\\_id\n\n\n\nSys\\_id of a entitlement characteristics record associated with the entitlement.Data type: String\n\nTable: Characteristic \\[sn\\_pss\\_core\\_entitlement\\_characteristic\\]\n\n
\n\nentitlement\\_name\n\n\n\nName of the entitlement.\n\nData type: String\n\n
\n\ninstall\\_base\\_items\\_covered\n\n\n\nList of sys\\_ids of the install base items covered under the entitlement. Data type: Array of Objects\n\n```\n\"install_base_items_covered\": [ \n {\n \"sys_id\": \"String\"\n }\n]\n```\n\n
\n\ninstall\\_base\\_items\\_covered.​sys\\_id\n\n\n\nSys\\_id of a install base items covered by the entitlement.Data type: String\n\nTable: Sold Product Covered \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\]\n\n
\n\nsold\\_prodocts\\_covered\n\n\n\nList of sys\\_ids of the products covered under the entitlement. Data type: Array of Objects\n\n```\n\"sold_products_covered\": [ \n {\n \"sys_id\": \"String\"\n }\n]\n```\n\n
\n\nsold\\_products\\_covered.​sys\\_id\n\n\n\nSys\\_id of a product associated with the entitlement.Data type: String\n\nTable: Sold Product Covered \\[sn\\_install\\_base\\_m2m\\_contract\\_sold\\_product\\]\n\n
\n\nsys\\_id\n\n\n\nSys\\_id of the associated entitlement record.Data type: String\n\nTable: Entitlement \\[service\\_entitlement\\]\n\n
### cURL request\n\nThe following example shows how to create an entitlement template.\n\n```\ncurl \"https://instance.servicenow.com/api/sn_pss_core/entitlement\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--data\n{\n \"state\": \"active\",\n \"entitlement_name\": \"indep entl\",\n \"account\": \"4c325111d1f53110f8776589fa411f3d\",\n \"start_date\": \"2023-10-03\",\n \"end_date\": \"2024-12-03\",\n \"sold_products_covered\": [\n {\n \"sold_product\": \"0df21151d1f53110f8776589fa411f1b\"\n }\n ], \n \"install_base_items_covered\": [\n {\n \"install_base\": \"e2639951d1f53110f8776589fa411f2b\"\n }\n ],\n \"entitlement_characteristics\": [\n {\n \"characteristic\": \"63418db7539e61106bfcddeeff7b1238\",\n \"characteristic_option\": \"495149b7539e61106bfcddeeff7b1262\",\n \"value\": \"20\",\n \"type\": \"coverage_and_usage\",\n \"entitlement_usage\": {\n \"used_units\": \"25\"\n } \n }\n ]\n}\n```\n\nResponse:\n\n```\n{\n \"result\": {\n \"sys_id\": \"5a651515d1f53110f8776589fa411f7b\",\n \"entitlement_name\": \"indep entl\",\n \"sold_products_covered\": [\n {\n \"sys_id\": \"d6651515d1f53110f8776589fa411f7c\"\n }\n ],\n \"install_base_items_covered\": [\n {\n \"sys_id\": \"12651515d1f53110f8776589fa411f7d\"\n }\n ],\n \"entitlement_characteristics\": [\n {\n \"sys_id\": \"12651515d1f53110f8776589fa411f7e\",\n \"entitlement_usage\": {\n \"sys_id\": \"de651515d1f53110f8776589fa411f7e\"\n }\n }\n ]\n }\n}\n```\n\n"}}