Changing a policy’s payment plan

An insurer can change a payment plan on a policy at any point during the policy period. This can be done in the BillingCenter user interface or using Cloud API.

When a payment plan is changed, BillingCenter reslices some or all of the charges for that policy period into new invoice items. These invoice items are placed onto new invoices. If any resliced item has been partially or fully paid, BillingCenter undistributes the money paid to these items and places it in an unapplied fund.

When changing payment plans, insurers can decide:

  • Which invoice items are affected
  • If money paid towards the invoice items is redistributed or not
  • Whether down payments are included in the reslicing

Previewing a payment plan change

You can preview the effects of a payment plan change as described in Preview a payment plan change.

Which invoice items are affected

When a payment plan is changed, a new set of invoices is created. The insurer decides which of the invoices items on the policy period are resliced and placed onto the new set of invoices. There are three options:
  • All invoice items - BillingCenter reslices all invoice items, regardless of which have been billed for or paid.
  • Planned items - BillingCenter reslices planned invoice items only and leaves the billed and due invoice items as is.
  • Not fully paid items - BillingCenter reslices the unpaid and partially paid invoice items only and leaves the fully paid invoice items as is.

Payment redistribution

If money has been applied to an invoice item that is going to be resliced, BillingCenter always undistributes the amount by placing it in the appropriate unapplied fund before reslicing. This money can be redistributed automatically to the new invoice items, or it can remain in the unapplied fund.

Down payments

Down payments can be given special treatment in certain circumstances when changing a payment plan. In situations where only planned invoice items are affected by a payment plan change, and the down payment has already been partially or fully paid, the insurer can choose to include down payment items in the reslicing. This means that:
  • The money for the paid down payment is added to an unapplied fund
  • The down payment item for the new payment plan is placed onto a new invoice

Special down payment treatment does not apply to out-of-sequence first installments.

For more information on payment plan changes, see the BillingCenter Application Guide.

Change a payment plan using Cloud API

Use the following endpoint to change a payment plan:

  • POST /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/change-payment-plan

There are three required fields when changing a payment plan:

Field Data type Description
invoiceItemsToInclude Typekey reference Reference to a typecode in the InvoiceItemFilterType typelist. Can be planneditems, allitems, or notfullypaiditems.
paymentPlan String The id of the new payment plan.
redistributePayments Boolean Whether to redistribute payment items or leave undistributed money in the unapplied fund.

The following field is optional when changing a payment plan:

Field Data type Description
includeDownPaymentItems Boolean Whether to include down payment items in reslicing. Default is false.

The includeDownPaymentItems field can be set whenever changing a payment plan. However, if all items are affected by the payment plan change, includeDownPaymentItems has no effect.

When changing payment plans, the following must be true:
  • The affected policy period is not archived.
  • If changing a payment plan for a policy period on a list bill account, the new payment plan is in the list of payment plans on the account.
Note: When changing a payment plan in the BillingCenter user interface, equity warnings alert you if a change will violate the recommended amount of equity. The user interface gives you the opportunity to cancel when this warning is shown. However, there is no mechanism to warn you about equity violations in Cloud API. The payment plan is changed whether or not the recommended equity is violated.

Example request

The example below provides a minimal change payment plan request.

In this example:
  • Only planned invoice items are resliced, plus the down payment, regardless of its billed status
  • The down payment for the old plan is reversed, and the down payment of the new plan is included in the newly-sliced invoice items
  • Any payments that have been made on planned invoices are redistributed
  • The new payment plan will be the payment plan with id bc:Swg0ZXoiI7If8P9w4JRqL
Command
POST /billing/v1/accounts/bc:SB8S98/policies/bc:S1jN86AM/policy-periods/bc:SLAC88W/change-payment-plan
Request body
{
    "data": {
        "attributes": {
            "includeDownPaymentItems": true,
            "invoiceItemsToInclude": {
                "code": "planneditems"
            },
            "paymentPlan": {
                "id": "bc:Swg0ZXoiI7If8P9w4JRqL"
            },
            "redistributePayments": true
        }
    }
}
Response
{
    "data": {
        "attributes": {
            "assignedRisk": false,
            "billingMethod": {
                "code": "DirectBill",
                "name": "Direct Bill"
            },
            "boundDate": "2024-06-28",
            "cancelStatus": {
                "code": "open",
                "name": "Open"
            },
            "chargeHeld": false,
            "closureStatus": {
                "code": "open",
                "name": "Open"
            },
            "confirmationNotificationState": {
                "code": "Notified",
                "name": "Notified"
            },
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "effectiveDate": "2024-06-28",
            "eligibleForFullPayDiscount": false,
            "equityBuffer": 30,
            "equityWarningsEnabled": true,
            "expirationDate": "2025-06-28",
            "fullPayDiscountEvaluated": false,
            "heldForInvoiceSending": false,
            "holdInvoicingWhenDelinquent": false,
            "id": "bc:S1OzDwkJOK9klnDF6cdCP",
            "offerNumber": "Acc B Policy A",
            "paymentDistributionEnabled": true,
            "paymentPlan": {
                "displayName": "D Quarterly 30% Down, 3 Max installments",
                "id": "bc:Swg0ZXoiI7If8P9w4JRqL",
                "type": "PaymentPlan",
                "uri": "/admin/v1/payment-plans/bc:Swg0ZXoiI7If8P9w4JRqL"
            },
            "pendingRemainingBalanceFix": false,
            "policyNumber": "Acc B Policy A",
            "policyNumberLong": "Acc B Policy A-1",
            "retrieved": false,
            "returnPremiumPlan": {
                "displayName": "Default Return Premium Plan",
                "id": "ret_premium_plan:1",
                "type": "ReturnPremiumPlan",
                "uri": "/admin/v1/return-premium-plans/ret_premium_plan:1"
            },
            "termConfirmed": true,
            "termNumber": 1,
            "westernMethod": false
        }
    }
}

