Enabling Installments
Certain business use cases require staged payment plans for invoices. To this end, JustOn allows for setting up installments, which represent models for intended payment plans.
Enabling installments involves the following mandatory tasks:
- Creating custom setting Installment OR Creating custom Installment configuration at the invoice
- Adding installment types to subscriptions or invoices
Optional setup steps may include:
- Configuring installment table on invoices
- Adding installment types to accounts or arbitrary objects
- Overwriting titles for individual installments and languages
Once set up, there are various ways to have the payment plans created based on your installment types:
- Creating an invoice from a subscription with an installment type set
- Finalizing a draft invoice with an installment type (and a date) set
- Creating installments manually from draft or open invoices
Info
In certain cases, there may be already payment balances assigned to an invoice. Assume, for example, there is a pre-payment that originates from a deposit invoice. When creating the installments for the final invoice, JustOn also creates a deposit installment, which represents the sum of the assigned payment balances. The remaining amount, which is due with the final invoice, is then distributed according to the specified payment plan.
Installment Information
JustOn supports two approaches for defining installments:
- For fixed payment plans, you can use the custom setting Installment. Each installment custom setting represents an invariable model for the intended payment plan.
- If your business requires variable payment plans, you apply custom installments using a JSON configuration. This allows for covering individually negotiated conditions, like, for example, account-specific initial amounts.
Irrespective of the approach, the installment configuration provides the following information in custom setting fields or, respectively, JSON keys:
Field JSON Key |
Required | Description | Examples |
---|---|---|---|
Name | () | Required for the custom setting. Defines the name of the payment plan model, which is referred to by the field Installment Type on the invoice, subscription, opportunity or account.The name must match with one of the picklist values of the Installment Type field on the invoice. |
|
Periodperiod |
The period configures the number of installment payments and their interval in days or months. The syntax is Nx(M) where N = interval , x = d | m (days or months), M = installments M is optional.The period calculation is based on the Payment Due Date , unless you use a Date Reference . When using date references, you can set fix instead of 0m for a better readability.You can combine different installment calculations defining multiple periods, separated by comma, like 1m(6),3m(2) . |
1m(12) = 12 installments, due once per month30d(6) = 6 installments, due every 30 days2m(4),120d = 5 installments, the first four are due every two months, the last is due 120 days after the penultimatefix,fix = 2 installments, each referring to a fixed date (see date references) |
|
Date ReferencedateReference |
Date references "anchor" installments to one or more specific dates, unbinding them from the Payment Due Date . The syntax is CUSTOMFIELD__C(M) where CUSTOMFIELD__C must be the API name of a date field on the invoice object, M = installments M is optional.You can address multiple installments by specifying multiple date references separated by comma. The first specified date reference refers to the first installment resulting from the Period definition.If there are less date references than periods, JustOn uses the field Payment Due Date instead. |
Date1__c(12) = 12 installments based on the field Date1__c . The corresponding installment cycle is defined using the Period value 1m(12) .FirstDueDate__c,SecondDueDate__c = 2 installments due at the dates defined by two custom fields. The corresponding period may be defined like fix,fix .FirstDueDate__c,PaymentDueDate__c(3) = 4 installments, special date handling for the first one. The corresponding period may be defined like fix,2m(3) . |
|
Raterate |
The rate is applied to the Grand Total of the invoice. The syntax is N(M) where N = % rate , M = installments M is optional.You can address multiple installments by specifying multiple rates separated by comma. The first specified rate refers to the first installment resulting from the Period definition.If there are less rates than periods, JustOn distributes the remaining amount equally to the remaining installments. |
20(5) = 5 installments, each with 20% of the grand total20,30,50 = 3 installments with 20%, 30% and 50% of the grand total25 = one installment of 25%, the remaining 75% are distributed equally to the remaining installments |
|
Amountamount |
The amount is taken from the Grand Total of the invoice. The syntax is N(M) where N = installment amount , M = installments M is optional.You can address multiple installments by specifying multiple amounts separated by comma. The first specified amount refers to the first installment resulting from the Period definition.If there are less amounts than periods, JustOn distributes the remaining amount equally to the remaining installments. |
100(4) = 4 installments, each with the amount of 100. If the grand total is larger than 400, the last installment holds the remaining amount instead.250.33 = one installment of 250,33, the remaining amount is distributed equally to the remaining installments50(2) = 2 installments of 50 each, the remaining amount is distributed equally to the remaining installments. |
|
Titletitles |
The title for each installment in the installment table in the invoice PDF, can contain placeholders. Preconfigured placeholders include [PosNo] = number of the current installment[InstallmentAmount] = amount of the current installment[InstallmentRate] = rate of the current installment (only applicable if the rate configuration is used)[InstallmentDate] = due date of the current installment |
Installment custom settingInstallment [PosNo] ([InstallmentRate]) JSON configuration "titles": {"default":{"default":"Installment [PosNo]"}} |
Info
Leaving Rate
and Amount
blank distributes the invoice amount equally to the installments as defined in Period
.
Note
Rate
and Amount
must not be used in the same installment configuration.
Installment Examples
This section summarizes some examples for the installment configuration, illustrating its behavior.
Four equally distributed monthly installments
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2017-12-05 |
Installment Type | Four by Month |
Installment custom setting
Field | Value |
---|---|
Name | Four by Month |
Period | 1m(4) |
Rate | |
Amount | |
Title | Installment [PosNo] |
Resulting payment plan
Title | Date | Amount | Rate |
---|---|---|---|
Installment 1 |
2017-12-05 |
25,00 |
|
Installment 2 |
2018-01-05 |
25,00 |
|
Installment 3 |
2018-02-05 |
25,00 |
|
Installment 4 |
2018-03-05 |
25,00 |
Five equally distributed monthly installments, due end of month, overwritten titles
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2017-12-31 |
Installment Type | Five by Month |
Installment custom setting
Field | Value |
---|---|
Name | Five by Month |
Period | 1m(5) |
Rate | |
Amount | |
Title | Installment [PosNo] |
Title1__c | First Rate |
TitleLast__c | Last Rate |
Resulting payment plan
Title | Date | Amount | Rate |
---|---|---|---|
First Rate |
2017-12-31 |
20,00 |
|
Installment 1 |
2018-01-31 |
20,00 |
|
Installment 2 |
2018-02-28 |
20,00 |
|
Installment 3 |
2018-03-31 |
20,00 |
|
Last Rate |
2018-04-30 |
20,00 |
Three installments, distributed by rate, regular period
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2017-12-05 |
Installment Type | Three by Two Months |
Installment custom setting
Field | Value |
---|---|
Name | Three by Two Months |
Period | 2m(3) |
Rate | 20,30,50 |
Amount | |
Title | Installment [PosNo] |
Resulting payment plan
Title | Date | Amount | Rate |
---|---|---|---|
Installment 1 |
2017-12-05 |
20,00 |
20 |
Installment 2 |
2018-02-05 |
30,00 |
30 |
Installment 3 |
2018-04-05 |
50,00 |
50 |
Three installments, distributed by rate, irregular period
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2018-03-15 |
Invoice Date | 2018-03-01 |
Payment Due | 14 (days) |
Installment Type | Three Irregular |
Installment custom setting
Field | Value |
---|---|
Name | Three Irregular |
Period | 17d,103d,0d |
Rate | 20,30,50 |
Amount | |
Title | Installment [PosNo] |
Resulting payment plan
Title | Date | Amount | Rate | Notes |
---|---|---|---|---|
Installment 1 |
2018-03-15 |
20,00 |
20 |
The first installment date is always the payment due date. |
Installment 2 |
2018-04-01 |
30,00 |
30 |
17 days are added to the first installment date. |
Installment 3 |
2018-07-13 |
50,00 |
50 |
103 days are added to the second installment date. |
Three installments with fixed first amount, regular period
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2017-12-05 |
Installment Type | 30 Deposit |
Installment custom setting
Field | Value |
---|---|
Name | 30 Deposit |
Period | 20d(3) |
Rate | |
Amount | 30 |
Title | Installment [PosNo] |
Resulting payment plan
Title | Date | Amount | Rate |
---|---|---|---|
Installment 1 |
2017-12-05 |
30,00 |
|
Installment 2 |
2017-12-25 |
35,00 |
|
Installment 3 |
2018-08-14 |
35,00 |
Existing pre-payment, four equally distributed monthly installments
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Date | 2018-06-01 |
Payment Due Date | 2018-07-31 |
Pre-Payment | 40,00 |
Installment Type | Four by Month |
Installment custom setting
Field | Value |
---|---|
Name | Four by Month |
Period | 1m(4) |
Rate | |
Amount | |
Title | Installment [PosNo] |
TitleDeposit__c | Received Payment |
Resulting payment plan
Title | Date | Amount | Rate |
---|---|---|---|
Received Payment |
2018-06-01 |
40,00 |
|
Installment 1 |
2018-07-31 |
15,00 |
|
Installment 2 |
2018-08-31 |
15,00 |
|
Installment 3 |
2018-09-30 |
15,00 |
|
Installment 4 |
2018-10-31 |
15,00 |
Four equally distributed installments with custom date as anchor
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2017-12-05 |
Date1__c | 2018-02-01 |
Installment Type | Different Anchor |
Installment custom setting
Field | Value |
---|---|
Name | Different Anchor |
Period | 1m(4) |
Date Reference | Date1__c(4) |
Rate | |
Amount | |
Title | Installment [PosNo] |
Resulting payment plan
Title | Date | Amount | Rate |
---|---|---|---|
Installment 1 |
2018-02-01 |
25,00 |
|
Installment 2 |
2018-03-01 |
25,00 |
|
Installment 3 |
2018-04-01 |
25,00 |
|
Installment 4 |
2018-05-01 |
25,00 |
Four equally distributed installments with custom dates
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2017-12-05 |
Date1__c | 2018-02-03 |
Date2__c | 2018-05-07 |
Date3__c | 2018-11-13 |
Date4__c | 2019-05-19 |
Installment Type | Four custom dates |
Installment custom setting
Field | Value |
---|---|
Name | Four custom dates |
Period | 0m(4) orfix,fix,fix,fix |
Date Reference | Date1__c,Date2__c,Date3__c,Date4__c |
Rate | |
Amount | |
Title | Installment [PosNo] |
Resulting payment plan
Title | Date | Amount | Rate |
---|---|---|---|
Installment 1 |
2018-02-03 |
25,00 |
|
Installment 2 |
2018-05-07 |
25,00 |
|
Installment 3 |
2018-11-13 |
25,00 |
|
Installment 4 |
2019-05-19 |
25,00 |
Four equally distributed installments, first with custom date
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2018-03-01 |
Date1__c | 2018-02-03 |
Installment Type | One custom date |
Installment custom setting
Field | Value |
---|---|
Name | One custom date |
Period | fix,15d(3) |
Date Reference | Date1__c |
Rate | |
Amount | |
Title | Installment [PosNo] |
Resulting payment plan
Title | Date | Amount | Rate |
---|---|---|---|
Installment 1 |
2018-02-03 |
25,00 |
|
Installment 2 |
2018-03-01 |
25,00 |
|
Installment 3 |
2018-03-16 |
25,00 |
|
Installment 4 |
2018-03-31 |
25,00 |
Four installments, distributed by rate, last with custom date
Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2018-03-01 |
Date1__c | 2019-12-31 |
Installment Type | Last custom date |
Installment custom setting
Field | Value |
---|---|
Name | Last custom date |
Period | 1m(3),fix |
Date Reference | PaymentDueDate__c(3),Date1__c |
Rate | 20(3) |
Amount | |
Title | Installment [PosNo] |
Resulting payment plan
Title | Date | Amount | Rate |
---|---|---|---|
Installment 1 |
2018-03-01 |
20,00 |
|
Installment 2 |
2018-04-01 |
20,00 |
|
Installment 3 |
2018-05-01 |
20,00 |
|
Installment 4 |
2019-12-31 |
40,00 |
Defining Fixed Installments
For fixed payment plans, you can use the custom setting Installment. Each installment custom setting represents an invariable model for the intended payment plan.
Depending on your organization's requirements, you must create individual installment settings to cover specific staged payment plans.
-
In Setup, open Custom Settings.
In Salesforce Lightning, navigate to Custom Code > Custom Settings.
In Salesforce Classic, navigate to Develop > Custom Settings.
-
Click Manage in the row of Installment.
- Click New.
-
Specify the details as necessary.
The mandatory information include the name, period and title. Set a rate or amount as necessary.
For details, see Installment Information.
-
Click Save.
This creates the new payment plan model and makes it available for subscriptions and invoices.
Defining Variable Installments
If your business requires variable payment plans, you apply custom installments using a JSON configuration instead of custom settings. This allows for covering individually negotiated conditions, like, for example, account-specific initial amounts. To this end, you need an additional custom field on the invoice that holds the JSON configuration.
Info
The support for variable installment configurations is available as of JustOn 2.68.1.
Enabling custom installments involves:
- Defining the configuration in JSON notation
- Creating an additional custom field on the invoice that holds the JSON configuration
- Setting the
Installment Type
field on the invoice (or the source object) toCustom
Defining JSON Configuration
The JSON configuration for installments uses the same information and follows the same rules as the custom setting. The keys amount
, dateReference
, period
, and rate
are used and work exactly the same way. The titles
key, however, differs – it expects the data in a map structure like "index" : { "language" : "value" }
(see Overwriting Titles for Individual Installments and Languages).
Assume, for example, a payment plan that involves two installments, with a fixed first amount of 100
. The corresponding JSON configuration would look like this:
{
"period": "1m(2)",
"amount": "100",
"titles": {
"default":{
"default":"Installment [PosNo]",
"de":"Rate [PosNo]"
}
}
}
Creating Custom Installment Field
To hold the intended JSON configuration, you need the custom field CustomInstallment
on the Invoice object. The field can be either a large text field to be filled from a source object via the ON field mechanism (or other automation means), or a formula field to produce the JSON, which allows for fetching values from other fields.
- Navigate to the fields list of the Invoice object.
-
Create the following new field.
API Name Data Type Description CustomInstallment Formula (Text)
Text AreaSpecifies the JSON configuration for variable installments. As soon as you want to retrieve values from other fields, you use a formula. Make sure that in this case, you must apply Salesforce's rules for building formula fields (see Build a Formula Field in the Salesforce Help), namely enclosing the strings with quotation marks and combining the strings with the concatenation operator.
Assume a payment plan that involves two installments, with a fixed first installment whose amount is fetched from a custom Account field
First Installment
. The formula to produce the JSON as required would look as follows:'{' & ' "period": "1m(2)",' & ' "amount": "' & ONB2__Account__r.First_Installment__c & '",' & ' "titles": {' & ' "default":{' & ' "default":"Installment [PosNo]",' & ' "de":"Rate [PosNo]"' & ' }' & ' }' & '}'
Setting Installment Type
If you apply variable installments using the CustomInstallment
field, make sure to set the Installment Type
field on the invoice (or the source object) to Custom
.
Info
You can use the ON field mechanism, Salesforce processes or other automation tools to have the Installment Type
field set automatically in this case.
Adding Installments to Subscriptions or Invoices
Depending on whether you use installment custom settings or apply custom installments using a JSON configuration, the steps for enabling installments on subscriptions or invoices differ.
Using Installment Custom Setting
After defining the installment setting, you must make it available for subscriptions or invoices, depending on your business requirements. To do so, you add the intended installment types to the value picklist for the Installment Type
field of the Subscription or Invoice object.
Make sure that the field Installment Type
is visible in the subscription or invoice layout. For help about modifying page layouts, see Managing Page Layouts.
- Navigate to the
Installment Type
field of the Subscription or Invoice object. - In the Values section, click New.
- Type the name of the defined installment type setting into the text area.
-
Click Save.
This makes the installment setting available for use with subscriptions or invoices. Repeat this step for every (previously defined) installment type that you want to make available.
For help about editing fields, see Managing Object Fields.
Using JSON Configuration
To hold the intended JSON configuration, you need the custom field CustomInstallment
on the Invoice object. You can fill this field from the subscription using the ON field mechanism. To this end, you create the field CustomInstallment
on the Invoice object as a text field (see Creating Custom Installment Field) and, in addition, the custom field ON_CustomInstallment
on the Subscription object.
- Navigate to the fields list of the Subscription object.
-
Create the following new field.
API Name Data Type Description ON_CustomInstallment Formula (Text) Specifies the formula that yields the JSON configuration for variable installments. As soon as you want to retrieve values from other fields, you use a formula. Make sure that in this case, you must apply Salesforce's rules for building formula fields (see Build a Formula Field in the Salesforce Help), namely enclosing the strings with quotation marks and combining the strings with the concatenation operator.
Assume a payment plan that involves two installments, with a fixed first installment whose amount is fetched from a custom Account field
First Installment
. The formula to produce the JSON as required would look as follows:'{' & ' "period": "1m(2)",' & ' "amount": "' & ONB2__Account__r.First_Installment__c & '",' & ' "titles": {' & ' "default":{' & ' "default":"Installment [PosNo]",' & ' "de":"Rate [PosNo]"' & ' }' & ' }' & '}'
Once set up, JustOn copies the JSON configuration produced by the formula to the invoice field
CustomInstallment
on invoice creation.
Adding Installments to Accounts or Arbitrary Objects
Depending on your business requirements, you can also make the installment settings available for use with accounts or objects based on which you create invoices using the generic invoice run. When defining an installment on the account or the accordingly configured source object, JustOn copies it to the invoice when creating an invoice for this account or from this object.
In addition, you can apply installments manually to draft or open invoices. This allows, for example, to help customers who have failed to pay an invoice: You retroactively provide a payment plan for an invoice that has already produced a dunning reminder.
Depending on whether you use installment custom settings or apply custom installments using a JSON configuration, the steps for enabling installments on accounts or invoice source objects differ.
Using Installment Custom Setting
Making installment settings available for use with accounts or invoice source objects involves two steps:
- Adding the field
ON_InstallmentType
to the Account or invoice source object - Adding the defined installment types to this field
To add the field ON_InstallmentType
to the Account or invoice source object:
- Navigate to the fields list of the corresponding object.
-
Create the following new field.
Label API Name Data Type Description Installment Type ON_InstallmentType Picklist
Text (255)
Formula (Text)Specifies the installment type, is copied to the invoice during the invoice run. For help about creating fields, see Managing Object Fields.
If you have created the field ON_InstallmentType
as a picklist, you must add the intended installment types to the corresponding value picklist.
- Navigate to the
ON_InstallmentType
field of the Account or invoice source object. - In the Values section, click New.
- Type the name of the defined installment type setting into the text area.
-
Click Save.
This makes the installment setting available for use with accounts or objects based on which you create invoices. Repeat this step for every (previously defined) installment type that you want to make available.
For help about editing fields, see Managing Object Fields.
Info
If you have created the field ON_InstallmentType
as a text or a text formula field, users must specify the exact name of the installment type that they want to apply.
Using JSON Configuration
To hold the intended JSON configuration, you need the custom field CustomInstallment
on the Invoice object. You can fill this field from the account or invoice source record using the ON field mechanism.
To this end, you create the following fields:
CustomInstallment
on the Invoice object as a text field (see Creating Custom Installment Field)ON_CustomInstallment
on the Account or invoice source objectON_InstallmentType
on the Account or invoice source object to be set toCustom
(see Setting Installment Type)
To create the custom field ON_CustomInstallment
:
- Navigate to the fields list of the Account or invoice source object.
-
Create the following new field.
API Name Data Type Description ON_CustomInstallment Formula (Text) Specifies the formula that yields the JSON configuration for variable installments. As soon as you want to retrieve values from other fields, you use a formula. Make sure that in this case, you must apply Salesforce's rules for building formula fields (see Build a Formula Field in the Salesforce Help), namely enclosing the strings with quotation marks and combining the strings with the concatenation operator.
Assume a payment plan that involves two installments, with a fixed first installment whose amount is fetched from a custom Account field
First Installment
. The formula to produce the JSON as required would look as follows:'{' & ' "period": "1m(2)",' & ' "amount": "' & ONB2__Account__r.First_Installment__c & '",' & ' "titles": {' & ' "default":{' & ' "default":"Installment [PosNo]",' & ' "de":"Rate [PosNo]"' & ' }' & ' }' & '}'
Once set up, JustOn copies the JSON configuration produced by the formula to the invoice field
CustomInstallment
on invoice creation.
Overwriting Titles for Individual Installments and Languages
You can create installment-specific and language-specific titles for individual installments.
When using fixed installments, you add additional title fields to the installment custom setting. The field names must follow a specific syntax in order to be applied by JustOn, as illustrated in the following examples.
Overwrite Target | Field Name | Examples |
---|---|---|
Title for the deposit installment | TitleDeposit__c |
Deposit |
Title for the deposit installment on German invoices | TitleDeposit_de__c |
Anzahlung |
Title for the first installment | Title1__c |
First Installment |
Title for the first installment on German invoices | Title1_de__c |
Erste Rate |
Title for the last installment | TitleLast__c |
Last Installment |
Title for the last installment on German invoices | TitleLast_de__c |
Schlussrate |
Title for the fifth installment | Title5__c |
Fifth Installment |
When using variable installments, you use the JSON key titles
to define a data map like "index" : { "language" : "value" }
.
"titles": {
"deposit":{
"default":"Deposit",
"de":"Anzahlung"
},
"1":{
"default":"First Installment",
"de":"Erste Rate"
},
"last":{
"default":"Last Installment",
"de":"Schlussrate"
},
"5":{
"default":"Fifth Installment"
}
}
The following example illustrates the behavior.
(1) Invoice
Field | Value |
---|---|
Grand Total | 100,00 |
Payment Due Date | 2017-12-31 |
Installment Type | Five by Month |
(2) Installment custom setting
Field | Value |
---|---|
Name | Five by Month |
Period | 1m(5) |
Rate | |
Amount | |
Title | Installment [PosNo] |
Title1__c | First Installment |
TitleLast__c | Last Installment |
(2) Custom installment JSON configuration
{
"period": "1m(5)",
"titles": {
"default":{
"default":"Installment [PosNo]"
},
"1":{
"default":"First Installment"
},
"last":{
"default":"Last Installment"
}
}
}
Resulting payment plan
Title | Date | Amount |
---|---|---|
First Installment |
2017-12-31 |
20,00 |
Installment 1 |
2018-01-31 |
20,00 |
Installment 2 |
2018-02-28 |
20,00 |
Installment 3 |
2018-03-31 |
20,00 |
Last Installment |
2018-04-30 |
20,00 |
Configuring Installment Table on Invoices
With an applied installment configuration, JustOn automatically prints the payment plan to the invoice PDF. There are two template fields that control the display of the corresponding installment information:
Template Field | Description |
---|---|
Installment Columns | Defines the columns for the installment table, must be a list of payment field names separated by semicolons. Defaults to Title__c;Date__c;Amount__c . |
Installments Text | Specifies text to be rendered above the installment table. |
To configure the contents of the installment table:
- Open the template to be edited.
-
In the Information section, double-click the
Installment Columns
field and specify the installment table configuration as required.Alternatively, you can click Edit in the detail view to edit the field.
-
Click Save.
To specify a text that introduces the payment plan:
- Open the template to be edited.
-
In the Additional Content section, double-click the
Installment Text
field and type the text as required.Alternatively, you can click Edit in the detail view to edit the field.
-
Click Save.
Hiding Deposit Installment on Invoice PDF
When creating installments, JustOn may create a deposit installment that represents the sum of payment balances assigned to the invoice. By default, the deposit payment is the first entry of the payment plan as printed to the invoice PDF. Depending on your requirements, however, you may decide not to show the received payment in the list of payments still to be made.
You can use a custom CSS rule to suppress the deposit payment row in the printed invoice:
- Open the template to be edited.
-
In the Layout & Design section, double-click the
Custom CSS
field and specify the following CSS code:.is-print-invoice .depositInstallmentRow { display: none; }
-
Click Save.
Next steps:
Setting up an installment type for a subscription
Setting up an installment type for an invoice
Creating installments manually from draft or open invoices
Return to JustOn Administration.