Credits and billing

Live API keys (ss_live_…) spend credits; test keys (ss_test_…) never do (Test mode).

What things cost

Your first API key comes with 4 free credits for live images (once per account).

• A credit is charged when the generation or set is created (creditsCharged), all at once for a set: without enough credits the request is 402 INSUFFICIENT_CREDITS (details.requiredCredits, details.availableCredits, details.topUpUrl) and nothing is created.
• Quote a set first with POST /screenshot-sets?dryRun=true: it answers credits and whether your balance is sufficient, and charges nothing.
• A generation that fails, or that you cancel before it starts, is refunded automatically (creditsRefunded). Retrying failed images of a set charges only the images it retries.
• Credits are spent from your monthly plan first, then from trial credits, then from purchased packs. Plan credits reset every month (they do not roll over); purchased credits do not expire.

Check the balance and usage

GET /credits and GET /usage need the usage:read scope. Usage covers live generations of the whole account (every key and surface) per UTC day, per API key (groupBy=key) or per source (groupBy=source), for a range of up to 366 days (from inclusive, to exclusive, YYYY-MM-DD).

curl -sS https://api.storeshot.art/v1/credits \
  -H "Authorization: Bearer $STORESHOT_API_KEY" | jq .

curl -sS 'https://api.storeshot.art/v1/usage?from=2026-10-01&to=2026-11-01&groupBy=key' \
  -H "Authorization: Bearer $STORESHOT_API_KEY" \
  | jq -r '.data[] | "\(.key) generations=\(.generations) credits=\(.creditsUsed)"'

const api = 'https://api.storeshot.art/v1';
const headers = { Authorization: `Bearer ${process.env.STORESHOT_API_KEY}` };

const credits = await (await fetch(`${api}/credits`, { headers })).json();
console.log('credits left:', credits.total, credits.balances);

const usage = await (
  await fetch(`${api}/usage?from=2026-10-01&to=2026-11-01&groupBy=source`, { headers })
).json();
for (const bucket of usage.data) console.log(bucket.key, bucket.generations, bucket.creditsUsed);

import os, requests

api = "https://api.storeshot.art/v1"
headers = {"Authorization": f"Bearer {os.environ['STORESHOT_API_KEY']}"}

credits = requests.get(f"{api}/credits", headers=headers).json()
print("credits left:", credits["total"], credits["balances"])

usage = requests.get(
    f"{api}/usage", headers=headers, params={"from": "2026-10-01", "to": "2026-11-01"}
).json()
for day in usage["data"]:
    if day["generations"]:
        print(day["key"], day["generations"], day["creditsUsed"])

A webhook with the credits.low event tells you when a charge takes the live balance below a threshold you choose.

Monthly plans

Credit packs

Buy a plan or a pack in the developer console; the pricing page compares them. Checkouts through the API (POST /billing/checkout) need a live key with billing:write or a console session; test keys never buy.