The policy period object is returned. The paymentPlan field is the only field that has been changed on this object.

Viewing results of a payment plan change

To see the results of changing the payment plan, query for the invoices or invoice items themselves.

On invoices, you can see the total amount due for that invoice. For information on retrieving invoices, see Working with invoices.

In the base configuration, the original invoices remain in the invoice stream. However, because the original invoice items on these invoices are reversed, there may be no amount due on them.

To view invoice items, you must query for them separately. For more, see Working with invoice items.

Preview a payment plan change

You can use Cloud API to preview what a policy period's new invoice items would look like after a payment plan change without persisting any data to the database.

This Cloud API feature duplicates the functionality of the "Change Payment Plan" screen in the BillingCenter, which shows the new values of resliced invoice items. You can preview a payment plan change with the following endpoint: POST /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/change-payment-plan-preview

The endpoint accepts the same required fields in the request body as the POST /change-payment-plan endpoint.

Payment plan change preview items

The request returns a response object with an array of preview items. A preview item is a data object that represents an invoice item that BillingCenter would create in the event of an actual payment plan change. Preview items are not stored in the database and only exist within individual API calls.

Preview items include the following information:

  • The amount of the invoice item
  • The category of the charge
  • The payer account
  • The invoice stream
  • The type of invoice item (such as installment, one-time, or down payment)

The previewItems array contains the preview items created by the payment plan change preview. Items that are reversed by the change appear in the preview as items with an amount of $0.

Example of a payment plan change preview

A policy with a single premium charge of $1000 uses a "Monthly 10% Down, 9 Max installments" payment plan. $150 of the premium has been paid, covering the down payment and half of the first installment.

An application wants to change the payment plan to "Quarterly 30% Down, 3 Max installments." They want all invoice items to be resliced and for paid funds to be redistributed to the new invoice items. To preview this change, they would send the following request:

Command

POST /billing/v1/accounts/bc:SB8S98/policies/bc:S1jN86AM/policy-periods/bc:SLAC88W/change-payment-plan-preview

Request body

{
  "data": {
    "attributes": {
      "includeDownPaymentItems": true,
      "invoiceItemsToInclude": {
        "code": "allitems"
      },
      "paymentPlan": {
        "id": "bc:Sf3jkQ5H7DJhc0bJukjmc"
      },
      "redistributePayments": true
    }
  }
}

The response includes six preview items:

  • Two items with $0 due from the original down payment and first installment, which were reversed and show up as $0 invoice items.
  • One down payment item for $300. This is included because includeDownPaymentItems is set to true, and $150 has been paid against it because redistributePayments is set to true.
  • Three installment items for $233.33.

Response

