¶ Quota Billing
Pre-sell units and track customer balances using RevCent's quota billing. Great for businesses that sell "units", ie. use credits, virtual tokens, etc.
RevCent supports quota based products, where a customer purchases a certain amount of "units" and has a running balance via a quota account. Create a sale containing one or more quota based products and utilize the RevCent API to manage all aspects of quota based revenue. Subsequent purchases by an existing customer will automatically credit the running balance of the customers' account. Send requests to retrieve a customers' balance, credit or debit the balance as well as retrieve ledger entries for a quota account.
¶ Before You Proceed
Quota billing requires that you know which one of your customers and/or users are purchasing and consuming quota units along with their RevCent customer ID. You of course don't want to debit or credit units for the wrong customer. Therefore, you must have some form of an identification mechanism internally on your end to discern customers from one another with their associated customer ID in RevCent. Linking the customer ID in RevCent with your internal customer is essential in order to appropriately credit/debit the proper customer. Contact us if you need help or guidance for internal customer identification.
¶ Concepts
Quota Account: A quota account is created when one or more quota products is initially sold to a customer without an existing quota account. The quota account is specific to a customer and contains a running balance of quota units, each quota unit being the quota product sold with specific unit amounts. If a quota account already exists for a customer, then their quota account will receive appropriate unit credits upon subsequent purchases.
Quota Account Ledger Entry: A quota account ledger entry is created by RevCent when any action that affects the balance of a customers' quota account, via web or API, occurs. An entry will be created for either the purchase of a unit product, a quota account debit or a quota account credit. You are able to set metadata during an API request (sale create, account debit, account credit) which will attach to the ledger entry, allowing you to record and gather metrics for credits and debits.
Quota Unit Group: A quota unit group is the organization of quota units. A quota account for a customer is created based on the quota unit group that was initially purchased. This allows you to implement multiple brands without cross balance conflicts and better metrics tracking, i.e. The customer may have two quota accounts, but units are separated by unit group (brand).
Quota Unit: A quota unit is the actual unit the customer is purchasing, i.e. "Phone Minute" or "App Currency". When you create a quota based product you associate a quota unit and set a unit amount. When a quota based product is purchased, the unit amount specified in the product is credited to a customers' quota account. Multiple products can contain the same unit, allowing you to sell varying unit amounts at custom prices, i.e. 100 Minutes or 1000 Minutes. You can set a unit amount of 1 and allow units to be purchased based on product quantity as well.
¶ Quota Account
Created by RevCent on initial sale
A quota account is created when one or more quota products is initially sold to a customer without an existing quota account. The quota account is specific to a customer and contains a running balance of quota units, each quota unit being the quota product sold with specific unit amounts. If a quota account already exists for a customer, then their quota account will receive appropriate unit credits upon subsequent purchases.
¶ View Quota Accounts
View all quota accounts by clicking Revenue > Quota > Accounts in the sidebar or go to https://revcent.com/user/quota-accounts
¶ Quota Account Details
View quota accounts' details by searching for the quota account in the top navigation search box, or clicking on the quota account ID when viewing all quota accounts
The quota account details page will display all related entities of the quota account, i.e. products sold, shipping, tax, etc. A quota account keeps track of the current balance of all quota units a customer has purchased and consumed.
¶ Credit/Debit
Manually credit or debit a quota account unit balance by a specified unit amount. This can also be done programmatically using the RevCent API.
¶ Disable
If you wish to disable the quota account, not allowing any future modifications.
¶ Quota Account Ledger Entry
Created by RevCent when a quota account debit or credit occurs
A quota account ledger entry is created by RevCent when any action that affects the balance of a customers' quota account, via web or API, occurs. An entry will be created for either the purchase of a unit product, a quota account debit or a quota account credit. You are able to set metadata during an API request (sale create, account debit, account credit) which will attach to the ledger entry, allowing you to record and gather metrics for credits and debits.
¶ View Quota Account Ledger Entries
View all quota account ledger entries by clicking Revenue > Quota > Ledger Entries in the sidebar or go to https://revcent.com/user/quota-account-ledger-entries
¶ Quota Account Ledger Entry Details
View a quota account ledger entry details by searching for the quota account ledger entry in the top navigation search box, or clicking on the quota account ledger entry ID when viewing all quota account ledger entries.
¶ Quota Unit Group
Created by you
A quota unit group is the organization of quota units. A quota account for a customer is created based on the quota unit group that was initially purchased. This allows you to implement multiple brands without cross balance conflicts and better metrics tracking, i.e. The customer may have two quota accounts, but units are separated by unit group (brand).
¶ View Quota Unit Groups
View all quota unit groups by clicking Revenue > Quota > Unit Groups in the sidebar or go to https://revcent.com/user/quota-unit-groups
¶ Create Or Edit A Quota Unit Group
Create a new quota unit group by clicking the Create New Quota Unit Group button when viewing all quota unit groups, or go to https://revcent.com/user/new-quota-unit-group
Edit an existing quota unit group by clicking the edit button when viewing all quota unit groups.
¶ Name
Set a name for the quota unit group.
¶ Description
Set a description for the quota unit group.
¶ Status
Set the status for the quota unit group.
¶ Quota Unit
Created by you
A quota unit is the actual unit the customer is purchasing, i.e. "Phone Minute" or "App Currency". When you create a quota based product you associate a quota unit and set a unit amount. When a quota based product is purchased, the unit amount specified in the product is credited to a customers' quota account. Multiple products can contain the same unit, allowing you to sell varying unit amounts at custom prices, i.e. 100 Minutes or 1000 Minutes. You can set a unit amount of 1 and allow units to be purchased based on product quantity as well.
¶ View Quota Units
View all quota units by clicking Revenue > Quota > Units in the sidebar or go to https://revcent.com/user/quota-units
¶ Create Or Edit A Quota Unit
Create a new quota unit by clicking the Create New Quota Unit button when viewing all quota units, or go to https://revcent.com/user/new-quota-unit
Edit an existing quota unit by clicking the edit button when viewing all quota units.
Important: If creating a quota unit, you must first create a quota unit group. A quota unit must be assigned to a quota unit group.
¶ Name
Set a name for the quota unit.
¶ Description
Set a description for the quota unit.
¶ Status
Set the status for the quota unit.
¶ Quota Unit Group
Select a quota unit group. A quota unit group organizes and shares settings with other grouped units. Also, grouped units are placed within a customers' single quota account. Required.
¶ Save Quota Unit ID Internally
Important: You should save and match the created RevCent quota unit ID within your internal systems' respective product. The reason for saving the quota unit ID is so that you debit or credit the correct unit when your customer consumes said unit. For example, if a customer has Gold Tokens as well as Silver Tokens in their account and the customer uses a Gold Token you will want to deduct the Gold Token using the RevCent quota unit ID for Gold Token.
¶ Modifying Quota Account Balance
The entire purpose of quota billing is to keep track of a specific customers' quota account balance and instantly record when a balance is affected. When a customer consumes a specific quota unit, notify RevCent to modify the balance using the RevCent API or the web app. RevCent keeps a real-time running balance for each customer. With the API you have the option to attach metadata for granular metrics.
¶
Getting The Quota Account ID
It is important to link the quota account ID in RevCent with your internal customer. You can get the specific quota account ID and the customer ID in an initial sale response. The reason for retrieving the quota account ID is to be able to deduct the proper customers' quota account balance for the specific quota unit being consumed. How you plan to perform authorization and/or identification of what customer, and their quota account ID, is up to you.
Note: You can also retrieve an initial sale API response using a Firehose.
¶ Initial Sale API Response
Quota Account ID: The initial sale JSON response will contain a quota_accounts array, which contains one or more quota account objects depending on the number of quota unit groups within the quota units purchased. Each quota account object has an id property, this is the quota account ID you will need to modify a customers' quota account in future requests. In the example below, the quota account ID is 4rybZlBnGyCk85zlMmGj. To view a full non redacted example of an initial sale response, check out our API docs.
Advanced: Most RevCent users will only have one quota account object within the quota_accounts array in the sale response. However, if you sell multiple quota units using different quota unit groups in a single sale, utilize the quota_account_units array to parse quota units purchased and associated them with your stored quota accounts.
Customer ID: You will also find the customer_id property, which is the ID for the customer in RevCent. In the example below, the customer ID is VPwvq5lOkafJwqGVZB5v. Use the customer ID for future purchases to credit a customers' existing quota account appropriate unit(s).
{
...
"customer_id": "VPwvq5lOkafJwqGVZB5v",
"quota_accounts": [
{
"id": "4rybZlBnGyCk85zlMmGj",
"quota_unit_group": {
"id": "6rnQQzm2mkSmrAorQ6ym",
"name": "Currency Tokens"
},
"quota_account_units": [
{
"id": "6rnmX4jmGjcvW6AGKrwJ",
"name": "Silver Token",
"balance": 50
}
]
}
]
...
}
¶ Create a Ledger Entry via API
You can notify RevCent programmatically via API when a customer consumes a quota unit as frequently as you want. You identify the quota account (customer) and the specific quota unit via the quota_account_id and quota_unit_id properties. Read more on getting the account ID from an initial sale response. View more information on the API request.
In the example below we are assuming that the quota unit is a search credit, with 1 unit equaling 1 search. When a search is conducted, we send a debit request for the quota account and the specific quota unit. We specify the quota unit ID as a customer may have multiple quota units within their quota account, i.e. simple search unit, advanced search unit, etc.
{
"request": {
"type": "quota_account",
"method": "debit",
"quota_account_id": "0pP7L8X7Xoi0AG7k8Y5L",
"quota_unit_id": "d9JqY40GoYc7WvVA2dgz",
"unit_amount": 1,
"metadata": [
{
"name": "people_search_string",
"value": "john doe"
}]
}
}
¶ API Request Properties
¶ request
The main request object containing the details of the call.
¶ type
The API call type. quota_account
¶ method
The API call method. debit or credit
¶ quota_account_id
Important: This identifies the customers' quota account. RevCent needs to know the quota account ID in order to credit or debit the correct customer at the correct amount. When you supply the quota account ID RevCent knows who the customer is. The quota_account_id is supplied during the initial sale response. Read more on getting the account ID from an initial sale response.
¶ quota_unit_id
Important: This identifies the quota unit being debited or credited within the customers' quota account. RevCent needs to know the quota unit ID in order to credit or debit the correct quota unit at the correct amount. Retrieve the quota_unit_id in the web app when viewing quota units as well as during the initial sale response for the specific product purchased. Read more about saving a quota unit ID internally when creating one in RevCent.
¶ unit_amount
The usage amount relative to the debit or credit. This tells RevCent how much to either debit or credit depending on the api call method. In the example above we are recording that the customer consumed 1 unit via the debit method. This will deduct 1 unit from the customers' quota account for the specific quota unit via the quota_unit_id.
¶ metadata
The metadata property is an array of objects, each object being a name, value pair. This is useful for recording the specific details of the individual consumption as well as perform aggregate metrics in your RevCent dashboard. In the example above we attached the person search string as metadata, letting us match it with internal search records for a specific customer. You can attach multiple metadata objects for even more detailed information.
¶ Create a Ledger Entry via Web
You can also create a quota account ledger entry manually via the RevCent web app. View the specific quota account to modify and click the Credit/Debit button in the Tools column.
¶ Credit/Debit Modal
After clicking the Credit/Debit button a pop up will appear. Select the method, unit and enter an amount.
¶ Method
The usage method relative to the entry.
Options:
- Credit: Credit the quota account for a specified unit and amount.
- Debit: Debit the quota account for a specified unit and amount.
¶ Unit
Select the quota unit which you are either crediting or debiting within the quota account.
¶ Amount
The amount of units. This tells RevCent how many units to either debit or credit depending on the method and unit selected.
Once you have selected the Method, Unit and entered the Amount, click the Confirm button and wait for the page to reload.
¶ Business Model Examples
Below are some examples showing how quota billing works given different business models.
¶ Search Credits
This is an example of a single quota unit product, a Search Unit. You sell a 10 pack of search units as a single product. When a customer purchases the 10 pack, the units are credited to the customers' quota account. Each time a customer conducts a search it consumes 1 unit, which creates a ledger entry in RevCent and debits the quota account. Subsequent purchases by the customer will credit the specific customers' existing quota account.
¶ Search Credits (Multi Product)
This is an example of a single quota unit with multiple products. Each individual search conducted is equal to 1 quota unit within RevCent. You sell a 10 pack of search units, a 20 pack of search units and a single pack.
The single pack allows the customer to purchase the exact amount of search units they want based on the quantity they specify when purchasing the Single Pack. Depending on the product purchased, the amount of search units credited to the quota account depends on the unit amount within the product and the quantity of the product purchased.
This multi product approach gives you the flexibility to create different pricing for the same quota unit at varying unit amounts, i.e. 1 search is $1.49, 10 searches is $9.99 and 20 searches is $14.99.
¶ Virtual Currency (Multi Unit)
This is an example of multiple quota units within a single quota unit group. A Tokens quota unit group is created, and two different quota units, Silver and Gold, are created and attached to the Tokens quota unit group. When a customer purchases one or both tokens, the quota account keeps a running balance of each. The quota unit group is what determines the grouping of units within a single quota account. This allows you to keep a running balance of multiple tokens within a single account. When the customer consumes either token, the quota account is modified according to the quota unit consumed, thus modifying the available balance of the specific unit.
