Enabling Installments

← Setting Up Invoice Options

To support staged payment plans for invoices, JustOn Billing & Invoice Management allows for setting up installments, which represent models for intended payment plans.

Enabling installments involves the following mandatory tasks:

Creating fixed installments via custom setting Installment OR creating variable installment configurations on 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
Adding the Installments button to the Invoice page layout

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

Installment Information

JustOn supports several use cases that rely on installments:

Fixed payment plans

You can calculate the payment plan based on a configurable number of installment payments and a configurable interval. Optionally, you can set fixed amounts or rates, otherwise JustOn distributes the amount equally to the installments. Once defined and set, this invariable model is applied to all accordingly produced invoices.

Service period-based payment plans

You may need to create installments that correspond to the service periods of invoice line items. So instead of configuring a model to be applied, you directly relate the payment plan to the service period months (or quarters). The resulting installment amounts for each invoice line item are evenly distributed across their respective service period fractions spanned by its total service period (as defined by the Invoice Line Item fields Service Period Start and Service Period End).

This provides for easily modeling recurring billing with "permanent" invoices.

For both fixed and service period-based payment plans, you can use the custom setting Installment.

Variable payment plans

You may have to cover individually negotiated conditions, like, for example, account-specific initial amounts. In this case, you also define a calculation model to be applied but allow for variable data (as individually retrieved from specific fields) as the input.

To support such scenarios, you apply custom installments using a JSON configuration.

Irrespective of the approach, the installment configuration provides the following information in custom setting fields or, respectively, JSON keys:

Field JSON Key	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.
Period `period`	The period controls the number of installment payments and their interval. JustOn supports two approaches: service period-based installments and calculated installments.
	For service period-based installments, the possible values include `Service Month` – creates one installment per service month between the service period start and service period end of the invoice line item `Service Quarter` – creates one installment per service quarter (= 3 service months) between the service period start and service period end of the invoice line item For service period-based installments, leave `Rate` and `Amount` blank. The resulting installment amounts are evenly distributed across their respective service period fractions.	`Service Month` = one installment for each service month
	For calculated installments, the configuration 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`(= the first installment 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)`. Since the first installment is bound to the payment due date – or, with `Date Reference`, to a custom date –, the first date definition for irregular dates determines the date of the second installment, the second that of the third, etc. However, you still need as many date definitions as intended installments. We recommend to use `0d` as the last one to complete the number.	`1m(12)` = 12 installments, due once per month `30d(6)` = 6 installments, due every 30 days `2m(4),120d` = 5 installments, the first four are due every two months, the last is due 120 days after the penultimate `30d,90d,0d` = 3 installments (with irregular dates), the first on the payment due date, the second 30 days after the first installment, the third 90 days after the second installment `fix,fix` = 2 installments, each referring to a fixed date (see date references)
Date Reference `dateReference`	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)`.
Rate `rate`	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 total `20,30,50` = 3 installments with 20%, 30% and 50% of the grand total `25` = one installment of 25%, the remaining 75% are distributed equally to the remaining installments
Amount `amount`	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 installments `50(2)` = 2 installments of 50 each, the remaining amount is distributed equally to the remaining installments.
Title `titles`	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 setting `Installment [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
`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
`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 dates

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]`

Since the first installment is bound to the payment due date – or, with Date Reference, to a custom date –, the first date definition in Period determines the date of the second installment, the second that of the third, etc. However, you still need as many date definitions as intended installments. We recommend to use 0d as the last one to complete the number.

Resulting payment plan

Title	Date	Amount	Rate
`Installment 1`	`2018-03-15`	`20,00`	`20`
`Installment 2`	`2018-04-01`	`30,00`	`30`
`Installment 3`	`2018-07-13`	`50,00`	`50`

Four installments, irregular dates, with custom date as anchor

Invoice

Field	Value
Grand Total	`1000,00`
Payment Due Date	`2021-07-15`
Invoice Date	`2021-07-01`
Date1__c	`2021-07-30`
Installment Type	`Four Irregular`

Installment custom setting

Field	Value
Name	`Four Irregular`
Period	`30d,90d,180d,0d`
Date Reference	`Date1__c(4)`
Rate
Amount
Title	`Installment [PosNo]`

Since the first installment is bound to the payment due date – or, with Date Reference, to a custom date –, the first date definition in Period determines the date of the second installment, the second that of the third, etc. However, you still need as many date definitions as intended installments. We recommend to use 0d as the last one to complete the number.

Resulting payment plan

Title	Date	Amount
`Installment 1`	`2021-07-30`	`250,00`
`Installment 2`	`2021-08-29`	`250,00`
`Installment 3`	`2021-11-27`	`250,00`
`Installment 4`	`2022-05-26`	`250,00`

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
`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 with prepaid balance

