Creating a Direct Milestone Custom Plan

You can create direct milestone custom plans on the fly without using any plan template. You can create a direct milestone custom plan for an Order Line Item (OLI), a Line Item, or a set of OLIs or Line Items containing One-Time or Recurring products. The plan ID of the direct custom plan is associated with the OLIs or Line Items listed in the plan. If an OLI or Line Item already has a custom plan ID associated with it, the new direct plan ID replaces the previous plan ID.

Direct plans are in Active status when you create them.

Prerequisites

• For creating a custom plan for an OLI

  • OLI is not Activated.

  • The order is not Activated.

  • The intended OLIs for which a billing plan is to be created must refer to the same order.

• For creating a custom plan for Line Item
  • The intended Line Items for which a billing plan is to be created refers to the same Proposal.

API Input Parameters

To create a direct milestone custom plan you must enter the parameters for the plan header and the plan line items.

Parameters for Plan Header

Enter the  following parameters for every set of OLIs or Line Items:

• Name: Name of the custom plan, for example, My_Custom_Plan_1
• Plan Type: Milestone
• Periods Needed: Specify if periods are required for the plan, if the Plan Type is Milestone, the value is No.
• Number of Installments: Specify the number of installments you want to make the payments, for example, 3.
• Based On: Percentage
• Computation Method: Custom or Even Distribution
• Description: Describe the custom plan (optional).
• OLI ID or Line Item ID: IDs of the OLI or Line Item.

Parameters for Plan Line Items

Enter the  following parameters for every line item of the plan:

• Milestone Expected Date: Specify when the milestone is expected to be completed.
• Payment Term: The payment term associated with the plan.
• Percentage: The percentage of each installment.
• Comments: Write your comments (optional).

For example, the requirement is to bill the customer in three installments, 40.33333333%, 25.33333333%, and 34.33333334.%, enter the following parameters: 

Because there are three installments, you must provide the line item details for three plan lines. The engine auto-computes the first or last value in the percent field if you have enabled the Fee Amount Rounding Schedule setting at the Billing Setting level. This is elaborated in the Rounding the Values and Auto-Computation section.

When a direct custom plan is created for a Line Item, the custom plan ID is populated on it and its Proposal.

When you initiate billing, the billing header will have three Billing Schedule Records (BSRs) containing 40.33333333%, 25.33333333%, and 34.33333334% of the Total Contract Value (TCV (sales)) respectively.

Activating the Order and Initiating the Billing

When you activate the OLI on which the above custom plan is created, and initiate the billing process, the BSRs, and BSDs guided per the custom plan are created. These milestone BSRs and BSDs are slightly different from the recurring products.

On the BSRs:

• The Actual Fee Amount field is Null.
• The Ready for Invoice Date field is Null.
• The Status is Pending Milestone.
• The Payment Term field has the same value indicated in the plan line item.

On the BSDs:

• The Record Type field is Milestone.

• The Milestone Expected Date field has the same value indicated in the plan line item.

• The Milestone Percent field has the same value as the plan line item.

• The Milestone Status is Expected

• The Derived Invoice Status field is Pending.

Consider the example:

A new sale is initiated for a service with a TCV (Sales) of USD 1,200.00. The above direct milestone custom plan is created on the OLI before its activation.  The start date is 01-January-2024 and the end date is 31-December-2024.

You have activated the order (OLI-1) and initiated the billing to create three BSRs and BSDs per the custom plan.

BSRs have the following data:

BSDs have the following data:

You must complete the milestone-type BSDs to compute the actual fee amount. The process to complete the milestone-type BSDs is given in Completing the Milestone.

Before you complete the milestone, you must query the milestone-type BSDs using an API.

Querying BSDs of Milestone Type

You can query the milestone BSDs based on Order Line Item ID, Billing Header ID, or Billing Schedule Records ID. To query for milestone-type BSDs, pass the values for the following parameters:

Object: Pass the Order Line Item ID, Billing Header ID, or Billing Schedule Records ID.

Milestone Expected From Date: Pass a date or keep it as Null.

Milestone Expected To Date: Pass a date or keep it as Null.

Show Data For: Select from All or Pending.

The Milestone Expected From Date and Milestone Expected To Date fields are optional. You can choose to enter either or skip both.

When you initiate the API to query milestone-type BSDs based on the input criteria in the above fields, it filters the relevant results.

If in the above example, you entered OLI-1 in the Object field and selected All in the Show Data For field, you can see the following data for the filtered BSDs:

Completing the Milestone

The actual fee amount is not computed instantly when the milestone-type BSDs are created. You must complete the milestone to invoke the logic to compute the actual fee amount of the BSD. The logic computes the actual fee amount based on the value in the Milestone Percent field of the BSD.

To complete the milestone of a BSD you must enter the following values:

• Billing Schedule Detail Record ID

• Milestone Completion Date

• Milestone Completed By - Default for logged-in users

When you call the API to complete the milestone with the above set of data, the following fields are updated:

On the BSD:

• The Actual Fee Amount field on the BSD is updated to a value equal to the product of Milestone Percent and the Current Unbilled Amount.
• The Milestone Status is updated to Complete, the Derived Invoice Status is updated to Pending, and the Milestone Completion Date is updated to the date you entered.

On the BSR:

• The values for the Actual Fee Amount and Ready for Invoice Date fields are fetched from the Actual Fee Amount and Milestone Completion Date fields of the BSD.
• The Invoice Status is updated to Pending Billing.

On the BH, the Pending Invoice Amount field is updated based on the rolled-up amount from the BSR.

In the above example, to complete the BSD-1 milestone, you entered "BSD-1" for the BSD ID and "05-March-2024" for the Milestone Completion Date. On execution, the BSD shows:

The BSR is populated with the following data:

The actual fee amount is calculated and updated on the BSD after it is completed, then this amount is rolled up to the BSR. From the BSR the value is fetched and updated on the BH. So the Pending Invoice Amount field on the BH is updated to USD 483.99 which is equal to 40.33333333% of USD 1,200.00.

Rounding the Values and Auto-Computation

For any of the computation methods (Even Distribution or Custom), the engine auto-computes either the first or last installment value. It ensures that the sum of the percentage of all the installments is always equal to 100. Depending on whether the Fee Amount Rounding Schedule setting is set to First or Last, the engine also rounds off the value to eight decimal places. This is described in the following table:

Considering the above example and assuming that you have enabled the Fee Amount Rounding Schedule setting to either First or Last at the Billing Setting level, the milestone BSDs show the following milestone percentage for a Custom computation method: