Enabling 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 Billing & Invoice Management 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.

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

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

Info

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 Controlling Usage Data 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) or Picklist	✅	Defines the type of the (usually transient) transaction: `Transaction` for the continuous invoice run – the usual option for billing usage data. `Transaction` or `Detail` when creating "tangible" transaction records.
ON_OrderNo	Formula (Text) or 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, `CASESAFEID(Account__c)`.
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)/ Formula (Date/Time) or 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_Date` as a formula field with the return type `Date` but the referenced field is of the type `Date/Time`, the operator `DATEVALUE` must precede the referenced field, like `DATEVALUE(<datetime_field>)`.
ON_Quantity	Formula (Number) or Number		Data field, specifies the quantity or volume information as accumulated for the transaction.

For help about creating fields, see Managing Object Fields.

Info

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 Transactional
- Each item's value of the OrderNo field matches one of the possible values of the custom object's ON_OrderNo field (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".

Info

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 Must not exceed 38 ASCII characters. Special characters like brackets will be URL encoded, which makes them count three, like `(` makes `%28`.
Target	✅	Specifies the API name of the custom object that is to be converted to transactions	`MyObject__c`
Use Case	✅	Specifies the filter use case: `Continuous` for 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__c` indexed, and then use `Continuous Daily` for the continuous invoice run (for details, see here). `Transaction` for creating "tangible" transaction records.	`Continuous`
Condition		Specifies a condition expression as used in an 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_Subscription` and `ON_Invoice` is already filled will be ignored. SOQL expressions in filter conditions must not contain line breaks.

For help about creating filters, see Filters.

Info

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

Info

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, as described here) 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 Continuous (or Continuous Daily).
  For details, see Creating Transaction Filter.
Schedule a parameterized invoice run with the corresponding transaction filter (use case Continuous/Continuous Daily) added as a parameter.
For details, see Parameterized Invoice Run.

Info

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:

Field	Value
Transaction Price Field	`ON_Price__c`
Aggregate Indiv. Priced Transactions (checkbox)	`true`

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 ClickRevenue__c and Impressions__c, respectively, the corresponding item fields must specify the following values:

Field	Value
Transaction Price Field	`ClickRevenue__c`
Transaction Quantity Field	`Impressions__c`

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_SKU on your custom usage data object, the Transaction object and the Invoice Line Item object
set the field ON_SKU to be aggregated via the field Transaction Aggregation Fields of the corresponding subscription item ({"ON_SKU__c":"LAST"})
add the field ON_SKU__c to the field Table Columns of the invoice template to be used

Doing so

copies the value from ON_SKU on the custom usage data object to ON_SKU on the (temporary) transaction
aggregates the values of ON_SKU of all transactions
copies the aggregated value to ON_SKU on the invoice line item
prints the value of ON_SKU of 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:

Tier	Price	Commission
A	50,00	10%
B	100,00	9%
C	150,00	8%
...

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__c on the Order object to hold the sales volume
Creating the target field BasketAmount__c on the Transaction object
Specifying the field BasketAmount__c as the price source field in the item field Transaction Price Field like transaction.BasketAmount__c
Specifying the average calculation in the Item field Transaction Aggregation Fields like {"BasketAmount__c":"AVG"}
Specifying the commission tier price to be used in the Item field Transaction Commission Tier Price Field like transaction.BasketAmount__c
Selecting the Item checkbox Aggregate Indiv. Priced Transactions to 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

Subscription settings

Item	Order No.	Billing Type
Product 1	PROD1	Transactional

Price Tier	Quantity	Price
A	100	10,00
B		5,00

Custom object records to be matched with the transactional item

Criterion	Order No.	Quantity
1	PROD1	30
1	PROD1	40
2	PROD1	50

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
Product 1	70	700,00
Product 1	50	500,00

With the checkbox Ignore Criterion For Price Tier Quantity selected, however, JustOn combines the quantities and consequently applies price tier B:

Invoice Line Item	Quantity	Price
Product 1	70	350,00
Product 1	50	250,00