Billing

How Ray9 charges — credits, plan tiers, top-ups, refunds. Everything money-related lives here.

Ray9 bills on a credit model. You buy credits as a one-time top-up; every API call debits credits according to its endpoint. There's no monthly subscription on the standard plan — you pay for what you use, and credits don't expire. A hard balance cutoff means you can't accidentally run up a bill.

Credits and mils

The credit unit is a mil (one-thousandth of a US dollar, $0.001). Balances and per-call costs are stored and displayed in mils to keep arithmetic exact for sub-cent operations. A $1.00 top-up grants 1000 mils; a SERP call costs 5 mils.

We display balances as mils in API responses (creditsRemaining, creditsCharged) and as either mils or formatted USD in the dashboard, depending on the surface.

Plans

Two plans, with one transition between them.

Plan	Monthly fee	Includes	Endpoints
Free	$0	$1.00 (1000 mils) free credit on signup	SERP only
PayG	$0	Credits via top-up (min $5.00)	All endpoints (SERP + keyword + backlink + AI visibility surfaces as they ship)

A new org starts on Free with 1000 mils granted automatically. The first paid top-up flips the plan to PayG, sticky — Ray9 doesn't downgrade you back to Free even if your balance hits zero on PayG. Once PayG, always PayG.

Per-endpoint cost

Each endpoint debits a fixed cost per call. The list today (the only endpoint live in v1):

Endpoint	Cost per call
`POST /v1/serp/search`	5 mils ($0.005)
`GET /v1/usage`	Free (read-only)
`GET /health`	Free (no auth required)

When more endpoints land, each gets a row here with its mil cost. Costs are independent of result size — a SERP query at depth: 100 costs the same 5 mils as one at depth: 10.

Topping up

PayG top-ups are pay-what-you-want with a minimum. Quick-amount buttons in the dashboard:

Amount	Mils	Approx SERP calls
$5.00 (minimum)	5,000	1,000
$10.00	10,000	2,000
$20.00	20,000	4,000
$50.00	50,000	10,000
$100.00	100,000	20,000

You can also enter a custom amount ≥ $5.00. Top-ups are processed instantly — your balance updates within seconds of the payment confirmation.

Top up at Settings → Billing.

Quota behaviour at zero

When your balance can't cover the next request, Ray9 returns 402 out_of_credits:

{
  "requestId": "req_…",
  "error": {
    "code": "out_of_credits",
    "message": "Insufficient credit balance for this request. Top up to continue.",
    "details": { "action": "topup", "topup_url": "https://app.ray9.ai/settings/billing" }
  }
}

Your client should surface this to the human user with a top-up CTA — programmatic retry won't help. The cutoff is hard: there's no overage billing, no auto-recharge by default, and no allowing-into-debt — once balance < cost, all billable endpoints 402 until you top up.

Plan-gated endpoints

Free covers SERP only. Hitting a PayG-only endpoint (keywords, backlinks, AI visibility) on a Free plan returns 402 plan_required:

{
  "requestId": "req_…",
  "error": {
    "code": "plan_required",
    "message": "Endpoint 'keywords' is not available on the 'free' plan. Top up to unlock.",
    "details": {
      "required_plan": "payg",
      "current_plan": "free",
      "action": "topup",
      "topup_url": "https://app.ray9.ai/settings/billing"
    }
  }
}

Top up any amount ≥ $5.00 and the org transitions Free → PayG, unlocking everything in one shot.

Failed calls don't bill

Both 4xx and 5xx leave your balance unchanged. Validation, auth, plan, and rate-limit failures reject the request before any debit, so there's nothing to charge in the first place. For requests that pass the gates and then fail downstream — a 5xx from our side, or a service-originated soft 4xx — the debit is automatically refunded after the response is sent. See Errors → Credits and errors. Cached 200s and live 200s are the only billing events.

The one orphan-credit case: a successful 200 the client never received (network-level timeout). The handler completed and the credit was charged, but the response didn't make it back. Your retry will be billed a second time.

Reading your balance

Three ways to read your current balance:

creditsRemaining field on every successful billed response — zero round-trips.
x-ray9-credit-balance response header on the same calls — useful when you want to inspect headers without parsing the body.
GET /v1/usage — a dedicated read-only endpoint that returns { creditBalanceMils, plan } without billing anything.

curl https://api.ray9.ai/v1/usage \
  -H "Authorization: Bearer rk_…"

{
  "creditBalanceMils": 985,
  "plan": "free"
}

The dashboard at Settings → Billing shows the same balance plus history.

Cancellation, refunds, and inactive accounts

There's nothing to cancel — Ray9 doesn't run a recurring subscription on PayG. If you stop using the API, your remaining credits stay on your account indefinitely (no expiry), and no further charges occur.

Refunds for unused credits are issued case-by-case — contact contact@ray9.ai with your account email and a brief reason. Single-use top-ups are typically not refunded once consumed against API calls.

Payment methods

Credit cards via our payment processor. Invoicing for annual prepaid commitments is available on request — email contact@ray9.ai.

Billing

On this page