Plans and billing

Every plan has every feature: analytics, crawler and AI-bot analytics, journeys, A/B tests, bot protection, Search Console, the API and MCP. Plans differ only by volume, and data is kept forever on all of them.

Months are calendar months in UTC. Paid subscriptions renew on the 1st, so a billing period is the month that usage is counted in; the first payment covers the rest of the current month, pro rata.

Above the allowance

On a paid plan nothing is dropped. Usage above the allowance is billed at the end of the period, pro rata:

• $10 per extra 1M pageviews (one cent per 1,000),
• $1 per extra 1M server requests (one cent per 10,000),
• $1 per extra proxy hostname per month, for each month it exists.

Worked examples, for one month:

Free never bills. The owners get an email at 80% and at 100% of an allowance. Pageviews keep counting past 100%; past 150% of its server requests, Free stops logging server requests until the month turns. Paid plans get the 80% and 100% emails too, as a heads-up.

Your plan and usage

GET /v1/billing (scope billing:read, which owners and admins have) answers the plan, the subscription's status, this month's usage, the overage so far in cents, and a projection to the end of the month.

curl https://api.usherstats.com/v1/billing \
  -H "Authorization: Bearer $US_TOKEN"

Subscribe

Paying is the owner's: it needs billing:write, which only owners have (and tokens they make with it). Tokens restricted to some sites cannot change billing.

POST /v1/billing/checkout answers the URL of a Stripe Checkout page for the plan, monthly or yearly. The plan changes when Stripe confirms the payment, not before.

curl https://api.usherstats.com/v1/billing/checkout \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan": "growth", "interval": "month"}'

Until the payment is confirmed there is no subscription to change, so a plan change is refused:

curl https://api.usherstats.com/v1/billing/plan \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan": "starter"}'

Change plan, update the card, cancel

POST /v1/billing/plan changes the plan of a subscription:

• an upgrade applies once the difference for the rest of the period, invoiced immediately, is paid; if the card is declined the answer is 402 and the plan stays as it was;
• a downgrade applies when the period you paid for ends; until then you keep the larger plan;
• {"plan": "free"} cancels at the end of the period. Nothing is deleted: the workspace moves to Free and keeps its data. Choosing a plan again before the period ends withdraws the cancellation.

Switching between monthly and yearly billing in place is not available yet: cancel, and subscribe again when the period ends.

POST /v1/billing/portal answers a link to Stripe's customer portal, where you update the card, download invoices and receipts, or cancel at the end of the period. It needs a billing account, which the first subscription creates:

curl -X POST https://api.usherstats.com/v1/billing/portal \
  -H "Authorization: Bearer $US_TOKEN"

When a payment fails

The owners get an email with a link to pay the invoice, and nothing changes for 7 days. If the invoice is still unpaid then, the workspace moves to Free (data kept, collection continues within Free's allowances) and the owners are told. Paying the invoice later restores the plan.

Stripe's webhook

POST /v1/billing/webhook is for Stripe only. It accepts a request only with a valid Stripe-Signature made in the last 5 minutes, and applies each event once:

curl https://api.usherstats.com/v1/billing/webhook \
  -H "Content-Type: application/json" \
  -d '{"id": "evt_1", "type": "customer.subscription.deleted"}'