BillingBilling Overview

Billing Overview

Bloqr supports three complementary billing paths:

Billing Overview

Bloqr supports three complementary billing paths:

  1. Personal subscriptions — monthly auto-pay with a 7-day base-plan trial.
  2. Business / organization billing — monthly auto-pay or invoice terms, with Cloudflare consumption pass-through for invoiced orgs.
  3. Pay As You Go (PAYG) — per-call billing through Stripe Checkout with short-lived API sessions.

Billing Models

Pay As You Go (PAYG)

PAYG is designed for low-volume or occasional API access. A completed Stripe payment is converted into a deterministic PaygSession, which is then sent in X-Payg-Session.

PropertyValue
Price per callConfigurable via PAYG_PRICE_PER_CALL_USD_CENTS (default: $0.01)
Session size10 calls per payment by default, or the purchased Stripe quantity
Session TTL1 hour
Rate limit120 req/min, 500 req/day
Max rules per list50,000
Max sources per compile5
Retention7 days

PAYG uses the x402 protocol for machine-readable payment negotiation:

  • X-Payment-Required — sent by the server in 402 responses with the payment specification.
  • X-Payg-Session — sent by the client in subsequent requests once a session is purchased.

Session Flow

Client                          Server
  |                               |
  |-- GET /api/compile ---------->|
  |<-- 402 Payment Required -------|
  |   X-Payment-Required: {...}   |
  |                               |
  |-- POST /stripe/payg/checkout ->|
  |<-- { checkoutUrl } ------------|
  |                               |
  |-- (completes Stripe Checkout) |
  |-- POST /payg/session/create -->|
  |   { checkoutSessionId }        |
  |<-- { sessionToken } -----------|
  |                               |
  |-- GET /api/compile ----------->|
  |   X-Payg-Session: <token>     |
  |<-- 200 OK ---------------------|
  |   X-Payg-Session-Remaining: 9 |

Subscription Plans

PlanTrialRate LimitDaily LimitFeatures
Free—60 req/min—Basic compilation
Pro7 days300 req/min10,000/dayAST storage, webhooks, version history
Vendor7 days600 req/min50,000/dayAll Pro + translation, CDN distribution
Enterprise7 daysUnlimitedUnlimitedAll Vendor + dedicated SLA

Add-ons are modelled as separate Stripe products / prices with shorter 1–2 day trials. Product metadata must mirror SubscriptionPlan feature flags and SUBSCRIPTION_TIER_LIMITS.

Architecture

Environment Variables

VariableTypeDescription
STRIPE_PUBLISHABLE_KEYNon-secretLive Stripe publishable key (safe for frontend)
STRIPE_SECRET_KEYSecretLive Stripe secret key
STRIPE_WEBHOOK_SECRETSecretLive webhook signing secret
STRIPE_TEST_SECRET_KEYSecretSandbox Stripe secret key
STRIPE_TEST_WEBHOOK_SECRETSecretSandbox webhook signing secret
STRIPE_BILLING_MODENon-secretDefault request billing mode (live or sandbox)
BILLING_MODE_OVERRIDESKVPer-user / per-org live vs sandbox overrides
USAGE_LEDGERKVRolling usage counters for Stripe metering aggregation
STRIPE_PAYG_PRICE_IDNon-secretStripe Price ID for PAYG checkout
PAYG_PRICE_PER_CALL_USD_CENTSNon-secretPrice per API call (default: 1)
PAYG_CONVERSION_THRESHOLD_USD_CENTSNon-secretUpsell threshold (default: 2000 = $20)

Mode resolution happens in worker/services/stripe-service.ts:

  1. Check BILLING_MODE_OVERRIDES using the org ID, then the user ID.
  2. Fall back to STRIPE_BILLING_MODE.
  3. Select the matching live or sandbox Stripe keys for the request.

wrangler.toml defines [env.staging] with STRIPE_BILLING_MODE = "sandbox" so a single deployment can default staging traffic to Stripe test mode.

Database Additions

Billing state is persisted in:

  • StripeProductCache — Stripe product / price read cache for pricing UX.
  • BillingUsageEvent — append-only API usage ledger.
  • CloudflareUsageSnapshot — Cloudflare pass-through usage for invoiced orgs.
  • BillingModeOverride — persisted source of truth for live / sandbox overrides.
  • PaygCustomer, PaygPaymentEvent, PaygSession — PAYG customer, payment, and session state.
Was this page helpful?