Delinquency plans

A delinquency plan is a set of values and delinquency workflows that determine how to execute delinquencies for a given set of accounts or policies. When you create an account, you must explicitly specify a delinquency plan. You cannot create an account without a delinquency plan. (You can optionally specify a delinquency plan for a policy. If a policy has no delinquency plan, the account's plan is used.)

As of this release, there is no mechanism in Cloud API for working with delinquency plan workflow values (reasons and events.) To create or modify these values, you must work directly with BillingCenter or through some other existing integration.

Querying for delinquency plans

Use the following endpoints to query for delinquency plans:

  • GET /admin/v1/delinquency-plans
    • Retrieves information on all delinquency plans
  • GET /admin/v1/delinquency-plans/{delinquencyPlanId}
    • Retrieves information about the specified delinquency plan

For example, the following is a snippet of the response for retrieving the sample data's "Standard Delinquency Plan" delinquency plan (bc:202):

GET /admin/v1/delinquency-plans/bc:202

{
  "data": {
    "attributes": {
      "acctEnterDelinquencyThresholdDefaults": {
        "usd": "10.00"
      },
      "applicableSegments": {
        "code": "all"
      },
      "cancellationTarget": {
        "code": "DelinquentPolicyOnly"
      },
      "cancellationThresholdDefaults": {
        "usd": "11.00"
      },
      "currencies": [
        {
          "code": "usd"
        }
      ],
      "description": "Enter Delinquency at 10",
      "effectiveDate": "2022-03-28",
      "exitDelinquencyThresholdDefaults": {
        "usd": "5.00"
      },
      "gracePeriodDayUnit": {
        "code": "calendar"
      },
      "gracePeriodDays": 0,
      "holdInvoicingOnDlnqPolicies": false,
      "id": "bc:202",
      "inUse": true,
      "lateFeeAmountDefaults": {
        "usd": "100.00"
      },
      "name": "Standard Delinquency Plan",
      "planOrder": 1,
      "polEnterDelinquencyThresholdDefaults": {
        "usd": "10.00"
      },
      "reinstatementFeeAmountDefaults": {
        "usd": "100.00"
      },
      "writeoffThresholdDefaults": {
        "usd": "0.00"
      }
    },

Creating delinquency plans

Use the following endpoint to create a delinquency plan:

  • POST admin/v1/delinquency-plans

Threshold values

A delinquency plan has five threshold values:

  • cancellationThresholdDefaults
  • acctEnterDelinquencyThresholdDefaults
  • polEnterDelinquencyThresholdDefaults
  • exitDelinquencyThresholdDefaults
  • writeoffThresholdDefaults

There is validation logic requiring these values to be higher or lower than the other values.

  • The cancellationThresholdDefaults value (referred to in the following table as "High threshold") must be greater than all other threshold values.
  • The acctEnterDelinquencyThresholdDefaults and exitDelinquencyThresholdDefaults values (referred to in the following table as "Middle threshold") can have the same value or different values. But both must be less than cancellationThresholdDefaults and both must be greater than both exitDelinquencyThresholdDefaults and writeoffThresholdDefaults.
    • The exitDelinquencyThresholdDefaults and writeoffThresholdDefaults values (referred to in the following table as "Low threshold") can have the same value or different values. But both must be less than all other threshold values.

Minimum creation criteria

When you create a delinquency plan, you must specify the values in the following table.

Field Value Comments
Non-threshold values
cancellationTarget A value from the CancellationTarget typelist
currencies Array of currency codes
effectiveDate datetime
gracePeriodDays integer
gracePeriodDayUnit A value from the DayUnit typelist
holdingInvoicingOnDlnqPolicies Boolean
name string
High threshold
cancellationThresholdDefaults Decimal This value must be greater than all other threshold defaults.
Middle threshold
acctEnterDelinquencyThresholdDefaults Decimal This value must be lower than cancellationThresholdDefaults, but higher than the two "low threshold" values.
polEnterDelinquencyThresholdDefaults Decimal This value must be lower than cancellationThresholdDefaults, but higher than the two "low threshold" values.
Low threshold
exitDelinquencyThresholdDefaults Decimal This value must be lower than cancellationThresholdDefaults and the "middle threshold" values.
writeoffThresholdDefaults Decimal This value must be lower than cancellationThresholdDefaults and the "middle threshold" values.

Example of creating a delinquency plan

For example, the following creates a new delinquency plan:

POST /admin/v1/delinquency-plans

{
  "data": {
    "attributes": {
      "cancellationTarget": {
        "code": "DelinquentPolicyOnly"
      },
      "currencies": [
        {
          "code": "usd"
        }
      ],
      "effectiveDate": "2022-03-28",
      "gracePeriodDays": 0,
      "gracePeriodDayUnit": {
        "code": "calendar"
      },
      "holdInvoicingOnDlnqPolicies": false,
      "name": "Cloud API Delinquency Plan",
      "cancellationThresholdDefaults": {
        "usd": "11.00"
      },
      "acctEnterDelinquencyThresholdDefaults": {
        "usd": "10.00"
      },
      "polEnterDelinquencyThresholdDefaults": {
        "usd": "10.00"
      },
      "exitDelinquencyThresholdDefaults": {
        "usd": "5.00"
      },
      "writeoffThresholdDefaults": {
        "usd": "0.00"
      }
    }
  }
}

Modifying delinquency plans

PATCHing delinquency plans

Use the following endpoint to PATCH an existing delinquency plan:

  • PATCH /delinquency-plans/{delinquencyPlanId}

When a delinquency plan is assigned to at least one account or policy, 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.
  • Only the expirationDate can be modified.

For example, the following changes delinquency plan bc:202 so that grace period is calculated in calendar days and the plan expires on June 6, 2025.

  • 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/delinquency-plans/bc:202

{
  "data": {
    "attributes": {
        "expirationDate": "2025-06-06",
        "gracePeriodDayUnit": {
            "code": "calendar"
        }
    }
  }
}

DELETEing delinquency plans

Use the following endpoint to DELETE an existing delinquency plan:

  • DELETE /delinquency-plans/{delinquencyPlanId}

When a delinquency plan is assigned to at least one account or policy, 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:202 (assuming that it is not in use).

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

<no request body>