Field	Value
Grand Total	`100,00`
Date	`2018-06-01`
Payment Due Date	`2018-07-31`
Prepayment	`-40,00`
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	Open Payment Amount
`Installment 1`	`2018-07-31`	`25,00`	`0,00`
`Installment 2`	`2018-08-31`	`25,00`	`10,00`
`Installment 3`	`2018-09-30`	`25,00`	`25,00`
`Installment 4`	`2018-10-31`	`25,00`	`25,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
`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)` or `fix,fix,fix,fix`
Date Reference	`Date1__c,Date2__c,Date3__c,Date4__c`
Rate
Amount
Title	`Installment [PosNo]`

Resulting payment plan

Title	Date	Amount
`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, others based on payment due 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
`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, others based on payment due 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
`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`

Installments created per service month from invoice line item service periods

Assume an invoice (with a payment due of 10) created for a recurring item with a billing factor of 12.

#	Quantity	Unit Price	Billing Factor	Service Period Start	Service Period End	Tax Rate	Pos Total (net)
1	1	100,00	12	2019-04-15	2020-04-14	19%	1200,00

						Subtotal Net		1200,00
						Tax		228,00
						Grand Total		1428,00

For service month-based installments to work with one-time items, the billing factor and the billing unit must be empty.

Applying this installment custom setting

Field	Value
Period	`Service Month`
Rate
Amount
Title	`Installment [PosNo]`

Produces the following payment plan (note that the installment date is calculated using ServicePeriodStart + PaymentDue):

Title	Service Period Start	Service Period End	Date	Amount
Installment 1	2019-04-15	2019-05-14	2019-04-25	119,00
Installment 2	2019-05-15	2019-06-14	2019-05-25	119,00
Installment 3	2019-06-15	2019-07-14	2019-06-25	119,00
...
Installment 12	2020-03-15	2020-04-14	2020-03-25	119,00

To display the service period in the installment table on the invoice PDF, specify the following configuration in the Installment Columns Template field: Title__c;ServicePeriodStart__c;ServicePeriodEnd__c;Date__c;Amount__c.

Installments created per service quarter from invoice line item service periods (using a JSON configuration)

Invoice

Field	Value
Grand Total	`166,00`
Installment Type	`Custom`
CustomInstallment__c	`{` `"period":"Service Quarter",` `"titles":{` `"default":{` `"default":"Installment [PosNo]"` `}` `}` `}`

Invoice line items

#	Quantity	Price	Service Period Start	Service Period End
1	1	120,00	2019-04-01	2019-09-31
2	1	46,00	2019-04-01	2019-05-31

The service period of the first invoice line item spans two quarters, so the price of 120,00 will be distributed over two installments of 60,00 each. The service period of the second invoice line item is within the first quarter, so the complete price of 46,00 is added to the first installment, which results in 106,00:

Title	Service Period Start	Service Period End	Amount
Installment 1	2019-04-01	2019-06-30	106,00
Installment 2	2019-07-01	2019-09-31	60,00

To display the service period in the installment table on the invoice PDF, specify the following configuration in the Installment Columns Template field: Title__c;ServicePeriodStart__c;ServicePeriodEnd__c;Amount__c.

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.

Click to enter Setup, then 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.

To make it available for subscriptions and invoices, you must add it to the value picklist for the Installment Type field of the Subscription or Invoice object.

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.

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) to Custom

Note

Irrespective of whether there is an Installment custom setting named 'Custom' in the organization, the system will retrieve the JSON-based variable installment configuration from the CustomInstallment field once this field is set.

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]"
        }
    }
}

As another example, assume you want to create installments for every quarter between the service period start and the service period end of an invoice. Note that in this case, you do not need to provide an amount or rate, as JustOn calculates the installments as the sum of the proportional distribution of the invoice line item amounts. The corresponding JSON configuration would look like this:

{
    "period": "Service Quarter",
    "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 Area Specifies 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]"' &
'        }' &
'    }' &
'}'
```
Assume a payment plan that involves four installments on defined dates (using dateReference) and with defined rates (using rate), see Installment Information. The formula to produce the JSON as required would look as follows:
```
'{' &
'    "period": "fix,fix,fix,fix",' &
'    "dateReference": "' & "Date1__c" & ',' & "Date2__c" & ',' & "Date3__c" & ',' & "Date4__c" & '",' &
'    "rate": "' & TEXT(Rate1__c * 100) & ',' & TEXT(Rate2__c * 100) & ',' & TEXT(Rate3__c * 100) & ',' & TEXT(Rate4__c * 100) & '",' &
'    "titles": {' &
'        "default": {' &
'            "default": "Installment [PosNo]",' &
'            "de": "Rate [PosNo]"' &
'        }' &
'    }' &
'}'
```
Remember that date fields to be used as date reference must be defined on the invoice. You can still use the ON field mechanism (or other automation tools) to have them set automatically.

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 flows or other automation tools to have the Installment Type field set automatically in this case.

