action.skip

Best Practice: Usage Billing

In many business models, companies charge their customers variable amounts based on their consumption of products or services during a defined period. Such usage data billing scenarios (aka metered billing or pay-per-use) may range from electricity or phone calls to worked hours in a service project or API calls in a SaaS business. Common to all of them is that you bill the customer on a regular basis – according to your billing cycle, and the amount varies – based on how much of the product or service the customer has used.

Take an example: A company controls their deals, involved products etc. using opportunities and opportunity products. One of their typical products is a subscription-based service, where the usages to be charged vary. Now the company wants the new subscriptions to be recorded automatically based on the opportunities, and, of course, the invoices to be automatically issued based on the actual service consumption. To this end, you combine JustOn's automatic subscription building and usage data billing.

Following this example, an implementation of this usage billing scenario may be:

(1) The company offers the service package, represented as a product in Salesforce.

(2) A customer subscribes to the service, and, in order to track the new deal, the company creates a new opportunity with the product attached.

(3) JustOn generates an account-specific subscription based on the new opportunity.

(4) The company continuously renders the service and tracks the actual usage consumed by the customer.

(5) JustOn periodically retrieves the usage data and saves it to a specifically configured object, for example, event.

(6) Upon the periodical invoice generation, JustOn itemizes the saved usage data, matches it against the defined subscription item and evaluates the provided quantity information, calculating the item's subtotal.

uc_subbuild_usage
Combining automatic subscription creation and usage data billing

Modeling this business use case with JustOn comprises at least the configuration tasks as listed below.

To set up the automatic subscription building:

To set up the usage data billing:

Info

Once set up as outlined in the example, JustOn automatically

  • creates an account-specific subscription
  • retrieves usage data and saves it to the (account-specific) event
  • itemizes the usage data and evaluates the consumption
  • generates the invoice based on the subscription, including the determined service usage

Setting Up Subscription Builder

Automatic subscription building helps managing subscriptions if your business requires to deal with a large or variable – read: increasing – number of subscriptions.

alt text

The way to set up the subscription builder depends on the nature of your products, your sales use cases and the representation of your source data in Salesforce.

For details, see Automatic Subscription Build.

Following the example, you want to bill an account-specific set of products under some account-specific conditions. To this end, you can use objects that are in a parent-child relationship, like opportunities with opportunity products. If set up accordingly, the subscription builder takes the parent object to produce the subscription, and the child objects to produce the subscription items. Optionally, you can involve a master supscription to pass identical information or conditions to be cloned for each produced individual subscription.

Configuring Target Object

In the context of subscription building, the target is the object whose records are both the data basis for the subscriptions and the target to which the created subscription is assigned.

The subscription builder requires a number of ON fields on the parent object, Opportunity, and on the child object, Opportunity Product.

  1. Navigate to the fields list of the parent object.

  2. Create the following new fields.

    API Name Data Type Description
    ON_Account Formula (Text) Specifies the Salesforce account ID or external ID.
    The formula uses the API name of the field that links the object to the account, for example, AccountId.
    ON_Subscription Lookup (Subscription) Links to the related subscription.
    With Salesforce CPQ installed, make sure to relate to the correct Subscription object. For details, see this article.
    ON_SubscriptionBuildError Text (255) Shows the error message in case the subscription creation has failed.
    ON_CurrencyIsoCode Formula (Text) Sets the subscription currency to the source object currency if
    a) you use multiple currencies and
    b) the account currency differs from the source object currency.
    The formula is TEXT(CurrencyIsoCode).

  3. Navigate to the fields list of the child object.

  4. Create the following new fields.

    API Name Data Type Description
    ON_OrderNo Formula (Text) Key to match source data to a subscription item, must be unique for each detail of the same master.
    ON_Price Formula (Currency) The net sales price of the item, required if the detail object is defined in a subscription build filter.
    ON_Quantity Formula (Number) The quantity of the item to be invoiced, required if the detail object is defined in a subscription build filter.
    ON_Title Formula (Text) The name or title of the item required if the detail object is defined in a subscription build filter.

