Best Practice: Subscription Update

Automatic subscription building helps managing subscriptions if your business requires to deal with a large or variable (increasing) number of subscriptions or to update subscriptions automatically.

Subscription Update Concepts

The subscription builder supports three different use cases for the subscription building:

Use Case Description
NEW Creates a new subscription.
REORDER Creates new items and adds them to an existing subscription. If there is no existing subscription, it builds a new subscription.
UPGRADE Creates a new subscription, sets an end date on the existing subscription and sets its status to Upgraded. Certain items (active, not already available, not excluded, matching service period) of the existing subscription are cloned and added to the new subscription.

To illustrate the use cases, assume the following example: You sell phone contracts, and you keep track of your deals using opportunities. For each opportunity you generate a subscription, which is finally invoiced.

When you close a deal with a new customer, the new (or updated) opportunity triggers the creation of a new subscription. This is covered with the use case NEW.

Now an existing customer orders an additional service, which you add as a new opportunity product on a new opportunity. This opportunity product becomes a new subscription item on the existing subscription. This is the use case REORDER - you add new subscription items, leaving the existing in place.

If, however, the customer decides to upgrade the calling plan, you must refund the amount that is already paid for the rest of the current contract term. This is where you apply the use case UPGRADE: you create a new subscription that includes items for any new products, but also credit items for products to be refunded, and the existing subscription terminates.

Hence, when updating subscriptions, the use cases REORDER or UPGRADE may apply.

  • REORDER

    Creates new items and adds them to an existing subscription. If there is no existing subscription, it builds a new subscription.

    REORDER is set automatically if

    • the use case is empty
    • there is exactly one existing active subscription for the target account
    • the start date of the new subscription is empty
  • UPGRADE

    Creates a new subscription, sets an end date on the existing subscription and sets its status to Upgraded. The new subscription relates to the original subscription via the field Previous Subscription.

    UPGRADE is set automatically if

    • the use case is empty
    • there is exactly one existing active subscription for the target account
    • the start date of the new subscription is not empty

    Certain items of the existing subscription are cloned and added to the new subscription:

    • the item is not already available in the new subscription
    • the item is not excluded by ON_ExcludeFromUpgrade__c (see ON Fields on Objects)
    • the item is active
    • the end date of the item is empty or after the start date of the new subscription

Configuring Subscription Builder

Following the outlined example, the simplest way to implement this scenario involves these tasks:

  1. Set up the subscription builder for opportunities and opportunity products, that is, objects in a parent-child relationship, as described in Automatically Building Subscriptions.

    Configuring parent object

    The subscription builder requires a number of ON fields on the parent object.

    • ON_Account, usually a Formula (Text) field to specify the Salesforce account ID
    • ON_Subscription, a Lookup field that links to the related subscription
    • ON_SubscriptionBuildError, a Text (255) field that shows the error message in case the subscription creation has failed

    For details, see Configuring Parent Object.

    Configuring child object

    The subscription builder requires a number of ON fields on the child object.

    • ON_OrderNo, usually a Formula (Text) field that holds the key to match source data to a subscription item
    • ON_Price, usually a Formula (Currency) field that holds the net sales price of the item, required if the detail object is defined in the subscription build filter
    • ON_Quantity, usually a Formula (Number) field that holds the quantity of the item to be invoiced, required if the detail object is defined in the subscription build filter
    • ON_Title, usually a Formula (Text) field that holds the name or title of the item, required if the detail object is defined in the subscription build filter

    For details, see Configuring Child Object

    Creating subscription build filter

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

    • Name - the filter name, available as an option when triggering the operation
    • Target - the API name of the target object, like Opportunity
    • Child Relation - the relationship name of the child object, like OpportunityLineItems
    • Use Case - the filter use case, must be SubscriptionBuilder
    • Condition - an (optional) condition (SOQL WHERE clause) to restrict the set of included records

    For details, see Creating Subscription Build Filter

    Enabling subscription generation

    Set up the way to invoke the subscription building process according to your requirements:

  2. Create, in addition, the fields ON_StartDate on the Opportunity object and ON_Subscription on the Account object to trigger the intended subscription update use cases, for example, like

    Object Field Description
    Opportunity ON_StartDate Specifies the start date to be transferred to the resulting subscription in order to trigger the UPGRADE use case. Can be set up to be filled manually by a user, automatically using a custom process on specific conditions, or automatically using a formula.
    Account ON_Subscription Specifies the current active subscription for the account in order to trigger the subscription update.

Workflow

Once set up accordingly, JustOn operates as follows:

(1) If there is

  • an active subscription associated to the account,
  • a new opportunity with a new product for the account,

the subscription builder applies the use case REORDER. It converts the new opportunity product to a new subscription item, adding it to the existing subscription.

subscription_build_reorder
Updating an existing subscription based on a new opportunity, applying the REORDER use case

(2) If there is

  • an active subscription associated to the account,
  • a new opportunity with a new or an updated product and a start date set for the account,

the subscription builder applies the use case UPGRADE. It sets an end date on the existing subscription and changes its status to Upgraded, as well as create a new subscription, which

  • starts at the specified start date
  • includes the new or updated items and the items of the previous subscription (if they are not specifically excluded)

subscription_build_upgrade
Terminating a subscription and creating a new subscription based on a new opportunity, applying the UPGRADE use case

Info

Remember that this document describes one (of several possible) ways to implement this scenario. The appropriate setup may vary depending on your individual business requirements.