> ## Documentation Index > Fetch the complete documentation index at: https://docs2.zenskar.com/llms.txt > Use this file to discover all available pages before exploring further. # Entitlements ## Explanation Entitlements represent your customer’s contractual right to use, access, or consume services within an agreed scope and time period. In Zenskar, entitlements act as **control primitives** that govern *what* a customer can use, *how much* they can consume, and *whether* a capability is available, independent of how revenue is billed or recognized. **Important:** Entitlements in Zenskar are **off-balance-sheet constructs**. They do not represent cash, financial liabilities, or actual revenue by themselves. The system tracks usage rights, not monetary claims. Issuing cash refunds for entitlements can create **discrepancies in accounting**, because Zenskar does not automatically reconcile entitlements with financial transactions. ### Entitlement taxonomy Zenskar supports multiple entitlement types to reflect different commercial and technical needs. Each entitlement type encodes a distinct kind of right and participates differently in usage evaluation and billing. | Entitlement type | What it represents | How it is measured | Does it get consumed? | Typical use cases | | ------------------------------ | ------------------------------------------------------------ | ---------------------------------- | --------------------- | ---------------------------------------------------- | | **Quantity-based entitlement** | Right to consume a measurable amount of a service or product | Units (e.g., API calls, seats, GB) | Yes | Metered usage, quotas, included usage | | **Credit-based entitlement** | Right to consume value expressed in a non-cash unit | Custom currency or credits | Yes | Prepaid credits, platform spend limits | | **Feature entitlement** | Right to access or enable a capability | Enabled / disabled | No | Feature gating, plan differentiation, service access | Each entitlement type serves a distinct purpose: * **Quantity-based entitlements** control *how much* of something can be consumed. For example, 1,000 API calls per month, 50 user seats, 500 GB storage, 100 messages per billing period. * **Credit-based entitlements** control *how much value* can be consumed, without representing real currency. For example, \$1,000 of platform credits, 500 AI tokens, prepaid service credits. * **Feature entitlements** control *whether* a capability or service is available at all. For example, SSO access, audit logs, premium API enablement, beta feature activation. #### Warnings and best practices 1. **Off-balance-sheet:** Entitlements are not financial instruments. They do not automatically appear in accounting books as assets or liabilities. Treat them as usage rights only. 2. **Cash refunds:** Users must avoid issuing cash refunds for entitlements. Doing so can create a mismatch between the financial ledger and entitlement balances, potentially resulting in accounting errors. 3. **Time validity:** Free units and other entitlements inherit their validity from the pricing model or contract phase. They do not carry independent time semantics. *** ## How-to guides ### Add an entitlement from the Entitlements module 1. Navigate to **Entitlements** in the left side panel. 2. On the **Entitlements** page, click on the **CREATE NEW ENTITLEMENT** button. 3. On the **Create New Entitlement** page, fill in the mandatory fields. *** ### Add an entitlement to a new product 1. Navigate to **Contracts > Products** in the left side panel. 2. Click on the **+ CREATE NEW PRODUCT**. 3. On the **Add New Product** page, add a **Free Units** node. 4. Click on the **Free Units Name** drop-down menu to select an entitlement. Alternatively, you may create a new entitlement by typing a new name, as shown below: 5. Optionally, you may click on the **Click here to charge overages** link to automatically add another free units node that consumes free units to compensate for overages. 6. Click on the **ADD PRODUCT** button. ### Add an entitlement to an existing product 1. Navigate to **Contracts > Products** in the left side panel. 2. On the **Products** page, click on the row containing the product you wish to edit. 3. On the **Edit Product** page, add a **Free Units** node. 4. Click on the **UPDATE** button. *** ## Assign an entitlement to a customer 1. Click on **Customers** in the left side panel. 2. On the **Customers** page, click on the row containing the customer name to whom you wish to assign an entitlement. 3. On the page showing customer details, click on the Entitlements tab. 4. Click on the **+ ADD ENTITLEMENT** button. 5. On the entitlements form, click on the **Select Entitlement** drop-down menu, and select the desired entitlement. 6. Select an expiry date. 7. Click on the **SAVE** button. *** ## Edit or dissociate entitlement assigned to a customer 1. Click on **Customers** in the left side panel. 2. On the **Customers** page, click on the row containing the customer name to whom you wish to assign an entitlement. 3. On the page showing customer details, click on the Entitlements tab, as shown below: 4. Click on the kebab menu located at the end of the row containing the entitlement you wish to edit or dissociate. 5. Click on **Edit** or **Delete**. *** ## Delete an entitlement 1. Navigate to **Entitlements** in the left side panel. 2. On the **Entitlements** page, click on the kebab menu located at the end of the row containing the entitlement you wish to delete. 3. Click on the **Delete** menu option. *** ## Reference ### Entitlement creation UI | Field | Description | Options / Notes | | --------------------------- | ------------------------------------------------ | -------------------------------------------------- | | **Entitlement Name**\* | Name of the entitlement | Required; displayed in UI and reports | | **Entitlement Description** | Short description of the entitlement | Optional; for internal clarity | | **Entitlement Type**\* | Type of entitlement | `Quantity (Units)` or `Credits (Currency)` | | **Unit Name** | Name of the unit for quantity-based entitlements | Displayed on invoices; required if type = Quantity | | **Select Product**\* | Product associated with this entitlement | Required; links entitlement to a product |