← Back to home

// client scope demo

Usage metering, subscriptions & PAYG

Walkthrough of how we align per-job metering, dual-channel reporting (Stripe + RapidAPI), subscription billing with proration and metered overage, API key deactivation after ultimate payment failure, and pay-as-you-go with card on file. Live actions use your existing Stripe test products and prices.

1. Migrate metering: page → per job (4 APIs)

Normalize each successful operation into a single job event before it hits billing. Whether the call is synchronous or async, the usage reporter emits one unit per completed job per API surface.

Before

Page-based unit

Usage tied to “pages processed” (or similar). One billable unit does not map cleanly to work done across heterogeneous APIs.

After

Per-job unit

Each completed job is one usage event. Same semantics across 4 APIs — easier caps, overage, and forecasting.

↓normalize & emit
API A → 1 job = 1 unitAPI B → 1 job = 1 unitAPI C → 1 job = 1 unitAPI D → 1 job = 1 unit

2. Usage reporting: Stripe + RapidAPI

Direct subscribers are billed in Stripe; marketplace users are billed via RapidAPI. Internally you still store job counts per account so finance and product see one consistent metric.

StripeDirect customers
  • Customer + Subscription in Stripe
  • Usage: Billing Meters / usage records → invoice line items
  • Webhooks drive entitlements & API key state
RapidAPIMarketplace customers
  • Billing events from RapidAPI (plans / quotas)
  • Map marketplace identity → internal account + usage ledger
  • Same job-based unit internally; reconcile channels in reporting

3. Subscriptions: proration & metered overage

Plan changes mid-cycle use Stripe's proration behavior (configurable per change). A metered price on the same subscription captures overage beyond included jobs.

Subscribe
Checkout / Payment Link
→
Included jobs
Plan allowance
→
Overage
Metered price
→
Change plan
Proration
→
Renewal
Invoice + charge

Upgrades, downgrades, and monthly ↔ annual switches use Stripe's proration settings on the subscription; overage lines attach the metered price you configure.

Base subscription price (env) price_1T5QHrDUd7No1OBGVGO7wq6M
Optional: set STRIPE_METERED_OVERAGE_PRICE_ID to show your overage price here.

4. When payments ultimately fail → deactivate API keys

Your webhook worker listens for terminal failure signals (e.g. repeated invoice.payment_failed, subscription past_due / unpaid). After business rules say “give up,” revoke or flag API keys and notify the customer.

Invoice dueSmart retries / dunninginvoice.payment_failed / unpaidDeactivate API keys

Simulate webhook (demo log)

5. Pay-as-you-go: card on file & auto-recharge

New API: customers keep a card on file; you decrement an internal balance per job and trigger an off-session PaymentIntent when balance drops below a threshold (auto-recharge). The button below runs a one-time Checkout top-up that saves the card for that model.

Card on file
Customer + default PM
↓
Balance / credits
Ledger decreases per job
↓
Below threshold
Off-session charge (auto-recharge)

Demo below uses a one-time Checkout top-up with setup_future_usage so the saved card can power production-style auto-recharge via PaymentIntents.

PAYG top-up price (env) Set STRIPE_PAYG_TOPUP_PRICE_ID (one-time price in Stripe)

Live demo (test mode)

Use Payment Links for a frictionless share, or programmatic Checkout (same products). Customer Portal returns here after managing the subscription.

Subscription (Pro / base plan)

Opens Stripe Checkout with STRIPE_PRO_PRICE_ID.

Optional: set NEXT_PUBLIC_STRIPE_PAYMENT_LINK_SUBSCRIPTION for a hosted link from the Dashboard.

PAYG top-up (one-time)

Saves card with setup_future_usage for auto-recharge patterns.

Configure STRIPE_PAYG_TOPUP_PRICE_ID to enable API checkout for PAYG.

Optional: NEXT_PUBLIC_STRIPE_PAYMENT_LINK_PAYG.

Webhook log (real + simulated)

No events yet. Run checkout or simulate failures above.

Full Connect split-payout walkthrough: Stripe Connect demo →

Next step: production cutover

We wire meters to Stripe Billing, align RapidAPI reporting, tune proration and dunning, and enforce API key lifecycle from subscription state.

Book a call