Skip to content

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 assume that this service sells a lot - the company wants the new subscriptions to be recorded automatically, and, of course, invoices 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, and creates a master subscription including the item, which is potentially to be invoiced.

(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 master subscription and 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 items and evaluates the provided quantity information, calculating the item's subtotal.

uc_mastersub_cir
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

Creating Master Subscription

Basically, a master subscription is a usual subscription that is not assigned to an account. That is, you just create a subscription, add all items and define any required conditions to be cloned, but do not assign it to an account.

  1. Open the Subscriptions tab.
  2. Click New.
  3. Specify the details as required.

    Add the required items and define the required conditions.

    Do not assign the subscription to an account. The field Account may be set as required, however. In this case, navigate to the Subscription page layout, open the field properties for the Account field and deselect the Required checkbox.

    The subscription name will be used as an input parameter when configuring the target object. JustOn recommends to prefix the master subscription name with MASTER.

  4. Click Save.

Info

For details, see Creating Subscriptions

Configuring Target Object

The subscription builder requires a number of ON fields on the opportunity as the target object.

  1. Navigate to the fields list of the target 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, TEXT(AccountId).
    ON_Subscription Lookup (Subscription) Links to the related subscription.
    ON_SubscriptionBuildError Text (255) Shows the error message in case the subscription creation has failed.
    ON_MasterSubscription Text (255)
    or
    Formula
    Specifies the name of the master subscription (which serves as a template and will be cloned).
    If configured as a formula field, the master subscription name is used for every record.

    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 copied to the generated subscriptions. For details, see ON Fields on Objects.

Creating Subscription Build Filter

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

  1. In Setup, 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
    Target Specifies the API name of the target object Order
    Opportunity
    MyObject__c
    Child Relation () Specifies the name of the child object. 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 parent-child relations, use the relationship name of the child object.
    OrderItems
    CO_Order_Line_Items__r
    Use Case Specifies the filter use case, must be SubscriptionBuilder SubscriptionBuilder
    Condition Specifies a condition (SOQL WHERE clause) to restrict the set of included records
    For details, see SOQL SELECT Syntax in the Salesforce Help.
    Status = 'Activated'

    For help about creating filters, see Filters.

Scheduling Subscription Build Job

You can set up a job in order to have subscriptions build 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.

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/apex/ONB2__JobsSetup to your org's domain name.

    As of JustOn 2.52, you can access the Scheduled Jobs page via the JustOn configuration app (App Launcher > 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. In Setup, 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 Force.com Developer Console (see Developer Console Functionality in the Salesforce Help):

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

Configuring Custom Object

The transaction builder requires a number of ON fields (controlling fields and data fields) on the object customized to hold usage data. 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 Description
    ON_Type Formula (Text)
    or
    Picklist
    Controlling field, defines the type of the created transaction, either Transaction or Detail.
    When using the continuous invoice run, set Transaction as the value.
    ON_OrderNo Formula (Text)
    or
    Text
    Controlling field, 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) Controlling field, links to the related subscription after the object records have been successfully processed.
    ON_Invoice Lookup (Invoice) Controlling field, links to the related invoice after the object records have been successfully billed.
    ON_LastError Text (255) Controlling field, displays the error message if the transaction creation has failed.
    ON_Account Formula (Text) Controlling field, 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 Controlling field, required when using the continuous invoice run. Determines whether to show the transaction on the invoice, deselected by default.
    ON_AddToCsv Checkbox Controlling field, required when using the continuous invoice run. Determines whether to export the transaction as CSV, deselected by default.
    ON_Date Formula (Date)
    or
    Date
    Data field, displays the date on which the transaction is considered for invoicing.
    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 details, see Fields on Custom Objects.

Creating Transaction Filter

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

  1. In Setup, 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 transaction build.

    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) target object that is to be converted to transactions MyObject__c
    Use Case Specifies the filter use case, either Transaction or Continuous.
    When using the continuous invoice run, set Continuous as the value.
    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.
    Continuous
    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_Subscription and ON_Invoice is already filled will be ignored.

    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. In Setup, 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/apex/ONB2__JobsSetup to your org's domain name.

    As of JustOn 2.52, you can access the Scheduled Jobs page via the JustOn configuration app (App Launcher > 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.
  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. In Setup, 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: The name of the batch parameters setting created before
    • Apex Class: ScheduledBatchChain
    • Frequency
    • Start
    • End
    • Preferred Start Time
  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.