To allow for manually applying variable installments, you must add the value Custom to the value picklist for the Installment Type field of the Invoice object.

Navigate to the Installment Type field of the Invoice object.
In the Values section, click New.
Type Custom into the text area.
Click Save.

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.

The name must match one of the installment settings for fixed installments.
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 example configurations, see Installment Examples.

Info

If you have not created an installment setting for fixed installments named Default, you may want to remove the Default value from the picklist. To do so, click Deactivate in the row of the Default value in the Values section (see Modifying Picklist Values).

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]"' &
'        }' &
'    }' &
'}'
```
Assume a payment plan that involves four installments on defined dates (using dateReference) and with defined rates (using rate), see Installment Information. The formula to produce the JSON as required would look as follows:
```
'{' &
'    "period": "fix,fix,fix,fix",' &
'    "dateReference": "' & "Date1__c" & ',' & "Date2__c" & ',' & "Date3__c" & ',' & "Date4__c" & '",' &
'    "rate": "' & TEXT(Rate1__c * 100) & ',' & TEXT(Rate2__c * 100) & ',' & TEXT(Rate3__c * 100) & ',' & TEXT(Rate4__c * 100) & '",' &
'    "titles": {' &
'        "default": {' &
'            "default": "Installment [PosNo]",' &
'            "de": "Rate [PosNo]"' &
'        }' &
'    }' &
'}'
```
Remember that date fields to be used as date reference must be defined on the invoice. You can still use the ON field mechanism (or other automation tools) to have them set automatically.

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. Remember that installments are not allowed for canceled invoices.

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.

For example configurations, see Installment Examples.

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 object
ON_InstallmentType on the Account or invoice source object to be set to Custom (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]"' &
'        }' &
'    }' &
'}'
```
Assume a payment plan that involves four installments on defined dates (using dateReference) and with defined rates (using rate), see Installment Information. The formula to produce the JSON as required would look as follows:
```
'{' &
'    "period": "fix,fix,fix,fix",' &
'    "dateReference": "' & "Date1__c" & ',' & "Date2__c" & ',' & "Date3__c" & ',' & "Date4__c" & '",' &
'    "rate": "' & TEXT(Rate1__c * 100) & ',' & TEXT(Rate2__c * 100) & ',' & TEXT(Rate3__c * 100) & ',' & TEXT(Rate4__c * 100) & '",' &
'    "titles": {' &
'        "default": {' &
'            "default": "Installment [PosNo]",' &
'            "de": "Rate [PosNo]"' &
'        }' &
'    }' &
'}'
```
Remember that date fields to be used as date reference must be defined on the invoice. You can still use the ON field mechanism (or other automation tools) to have them set automatically.

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 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": {
    "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.

In addition, you can modify or translate the labels for the column headers.

Modifying Installment Table Columns

To configure the contents of the installment table:

Open the template to be edited.
In the Information section, click next to 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.

To display the service period for service period-based installments, for example, specify
```
Title__c;ServicePeriodStart__c;ServicePeriodEnd__c;Date__c;Amount__c
```
Click Save.

Modifying Installment Table Column Headers

The template field Override Labels allows to define new labels for the fields that are displayed in the installment table. The field value is in JSON notation. For details, see Configuring Override Labels.

To modify or translate the column header labels:

Open the template to be edited.
In the Overrides section, click next to the Override Labels field and specify the override definition in JSON as required.

Alternatively, you can click Edit in the detail view to edit the field.

To define new labels for the default fields, you can use, for example:
```
{
    "Payment__c": {
        "Title__c": "Installment Payment",
        "Date__c":"Due Date",
        "Amount__c":"Due Amount"
    }
}
```
Click Save.

Specifying Installment Note

To specify a text that introduces the payment plan:

Open the template to be edited.
In the Additional Content section, click next to 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.

Enabling Installment Creation for Single Invoices

To enable the option for individually creating or modifying a payment plan for individual invoices, you may have to manually add the Installments button to the invoice record page.

Note

When upgrading JustOn Billing & Invoice Management from a pre-2.98 version, you must remove the deprecated installments button (labeled Deprecated installments) from the layout and add the new Installments button.

Open the Invoice record detail page in the Lightning App Builder.
1. Navigate to an invoice.
2. Click to open the Setup menu, then select Edit Page.
Select the top panel ("Highlights").
Click Add Action and select the action Installments.
Click Done on the action window, then Save in the Lightning App Builder.

For details on managing action buttons, see How to hide or add action buttons?

Next steps:

Configuring an installment type for a subscription
Configuring an installment type for an invoice
Creating installments manually from draft or open invoices