Use this skill when designing or implementing API monetization strategies - usage-based pricing, rate limiting, developer tier management, Stripe metering integration, or API billing systems. Triggers on tasks involving API pricing models, metered billing, per-request charging, quota enforcement, developer portal tiers, overage handling, and Stripe usage records.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use this skill when designing or implementing API monetization strategies - usage-based pricing, rate limiting, developer tier management, Stripe metering integration, or API billing systems. Triggers on tasks involving API pricing models, metered billing, per-request charging, quota enforcement, developer portal tiers, overage handling, and Stripe usage records.
[{"url":"https://docs.stripe.com/billing/subscriptions/usage-based","accessed":"2026-03-14T00:00:00.000Z","description":"Stripe usage-based billing and metering documentation"},{"url":"https://docs.stripe.com/api/usage-records","accessed":"2026-03-14T00:00:00.000Z","description":"Stripe usage records API reference"}]
license
MIT
maintainers
[{"github":"maddhruv"}]
When this skill is activated, always start your first response with the 🧢 emoji.
API Monetization
API monetization is the practice of turning API usage into a revenue stream
through pricing models, metering, and billing infrastructure. It spans from
defining developer tiers and rate limits to integrating with payment providers
like Stripe for usage-based billing. This skill covers the full stack: pricing
model design, quota enforcement, metered usage tracking, and Stripe integration
for automated invoicing.
When to use this skill
Trigger this skill when the user:
Wants to design a pricing model for a public or partner API
Needs to implement usage-based or metered billing for API calls
Asks about rate limiting strategies tied to paid tiers
Wants to integrate Stripe metering or usage records into an API
Needs to build a developer tier system (free, pro, enterprise)
Asks about tracking API consumption per customer
Wants to handle overage billing or throttling for quota breaches
Needs to design a developer portal with tiered access
Do NOT trigger this skill for:
General Stripe payments unrelated to API billing (use a Stripe skill)
API gateway configuration without a monetization component
Key principles
Meter before you bill - Never charge for usage you cannot accurately measure. Instrument every billable endpoint with reliable counters before enabling paid tiers. Lost meter events mean lost revenue or customer disputes.
Tiers define the product, not just the price - Each developer tier should differ in meaningful capabilities (rate limits, endpoints available, SLA, support level), not just volume. This prevents a race-to-the-bottom on price.
Rate limits are a feature, not just protection - Rate limits serve dual duty: they protect infrastructure AND enforce tier boundaries. Design them as a first-class part of the product, with clear headers and upgrade paths.
Idempotent usage reporting - Usage records must be idempotent. Network retries, duplicate webhook deliveries, and reprocessed queues should never double-count usage. Use idempotency keys on every usage report call.
Graceful degradation over hard cutoffs - When a customer hits a quota, prefer throttling or overage billing over immediately blocking access. Hard cutoffs break production systems and destroy trust.
Core concepts
Pricing models fall into three categories: flat-rate (fixed monthly fee per tier), usage-based (pay per API call or resource unit), and hybrid (base fee plus usage overage). Most successful API businesses use hybrid pricing because it provides revenue predictability while rewarding growth.
Metering is the infrastructure that counts billable events. A meter sits between the API gateway and the billing system. It must be durable (no lost events), idempotent (no double-counts), and near-real-time (customers see current usage). Common implementations use a message queue (Kafka, SQS) feeding an aggregation service that reports to Stripe.
Developer tiers are named bundles of quotas, rate limits, and feature flags. A typical structure is Free (heavily rate-limited, basic endpoints), Pro (higher limits, all endpoints, email support), and Enterprise (custom limits, SLA, dedicated support). Each tier maps to a Stripe Price with optional metered components.
Rate limiting enforces tier boundaries at the API gateway level. The standard approach is token bucket or sliding window per API key, returning 429 Too Many Requests with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
Stripe metering connects API usage to invoices. The flow is: create a metered Price on a Product, subscribe customers, then report usage via stripe.subscriptionItems.createUsageRecord(). Stripe aggregates usage and generates invoices at the billing cycle end.
Common tasks
Design a tier structure
Define tiers based on target customer segments. Each tier needs: a name, monthly base price, included API calls, rate limit (requests/minute), overage rate, and available endpoints.
Creates enormous Stripe API load, risks rate limiting from Stripe itself
Batch usage reports hourly or daily
Gotchas
In-memory usage buffers are lost on process restart - Buffering usage counts in a Map or similar in-process store means any crash or deploy loses that billing period's data. Use a durable queue (SQS, Redis with AOF, Kafka) as the write-ahead log before aggregating and reporting to Stripe.
action: 'set' on retried Stripe usage reports silently under-bills - If a usage record POST fails and you retry with action: 'set', the retry sets the total to the retry value, discarding any usage already recorded in the current billing period. Always use action: 'increment' so retries are safe.
Redis sorted set race condition in sliding window rate limiter - The ZREMRANGEBYSCORE + ZCARD + ZADD sequence is not atomic. Under high concurrency, two requests can both pass the check before either adds their entry, allowing a brief burst over the limit. Use a Lua script or MULTI/EXEC transaction to make the check-and-increment atomic.
Free tier users who never convert still cost infrastructure - A free tier with no rate limits or usage caps can be abused as free compute. Define hard rate limits even on the free tier, and implement API key rotation or abuse detection before going public.
Stripe metered price aggregate_usage cannot be changed after creation - If you create a metered price with aggregate_usage: 'sum' and later want 'max', you must create a new price and migrate subscribers. Plan the aggregation model before creating prices in production.
References
For detailed content on specific sub-domains, read the relevant file
from the references/ folder:
references/stripe-metering.md - Deep dive into Stripe metered billing setup, tiered pricing, and invoice lifecycle
Only load a references file if the current task requires it - they are
long and will consume context.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
