---
title: "Get the balance"
url: https://docs.corefinity.com/api/reference/billing/get-billing-balance
type: endpoint
last_updated: 2026-11-13
feature: billing
related:
  - https://docs.corefinity.com/guides/billing/billing-overview.md
  - https://docs.corefinity.com/mcp/tools/corestack_billing_balance_get.md
---
# Get the balance

Answers the account's balance on its own: what has accrued this month, what is outstanding on open invoices,
the credits available, each contract line's running figure, when the next invoice is issued and the latest
activity. The same block as `balance` in `GET /corestack/billing/account`.

```http
GET /api/corestack/billing/balance
```

- Scope: `read`
- Two-factor: required on your account (all)
- Rate limit: 120 a minute
- Try it in the console: on

## Query parameters

- `account` (integer): The billing account to read, by its `id` (see `GET /corestack/billing/account`). Left out, the request acts on your company's default billing account. An account that does not exist and one that is not your company's answer the same 404.
- `account_id` (integer): The same as `account`, under the name the MCP tools use. Send one of the two: when they name different accounts the request is refused `422 invalid` on `account_id`.

## Request

### curl

```bash
curl https://manage.corefinity.com/api/corestack/billing/balance \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json"
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->get('https://manage.corefinity.com/api/corestack/billing/balance');

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/billing/balance', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
  },
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.get(
    "https://manage.corefinity.com/api/corestack/billing/balance",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
)

data = res.json() if res.content else None
```

## Responses

### 200 The balance.

```json
{
  "accrued_this_period": {
    "amount": "337.10",
    "currency": "GBP"
  },
  "balance": {
    "amount": "1057.10",
    "currency": "GBP"
  },
  "credits_available": {
    "amount": "25.00",
    "currency": "GBP"
  },
  "currency": "GBP",
  "last_accrual_at": null,
  "lines": [
    {
      "accrued": {
        "amount": "337.10",
        "currency": "GBP"
      },
      "contract_line": {
        "id": 9001,
        "kind": "package",
        "label": "CC8"
      },
      "hourly": {
        "amount": "0.806452",
        "currency": "GBP"
      },
      "hours": 418,
      "monthly": {
        "amount": "600.00",
        "currency": "GBP"
      }
    }
  ],
  "next_invoice_at": "2027-02-01T00:30:00Z",
  "outstanding": {
    "amount": "720.00",
    "currency": "GBP"
  },
  "period": {
    "end": "2027-02-01T00:00:00Z",
    "start": "2027-01-01T00:00:00Z"
  },
  "recent_activity": [
    {
      "amount": {
        "amount": "337.10",
        "currency": "GBP"
      },
      "contract_id": 5120,
      "currency": "GBP",
      "kind": "usage_mtd",
      "product": "CC8 · Northwind UK 1",
      "through": null
    },
    {
      "amount": {
        "amount": "25.00",
        "currency": "GBP"
      },
      "at": "2027-01-12T14:20:00Z",
      "description": "Credit granted · Goodwill credit",
      "invoice": null,
      "kind": "credit_grant"
    },
    {
      "amount": {
        "amount": "720.00",
        "currency": "GBP"
      },
      "at": "2027-01-01T00:30:00Z",
      "description": "Invoice CF-100057",
      "invoice": {
        "id": 8140,
        "number": "CF-100057"
      },
      "kind": "invoice"
    },
    {
      "amount": {
        "amount": "-660.00",
        "currency": "GBP"
      },
      "at": "2026-12-01T00:31:12Z",
      "description": "Payment for CF-100042",
      "invoice": {
        "id": 8123,
        "number": "CF-100042"
      },
      "kind": "payment"
    },
    {
      "amount": {
        "amount": "-60.00",
        "currency": "GBP"
      },
      "at": "2026-12-01T00:30:00Z",
      "description": "Credit applied to CF-100042",
      "invoice": {
        "id": 8123,
        "number": "CF-100042"
      },
      "kind": "credit_applied"
    },
    {
      "amount": {
        "amount": "720.00",
        "currency": "GBP"
      },
      "at": "2026-12-01T00:30:00Z",
      "description": "Invoice CF-100042",
      "invoice": {
        "id": 8123,
        "number": "CF-100042"
      },
      "kind": "invoice"
    },
    {
      "amount": {
        "amount": "50.00",
        "currency": "GBP"
      },
      "at": "2026-11-01T09:00:00Z",
      "description": "Credit granted · Welcome credit",
      "invoice": null,
      "kind": "credit_grant"
    }
  ]
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the scope (`scope_required`, with the `scope` to use), your company requires two-factor authentication and you have not set it up (`two_factor_required`), or you may not read your company's billing (`billing_forbidden`): billing is for the company's owner, its billing contacts and its primary user.

```json
{
  "code": "billing_forbidden",
  "message": "Billing is available to your company's owner and billing contacts.",
  "reason": "billing_forbidden"
}
```

### 404 The id does not exist or is something you cannot see, or the feature is not on for your company (`feature_off`).

```json
{
  "code": "feature_off",
  "message": "Not found.",
  "reason": "feature_off"
}
```

### 422 `account` and `account_id` name different billing accounts (`invalid`, on `account_id`).

```json
{
  "code": "invalid",
  "errors": {
    "account_id": [
      "Send account or account_id, not both: they name different billing accounts."
    ]
  },
  "field": "account_id",
  "message": "Send account or account_id, not both: they name different billing accounts.",
  "reason": "invalid"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `billing_forbidden` | Billing is for the organisation's owner and billing contacts. Ask one of them to do this. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 404 | `feature_off` | This feature is not on for your organisation yet. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |

## The same task elsewhere

- Guide: [Billing](https://docs.corefinity.com/guides/billing/billing-overview.md)
- MCP tool: [`corestack_billing_balance_get`](https://docs.corefinity.com/mcp/tools/corestack_billing_balance_get.md)
