Billing & top-ups

Figgshield has three paid plans, billed annually only. Prices are displayed per month; the charge is always twelve times the monthly sticker, once a year. Credits are granted monthly regardless. There is no free tier.

Plans

GET /api/billing/plans/ — public, no authentication.

curl https://api.figgshield.ai/api/billing/plans/

[
  {
    "slug": "pro",
    "name": "Pro",
    "price_monthly_cents": 2900,
    "price_yearly_cents": 34800,
    "monthly_credits": 1100,
    "parallel_limit": 5,
    "features": ["1,100 credits a month", "5 generations in parallel"],
    "highlight": true
  }
]

The three plans:

Plan	Sticker	Charged annually	Credits / month	Parallel jobs	≈ images or clips
Starter	$12/month	$144/year	400	3	50 images / 11 clips
Pro (highlighted)	$29/month	$348/year	1,100	5	137 images / 31 clips
Studio	$75/month	$900/year	3,000	8	375 images / 85 clips

price_monthly_cents is the display sticker; price_yearly_cents = 12 × sticker is the only amount ever charged. highlight marks the plan to present as the default (Pro). Capacity figures assume 8-credit Nano Banana 2 images and 35-credit Kling clips.

Billing status

GET /api/billing/status/

curl https://api.figgshield.ai/api/billing/status/ \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY"

{
  "plan": { "slug": "pro", "name": "Pro", "parallel_limit": 5 },
  "status": "active",
  "interval": "yearly",
  "current_period_end": "2027-07-01T00:00:00Z",
  "cancel_at_period_end": false,
  "processor": "stripe",
  "has_payment_method": true
}

interval is always "yearly". plan is null while the account has no active subscription — in that state generation creation returns 402 subscription_required. has_payment_method tells you whether automatic top-ups can be enabled.

Checkout

POST /api/billing/checkout/ with {"plan": "<slug>"} — returns a Stripe Checkout URL to complete in a browser. Billing is annual; an interval field, if sent, is ignored.

curl https://api.figgshield.ai/api/billing/checkout/ \
  -X POST \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "pro" }'

{ "checkout_url": "https://checkout.stripe.com/c/pay/cs_..." }

POST /api/billing/portal/ returns a portal_url to the Stripe billing portal for managing the payment method, invoices and cancellation.

Top-ups

Top-ups buy extra credits between grants, at your plan’s rate. The conversion formula:

credits = floor(amount_cents × plan.monthly_credits ÷ plan.price_monthly_cents)

For example, a $50 top-up on Pro: floor(5000 × 1100 ÷ 2900) = 1,896 credits. The minimum top-up is 5000 cents ($50) — below that the request fails with 400 validation_error. Top-ups require an active subscription.

Manual top-up

POST /api/billing/topup/ with {"amount_cents": <int ≥ 5000>} — returns a Stripe Checkout URL (one-off payment). The credits land as a ledger entry of type topup once payment completes.

curl https://api.figgshield.ai/api/billing/topup/ \
  -X POST \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 5000 }'

Automatic top-ups

GET /api/billing/topup/settings/ / PATCH the same URL:

curl https://api.figgshield.ai/api/billing/topup/settings/ \
  -X PATCH \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_topup_enabled": true,
    "auto_topup_amount_cents": 5000,
    "auto_topup_threshold_credits": 50
  }'

Field	Meaning
auto_topup_enabled	Enabling requires an active subscription and a payment method on file (has_payment_method).
auto_topup_amount_cents	Amount charged per automatic top-up; minimum 5000 ($50).
auto_topup_threshold_credits	Balance level that triggers a top-up; must be ≥ 0.
preview_credits	Read-only: how many credits the configured amount buys at your current plan rate.

When enabled, an automatic top-up fires in two situations, server-side and atomically:

1. On generation create, if your balance cannot cover the job’s cost: the saved payment method is charged off-session, credits are granted, and the generation proceeds. If the payment fails, the request returns 402 insufficient_credits.
2. After any burn that leaves the balance below auto_topup_threshold_credits.

At most one automatic top-up per hour fires, as a guard against loops.

Webhooks

POST /api/billing/webhooks/stripe/ (signature-verified) receives payment events from Stripe and fast-acknowledges with 200. It is called by Stripe, not by API clients — you never need to call it. Affiliate commission payouts run through Stripe Connect off the same invoice.paid events.