Billing via API

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

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

Authorization: Bearer sk_live_xxxxx

With an API key, billing routes require billing:read or billing:manage scopes — see Scopes. With sessionToken, OWNER/ADMIN workspace members can operate without key scopes.

Get subscription

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. POST /v1/platform/workspaces/:id/subscription

{
  "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.

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.

Simple guides

Learn more

Workspaces

OAuth 2.1

AI and no-code

BYOK

Changelog

Platform API

Account

API Keys

Billing

Credits

Team

Metadata

OAuth

Webhooks

Deliveries

Logs

Workspaces

Authentication

Get subscription

Cancel subscription

Balance (pay-as-you-go)

Payment cards

Credit usage history

Common errors

​Authentication

​Get subscription

​Subscribe to a plan

​Cancel subscription

​Balance (pay-as-you-go)

​Payment cards

​Credit usage history

​Common errors

Authentication

Get subscription

Subscribe to a plan

Cancel subscription

Balance (pay-as-you-go)

Payment cards

Credit usage history

Common errors