> ## Documentation Index
> Fetch the complete documentation index at: https://zenskar.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

| Entitlement type | What it represents                                                | Consumed?                               | Creatable from the Entitlements page?                                                                                                                                                             |
| ---------------- | ----------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Quantity**     | A numeric balance, for example API calls, seats, or GB of storage | Yes, deducted against a granted balance | Yes                                                                                                                                                                                               |
| **Credits**      | A non-cash value balance, for example platform credits            | Yes, deducted against a granted balance | Yes                                                                                                                                                                                               |
| **Feature**      | An on/off capability rather than something that is drawn down     | No                                      | No, not currently. Feature entitlements exist under the hood, for example Zenskar generates one automatically for a boolean-type product, but there is no UI flow today for creating one yourself |

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.

<Note>
  The Free Units mechanism is only available for organizations on the earlier contract experience. If your organization has the newer Contracts V3 experience turned on, Entitlements does not currently appear in the sidebar, and there is no equivalent way to attach free units to a newer-style product.
</Note>

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

<Warning>
  Entitlements are usage-rights bookkeeping, not a financial instrument. Zenskar does not automatically reconcile entitlement balances with payments or refunds, since nothing in the product links an entitlement to an invoice payment or a refund transaction. If you issue a cash refund to a customer, their entitlement balance is not adjusted for you. As a best practice, avoid treating entitlement balances as a stand-in for cash, and if a refund is meant to also claw back or restore an entitlement balance, adjust that balance yourself as a separate step.
</Warning>

***

## 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**.

<Warning>
  Deleting an entitlement shows no warning if it is still linked to a product's Free Units node or has active customer grants. Before deleting, confirm the entitlement is not referenced anywhere you still need it, since removing it can silently break the products and customer balances that depend on it.
</Warning>

### 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

| Field                   | Required | Notes                                                                                                             |
| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| Entitlement Name        | Yes      | Displayed throughout the UI and on the Balances tab                                                               |
| Entitlement Description | No       | Internal notes only                                                                                               |
| Entitlement Type        | Yes      | `Quantity` or `Credits`. `Feature` is not selectable here                                                         |
| Unit Name / Credit Name | Yes      | Shown once a type is picked. Labeled "Unit name" for `Quantity`, "Credit name" for `Credits`. Appears on invoices |

### Entitlement grant fields (Customer > Entitlements tab)

| Field              | Required | Notes                                            |
| ------------------ | -------- | ------------------------------------------------ |
| Select Entitlement | Yes      | Any existing `Quantity` or `Credits` entitlement |
| Quantity           | Yes      | The size of the balance granted to this customer |
| Active from        | Yes      | `Immediately` or a specific date                 |
| Expiry             | Yes      | `Forever` or a specific date                     |

### Free Units product-feature fields

| Field               | Notes                                                                                                                                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Feature             | A custom label for this Free Units node                                                                                                                 |
| Type                | `Add`, `Add and Consume`, or `Consume`                                                                                                                  |
| Free Units quantity | The number of units this node adds and/or consumes                                                                                                      |
| Expires             | `Custom`, `Never`, `End of Contract`, or `End of Product Billing Period`                                                                                |
| Grant at            | `On Invoice Approval`, `On Invoice Creation`, or `On Payment Success`                                                                                   |
| Consume at          | `On Invoice Approval`, `On Invoice Creation`, or `Daily`                                                                                                |
| Free Units Name     | The entitlement this node draws from. Selecting an existing name reuses that entitlement; typing a new name creates a new `Quantity` entitlement inline |

### 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.