Custom Action to Renew Contracts

You can implement customizations to renew contracts automatically. You can do this programmatically via the API, or you can do it without writing code by invoking the following Apex action from a Salesforce flow:

Category

 Apex Action Apex Class Purpose
Billing Contract Renew Billing Contracts Asynchronously ContractsServiceActionRenewAsync

Takes a collection of billing contract IDs and creates renewal contracts with the status "Draft" based on supplied pricing and date input options.

The process runs asynchronously using Queueable Apex. When you supply a collection of contract IDs to the Apex action, they are split into groups and processed. The group size is determined by the Renew Contracts: Scope Size field in the Background Process Settings custom setting.

Input Parameters

The Renew Billing Contracts Asynchronously Apex action has the following input parameters for each billing contract passed to it.

For more information about creating renewals using the different pricing and duration options, see Renewals.

Parameter

Required or Optional

Description
Billing Contract ID to be renewed Required ID of the contract to be renewed.
Contract duration option Required

Specify whether the renewal's duration is the same number of days, or the same number of months, as the active contract.

You must supply one of the following supported values. They are case-insensitive.

  • AsDays - The renewal's duration is the same number of days as the active contract. For example, if the active contract's start date is January 1, 2024 and its end date is December 31, 2024 (a leap year), the renewal is created with a duration of 366 days meaning that its start date is January 1, 2025 and its end date is January 1, 2026.
  • AsMonths - The renewal's duration is the same number of months as the active contract. For example, if the active contract's start date is January 1, 2024 and its end date is December 31, 2024 (a leap year), the renewal is created with a duration of 12 months meaning that its start date is January 1, 2025 and its end date is December 31, 2025.
Contract line duration option Required

Specify whether contract line items on the renewal have the same start and end dates as on the active contract, or have their start and end dates extended to the renewal's start and end dates.

You must supply one of the following supported values. They are case-insensitive.

  • KeepSame - Contract line items on the renewal have the same start and end dates as on the active contract. For example, an annual contract might have one line for an on-going service which spans the full duration of the contract, and another line for an additional service which spans the first month only. By using KeepSame, the line for the ongoing service will span the whole year of the renewal contract, and the line for the additional service will span the first month only (matching the duration of the lines on the active contract).
  • ExtendToMatchContractDuration - Contract line items on the renewal have their start and end dates extended to the renewal's start and end dates. For example, an annual contract might have one line for an on-going service which spans the full duration of the contract. Three months after the contract starts, the customer adds a product for another on-going service. By using ExtendToMatchContractDuration, the line for the original on-going service spans the full duration of the renewal contract as before, and the line for the add-on product is extended to the full duration of the renewal contract (not starting three months in as it did on the active contract).
Percentage Optional

The percentage by which unit prices are updated on the renewal. This must be a decimal value. See "More Information about the Pricing Options" below.
Pricebook ID Optional

The price book from which to obtain unit prices for the renewal. See "More Information about the Pricing Options" below.

More Information about the Pricing Options

If you supply both Percentage and Pricebook ID, an error is reported and the renewal is not created.

If you supply neither Percentage nor Pricebook ID, the renewal is created with the existing unit prices.

If you supply a percentage with decimal places, depending on the unit prices on the active contract, unit prices on the renewal might end with very small numbers which could result in rounding issues. For example, if the unit price is 0.01 and the percentage is 0.01 the unit price on the renewal will be 0.010001. We recommend you check the unit prices on your renewals before activating them.

Output Values to Store for Error Handling

By default, errors are recorded in Billing Central logs. If you prefer to notify the user by email when an error occurs during the flow, you can store the return values in resources which are available to other flow elements. For an illustration of how to do this, see Sample Flows to Renew Contracts.

When configuring the action in a flow, click Advanced and select the Manually Assign Variables checkbox to store the following return values.

Output Variable

Description
Billing Contract ID to be renewed ID of the contract that has been queued for renewal.
Has Errors Assign this to a boolean variable to store the outcome of the renewal action, so it can be used by a Decision element later in the flow.
Error Message Assign this to a text variable which can be used to store the error message so that an Action element can email it to the user.
Warning:

Some types of errors are only recorded in logs. We recommend you monitor the Apex Jobs tab for any ContractsServiceActionRenewAsync job failures which can include Salesforce exceptions (such as breached Governor limits), internal Billing Central exceptions (such as the specified renewal percentage is invalid) or Billing Central errors (such as the contract already has a renewal). In the case of Salesforce exceptions, Billing Central will split the group of contracts and retry, or will log an error for each one when no further splitting can be done. In the case of internal Billing Central exceptions or errors, logs are recorded and no retry is attempted.

If the Apex Jobs tab lists a ContractsServiceActionRenewAsync job as having failed, use the job's Apex Job ID to find the log with that Run Id. Log details include the record ID of the billing contract that failed to be renewed. See Log Fields for details.

Permissions

To configure a Salesforce flow to use this Apex action, you must be assigned a permission set that includes access to the corresponding Apex class. The class is included in the following packaged permission set:

  • Billing Central API

For more information about creating Salesforce flows, see the Salesforce Help.

Sample Flows to Renew Contracts

For illustrations of how flows can be configured to use this Apex action, see Sample Flow to Renew Contracts Using Fixed Input Parameters and Sample Flow to Renew Contracts Using Input Parameters Derived from Fields on Account Extension.

Note:

The sample flow descriptions do not give step-by-step instructions on how to create the flows. The information is intended for administrators who are already experienced at creating Salesforce flows. Refer to the Salesforce Help if you need information about how to create flows.