Charges and charge patterns

Every account typically has one or more policies.

When BillingCenter receives information about a policy, it typically comes with billing requirements for that policy. These billing requirements are stored in BillingCenter as charges.

A charge is a cost related to either a policy period or an account that must be processed and tracked as an individual unit. For example, a Personal Auto policy could have three charges:

  • A $1200 charge for the premium
  • A $53 charge for taxes
  • A $10 charge for an installment fee

BillingCenter categorize charges using charge patterns. The role of a charge pattern is to identify the charge type and how BillingCenter handles charges of this type.

The following topic discusses how to manage charge patterns through Cloud API.

Overview of charge patterns

BillingCenter categorize charges using charge patterns. The role of a charge pattern is to identify the charge type and how BillingCenter handles charges of this type.

Every charge pattern specifies the following:

  • Subtype – The broad type of charge pattern. In the base configuration, the following types are used during the charge invoicing process:
    • ImmediateCharge – Charges that do not recur and can immediately be recognized as revenue, such as late fees.
    • PassThroughCharge – Charges that are never recognized as revenue and merely pass through the insurer’s accounting system, such as taxes or regulatory fees.
    • ProRataCharge – Charges that are initially entered as unearned and subsequently become earned proportionately over time, such as premium.
  • Category – A more granular identification of the charge pattern's type, such as Fee, General, Premium, or Tax.
  • InvoiceTreatment – Whether the charge can billed over multiple invoices or must be billed on a single invoice.

For more information on the business functionality of charge patterns, see the Application Guide.

Working with charge patterns

Querying for charge patterns

Use the following endpoints to retrieve information about charge patterns:

  • GET /admin/v1/charge-patterns
  • GET /admin/v1/charge-patterns/{chargePatternId}

For example, the following request retrieves information about charge pattern default_data:16.

GET /admin/v1/charge-patterns/default_data:16

{
    "data": {
        "attributes": {
            "category": {
                "code": "premium",
                "name": "Premium"
            },
            "chargeCode": "PremiumIncludingTaxes",
            "chargeName": "Premium Including Taxes",
            "id": "default_data:16",
            "includedInEquityDating": true,
            "internalCharge": true,
            "invoiceTreatment": {
                "code": "depositandinstallments",
                "name": "Down Payment and Installments"
            },
            "periodicity": {
                "code": "monthly",
                "name": "Monthly"
            },
            "priority": {
                "code": "medium",
                "name": "Medium"
            },
            "reversible": false,
            "subtype": "ProRataCharge",
            "tAccountOwnerType": "PolicyPeriod",
            "tAccountsLazyLoaded": true
        }
        ...
    }
}

Creating charge patterns

To create a charge pattern, use the following endpoint:

  • POST /admin/v1/charge-patterns

When you create a charge pattern, you must specify all the fields in the following table.

Name Datatype Comments
category A value from the ChargeCategory typelist, such as premium or tax
chargeCode A unique code for the charge pattern
chargeName A user-friendly name for the charge pattern
includedInEquityDating Boolean
invoiceTreatment A value from the InvoiceTreatment typelist, such as depositandinstallments or onetime
periodicity A value from the Periodicity typelist, such as monthly or weekly This field is required only for ProRataCharge charge patterns.
subtype The charge pattern's subtype, such as ProRataCharge or ImmediateCharge
tAccountOwnerType

The type of entity that owns the T-account that tracks this type of charge.

 The valid values for this field depend on the charge pattern's subtype. For example, for ProRataCharge charge patterns, the only valid value isPolicyPeriod. For a complete discussion of the valid values, see the Application Guide.
tAccountsLazyLoaded Boolean

For example, the following request creates a new charge pattern.

POST /admin/v1/charge-patterns

{
  "data": {
    "attributes": {
        "category": {
            "code": "premium"
        },
        "chargeCode": "PremiumExcludingTaxes",
        "chargeName": "Premium Excluding Taxes",
        "includedInEquityDating": true,
        "invoiceTreatment": {
            "code": "depositandinstallments"
        },
        "periodicity": {
            "code": "monthly"
        },
        "subtype": "ProRataCharge",
        "tAccountOwnerType": "PolicyPeriod",
        "tAccountsLazyLoaded": true
    }
  }
}

Working with charges

A charge is a cost related to either a policy period or an account that must be processed and tracked as an individual unit. For example, a Personal Auto policy could have three charges:

  • A $1200 charge for the premium

  • A $53 charge for taxes

  • A $10 charge for an installment fee

Some charges are billed over a series of invoices, such as a charge that is billed as a down payment and a set of monthly installments. To enable this, BillingCenter does not place charges directly onto invoices. Instead, BillingCenter converts every charge into one or more invoice items and then places these invoice items on invoices. An invoice item is a line item that represents all or part of a charge.

Cloud API provides endpoints for working with charges and their invoice items.

Querying for charges

A charge can be associated directly with an account (an account-level charge) or with an account's policy's period (a policy-level charge). You can use the following endpoints to query for charges associated with a given account or policy period:

  • GET /billing/v1/accounts/{accountId}/charges

  • GET /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/(policyPeriodId}/charges

For more information, see Account-level charges and Policy-level charges.

Accessing a specific charge

Use the following endpoint to access a specific charge:

  • GET /billing/v1/charges/{chargeId}

A call to this endpoint is typically preceded by a call to retrieve the charges for an account or policy period, as described in the previous topic.

For example, suppose you query for a policy period's charges and identify that there is one premium charge whose id is bc:1212. The following request accesses that specific charge.

Command

GET /billing/v1/charges/bc:1212

Response payload

{
    "data": {
        "attributes": {
            "amount": {
                "amount": "1200.00",
                "currency": "usd"
            },
            "chargeDate": "2023-05-24T17:58:44.732Z",
            "chargePattern": {
                "displayName": "Premium",
                "id": "default_data:1"
            },
            "holdStatus": {
                "code": "none",
                "name": "Not Held"
            },
            "id": "bc:1212",
            "reversed": false,
            "skipInvoiceItemCreation": false,
            "totalInstallments": 9,
            "writtenDate": "2023-05-24T17:58:43.762Z"
        },
        ...

Accessing invoice items

Use the following endpoints to access the invoice items for a given charge:

  • GET /billing/v1/charges/{chargeId}/invoice-items

  • GET /billing/v1/charges/{chargeId}/invoice-items/{invoiceItemId}

For example, the following request retrieves the invoice items for charge bc:1212. The response as shown below includes the first two invoice items: the down payment item and the first installment item.

Command

GET /billing/v1/charges/bc:1212/invoice-items

Response payload

{
    "count": 10,
    "data": [
        {
            "attributes": {
                "amount": {
                    "amount": "120.00",
                    "currency": "usd"
                },
                "eventDate": "2023-04-29",
                "id": "bc:STfiGLle2rKWvhYwGLYlA",
                "invoiceDateOverride": {
                    "code": "none",
                    "name": "None"
                },
                "reversed": false,
                "type": {
                    "code": "deposit",
                    "name": "Down Payment"
                }
            },
            ...
        },
        {
            "attributes": {
                "amount": {
                    "amount": "120.00",
                    "currency": "usd"
                },
                "eventDate": "2023-07-01",
                "id": "bc:SIN97D4oBanb3p5_IjrAL",
                "installmentNumber": 1,
                "invoiceDateOverride": {
                    "code": "none",
                    "name": "None"
                },
                "reversed": false,
                "type": {
                    "code": "installment",
                    "name": "Installment"
                }
            },
            ...
        },
        ...