Billing & Usage

Understand monthly Action usage, plan limits, overage behavior, and the billing API.

ActionBox measures usage on the server. The billing page and GET /v1/billing return the active workspace's current plan, live Action count, limits, and overage meter. The usage period starts at midnight UTC on the first day of each month.

Plan limits

Plan	Live Actions included / month	Active Sources	Devices	Watches	History	Context / Action
Developer	1,000	3	2	5	7 days	16 KB
Pro	25,000	Unlimited	Unlimited	50	30 days	64 KB
Founder	15,000	Unlimited	Unlimited	50	90 days	64 KB
Team	250,000	Unlimited	Unlimited	Unlimited	90 days	128 KB

Developer has no paid overage: new live Actions are blocked after the included allowance. Pro, Founder, and Team can continue past the included allowance and meter overage according to the current plan terms. Prices and checkout status are authoritative on the pricing page and billing portal; do not hard-code a price in an integration.

In the hosted production service, test-key Actions exercise the protocol without consuming paid Action quota and are isolated from the live inbox, live idempotency records, push hints, and terminal callbacks. Use a test key for integration checks, not as a way to bypass live limits.

Read the authoritative snapshot

Use a user session to read billing data:

curl -fsS https://api.actionbox.cloud/v1/billing \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

The response includes entitlements, usage_count, overage_actions, overage_charge_usd, period_start, and the billing status. A workspace is billed through its owner; only the billing owner can open the customer billing portal through POST /v1/billing/portal.

Read quota headers from Action creation

Source-authenticated Action-creation responses include these useful headers:

Header	Meaning
`X-Actionbox-Plan`	Plan used for this request
`X-Actionbox-Quota-Limit`	Included live Actions in the current period
`X-Actionbox-Quota-Remaining`	Included Actions not yet used, never below zero
`X-Actionbox-Quota-Reset`	Unix timestamp for the next UTC monthly period
`X-Actionbox-Overage-Actions`	Live Actions above the included allowance
`X-Actionbox-Overage-Rate`	Meter rate, or `hard-block` on Developer

Treat the response body and headers as informational. Admission is decided by the server at create time, so do not rely on a locally cached counter to decide whether to submit an Action.

What gets blocked

Error	Meaning	Fix
`429 QUOTA_EXCEEDED`	Developer live Action allowance is exhausted	Wait for the next period, reduce duplicate creation, or move to an eligible paid plan.
`429 RATE_LIMITED`	Request-rate or hourly admission limit was reached	Honor `Retry-After`, add bounded backoff, and spread worker retries.
`403 SOURCE_LIMIT_REACHED`	Too many active Sources for the plan	Revoke an unused Source or review the plan.
`403 DEVICE_LIMIT_REACHED`	Too many active connected devices	Revoke an old installation or review the plan.
`403 WATCH_LIMIT_REACHED`	Too many active Watches	Archive an unused Watch or review the plan.
`413 PAYLOAD_CONTEXT_TOO_LARGE`	Context exceeds the plan's per-Action ceiling	Summarize the context and link to an access-controlled artifact.

Exact idempotency retries and deduplicated replays remain safe even when a Developer workspace has reached its quota. Use the same idempotency key only for the same request body; a changed body requires a new key.

Billing recovery

If the dashboard reports that live pricing is temporarily unavailable, do not assume a price or retry checkout in a loop. Confirm the plan and status from GET /v1/billing, then retry the billing page once live pricing is available again. Your current plan is unchanged while checkout is unavailable.

Keep billing support safe

For a billing question, send the workspace ID, plan/status, approximate UTC time, HTTP status, and X-Request-ID. Never send a payment method, customer portal URL, Source key, user token, webhook secret, or full billing response if it contains personal or payment data.