Billing & top-ups

Figgshield has three paid plans, billed annually by default — prices are displayed per month and the annual charge is twelve times the monthly sticker, once a year — or monthly at a higher sticker (1.3 × the annual-billing sticker). Credits are granted monthly and are identical on both intervals. 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,
    "price_monthly_billed_cents": 3770,
    "monthly_credits": 1100,
    "parallel_limit": 5,
    "features": ["1,100 credits a month", "5 generations in parallel"],
    "highlight": true
  }
]

The three plans:

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

price_monthly_cents is the display sticker on yearly billing; price_yearly_cents = 12 × sticker is the amount charged annually. price_monthly_billed_cents (1.3 × the sticker) is the amount charged each month on monthly billing. Credits are the same on both intervals. highlight marks the plan to present as the default (Pro). The ”≈ images or clips” figures are approximate — they assume entry-resolution images and short 720p clips; exact per-generation costs vary by model and option (see get_model_pricing or the pricing page).

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 "yearly" or "monthly", matching the interval chosen at checkout. 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>", "interval": "yearly" | "monthly"} — returns a Stripe Checkout URL to complete in a browser. interval is optional and defaults to "yearly"; send "monthly" to be charged price_monthly_billed_cents each month instead of price_yearly_cents once a year.

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

{ "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.

Two credit buckets

Your balance is made of two kinds of credit, tracked separately in the usage summary as plan_balance and topup_balance:

• Plan credits (plan_balance) are granted each billing month — a 30-day cycle from when you subscribe. They reset to your plan’s monthly allotment at the start of each cycle and do not roll over: unused plan credits are cleared at each reset.
• Top-up credits (topup_balance) are the extra credits you purchase. They are separate from the monthly reset: they carry over from one billing month to the next and expire 12 months after the date of purchase.

A generation always spends plan credits first, then top-up credits, so your monthly allotment is used up before any purchased credits are touched. The credits.balance in the usage summary is simply plan_balance + topup_balance.

Top-ups

Top-ups buy extra credits between grants, at your plan’s rate. They land in topup_balance, survive each monthly reset, and expire 12 months after purchase. 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.