Plans, credits, and entitlements

Purpose

Billing determines the credits, retention, and product capabilities available to an organization. Open Settings → Billing for the current subscription and exact commercial terms.

Settings → Billing is organized in four tabs:

Tab	Use it to
Overview	See your plan, licenses this month, and credit balances; fix payment failures
Top-ups	Buy credit packs, manage Team licenses, or subscribe to the SAST add-on
Plan	Change plan or billing period, open the Stripe portal, redeem a coupon; auto-recharge is under Advanced options
History	Stripe invoices and the credit ledger (filters + CSV export)

Client organizations only see History (parent billing account).

Who

Billing owners manage subscriptions. Organization owners can review entitlements; members should contact an owner for changes.

Prerequisites

Know which organization is being billed and whether the work uses core scans or source code security scans: they use separate credit pools.

How it works

Plan	Credits and scale	Included gates
Free	100 core credits; 3 active licenses / month; 1 repository; 30-day retention	Basic policy; no pay-as-you-go, API, webhooks, export, SSO, bundles, or audit logs
Starter	800 core credits; 10 active licenses / month; 8 repositories; 90-day retention	Standard policy and proof export; pay-as-you-go available; no API or webhooks
Team	Minimum 5 licenses / month (Stripe quantity); 100 core credits per license; unlimited repositories; 365-day retention	Complete policy, API, webhooks, Jira/Linear issue trackers, basic SSO, bundles, audit logs, proof export, Auditor Export Pack, 99.9% SLA
Regulated	Custom credit and commercial agreement; unlimited retention and scale	Complete policy, full SSO, API, webhooks, bundles, audit logs, proof export, Auditor Export Pack, 99.99% SLA

Starter vs Team: Starter is a fixed scan pack (credits, repos, proof export). Team is the org platform: API, webhooks, SSO, audit logs, Auditor Export Pack, unlimited repos, and SLA. Team credits scale with licenses — upgrading for features, not for a larger fixed credit bucket.

In-app upgrade cues: On Free and Starter, the app may show locked nav items, blur previews, and meters with an upgrade path. Owners/admins get a Checkout CTA under Settings → Billing → Plan. Members see an ask-an-admin message — they cannot open full billing status (GET /billing/status is Settings-only). The UI never invents a Free plan when status is unavailable; members learn the real plan id from the lightweight credits-alert endpoint so Team orgs are not false-locked. Locked Team features (SSO, webhooks, API tokens, …) show an in-app wall without calling those gated Settings APIs until the plan allows them.

Licenses (MAU): Each person who uses the product in a calendar month consumes one license. Unused licenses are lost at month end. Yearly billing is prepaid payment only — the same monthly license rules apply. Admins buy more mid-cycle (Team) or schedule a lower quantity for the next billing renew. Soft-removing a member does not free a license already consumed that month.

SAST is a separate pool/add-on: SAST Starter includes 50 SAST credits; SAST Team includes 50 SAST credits per license. Exact prices and availability are shown in Billing.

Credit history: Organization owners and admins can review a read-only ledger under Settings → Billing → History (filters + CSV export). Consume rows include project unit (when recorded) and trigger (sourceTrigger). Automatic platform scan refunds appear as grants with source=scan_failure_refund. On a client organization, the ledger shows the parent billing account. Members without billing access cannot open it. Support adjustments appear with a motif; there is no customer self-serve credit remediation. See Credits.

Invoices

Invoices are Stripe-only mirrors (hosted invoice URL / PDF / number). They appear in Settings → Billing → History after a Stripe payment (subscription, seats, credit pack Checkout, or auto-recharge). On Free with no Stripe customer, an empty invoice list is expected.

The billing overview (home and Settings → Billing → Overview) shows usage (licenses, credit balances, consumption) — not a projected end-of-period cost total. Billed amounts are those on the Stripe invoices listed above.

Emails

After Stripe confirms payment, owners and admins of the parent organization may receive fail-open billing emails: subscription active (first paid period), renewal or pack receipts, auto-recharge success or failure, and payment failed. Receipt emails include a View your invoice link when Stripe provides a hosted invoice URL (subscription, auto-recharge, and credit-pack Checkout). Emails do not replace the in-app invoice list or Stripe Customer Portal.

Payment method and portal

Completing Stripe Checkout for a plan subscription, SAST add-on, or credit pack establishes the customer’s default payment method when none is set yet (required for off-session auto-recharge). Use Manage in Stripe (Customer Portal) under Settings → Billing → Plan to change the card, download Stripe invoices, or cancel the paid plan. Return URLs stay on the app billing Plan tab.

Auto-renew

When auto-renew is on, Stripe renews the plan at period end. When off, the paid plan ends at period end and the organization returns to Free (credits, retention, and gates adjust then). Stripe drives paid renewals and period grants for Stripe subscriptions.

Paid period vs calendar month: included credits refill when Stripe renews the subscription (the anniversary date shown in Billing), not on the 1st of the calendar month. MAU licenses still reset on the calendar month. Auto-recharge pack caps reset with the paid billing period.

