Documentation
Documentation

Entitlements

Entitlements refer to services or products that your customers are entitled to.

What are entitlements?

Entitlements refer to services or products that your customers are entitled to. Entitlements are generally used to store customer balances. Customer balances can be created in various ways. Some are listed below:

  • Quantity-based entitlement (measured in units):
    • You sell 10 units of a service or product to a customer for $100. In this case, the customer is entitled to 10 units of said service or product.
    • You sell a subscription for $100 per month, and each month you offer the customer 50 free units to consume as a part of the subscription. If these free units are not consumed during the month, they are carried forward until the contract is active. In this case, the free units are tracked across billing cycles using entitlements.
  • Credit-based entitlement (measured in currency): you sell $1000 worth of credits to a customer for $900. In this case, your customer is entitled to spend $1000 on your platform.

🚧

Entitlements vs free units

Free units that expire at the end of product billing period need not be tracked across billing periods. Therefore, an entitlement is optional for such free units. For all other expiry conditions, an entitlement must be attached to the free units node.

Add an entitlement from the Entitlements module

  1. Navigate to Entitlements > Entitlements in the left side panel.
  2. On the Entitlements page, click on the CREATE NEW ENTITLEMENT button.
  1. On the Create New Entitlement page, fill the details:
    1. Entitlement information:
    2. Entitlement type
      1. Select one option: Quantity (units) or Credits (currency)
      2. Enter a unit name: this is the name of the unit that will be displayed in the invoice.

Add an entitlement to a product

An entitlement can be added to a new or an existing product in the form of a:

  • Free Units feature node
  • Credits feature node

Parameters of the free units node

Type

TypeDescription
AddAdd free units to your customer's account
ConsumeDeduct free units from your customer's account
Add and consumeAdd or deduct free units from your customer's account based on calculations during invoice generation

Quantity of free units

Enter the quantity or credits that you wish to offer your customers.

Expiry condition

ConditionDescription
CustomThe free units are tracked as entitlements across billing cycles based on a cadence value (a number) and unit (days, weeks, months or years)
NeverThe free units are tracked as entitlements even across contracts. For example, the free units are carried forward even when a new contract is signed with the customer.
End of contractThe free units are tracked as entitlements until they expire when the contract ends. Free units are not tracked when a new contract is signed
End of product billing periodThe free units expire at the end of product billing cycle and need no further tracking.

Granting condition

ConditionDescription
On invoice approval
On Invoice creation
On payments success

Free units name (entitlement)

An entitlement can be attached to the free-units node using the Free Units Name drop-down menu.

A new entitlement can be created and attached to the free-units node by typing a new name.

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:

  1. 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.
  1. 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, as shown below:
  1. Click on the + ADD ENTITLEMENT button.
  2. On the entitlements form, click on the Select Entitlement drop-down menu, and select the desired entitlement.
  3. Select a date.
  4. 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:
  1. Click on the kebab menu located at the end of the row containing the entitlement you wish to edit or dissociate.
  2. Click on Edit or Delete.

Delete an entitlement

  1. Navigate to Entitlements > 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.

Updated 5 months ago