# BillingNotice

A billing event in a tenant: it ran out of credit or got it back, used up an allowance, ran low on balance, or its plan changed (including a failed renewal payment and the reminders after it). Sent to the tenant's `Billing` webhooks as it happens, and emailed to its admins.

**Kind:** an object, used in responses.

## Fields

Every field is present in a response; empty ones are `null`.

| Field | Type | Description |
|---|---|---|
| `kind` | [`BillingNoticeKind`](https://docs.maitento.com/reference/types/billing-notice-kind.md) | What happened. |
| `meter` | [`BillingMeter`](https://docs.maitento.com/reference/types/billing-meter.md)`\| null` | The meter whose allowance is used up (for `BillingNoticeKind.AllowanceUsed`). |
| `balance` | `number \| null` | The balance when it happened. |
| `currency` | `string \| null` | The currency of `BillingNotice.Balance`. |
| `tier` | [`SkuTier`](https://docs.maitento.com/reference/types/sku-tier.md)`\| null` | The plan the tenant is on now (for plan changes). |
| `previousTier` | [`SkuTier`](https://docs.maitento.com/reference/types/sku-tier.md)`\| null` | The plan it was on before (for plan changes and a failed renewal payment). |
| `frozenUntilUtc` | `datetime \| null` | After a failed renewal payment: when, if it's still unpaid, the subscription is cancelled and Free's limits apply in full (UTC). |
| `occurredAtUtc` | `datetime` | When it happened (UTC). |
| `userCreatedById` | `uuid` | The id of the user who created it. A call made with an API key is recorded as the key's user. |
| `tenantId` | `uuid` | The id of the tenant it belongs to. |
| `id` | `uuid` | The unique id. Use it in `by-id` routes and wherever another object refers to this one. |
| `dateCreated` | `datetime` | When it was created, in UTC. |
| `dateUpdated` | `datetime` | When it was last changed, in UTC. |

## Example

```json
{
  "kind": "OutOfCredit",
  "meter": "Standard",
  "balance": 0,
  "currency": "...",
  "tier": "Free",
  "previousTier": "Free",
  "frozenUntilUtc": "2026-10-26T12:00:00.0000000Z",
  "occurredAtUtc": "2026-10-26T12:00:00.0000000Z",
  "userCreatedById": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "tenantId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "dateCreated": "2026-10-26T12:00:00.0000000Z",
  "dateUpdated": "2026-10-26T12:00:00.0000000Z"
}
```

## Where it's used

- [`billing.notices`](https://docs.maitento.com/reference/api/billing.md) (`GET /billing/notices`)