Payment allocation plans

A payment allocation plan is a set of values associated with accounts that determine how money in unapplied funds is allocated to unpaid invoice items. For a complete description of the business functionality of payment allocation plans, see the Application Guide.

Some functionality is common to all plans. This includes the following:

Plan order
Endpoints for plan testing
Multicurrency functionality with plans

For more information on the common functionality, see Overview of plans.

Two sets of criteria

Payment allocation plans have two sets of criteria:

Criteria that determine which invoice items are eligible to be paid (to have funds distributed to them)
Criteria that determine the order in which eligible items are paid

Distribution criteria

Payment allocation plans use a set of criteria to define the invoice items eligible to be paid (to have funds distributed to them). The criteria are additive. Invoice items must meet all criteria to be eligible.

The base configuration includes several distribution criteria. For example:

Billed or Due - Invoice items are eligible if they are on invoices that are billed or due.
Invoice - If the payment targets a specific invoice, only invoice items on that invoice are eligible.
Positive - Only invoice items with positive amounts are eligible.
Policy Period - If the payment targets a specific policy period, only invoice items on invoices for that policy period are eligible.
Next planned invoice - Invoice items are eligible if they are on billed or due invoices, or if they are on the next planned invoice.
Past due - Invoice items are eligible if they are on due invoices.

Invoice item ordering

If the total amount of all eligible invoice items is greater than the amount to be distributed, BillingCenter must determine which of the eligible invoice items will be paid. Payment allocation plans have a second set of criteria to specify the order in which the eligible invoice items are paid. These criteria are applied consecutively. Invoice items are ordered by the first criteria. Then, for invoice items with the same rank, invoice items are ordered by the second criteria, and so on.

The base configuration includes several distribution criteria. For example:

Recapture charges - Rank invoice items associated with recapture charges first.
Event date - Rank invoice items based on their placement dates.
Charge pattern - Rank invoice items according to the priority of their charge pattern.
Bill date - Rank invoice items based on the bill dates of their invoices.

Querying for payment allocation plans

Use the following endpoints to query for payment allocation plans:

GET /admin/v1/payment-allocation-plans
GET /admin/v1/payment-allocation-plans/{paymentAllocationPlanId}

For example, the following is a snippet of the response for retrieving the sample data's "Default Payment Allocation Plan" (cash_plan:1):

GET /admin/v1/payment-allocation-plans/cash_plan:1