Auto-recharge (core credits)

Opt-in only (off by default). Billing admins can enable auto-recharge under Settings → Billing → Plan → Advanced options when a Stripe customer and default payment method exist. After a successful paid plan Checkout or an in-app paid plan change, billing admins may also see a one-time prompt with the same settings form (dismiss with Maybe later, or enable in one save). When the core balance falls to the configured threshold, CodeCleared charges the selected credit pack off-session via a Stripe Invoice (same catalog as manual packs: core-100, core-500) so the receipt appears in the in-app invoice list. A monthly cap limits how many packs can be purchased per billing period (default 3, max 10). Each successful charge sends a billing email to org owners/admins and writes an audit event. If a charge fails (missing card, declined payment, grant error, …), owners/admins get a failure email and an audit event is recorded; credits are not added. Repeated failures back off retries (15 minutes, then 1 hour, then 6 hours) and send at most one failure email per streak until a charge succeeds, the billing period resets, or an admin changes auto-recharge settings. Auto-recharge invoice failures do not set the global subscription payment-failed flag (402 payment_failed) — only failed subscription invoices do. While a charge is in flight, members may see an amber banner instead of the red depletion wall. Requires a PAYG-enabled paid plan (Starter or Team — not Free or Regulated) and no unresolved payment failure. CodeCleared platform administrators can inspect read-only auto-recharge status in the CC Admin credits snapshot (see Credits).

Auto-recharge (SAST credits)

Same opt-in model as core, with independent settings (GET/PATCH /billing/auto-recharge?pool=sast). Available when the organization has an active SAST add-on, a Stripe customer, a default payment method, and a PAYG-enabled paid plan (Starter or Team). After a successful SAST add-on Checkout, billing admins may see the same style of one-time prompt for the SAST pool (dismiss or enable). When the SAST balance falls to the configured threshold, CodeCleared charges the selected SAST pack off-session (sast-25 today) via Stripe Invoice. Monthly caps, failure backoff, emails, audit events, and the no payment_failed flag policy match core auto-recharge. While a SAST charge is in flight, members may see an amber SAST auto-recharge in progress banner instead of the red SAST depletion wall. Core and SAST pools never cross-fund each other.

Cancel SAST

You can deactivate the SAST add-on at SAST period end without cancelling the plan subscription. SAST stays available until that date; after deactivation, a new add-on subscription is required (purchased SAST credits alone do not unlock SAST). While cancellation is pending, you can undo it in Billing so SAST renews as before.

Lifecycle matrix

Change	When it takes effect
Free → paid (Checkout)	Immediate after Stripe confirms payment
Plan or billing period change (active Stripe subscription)	Next renew
Seats ↑	Mid-cycle (prorated)
Seats ↓	Scheduled for next renew (current pool does not shrink mid-cycle)
Auto-renew off	Paid plan ends at period end → Free
Cancel SAST	SAST add-on ends at SAST period end; plan unchanged (undo available while pending)

Payment failed → 402

Unresolved subscription payment failure sets a billing flag (lastPaymentFailedAt). Auto-recharge pack charge failures do not set this flag. Scans and other billable work can return 402 with payment_failed until the subscription payment method is updated in the portal. See Credits and 402 responses.

Business rules

Core credits do not fund SAST usage. Free cannot use pay-as-you-go. API and webhooks are generally available from Team; Regulated terms are custom. A 402 is an entitlement or applicable-credit-pool response, not a malformed request.

Scan data retention: Each plan sets a maximum retention window (see table). When a plan change is applied (upgrade or downgrade — immediately, or at renew when scheduled), the organization preference is reset to that plan’s maximum. Owners/admins can then shorten it under Settings → Organization, but cannot keep scan payloads longer than the plan allows. Regulated retention is unlimited (no automatic vacuum); the synced preference uses the longest selectable UI value (365 days). Older detailed scan payloads are vacuumed by a daily job.

Scenarios & edge cases

Core credits remain but SAST returns 402: obtain SAST credits or an included entitlement. A Team organization has fewer than five active licenses: it does not meet the Team minimum. seat_license_required: Team can purchase more licenses mid-cycle; Free/Starter must upgrade (or wait until next month). Soft-removing a member does not free a license already consumed that month. A feature disappears after a plan change: confirm the new plan’s gate and export records before retention changes apply. Retention setting rejects a longer period: upgrade the plan, or choose a value at or below the plan cap. payment_failed 402: update the payment method in Billing / Stripe portal, then retry.

Limits

Plan limits are organization-level. Do not assume unused credits transfer between pools or plans. Use Billing for the authoritative balance and current pricing.

Common errors

• Retrying a 402 without changing credits, payment method, or entitlement.
• Treating SAST and core credits as interchangeable.
• Assuming API access on Free or Starter.
• Expecting invoices on Free before any Stripe payment.

Links

• Credits
• Credits and 402 responses
• Service tokens
• Auditor Export Pack
• Reports and proof exports