{
  "data": {
    "attributes": {
      "previewItems": [
        {
          "amount": {
            "amount": "0.00",
            "currency": "usd"
          },
          "category": {
            "code": "premium",
            "name": "Premium"
          },
          "eventDate": "2025-10-15",
          "invoiceStream": {
            "displayName": "Monthly",
            "id": "bc:SwxykiTRreHoEACmu81Ox",
            "type": "AccountInvoiceStream",
            "uri": "/billing/v1/accounts/bc:SB8S98/invoice-streams/bc:SwxykiTRreHoEACmu81Ox"
          },
          "paidAmount": {
            "amount": "0.00",
            "currency": "usd"
          },
          "payerAccount": {
            "displayName": "Map-100-Elevator",
            "id": "bc:SMmGnBqgVLm3hf6zsjIGh",
            "type": "Account",
            "uri": "/billing/v1/accounts/bc:SB8S98"
          },
          "paymentDueDate": "2025-10-22",
          "type": {
            "code": "deposit",
            "name": "Down Payment"
          }
        },
        {
          "amount": {
            "amount": "0.00",
            "currency": "usd"
          },
          "category": {
            "code": "premium",
            "name": "Premium"
          },
          "eventDate": "2025-11-15",
          "invoiceStream": {
            "displayName": "Monthly",
            "id": "bc:SwxykiTRreHoEACmu81Ox",
            "type": "AccountInvoiceStream",
            "uri": "/billing/v1/accounts/bc:SB8S98/invoice-streams/bc:SwxykiTRreHoEACmu81Ox"
          },
          "paidAmount": {
            "amount": "0.00",
            "currency": "usd"
          },
          "payerAccount": {
            "displayName": "Map-100-Elevator",
            "id": "bc:SMmGnBqgVLm3hf6zsjIGh",
            "type": "Account",
            "uri": "/billing/v1/accounts/bc:SB8S98"
          },
          "paymentDueDate": "2025-11-22",
          "type": {
            "code": "installment",
            "name": "Installment"
          }
        },
        {
          "amount": {
            "amount": "300.00",
            "currency": "usd"
          },
          "category": {
            "code": "premium",
            "name": "Premium"
          },
          "eventDate": "2025-12-15",
          "invoiceStream": {
            "displayName": "Monthly",
            "id": "bc:SwxykiTRreHoEACmu81Ox",
            "type": "AccountInvoiceStream",
            "uri": "/billing/v1/accounts/bc:SB8S98/invoice-streams/bc:SwxykiTRreHoEACmu81Ox"
          },
          "paidAmount": {
            "amount": "150.00",
            "currency": "usd"
          },
          "payerAccount": {
            "displayName": "Map-100-Elevator",
            "id": "bc:SMmGnBqgVLm3hf6zsjIGh",
            "type": "Account",
            "uri": "/billing/v1/accounts/bc:SB8S98"
          },
          "paymentDueDate": "2025-12-22",
          "type": {
            "code": "deposit",
            "name": "Down Payment"
          }
        },
        {
          "amount": {
            "amount": "233.34",
            "currency": "usd"
          },
          "category": {
            "code": "premium",
            "name": "Premium"
          },
          "eventDate": "2026-01-15",
          "invoiceStream": {
            "displayName": "Monthly",
            "id": "bc:SwxykiTRreHoEACmu81Ox",
            "type": "AccountInvoiceStream",
            "uri": "/billing/v1/accounts/bc:SB8S98/invoice-streams/bc:SwxykiTRreHoEACmu81Ox"
          },
          "paidAmount": {
            "amount": "0.00",
            "currency": "usd"
          },
          "payerAccount": {
            "displayName": "Map-100-Elevator",
            "id": "bc:SMmGnBqgVLm3hf6zsjIGh",
            "type": "Account",
            "uri": "/billing/v1/accounts/bc:SB8S98"
          },
          "paymentDueDate": "2026-01-22",
          "type": {
            "code": "installment",
            "name": "Installment"
          }
        },
        {
          "amount": {
            "amount": "233.33",
            "currency": "usd"
          },
          "category": {
            "code": "premium",
            "name": "Premium"
          },
          "eventDate": "2026-04-15",
          "invoiceStream": {
            "displayName": "Monthly",
            "id": "bc:SwxykiTRreHoEACmu81Ox",
            "type": "AccountInvoiceStream",
            "uri": "/billing/v1/accounts/bc:SB8S98/invoice-streams/bc:SwxykiTRreHoEACmu81Ox"
          },
          "paidAmount": {
            "amount": "0.00",
            "currency": "usd"
          },
          "payerAccount": {
            "displayName": "Map-100-Elevator",
            "id": "bc:SMmGnBqgVLm3hf6zsjIGh",
            "type": "Account",
            "uri": "/billing/v1/accounts/bc:SB8S98"
          },
          "paymentDueDate": "2026-04-22",
          "type": {
            "code": "installment",
            "name": "Installment"
          }
        },
        {
          "amount": {
            "amount": "233.33",
            "currency": "usd"
          },
          "category": {
            "code": "premium",
            "name": "Premium"
          },
          "eventDate": "2026-07-15",
          "invoiceStream": {
            "displayName": "Monthly",
            "id": "bc:SwxykiTRreHoEACmu81Ox",
            "type": "AccountInvoiceStream",
            "uri": "/billing/v1/accounts/bc:SB8S98/invoice-streams/bc:SwxykiTRreHoEACmu81Ox"
          },
          "paidAmount": {
            "amount": "0.00",
            "currency": "usd"
          },
          "payerAccount": {
            "displayName": "Map-100-Elevator",
            "id": "bc:SMmGnBqgVLm3hf6zsjIGh",
            "type": "Account",
            "uri": "/billing/v1/accounts/bc:SB8S98"
          },
          "paymentDueDate": "2026-07-22",
          "type": {
            "code": "installment",
            "name": "Installment"
          }
        }
      ]
    }
  }
}