Unapplied funds

BillingCenter manages payments and credits using unapplied funds. An unapplied fund is a T-account where money is stored before it is distributed to unpaid invoice items. All payments pass through an unapplied fund, even when they are distributed immediately.

BillingCenter automatically creates and modifies unapplied funds as needed. In the user interface, the only thing you can do is view information about them. Therefore, in Cloud API, the only REST method supported by the unapplied-funds endpoints is GET.

Use the following endpoints to retrieve information about an account's unapplied funds:

  • GET /billing/v1/accounts/{accountId}/unapplied-funds
  • GET /billing/v1/accounts/{accountId}/unapplied-funds/{unappliedFundId}

Unapplied funds for account-level billing accounts

If an account uses account-level billing, then it typically has a single default unapplied fund. For example, the following command retrieves the unapplied funds for account bc:505, which uses account-level billing.

Command

GET /billing/v1/accounts/bc:505/unapplied-funds
Response
{
    "count": 1,
    "data": [
        {
            "attributes": {
                "displayName": "Default",
                "id": "bc:SVR_B0B2oxbGhbxlWd2q9",
                "tAccount": {
                    "displayName": "Default Unapplied",
                    "id": "bc:SGFmh4LDkua9patoNbg6x"
                }
            },
            ...
        }
    ],
    ...

Unapplied funds for policy-level billing accounts

If an account uses policy-level billing, then it typically has multiple unapplied funds: a default unapplied fund for the account and one additional unapplied fund for each policy. For example, the following command retrieves the unapplied funds for account bc:606. This account uses policy-level billing and has one policy, PA-123456.

Command

GET /billing/v1/accounts/bc:606/unapplied-funds
Response
{
    "count": 2,
    "data": [
        {
            "attributes": {
                "displayName": "Default",
                "id": "bc:Sni0qvG6GCKZ6f2NBy6oT",
                "tAccount": {
                    "displayName": "Default Unapplied",
                    "id": "bc:SS5Q1UYTyCofJkXFUOPp1"
                }
            },
            ...
        },
        {
            "attributes": {
                "description": "PA-123456",
                "displayName": "PA-123456",
                "id": "bc:SrNPNmnkec1p81ANruzaG",
                "policy": {
                    "displayName": "PA-123456",
                    "id": "bc:9931",
                    "type": "Policy",
                    "uri": "/billing/v1/accounts/bc:606/policies/bc:9931"
                },
                "tAccount": {
                    "displayName": "Designated Unapplied (PA-123456)",
                    "id": "bc:S6oMTQUguwvoq2fj6XZ3I"
                }
            },
            ...
        }
    ],
    ...

Additional filter options

Some GET endpoints that return collections have filter options that may not appear in the API definition for one reason or another. This documentation refers to them as additional filter options.

The GET /billing/v1/accounts/{accountId}/unapplied-funds endpoint has the following additional filter options:

  • policyId

Unapplied funds balance

The unapplied fund resource does include a balance field, but it is not returned by default. You can use the fields query parameter to include it in the response.

For example, the following command retrieves all fields for the unapplied funds for account bc:606. Based on the response, there balance for the default unapplied fund is $0.00, and the balance for the policy unapplied fund is $120.00

Command

GET /billing/v1/accounts/bc:606/unapplied-funds?fields=*all

Response
{
    "count": 2,
    "data": [
        {
            "attributes": {
                "balance": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "displayName": "Default",
                "id": "bc:Sni0qvG6GCKZ6f2NBy6oT",
                "tAccount": {
                    "displayName": "Default Unapplied",
                    "id": "bc:SS5Q1UYTyCofJkXFUOPp1"
                }
            },
            ...
        },
        {
            "attributes": {
                "balance": {
                    "amount": "120.00",
                    "currency": "usd"
                },
                "description": "PA-123456",
                "displayName": "PA-123456",
                "id": "bc:SrNPNmnkec1p81ANruzaG",
                "policy": {
                    "displayName": "PA-123456",
                    "id": "bc:9931",
                    "type": "Policy",
                    "uri": "/billing/v1/accounts/bc:606/policies/bc:9931"
                },
                "tAccount": {
                    "displayName": "Designated Unapplied (PA-123456)",
                    "id": "bc:S6oMTQUguwvoq2fj6XZ3I"
                }
            },
            ...
        }
    ],
    ...