> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing via API

> Check plan, balance, subscription, cards, and recharges without opening the dashboard.

<Tip>
  Billing via API is the **remote cash register**: subscribe, recharge balance, and add cards — same as the dashboard, over HTTP.
</Tip>

With an API key (or login `sessionToken`), the Platform API exposes workspace billing at `/v1/platform/workspaces/:id/*`. Useful for AI agents that provision accounts and immediately subscribe or recharge.

## Authentication

```http theme={null}
Authorization: Bearer sk_live_xxxxx
```

With an API key, billing routes require `billing:read` or `billing:manage` scopes — see [Scopes](/en/platform-api/como-funciona/escopos-api-key). With `sessionToken`, OWNER/ADMIN workspace members can operate without key scopes.

## Get subscription

```bash theme={null}
curl https://api.notifique.dev/v1/platform/workspaces/WORKSPACE_ID/subscription \
  -H "Authorization: Bearer sk_live_..."
```

Returns current plan, cycle credits, subscription status at the payment provider, next charge, and billing snapshot. Credits vs balance concepts: [Billing](/en/guides/introducao/cobranca-e-pague-pelo-uso).

## Subscribe to a plan

`POST /v1/platform/workspaces/:id/subscription`

```json theme={null}
{
  "tierIndex": 1,
  "billingType": "CREDIT_CARD",
  "cpfCnpj": "12345678901",
  "mobilePhone": "5511999999999",
  "paymentMethodId": "pm_xxx",
  "couponCode": "optional"
}
```

* `tierIndex` — plan index (0 = Free, 1 = Basic, …; maximum **10**)
* `billingType` — `PIX` or `CREDIT_CARD`
* With a saved card, use `paymentMethodId`; with PIX, response may include payment details

## Cancel subscription

`DELETE /v1/platform/workspaces/:id/subscription` — cancels renewal; access until end of cycle per plan policy.

## Balance (pay-as-you-go)

| Method | Route                                          | Scope            |
| ------ | ---------------------------------------------- | ---------------- |
| GET    | `/v1/platform/workspaces/:id/balance`          | `billing:read`   |
| POST   | `/v1/platform/workspaces/:id/balance/recharge` | `billing:manage` |

Minimum recharge and balance expiry follow product rules (min. R\$ 30, 90-day batches). `billingType`: `PIX` or `CREDIT_CARD`.

## Payment cards

| Method | Route                                               | Scope            |
| ------ | --------------------------------------------------- | ---------------- |
| GET    | `/v1/platform/workspaces/:id/payment-methods`       | `billing:read`   |
| POST   | `/v1/platform/workspaces/:id/payment-methods`       | `billing:manage` |
| PATCH  | `/v1/platform/workspaces/:id/payment-methods/:pmId` | `billing:manage` |
| DELETE | `/v1/platform/workspaces/:id/payment-methods/:pmId` | `billing:manage` |

Tokenization sends `creditCard` and `creditCardHolderInfo` (name, email, tax ID, address, phone). Cards stay with the payment provider; API returns IDs for reuse in subscription and recharge.

## Credit usage history

`GET /v1/platform/workspaces/:id/credits/usage` — scope `billing:read`.

Returns current credit balance, cycle renewal, balance in BRL, and a paginated `usage` list with channel, charge amount, `correlationId`, and `apiKeyId`. Useful for audits and agents explaining spend to customers.

```bash theme={null}
curl "https://api.notifique.dev/v1/platform/workspaces/WORKSPACE_ID/credits/usage?page=1&limit=20" \
  -H "Authorization: Bearer sk_live_..."
```

## Common errors

* **402** `INSUFFICIENT_CREDITS` / `WORKSPACE_BLOCKED` — no credits or balance to send
* **403** — missing `billing:read` or `billing:manage` on API key
* **503** — billing not configured in environment (provedor de pagamento)

Read-only alternative via messaging API: `GET /v1/workspaces/:id?include=billing` with workspace scope.