Billing and plans

Your plan sets monthly limits, such as emails, SMS and seats. Usage is counted per calendar month.

What you need first

• A key with settings:read to look, settings:write to start a checkout.

1. See your plan and usage

curl -s "$BASE/v1/billing" -H "Authorization: Bearer $HERMETICA_API_KEY"

You get the plan, its limits and what you have used. An empty limit (null) means unlimited. Soft limits warn you before you reach a hard one.

2. Compare plans

curl -s "$BASE/v1/billing/plans" -H "Authorization: Bearer $HERMETICA_API_KEY"

3. Look back

curl -s "$BASE/v1/billing/usage?months=6" -H "Authorization: Bearer $HERMETICA_API_KEY"
curl -s "$BASE/v1/billing/usage/2026-11" -H "Authorization: Bearer $HERMETICA_API_KEY"

The month is YYYY-MM. An impossible month answers 400.

4. Upgrade

curl -s -X POST "$BASE/v1/billing/checkout" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"planId":"starter","successUrl":"https://app.example.com/billing/done","cancelUrl":"https://app.example.com/billing"}'
# {"url":"https://checkout..."}

Open the url to pay. The plan changes when the payment goes through.

To change the card, see invoices or cancel, open the billing portal: POST /v1/billing/portal {"returnUrl":"https://app.example.com/billing"}. Invoices are also at GET /v1/billing/invoices.

If checkout answers 412 "No billing provider is configured", payments are not set up on this server yet. Contact support to change your plan.

What happens at a limit

Past a hard limit, the call answers 412 with details.code: "plan_limit_exceeded" and the metric, until the next month or an upgrade. Check GET /v1/billing before a large campaign.

Next: Reports and dashboards.