Billing

Billing is powered by Stripe. These endpoints create Stripe Checkout sessions for plan upgrades and Stripe Billing Portal sessions for managing existing subscriptions.

All billing endpoints require a valid API key.

Credit meter (live)

When QUOTA_ENFORCEMENT is on (production free-beta):

Successful billable work debits the tenant credit ledger (hit-only: empty results cost 0).
Responses include X-Credits-Consumed and often X-Credits-Remaining.
Free tenants hard-stop at HTTP 402 when the balance cannot cover the request.
Paid plans may allow overage (Stripe metered prices are configured for scrape/enrich/kyb).

See GET /v1/pricing for the live catalog and units per endpoint.

Endpoints

Endpoint	Method	Description
`/v1/billing/checkout`	POST	Start a Stripe Checkout session to subscribe to a plan
`/v1/billing/portal`	GET	Open the Stripe Billing Portal for an existing subscription
`/v1/billing/usage`	GET	Usage and quota (alias for `GET /v1/usage`)

POST /v1/billing/checkout

Creates a Stripe Checkout session for a plan subscription. Returns a url that redirects the user to Stripe's hosted checkout page.

If the tenant does not yet have a Stripe customer, one is created automatically using the email stored against the tenant in the database.

Request

POST /v1/billing/checkout
Content-Type: application/json
x-api-key: YOUR_KEY

Body

Field	Type	Required	Description
`plan`	string	Yes	Which plan to subscribe to. See the note below, the accepted values are legacy ids, not the plan names on the pricing page.
`successUrl`	string	Yes	URL Stripe redirects the user to after a successful payment. Must be `http(s)://`.
`cancelUrl`	string	Yes	URL Stripe redirects the user to if they cancel. Must be `http(s)://`.

plan accepts either public names (hobby, pro, scale) or legacy ids (starter, pro, business). Prefer the public names.

Example request

curl -X POST https://api.superscraper.dev/v1/billing/checkout \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "pro",
    "successUrl": "https://app.superscraper.dev/billing/success",
    "cancelUrl": "https://app.superscraper.dev/billing"
  }'

Response

HTTP 200 on success.

Field	Type	Description
`url`	string	Stripe Checkout session URL. Redirect the user to this URL to complete payment.

Example response

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3..."
}

Errors

Status	Error	Cause
400	`plan` is required	`plan` field missing
400	`successUrl` is required	`successUrl` field missing
400	`cancelUrl` is required	`cancelUrl` field missing
400	`successUrl/cancelUrl must be an allowed http(s) URL`	Non-`https://` scheme (e.g. `javascript:`) or origin not in `ALLOWED_REDIRECT_ORIGINS` allowlist
400	`Unknown plan: <plan>`	`plan` value not `"starter"`, `"pro"`, or `"business"`
400	`Invalid JSON body`	Malformed request body
401	`API key required`	Missing `x-api-key` header
404	`Tenant not found`	Authenticated tenant does not exist in the database
500	`Internal server error`	Stripe API error or database error

GET /v1/billing/portal

Opens a Stripe Billing Portal session for the authenticated tenant. Returns a url that redirects the user to Stripe's self-service portal where they can update payment methods, view invoices, and cancel subscriptions.

Requires that the tenant already has a Stripe customer ID (i.e. they have previously subscribed via /v1/billing/checkout).

Request

GET /v1/billing/portal
x-api-key: YOUR_KEY

No request body.

Example request

curl https://api.superscraper.dev/v1/billing/portal \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx"

Response

HTTP 200 on success.

Field	Type	Description
`url`	string	Stripe Billing Portal session URL. Redirect the user to this URL.

Example response

{
  "url": "https://billing.stripe.com/p/session/live_abcd1234..."
}

Errors

Status	Error	Cause
400	`No billing account found for this tenant`	Tenant has no Stripe customer ID, they have never subscribed
401	`API key required`	Missing `x-api-key` header
404	`Tenant not found`	Authenticated tenant does not exist in the database
500	`Internal server error`	Stripe API error or database error

Credit grants per plan

Each plan includes a monthly grant of credits per type, applied on subscription create/renew. These match the credits quoted on Pricing:

Plan	Scrape credits	Enrich credits	KYB credits
Free	1 000	1 000	0
Hobby	5 000	5 000	500
Pro	100 000	100 000	5 000
Scale	500 000	500 000	25 000

Credits are prepaid: each plan grants a monthly balance, and usage draws it down. A call that returns no data costs nothing. When you run low, top up or upgrade.

Notes

The Stripe Checkout session is created in subscription mode with a flat plan line item that grants the plan's monthly credit balance.
Open-redirect protection: successUrl and cancelUrl must use http:// or https:// schemes. If ALLOWED_REDIRECT_ORIGINS (comma-separated) is configured in the environment, both URLs must originate from an allowlisted origin.
Plan upgrades are processed asynchronously via the Stripe webhook (POST /webhooks/stripe). The tenant's plan is updated in the database when the checkout.session.completed event is received.

GET /v1/usage POST /v1/screenshot