{
    "data": {
        "attributes": {
            "description": "The default allocation plan...",
            "distributionCriteria": [
                {
                    "code": "BilledOrDue",
                    "name": "Billed or Due"
                },
                {
                    "code": "Invoice",
                    "name": "Invoice"
                },
                {
                    "code": "PolicyPeriod",
                    "name": "Policy Period"
                },
                {
                    "code": "Positive",
                    "name": "Positive"
                }
            ],
            "effectiveDate": "1990-01-01",
            "id": "cash_plan:1",
            "inUse": true,
            "invoiceItemOrderings": [
                {
                    "id": "ordering_type:1",
                    "invoiceItemOrderingType": {
                        "code": "RecaptureFirst",
                        "name": "Recapture Charges"
                    },
                    "priority": 1
                },
                {
                    "id": "ordering_type:2",
                    "invoiceItemOrderingType": {
                        "code": "EventDate",
                        "name": "Placement Date"
                    },
                    "priority": 2
                },
                {
                    "id": "ordering_type:3",
                    "invoiceItemOrderingType": {
                        "code": "ChargePattern",
                        "name": "Charge Pattern"
                    },
                    "priority": 3
                }
            ],
            "name": "Default Payment Allocation Plan",
            "planOrder": 1
        }
        ...

Note the following:

The plan specifies the following distribution criteria. Only invoice items meeting all criteria are eligible:
- Billed or Due (invoice items must be on invoices that are billed or due)
- Invoice (if the payment targets a specific invoice, only invoice items on that invoice are eligible)
- Policy Period (if the payment targets a specific policy period, only invoice items on invoices for that policy period are eligible)
- Positive (only invoice items with positive amounts are eligible)
The plan specifies the following invoice item ordering. If the total of unpaid invoice items is greater than the amount to allocate, invoice items are ordered using these criteria:
1. Recapture charges - Rank invoice items associated with recapture charges first.
2. Event date - Rank invoice items based on their placement dates.
3. Charge pattern - Rank invoice items according to the priority of their charge pattern.

The plan's planOrder value is 1. In the BillingCenter user interface, it is shown at the top of the list.

Creating payment allocation plans

Use the following endpoint to create a payment allocation plan:

POST /admin/v1/payment-allocation-plans

Minimum creation criteria

When you create a payment allocation plan, you must specify a name and an effective date. For example, the following payload is the minimum required to create a payment allocation plan:

POST /admin/v1/payment-allocation-plans

{
  "data": {
    "attributes": {
      "name": "Cloud API Default Payment Allocation Plan",
      "effectiveDate": "2020-01-01"
    }
  }
}

If you do not specify any distribution criteria, BillingCenter adds the following criteria by default:

Billed or Due
Invoice
Policy Period
Positive

If you do not specify any invoice item ordering criteria, BillingCenter adds the following criteria by default:

Recapture charges
Event date
Charge pattern

Thus, the payment allocation plan created above has the following attributes:

Name: Cloud API Default Payment Allocation Plan
Effective Date: January 1, 2020
Distribution criteria:
- Billed or Due
- Invoice
- Policy Period
- Positive
Invoice item ordering criteria:
1. Recapture charges
2. Event date
3. Charge pattern

Specifying distribution and invoice item ordering criteria

To specify distribution criteria, use the following syntax:

    "distributionCriteria": [
            {
                "code": "<typecode-from-DistributionFilterType-typelist>"
            },
            {
                "code": "<typecode-from-DistributionFilterType-typelist>"
            },
        ...
        ]

Distribution criteria are additive. You can declare them in any order.

To specify invoice item ordering criteria, use the following syntax:

    "invoiceItemOrderings": [
        {
            "invoiceItemOrderingType": {
                "code": "<typecode-from-InvoiceItemOrderingType-typelist>"
                }
        },
        {
            "invoiceItemOrderingType": {
                "code": "<typecode-from-InvoiceItemOrderingType-typelist>"
                }
        }      
    ]

Invoice item ordering criteria are ordered. When POSTing a new payment allocation plan, the first criteria in the payload is given a priority of 1 (it is executed first), the second is given a priority of 2 (it is executed second), and so on.

Example of creating a payment allocation plan with non-default criteria

For example, the following payload creates a payment allocation plan with the following criteria:

Distribution criteria of "Positive" and "Billed or Due"
Invoice item ordering criteria of "Charge pattern" (priority 1) and then "Event date" (priority 2)

POST /admin/v1/payment-allocation-plans

{
  "data": {
    "attributes": {
      "name": "Cloud API Specified Criteria Payment Allocation Plan",
      "effectiveDate": "2020-02-02"
      "distributionCriteria": [
        {
          "code": "Positive"
        },
        {
          "code": "BilledOrDue"
        }           
        ],
      "invoiceItemOrderings": [
        {
          "invoiceItemOrderingType": {
            "code": "ChargePattern"
            }
        },
        {
          "invoiceItemOrderingType": {
            "code": "EventDate"
            }
        }      
      ]
    }
  }
}

Modifying payment allocation plans

PATCHing payment allocation plans

Use the following endpoint to PATCH an existing payment allocation plan:

PATCH /admin/v1/payment-allocation-plans/{paymentAllocationPlanId}

When a payment allocation plan is assigned to at least one account, BillingCenter considers the plan to be in use.

When a plan is not in use:

Its inUse field is set to false.
The entire plan can be modified.

When a plan is in use:

Its inUse field is set to true.
Through Cloud API, only expirationDate and planOrder can be modified.

For example, the following changes payment allocation plan bc:5665 so that the effective date is March 3, 2020.

If the plan is not in use, the PATCH is successful.
If the plan is in use, the PATCH fails because it specifies a value that is not expirationDate.

PATCH /admin/v1/payment-allocation-plans/bc:5665

{
  "data": {
    "attributes": {
        "effectiveDate": "2020-03-03",
    }
  }
}

distributionCriteria and invoiceItemOrderings are both arrays. Keep in mind that, within Cloud API, PATCHing an array does not add new members to the existing members. It replaces the existing members with the new members.

If you want to add new distribution criteria or new invoice item ordering criteria to an existing payment allocation plan, you must first determine the existing criteria, and then specify an array with those criteria and the ones you wish to add. In the case of invoiceItemOrderings, you must also list old and new criteria in the desired order.

DELETEing payment allocation plans

Use the following endpoint to DELETE an existing payment allocation plan:

DELETE /admin/v1/payment-allocation-plans/{paymentAllocationPlanId}

When a delinquency plan is assigned to at least one account, BillingCenter considers the plan to be in use. When a plan is in use, it cannot be deleted.

For example, the following deletes delinquency plan bc:5665 (assuming that it is not in use).

DELETE /admin/v1/delinquency-plans/bc:5665

<no request body>