Billing, credits and limits

Agents run on the account's own plan and credits. Agent access has no price of its own, and an agent can't do more than the plan allows. This page covers what works before anyone pays, how the trial starts, what each action costs, the rate limits, and how to read a 402.

Who pays

The account owner pays, through Stripe, on one monthly subscription. An agent never enters payment details: it creates a checkout link and hands it to the owner. After that, everything an agent does is billed to the owner's plan in the same way as if the owner did it in the dashboard:

• Writing articles spends the site's article credits, which come with the plan.
• Adding a Studio site, restoring an archived one, or ending the trial early charges the owner's card on file. These are the only agent actions that cost money beyond the plan's monthly price.
• Nothing else an agent does is charged.

The owner receives Stripe's receipts and sees every charge in Dashboard → Plan & Billing, and every action in the activity log.

The Business plan

Rankbox has one plan. Each site on the account gets the full allowance.

See Plans and credits and /pricing.

What works before a plan

An account with no trial or plan, such as a new account an agent just created, can already do a lot:

"Paid plan" means an invoice has actually been paid: the trial converted, or the owner ended it early. A trial never counts as paid.

The trial

The trial is how most agent-created accounts start writing.

1. The agent calls POST /billing/checkout and gets a checkout_url with "mode": "trial". The link is valid for 7 days.
2. The owner opens it and adds a card on Stripe's checkout page. Nothing is charged that day.
3. Rankbox checks the card with a $1.00 authorization that it releases immediately. If the check fails, the trial exists but card_verified is false and generation stays off until the owner updates the card in the billing portal. The billing.card_check_failed event fires.
4. The trial starts: billing.status becomes trialing, the primary site gets 7 article credits, billing.trial_started fires, and autopilot starts writing on its next run.
5. On day 8, Stripe charges $49.50. The plan becomes active, the site's article balance resets to 30, and the backlink exchange, Reddit Presence and Studio open. billing.activated fires.

The owner can cancel any time before day 8 in the billing portal and pay nothing. An agent can end the trial early with POST /billing/activate, which charges $49.50 at once; do that only when the owner has asked, for example because they want backlinks or a second site this week. See The free trial.

Credits and resets

Each site has its own balances. GET /sites/{site_id}/credits returns them.

Rules that matter to agents:

• Reserved, then refunded on failure. An article credit is reserved when writing starts and refunded if it fails. A Reddit draft that is refused or fails refunds its credit.
• Deleting doesn't refund. Deleting a written article doesn't return its credit.
• Free actions. Research, scans, planning, scoring, rewriting a section, finishing your own article, publishing, syncing, recording a live URL, sweeps and recording a Reddit reply spend no credits.
• Refills follow payment, not the calendar. A period whose invoice fails grants nothing until it is paid.
• No top-ups. There is no larger plan and no credit pack. A site that runs out waits for the next period, or the owner adds a Studio site for another brand.

Plan states

GET /billing returns status and a few flags. What each state means for an agent:

Articles already published stay on the website whatever the plan does.

Studio sites

Studio adds sites to the account, for agencies and owners with several brands. Each extra site costs $49.50 a month on the same subscription and has the full allowance of its own: 30 article, 30 backlink and 30 Reddit reply credits a month.

• Paid plan only. During the trial, POST /sites returns 402 paid_plan_required. GET /billing/studio-quote returns a block with the reason.
• Charged at once, prorated. Adding a site charges the share of the current period that's left, and the site's first allowance is prorated the same way, rounded up and never below 1. A site added halfway through a period costs $24.75 and starts with 15 of each credit.
• One change at a time. A second Studio change while one is in progress returns 409 conflict for a few seconds.
• Removal runs to the end of the period. DELETE /sites/{site_id} stops billing from the next invoice; the site works until removes_at. Nothing is refunded. POST /sites/{site_id}/restore before that date undoes it for free.

See Studio: run several sites.

Rate limits

Limits apply per account (all its agent keys and OAuth connections together) or per IP address, in fixed one-minute windows unless noted.

The public articles API that websites call with site keys has its own budget: see Rate limits.

When a limit is hit, the API returns 429 with "code": "rate_limited" and a Retry-After header in seconds. Wait that long, then retry the same request. Every response also carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so you can slow down before hitting the limit.

async function rankbox(path: string, init: RequestInit = {}, attempt = 0): Promise<Response> {
  const res = await fetch(`https://rankbox.xyz/api/agent/v1${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.RANKBOX_AGENT_KEY}`, ...init.headers },
  });
  if ((res.status === 429 || res.status >= 500) && attempt < 5) {
    const wait = Number(res.headers.get("retry-after")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, wait * 1000));
    return rankbox(path, init, attempt + 1);
  }
  return res;
}

Reuse the same Idempotency-Key when you retry a POST, so a request that succeeded but whose answer was lost doesn't run twice.

Working within the limits

• Wait for jobs with wait=30. One long-poll request replaces up to 30 one-second polls.
• Prefer events to polling. A webhook costs no requests. GET /events every few minutes is enough when you poll.
• Batch planning. POST /sites/{site_id}/research with save: true adds up to 30 ideas in one AI operation.
• Don't fan out generation. Three articles in progress per site is the cap; queue the rest by scheduling them and let autopilot write them.
• Cache reads. Sites, keywords and settings change rarely. Read them once per session.

What a 402 means

A 402 always means the plan or the credits stand in the way, never a bug in your request. The code says which:

The error sentence names the cause and the date when there is one, so you can pass it to the owner as is.

Related

• Plans and credits: the allowances from the owner's side.
• The free trial: the trial, the card check and cancellation.
• Studio: run several sites: billing for extra sites.
• Agent API reference: the billing endpoints.
• Permissions and guardrails: spending actions and owner controls.