Info

Depending on your use case and its requirements, you can add more fields to have them copied to the generated subscriptions or items, for example, ON_StartDate. For details, see ON Fields on Objects.

Note

Make sure that

  • The billing type of the produced items will be set to Transactional
  • Each item's value of the OrderNo field will match one of the possible values of the custom object's ON_OrderNo field (see Configuring Custom Object)

Creating Subscription Build Filter

To define which objects and records to include in the subscription build process, you create a new custom filter.

Note

The subscription build job always processes all available subscription build filters. Be aware that this may, consequently, produce multiple subscriptions for an account.

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

  2. Click Manage in the row of Filters.

  3. Create the following filter for the subscription build.

    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 target object Order
    Opportunity
    MyObject__c
    Child Relation Specifies the name of the child object ( plural form). Required if you create items based on the child records.
    For master-detail relations, use the API name of the detail object. In case of standard Salesforce objects, you can use Workbench to find the correct name.
    For lookup relations, use the relationship name of the child object.    		 OrderItems
    CO_Order_Line_Items__r
    Subchild Relation Specifies the name of the subchild object. Required if you create item price tiers based on custom subchild records.
    For master-detail relations, use the API name of the detail object.
    For lookup relations, use the relationship name of the child object.    		 CO_Price_Tiers__r
    Use Case Specifies the filter use case, must be SubscriptionBuilder SubscriptionBuilder
    Condition Specifies a condition (SOQL WHERE clause, see SOQL SELECT Syntax in the Salesforce Help) to restrict the set of included records on batch processing
    The SOQL expressions in filter conditions must not contain line breaks.
    For details about explicitly excluding/including records, see Excluding Certain Source Records.    		 Status = 'Activated'

    For help about creating filters, see Filters.

Scheduling Subscription Build Job

You can set up a job in order to have subscriptions built automatically on a regular basis.

The subscription build job does not require additional parameters. That is, you can set up the job directly for the corresponding batch chain SubscriptionBuilderChain. For details, see Scheduling Concepts.

To schedule the subscription build batch chain, you can use either JustOn's Scheduled Jobs page or Salesforce's Schedule Apex functionality. For details, see Scheduling a Job.

Note

The subscription build job always processes all available subscription build filters. Be aware that this may, consequently, produce multiple subscriptions for an account.

Via JustOn's Scheduled Jobs page:

  1. Open the Scheduled Jobs page.

    Use the following URL https://login.salesforce.com/apex/ONB2__JobsSetup, or, if you are already logged in, append apex/ONB2__JobsSetup to your org's domain name.

    You can access the Scheduled Jobs page via the JustOn configuration app ( > JustOn Configuration > Jobs Setup).

  2. From the Apex Job drop-down list, select Subscription Builder Job.

    The Job Name field is automatically set to SubscriptionBuilderChain.

  3. From the Start Time drop-down list, select the preferred execution time.

  4. Optionally, edit the displayed cron expression to adjust the execution time.

  5. Click Schedule.

    This sets up the subscription build to be executed at the specified time.

Info

From the Scheduled Jobs page, you can also run the batch chain immediately.

Via Salesforce's Schedule Apex functionality:

  1. Click to enter Setup, then open Apex Classes.

    In Salesforce Lightning, navigate to Custom Code > Apex Classes.

    In Salesforce Classic, navigate to Develop > Apex Classes.

  2. Click Schedule Apex on top of the list.

  3. Specify the details as required.

    • Job Name: SubscriptionBuilderChain
    • Apex Class: ScheduledBatchChain
    • Frequency: Weekly or Monthly (with an according weekday or day of month setting)
    • Start
    • End
    • Preferred Start Time

  4. Click Save.

    This sets up the subscription build to be executed at the specified time.

For more details about job scheduling, see Scheduling a Job in the JustOn documentation and Schedule Apex in the Salesforce Help.

