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.

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