Entitlements

​

1. Concepts: What an entitlement is and how it connects to products and customers

An entitlement is a customer’s right to use, access, or consume something, tracked independently of how that usage is billed or recognized as revenue. An entitlement is not an invoice line item or a revenue schedule. It is a separate ledger of what a customer is allowed to draw on, for example a pool of API calls, a number of seats, or a balance of platform credits.

​

Entitlement types

Zenskar recognizes three kinds of entitlement, but only two of them can currently be created from the Entitlements page: For Quantity and Credits, using the entitlement always means subtracting from a balance that was granted to a customer. There is no partial state beyond the running balance itself.

​

How an entitlement relates to a product

The main way an entitlement gets attached to a product is the Free Units feature you add to a product’s pricing. A Free Units node can Add units to a customer’s balance, Consume units from it, or both, and it runs on a schedule you define, for example granting units when an invoice is approved and expiring them at the end of the billing period. When you open the Free Units Name picker on a Free Units node, you can either select an existing entitlement or type a brand-new name. Typing a new name creates a new Quantity entitlement inline, without needing to visit the Entitlements page first. For certain simple (“standalone”) products, Zenskar automatically creates a matching entitlement behind the scenes when you create the product. Do not be surprised if you see entitlements on the Entitlements page that you did not explicitly create yourself. These are a byproduct of product creation, not something to clean up.

​

How an entitlement relates to a customer

Attaching an entitlement to a product only sets up the mechanism. To actually give a specific customer a balance to draw on, you grant the entitlement to that customer directly, with:

• A quantity, the size of the balance being granted.
• An active-from point, either immediately or a specific future date.
• An expiry, either forever or a specific date.

This grant creates a balance for that customer that is drawn down over time as it is consumed, whether through a product’s Free Units node, usage-based consumption, or a manual adjustment. Each grant keeps a consumption log showing every deduction: the date, the quantity consumed, and the running balance left after it.

​

Entitlements track usage rights, not cash

---

​

2. Walkthrough: Grant a customer 1,000 free API calls per billing period

This walkthrough creates a Quantity entitlement, wires it into a product with a recurring Free Units grant, assigns it to a customer with an expiry date, and then checks that customer’s balance and consumption log.

1. Go to More > Entitlements and click Create New Entitlement.
   • Entitlement Name: API Calls.
   • Entitlement Type: Quantity.
   • Unit Name: API call. This shows up on invoices wherever this entitlement’s usage is reflected.
   • Click Save.
2. Go to Contracts > Products and open the product you want to attach this to (or create a new one).
3. Add a Free Units node to the product’s pricing:
   • Feature: a label of your choice, for example Included API calls.
   • Type: Add.
   • Free Units Name: select the API Calls entitlement you just created.
   • Free Units quantity: 1000.
   • Grant at: On Invoice Approval.
   • Expires: End of Product Billing Period, so the free units reset each period instead of accumulating indefinitely.
4. Save the product.
5. Go to Customers, open the customer you want to grant this to, and switch to the Entitlements tab.
6. Click + Add Entitlement:
   • Select Entitlement: API Calls.
   • Quantity: the balance to grant directly to this customer, for example 1000 if you are granting a one-off balance on top of what the product provides.
   • Active from: Immediately.
   • Expiry: pick a specific date, for example one year out.
   • Click Save.
7. Still on the customer’s Entitlements tab, open this grant to view its consumption log. As invoices are approved and usage is recorded against API Calls, each deduction appears here with its date, quantity consumed, and the balance remaining afterward.

---

​

3. How-to guides

​

Create an entitlement

1. Go to More > Entitlements.
2. Click Create New Entitlement.
3. Fill in Entitlement Name, optionally Entitlement Description, and pick an Entitlement Type (Quantity or Credits).
4. Once a type is picked, fill in the Unit Name (for Quantity) or Credit Name (for Credits). This name appears on invoices.
5. Click Save.

​

Edit an entitlement

1. Go to More > Entitlements.
2. Open the kebab menu on the row for the entitlement you want to change and click Edit.
3. Update the name, description, or unit/credit name.
4. Click Save.

​

Delete an entitlement

1. Go to More > Entitlements.
2. Open the kebab menu on the row for the entitlement you want to remove and click Delete.

​

Add Free Units to a new product

1. Go to Contracts > Products and click + Create New Product.
2. Add a Free Units node to the product’s pricing.
3. Open the Free Units Name dropdown and either select an existing entitlement, or type a new name to create a new Quantity entitlement inline.
4. Set the Type (Add, Add and Consume, or Consume), the Free Units quantity, and the Expires, Grant at, and Consume at schedule fields.
5. Optionally, click Click here to charge overages to automatically add a second Free Units node that consumes free units to offset overage usage.
6. Click Add Product.

​

Add Free Units to an existing product

1. Go to Contracts > Products and click the row for the product you want to edit.
2. Add a Free Units node the same way as for a new product.
3. Click Update.

​

Assign (grant) an entitlement to a customer

1. Go to Customers and open the customer you want to grant this to.
2. Switch to the Entitlements tab.
3. Click + Add Entitlement.
4. Select the entitlement, set the Quantity to grant, choose whether it is active from immediately or a specific date, and choose whether it expires forever or on a specific date.
5. Click Save.

​

Edit or remove an entitlement grant from a customer

1. Go to Customers, open the customer, and switch to the Entitlements tab.
2. Open the kebab menu at the end of the row for the grant you want to change.
3. Click Edit to change its quantity, active-from date, or expiry, or click Delete to remove the grant entirely.

​

View a customer’s entitlement consumption log

1. Go to Customers, open the customer, and switch to the Entitlements tab.
2. Open the grant you want to inspect. Its consumption log lists every deduction against the balance: date, quantity consumed, and the running balance after it.

​

View and filter the org-wide Balances tab

1. Go to More > Entitlements.
2. Switch to the Balances tab. This lists every customer’s balance across every entitlement in one table, not just the entitlement definitions themselves.
3. Filter the table by entitlement, customer, quantity, or added-on date to narrow it down.
4. Use the export action on the page to export entitlement data.

​

Troubleshooting

• Deleted an entitlement and something broke: entitlement deletion does not check whether the entitlement is in use. If a product’s Free Units node or a customer’s grant referenced it, that link is now broken. Recreate the entitlement, or rebuild the product and grant configuration, to restore it.
• Cannot find a way to create a Feature-type entitlement: this is expected. Feature exists as an underlying entitlement concept, for example it is used internally for boolean-type products, but the Entitlements page today only lets you create Quantity or Credits entitlements.
• A customer has an entitlement you never explicitly created: check whether it was auto-generated by a standalone product. Zenskar creates a matching entitlement automatically for certain simple products at creation time.
• Entitlements does not appear in the sidebar: this module is only available for organizations on the earlier contract experience. If your organization has the newer Contracts V3 experience turned on, Entitlements is not shown.

---

​

4. Reference

​

Location

More > Entitlements in the left sidebar. This is only available for organizations on the earlier contract experience; it does not appear for organizations on the newer Contracts V3 experience.

​

Entitlement creation fields

​

Entitlement grant fields (Customer > Entitlements tab)

​

Free Units product-feature fields

​

API reference

Entitlements, Free Units, and customer grants are configured through the app only. These are internal, UI-only flows and are not part of Zenskar’s public API reference.