Plans and multicurrency

Multicurrency is a feature that allows BillingCenter to process financial transactions for different accounts or producers in different currencies. Multicurrency is not enabled in the base configuration. When multicurrency is enabled, you must specify the list of currencies that this instance of BillingCenter supports.

There are five plans that have one or more monetary values. These plans are collectively known as multicurrencyplans because they can support logic in multiple currencies. This includes payment plans, billing plans, delinquency plans, commission plans, and agency bill plans.

The fields in these plans that store monetary values typically specify a fee (such as an invoice fee) or a threshold (such as a write-off threshold). Thus, the currency fields in multicurrency plans are often collectively referred to as fees and thresholds. When multicurrency has been enabled, you can specify a fee or threshold in multiple currencies.

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

Currencies at the plan level

Specifying the supported currencies in a POST

Every plan has a currencies property which lists the currencies supported by that plan.

  • A plan can support only currencies supported by the instance of BillingCenter.
  • A plan is required to support at least one currency.
  • A plan can optionally support any number of additional currencies.

When creating a plan, list the currency or currencies it supports in the currencies array. For example, the following is a snippet of the creation of a billing plan that supports USD and CAD.

POST /admin/v1/billing-plans

{
  "data": {
    "attributes": {
      ...
      "currencies": [
          {
              "code": "usd"
          },
          {
              "code": "cad"
          }
      ],
    ...

Extending the supported currencies in a PATCH

If a plan is not in use, you can add and remove currencies. For example, the following is a snippet of the PATCHing of a billing plan that currently supports USD and CAD. The PATCH adds EUR.

PATCH /admin/v1/billing-plans/bc:1221

{
  "data": {
    "attributes": {
        "name": "Cloud API Multicurrency Plan",
        "aggregation": {
          "code": "charges"
        },
        "currencies": [
            {
                "code": "usd"
            },
            {
                "code": "cad"
            },
            {
                "code": "eur"
            }
        ],
...

Once a plan is in use, you can no longer modify its currencies through Cloud API.

Currencies at the fee/threshold level

Every fee and threshold can specify multiple currency values. The following restrictions apply:

  • A fee/threshold can specify only the currencies supported by its plan.
  • A single fee/threshold cannot specify two values in the same currency. For a given fee/threshold, every currency can be specified no more than once.

Unlike plan currencies, which are specified in an array, fee/threshold currencies are specified in maps. The syntax for specifying currencies is shown below:

"<feeThresholdName>": {
  "<currency>": "<value>",
  "<currency>": "<value>",
  ...
},

For example, the following is a snippet of POSTing a billing plan that supports USD, CAD, and EUR. Two invoice fee values have been specified: one for USD and one for CAD. Even though the plan supports EUR, no EUR-specific invoice fee has been specified.

POST /admin/v1/billing-plans

{
  "data": {
    "attributes": {
        "name": "Cloud API Multicurrency Plan",
        "aggregation": {
          "code": "charges"
        },
        "currencies": [
            {
                "code": "usd"
            },
            {
                "code": "cad"
            },
            {
                "code": "eur"
            }
        ],
        "invoiceFeeDefaults": {
          "usd": "11.00",
          "cad": "13.50"
        },
        ...

Unlike PATCHing arrays, PATCHing maps is additive, not destructive. For example, the following snippet PATCHes the billing plan from the previous example. In this PATCH, the existing CAD value is changed to 14.00 and a new EUR value of 15.00 is specified. USD is not mentioned in the PATCH, and therefore will retain its original value.

PATCH /admin/v1/billing-plans/bc:1221

{
  "data": {
    "attributes": {
        "invoiceFeeDefaults": {
          "cad": "14.00",
          "eur": "15.00"
        }
    }
  }
}