# billing

9 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `billing.alerts`

```http
GET /billing/alerts
```

The low-balance and work-refused alerts the tenant's admins get.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fbilling%2Falerts).

**Response:** [`LowBalanceAlertSettings`](https://docs.maitento.com/reference/types/low-balance-alert-settings.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/billing/alerts" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const alerts = await mt.billing.alerts();
```
```python title="Python"
mt.billing.alerts()
```

## `billing.setAlerts`

```http
PUT /billing/alerts
```

Replaces the alerts (`Tenant.Admin`).

**Who can call it:** Tenant admins only, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fbilling%2Falerts).

**Request body:** [`LowBalanceAlertSettingsInput`](https://docs.maitento.com/reference/types/low-balance-alert-settings.md#in-a-request)

| Field | Type | Required | Description |
|---|---|---|---|
| `emailAtPercentOfLastTopUp` | `integer \| null` |  | Email when the balance falls to this percentage of the last top-up; null for no email. |
| `showPortalBanner` | `boolean` |  | Show a banner in the portal while the balance is low: below `LowBalanceAlertSettings.EmailAtPercentOfLastTopUp` of the last top-up, or below 20% of it when the email is off. The billing standing's `lowBalance` says when. |
| `emailWhenWorkRefused` | `boolean` |  | Email when work is refused because the balance has run out. |

**Response:** [`LowBalanceAlertSettings`](https://docs.maitento.com/reference/types/low-balance-alert-settings.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/billing/alerts" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"emailAtPercentOfLastTopUp":0,"showPortalBanner":false,"emailWhenWorkRefused":false}'
```
```ts title="TypeScript"
await mt.billing.setAlerts({ emailAtPercentOfLastTopUp: 20, showPortalBanner: true, emailWhenWorkRefused: true });
```
```python title="Python"
mt.billing.set_alerts(email_at_percent_of_last_top_up=20, show_portal_banner=True, email_when_work_refused=True)
```

## `billing.autoTopUp`

```http
GET /billing/auto-top-up
```

The automatic top-up: whether it's on, when it buys credit and how much, and whether it stopped.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fbilling%2Fauto-top-up).

**Response:** [`AutoTopUpView`](https://docs.maitento.com/reference/types/auto-top-up-view.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/billing/auto-top-up" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const autoTopUp = await mt.billing.autoTopUp();
```
```python title="Python"
mt.billing.auto_top_up()
```

## `billing.setAutoTopUp`

```http
PUT /billing/auto-top-up
```

Turns the automatic top-up on or off, or changes it (`Tenant.Admin`). Saving it again restarts one that stopped.

**Who can call it:** Tenant admins only, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fbilling%2Fauto-top-up).

**Request body:** [`AutoTopUpApiRequest`](https://docs.maitento.com/reference/types/auto-top-up-api-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | `boolean` |  |  |
| `thresholdAmount` | `number` |  | Buy more when the balance falls below this, in the billing currency. |
| `topUpAmount` | `number` |  | How much to buy each time; at least the minimum top-up. |

**Response:** [`AutoTopUpView`](https://docs.maitento.com/reference/types/auto-top-up-view.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/billing/auto-top-up" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false,"thresholdAmount":0,"topUpAmount":0}'
```
```ts title="TypeScript"
await mt.billing.setAutoTopUp({ enabled: true, thresholdAmount: 10, topUpAmount: 50 });
```
```python title="Python"
mt.billing.set_auto_top_up(enabled=True, threshold_amount=10, top_up_amount=50)
```

## `billing.balance`

```http
GET /billing/balance
```

The balance, and whether it can pay for more work.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fbilling%2Fbalance).

**Response:** [`TenantBalance`](https://docs.maitento.com/reference/types/tenant-balance.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/billing/balance" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const { balance, currency } = await mt.billing.balance();
```
```python title="Python"
mt.billing.balance()
```

## `billing.catalogue`

```http
GET /billing/catalogue
```

The plans on sale, cheapest first, with what each includes and costs (the tenant's own plan among them).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fbilling%2Fcatalogue).

**Response:** [`BillingCatalogue`](https://docs.maitento.com/reference/types/billing-catalogue.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/billing/catalogue" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const { tiers } = await mt.billing.catalogue();
```
```python title="Python"
mt.billing.catalogue()
```

## `billing.notices`

```http
GET /billing/notices
```

The tenant's latest billing notices (what its `Billing` webhooks were sent), newest first.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fbilling%2Fnotices).

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | `integer` |  |  |

**Response:** [`BillingNotice`](https://docs.maitento.com/reference/types/billing-notice.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/billing/notices" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const notices = await mt.billing.notices({ limit: 10 });
```
```python title="Python"
mt.billing.notices(limit=10)
```

## `billing.plan`

```http
GET /billing/plan
```

What the plan includes and costs: allowances, lanes, limits, retention, priority and prices.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fbilling%2Fplan).

**Response:** [`EffectiveEntitlements`](https://docs.maitento.com/reference/types/effective-entitlements.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/billing/plan" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const plan = await mt.billing.plan();
```
```python title="Python"
mt.billing.plan()
```

## `billing.standing`

```http
GET /billing/standing
```

Where the tenant stands: its plan and its state, its balance, whether it can start work (out of credit, or an allowance used up), any plan change on its way, and this billing period's use of each allowance.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fbilling%2Fstanding).

**Response:** [`BillingStanding`](https://docs.maitento.com/reference/types/billing-standing.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/billing/standing" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const standing = await mt.billing.standing();
```
```python title="Python"
mt.billing.standing()
```