Administration

Billing and plans

Understand plan limits, billing summary, checkout, portal, cancellation, and recovery endpoints.

Plan-controlled features

Workspaces have billing summary, entitlements, usage, dashboard overview, and permissions endpoints. The customer portal uses those to decide which features are available.

Start a paid plan through the checkout endpoint. Manage changes to an existing Stripe subscription through the billing portal so Stripe, the local subscription, and entitlements stay aligned.

GET /api/customer/billing
GET /api/customer/billing/details
POST /api/customer/billing/checkout: start a Stripe checkout session for a paid plan.
POST /api/customer/billing/portal: change or manage an existing Stripe subscription.
POST /api/customer/billing/change-plan: legacy internal subscriptions may only downgrade directly to Free Sandbox.
POST /api/customer/billing/cancel
POST /api/customer/billing/resume

Usage and limits

Message usage is measured in credits, not raw request count. Text messages and OTP use 1 credit. Images and documents use more credits because they consume more storage and delivery resources.

Applications should handle limit errors cleanly and guide operators to the billing page when a plan upgrade is required.

Free Sandbox: 20 credits/month, 1 workspace, HookMessage-managed sandbox numbers only, 1 member, 1 API client, no customer-owned number connections, no production sending, and no image or document attachments.
Pay-as-you-go: 100 credits/month included, 1 customer-connected number, 100 attachments/month, 500 MB private storage, 30-day retention, and a 5 MB maximum file size. Images cost 2 credits and documents cost 3 credits.
Starter: 1,500 credits/month, up to 2 customer-connected numbers, 2 members, 1 API client, 100 attachments/month, 500 MB private storage, 30-day retention, and a 5 MB maximum file size. Images cost 2 credits and documents cost 3 credits.
Pro: 6,000 credits/month, 3 workspaces, up to 5 customer-connected numbers, 5 members, 3 API clients, templates and webhooks, 1,000 attachments/month, 5 GB private storage, 90-day retention, and a 10 MB maximum file size. Images cost 2 credits up to 5 MB or 3 credits above 5 MB; documents cost 3 credits up to 5 MB or 5 credits above 5 MB.
Business: 25,000 credits/month, 10 workspaces, up to 15 customer-connected numbers, 15 members, 15 API clients, campaigns and automations, 5,000 attachments/month, 25 GB private storage, 365-day retention, and a 10 MB maximum file size. Images cost 2 credits up to 5 MB or 3 credits above 5 MB; documents cost 3 credits up to 5 MB or 5 credits above 5 MB.
A send containing text plus one attachment is charged once using the attachment tier; the text is not added as a second charge.
Credits are reserved when a send is accepted, consumed only after WhatsApp accepts the message, and released when delivery fails permanently or a queued send is cancelled.
The same idempotency key returns the original message and credit reservation instead of charging twice.
Upgrade recovery: send the operator to Dashboard > Billing & Plans, upgrade the plan, then retry with the same `idempotency_key` if the original request timed out or was not accepted.

plan-limit-errors.json

json

[
  {
    "status": 429,
    "body": {
      "error": "monthly_quota_exceeded",
      "message": "Workspace monthly message quota has been reached."
    }
  },
  {
    "status": 403,
    "body": {
      "error": "plan_limit_reached",
      "message": "Plan limit reached for this workspace resource."
    }
  },
  {
    "status": 403,
    "body": {
      "error": "plan_limit_reached",
      "message": "Connected number limit reached for this plan."
    }
  }
]

Need help?

Use Book Integration Help if you want setup help for OTP or automated customer messaging.

Continue building

Next steps

Start here

A plain-language map of Free Sandbox, paid sender modes, credentials, and the first successful request.

Free Sandbox quickstart

The shortest beginner path from a verified account to a queued Free Sandbox OTP.

Glossary

Understand workspaces, keys, senders, receivers, queue states, webhooks, and idempotency.

Authentication and access

HookMessage separates customer API keys, dashboard sessions, and internal platform access.

[ { "status": 429, "body": { "error": "monthly_quota_exceeded", "message": "Workspace monthly message quota has been reached." } }, { "status": 403, "body": { "error": "plan_limit_reached", "message": "Plan limit reached for this workspace resource." } }, { "status": 403, "body": { "error": "plan_limit_reached", "message": "Connected number limit reached for this plan." } } ]