Usage Data Billing
Usage data represent product consumptions (volume or traffic data, service coverage, etc.) that are to be invoiced. To this end, usage data include the following information:
- the date and time the consumption took place,
- the quantity for the consumption, like a number of worked hours, or a number of consumed units, etc.,
- an identifier, which is used to assign the usage data to a subscription item.
In broad strokes, usage data billing works as follows:
Itemizing and billing usage data
JustOn retrieves raw usage data (for example, via data import or a third-party integration) and usually saves it to custom objects. The continuous invoice run creates invoices and invoice line items out of these objects. It uses the transaction builder functionality to itemize the consumption data in the background, and then matches this data against the defined subscription items. Finally, it evaluates the provided quantity information and calculates the item's subtotal, producing the corresponding invoice line item.
Configuring usage data billing with JustOn
Usage data billing, continuous invoice run, transaction builder?
Usage data billing is the general name for JustOn's approach to generate invoices from custom object records that represent product consumptions (volume or traffic data, service coverage, etc.).
The continuous invoice run is the key player in this operation: it creates invoices and invoice line items from the object records that hold usage data. As the name suggests, it can run multiple times, repeatedly aggregating new usage data to existing invoice line items as long as an invoice is
The continuous invoice run, for its part, relies on the transaction builder. This mechanism itemizes the consumption data – converting it to actually billable items.
Now assume the following example:
You bill mobile phone services, and you distinguish three types of items: calls, text messages and internet data. These items are tracked separately by an external system, and are then imported. Finally, you want to distribute these items to three separate invoice line items on one invoice.
Modeling this business use case and setting up the transaction builder to itemize this usage data comprises the following major tasks:
- Configuring a custom object to hold both the usage data (quantity information) and the required controlling data
- Creating a subscription with three items (one for each service type)
- Creating a transaction filter
- Setting up the continuous invoice run
For the purpose of this documentation, we assume the minimum required steps to illustrate the setup for usage data billing, where the usage data involves the quantity information only and the subscription item defines the (common) price.
Your business use case may, in addition to the quantity information, require individual prices for the consumption data. For details, see Price and Quantity Fields.
For a complete overview of the available setup options, see Transactional Billing Options.
The section Additional Use Cases summarizes possible additional setup options for usage data billing, which may be helpful to cover your individual business use cases.
In addition, you must, of course, set up the usage data retrieval – either a data import or a third-party integration. Note, however, that this setup is not covered with this documentation, as it is too project-specific and cannot be generalized. For help with setting up the usage data retrieval, see Import Data Into Salesforce in the Salesforce Help or contact JustOn Support.
Configuring Custom Object
The transaction builder requires a number of ON fields (controlling fields and data fields) on the custom object.
- Navigate to the fields list of the custom object.
Create the following new fields.
API Name Data Type Controlling Field Description ON_Type Formula (Text)
Defines the type of the (usually transient) transaction:
Transactionfor the continuous invoice run – the usual option for billing usage data.
Detailwhen creating "tangible" transaction records.
ON_OrderNo Formula (Text)
Represents the key to match source data to a subscription item.
If you use a lookup relation or a formula to determine the order no, make sure that your logic produces the same order no value for both the source object and the item.
If you get individual records for different types of usage data, you need a formula that yields the intended target item.
If you get different usage data types in one record, you specify a comma-separated list of target items.
ON_Subscription Lookup (Subscription) Links to the related subscription after the object records have been successfully processed. ON_Invoice Lookup (Invoice) Links to the related invoice after the object records have been successfully billed.
If the produced invoice is canceled, the object records become subject to the invoice run again.
ON_LastError Text (255) Displays the error message if the transaction creation has failed. ON_Account Formula (Text) Specifies the Salesforce account ID or external ID, required if there is no or more than one account lookup on the object.
The formula uses the API name of the field that links the object to the account, for example,
ON_AddToTransactionTable Checkbox Required when using the continuous invoice run. Determines whether to show the itemized usage data records on the invoice, deselected by default. ON_AddToCsv Checkbox Required when using the continuous invoice run. Determines whether to export the itemized usage data records as CSV, deselected by default. ON_Date Formula (Date)/
Data field, displays the date on which the transaction is considered for invoicing.
The formula return type depends on the source field.
If you create
ON_Dateas a formula field with the return type
Datebut the referenced field is of the type
Date/Time, the operator
DATEVALUEmust precede the referenced field, like
ON_Quantity Formula (Number)
Data field, specifies the quantity or volume information as accumulated for the transaction.
For help about creating fields, see Managing Object Fields.
Depending on your use case and its requirements, you can add more fields to have them filled and copied to the generated invoices or invoice line items, for example, to provide individual prices with source records. For details, see Fields on Custom Objects.
Creating Subscription and Items
As the transactions are to be matched with subscription items for the invoice generation, you must prepare a "target" subscription and corresponding items.
Create the subscription as required.
For details, see Creating Subscriptions.
Add the items to the subscription as required.
Make sure that
- The billing type is set to
- Each item's value of the
OrderNofield matches one of the possible values of the custom object's
ON_OrderNofield (see Configuring Custom Object)
Your use cases may require configuring specific item data, for example, to retrieve individual prices from source records. For possible options, see Additional Use Cases.
For details, see Adding Items.
Following the example, you create a subscription and three items – "calls", "text messages" and "internet data".
- The billing type is set to
Your business may require invoicing a base price, irrespective of the actually incurred usage data costs. In this case, you must enable the minimum fee calculation.
Creating Transaction Filter
To define which objects and records to include when itemizing consumption data, you create a new custom filter.
Click to enter Setup, then open Custom Settings.
In Salesforce Lightning, navigate to Custom Code > Custom Settings.
In Salesforce Classic, navigate to Develop > Custom Settings.
Click Manage in the row of Filters.
Create the following filter.
Field Required Description Example Value Name Specifies the filter name, will be available as an option picklist value when triggering the operation Target Specifies the API name of the custom object that is to be converted to transactions
Use Case Specifies the filter use case:
Continuousfor the continuous invoice run – the usual option for billing usage data.
With large data sets, you can ask Salesforce to have the field
ON_Date__cindexed, and then use
Continuous Dailyfor the continuous invoice run. For details, see here.
Transactionfor creating "tangible" transaction records.
Condition Specifies a condition (SOQL WHERE clause) to restrict the set of included records.
For details, see SOQL SELECT Syntax in the Salesforce Help.
Note that objects on which
ON_Invoiceis already filled will be ignored.
Starting with JustOn 2.74, the SOQL expressions in filter conditions must not contain line breaks.
For help about creating filters, see Filters.
Create an individual transaction filter for each custom object whose records hold usage data to be billed.
Setting Up Continuous Invoice Run
The continuous invoice run creates invoices and invoice line items directly out of objects that hold usage data. It uses the transaction builder functionality to itemize the consumption data, but does not generate "tangible" transaction records. As the name suggests, it can run multiple times, repeatedly aggregating new usage data to existing invoice line items as long as the invoice is
Usage data billing requires the (continuous) invoice run using the transaction filter, triggered either manually or as a scheduled job. Manually generating an invoice from the target subscription (using the New Invoice button) does not invoke the transactional billing.
For the continuous invoice run to work:
Make sure that the following conditions are met:
The (custom) object that holds the usage data is set up for being processed with the transaction builder.
For details, see Configuring Custom Object.
There is a corresponding subscription and its items.
For details, see Creating Subscription and Items.
There is a corresponding transaction filter with the use case
For details, see Creating Transaction Filter.
Schedule a parameterized invoice run with the corresponding transaction filter (use case
Continuous Daily) added as a parameter.
For details, see Parameterized Invoice Run.
For further help with setting up usage data billing in general or the transaction builder in particular, contact JustOn Support.
Additional Use Cases
The following examples illustrate additional setup options for usage data billing, which may be helpful to cover your individual business use cases.
Aggregating individually priced source records
Think of usage data records that match with the same subscription item but that each define an individual price in the
ON_Price field. Now the continuous invoice run must aggregate these prices. To support this, you configure the following fields on the transactional item:
|Transaction Price Field||
|Aggregate Indiv. Priced Transactions (checkbox)||
Using custom price and quantity fields
Assume you want to use customized price and quantity information for usage data. If your custom usage data object holds this data in
Impressions__c, respectively, the corresponding item fields must specify the following values:
|Transaction Price Field||
|Transaction Quantity Field||
Passing custom usage information to invoice
This example assumes that you want to display a custom piece of information ("SKU") retrieved from your usage data in the invoice line item table.
To this end, you
- create the field
ON_SKUon your custom usage data object, the Transaction object and the Invoice Line Item object
- set the field
ON_SKUto be aggregated via the field
Transaction Aggregation Fieldsof the corresponding subscription item (
- add the field
ON_SKU__cto the field
Table Columnsof the invoice template to be used
- copies the value from
ON_SKUon the custom usage data object to
ON_SKUon the (temporary) transaction
- aggregates the values of
ON_SKUof all transactions
- copies the aggregated value to
ON_SKUon the invoice line item
- prints the value of
ON_SKUof the invoice line item to the invoice line item table
Commission based on average sales volume
Assume you want to calculate the commission based on the average sales volume, for example, the basket amount of an order. You create a commission tier table, for example:
The usage data object Order requires a custom field to hold the sales volume for a single order. To calculate the average amount over a certain period, you set up JustOn to aggregate the individual values of this field (see Aggregating Additional Fields), and to use this as the basis for allocating the intended commission (see Price and Quantity Fields).
Modeling this use case so involves:
- Creating the field
ON_BasketAmount__con the Order object to hold the sales volume
- Creating the target field
BasketAmount__con the Transaction object
- Specifying the field
BasketAmount__cas the price source field in the item field
Transaction Price Fieldlike
- Specifying the average calculation in the Item field
Transaction Aggregation Fieldslike
- Specifying the commission tier price to be used in the Item field
Transaction Commission Tier Price Fieldlike
- Selecting the Item checkbox
Aggregate Indiv. Priced Transactionsto combine transactions with individual prices
Consequently, JustOn calculates the average basket amount of all orders throughout the invoice run period, and allocates the commission tier as determined based on that average.
Using price tiers for transactional item, split by criterion
|Item||Order No.||Billing Type|
Custom object records to be matched with the transactional item
JustOn produces two invoice line items – one for criterion
1, and one for criterion
2. Without selecting the checkbox
Ignore Criterion For Price Tier Quantity, JustOn uses the individual quantities to determine the price tier. Accordingly, it applies price tier
A for the two invoice line items:
|Invoice Line Item||Quantity||Price|
With the checkbox
Ignore Criterion For Price Tier Quantity selected, however, JustOn combines the quantities and consequently applies price tier
|Invoice Line Item||Quantity||Price|
Return to JustOn Administration.