You can also invoke the subscription builder using the following code in the Salesforce Developer Console:

new ONB2.ChainRunner()
.execute(
    new ONB2.ChainFactory().getByName('SubscriptionBuilderChain')
);

Configuring Usage Data Billing

Usage data billing is JustOn's mechanism for generating invoices from custom objects that represent product consumptions (volume or traffic data, service coverage, etc.).

transaction_bill
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. In the background, the transaction builder converts this data to transactions. During the invoice run, JustOn matches the transactions against the defined subscription items, evaluates the provided quantity information and calculates the item's subtotal. This data then makes up the according invoice line item.

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.

Configuring Custom Object

In the context of usage data billing, the custom object is the object whose records hold the usage data, making the basis for the invoice generation. The transaction builder requires a number of ON fields (controlling fields and data fields) on this object. Following the example, you configure the Event object accordingly.

  1. Navigate to the fields list of the custom object.

  2. 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 Transaction Filter

To define which objects and records to include when itemizing consumption data, you create a new custom filter.

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

  2. Click Manage in the row of Filters.

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

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.

To set up a continuous invoice run, you schedule a parameterized invoice run with the corresponding transaction filter (use case Continuous/Continuous Daily) added as a parameter.

Setting up a parameterized invoice run involves two steps:

  • Defining parameters for the batch chain
  • Scheduling the batch chain

Configuring Batch Chain Parameters

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

  2. Click Manage in the row of Batch Parameters.

  3. Click New.

  4. Specify the details as required.

    • Name: Must match the Job Name to be set when scheduling the job
    • Batch Chain: InvoiceRunChain

    • Parameter 1: TransactionFilters = <value>

      Make sure to set the transaction filter name as defined in Creating Transaction Filter.

      You can set additional parameters as required.

  5. Click Save.

Scheduling Batch Chain

To schedule the batch chain, you can use either JustOn's Scheduled Jobs page or Salesforce's Schedule Apex functionality. For details, see Scheduling a Job.

Via JustOn's Scheduled Jobs page:

  1. Open the Scheduled Jobs page.

    Use the following URL https://login.salesforce.com/apex/ONB2__JobsSetup, or, if you are already logged in, append apex/ONB2__JobsSetup to your org's domain name.

    You can access the Scheduled Jobs page via the JustOn configuration app ( > JustOn Configuration > Jobs Setup).

  2. From the Apex Job drop-down list, select Batch Chain Job.

  3. In the Job Name field, specify the name of the batch parameters setting created before.

  4. From the Start Time drop-down list, select the preferred execution time.

    Your business may require to schedule multiple invoice runs. In order to prevent concurrent access to records or batch job limitations, they should, however, not run in parallel. Therefore, JustOn recommends to involve a certain time delay between the scheduled invoice runs – for example, one at 00:00, the next at 01:00, and so on. The interval may vary depending on the amount of records to be processed.

  5. Click Schedule.

    This sets up the invoice run to be executed on a regular basis at the specified time with the additional parameters set.

Info

From the Scheduled Jobs page, you can also run the batch chain immediately.

Via Salesforce's Schedule Apex functionality:

  1. Click to enter Setup, then open Apex Classes.

    In Salesforce Lightning, navigate to Custom Code > Apex Classes.

    In Salesforce Classic, navigate to Develop > Apex Classes.

  2. Click Schedule Apex on top of the list.

  3. Specify the details as required.

    Your business may require to schedule multiple invoice runs. In order to prevent concurrent access to records or batch job limitations, they should, however, not run in parallel. Therefore, JustOn recommends to involve a certain time delay between the scheduled invoice runs – for example, one at 00:00, the next at 01:00, and so on. The interval may vary depending on the amount of records to be processed.

  4. Click Save.

    This sets up the invoice run to be executed on a regular basis at the specified time with the additional parameters set.

For more details about job scheduling, see Scheduling a Job in the JustOn documentation and Schedule Apex in the Salesforce Help.