Api Rate Plan Designer

Api Rate Plan Designer

# API Rate Plan Designer

Designing API pricing is harder than designing the API itself. Most teams start with a flat per-request fee, then discover they're losing money on power users, confusing small customers with too-high minimums, and building billing systems that can't handle burst traffic or multi-dimensional quotas. Competitors with well-designed tiered plans capture both the high-volume and low-risk segments, leaving flat-rate APIs priced out of both markets. Worse, changing a pricing model after launch requires coordinated changes across billing code, rate limiting middleware, customer notifications, and SLA documentation. A poorly designed rate plan at launch locks in months of technical debt and customer confusion. This skill solves that by generating complete, production-ready rate plan designs: tier structures with unit economics, quota dimensions, rate limit algorithms, overage policies, SLA mappings, and rollout strategies. It outputs deployable OpenAPI extensions and billing logic templates, not abstract advice.

What It Does

• Generates multi-tier pricing structures (free, pro, enterprise) with per-tier unit economics
• Designs quota systems across multiple dimensions (requests, tokens, storage, users, concurrent connections)
• Maps rate limiting algorithms (token bucket, sliding window, fixed window) to each tier
• Computes break-even pricing from infrastructure costs, margin targets, and churn projections
• Generates OpenAPI 3.1 extensions for pricing metadata
• Creates customer-facing pricing pages and internal billing logic

Frameworks/Standards Covered

| Framework/Standard | Application | |---|---| | OpenAPI 3.1 (pricing extension) | Embed pricing metadata in API specs | | Pricing4APIs model | Academic pricing modeling framework | | Stripe billing model | Metered billing, tiered subscriptions, invoices | | AWS Usage Records | Pay-as-you-go and reserved capacity pricing | | Token Bucket Algorithm | Burst-tolerant rate limiting | | Sliding Window Log | Precise per-second quota enforcement | | Fixed Window Counter | Simple per-minute/hour quotas | | SLA 4OAI | SLA specification extension for OpenAPI | | ISO 20022 | Financial message pricing standards | | GDPR Article 20 | Data portability compliance across tiers |

Quick Start

```bash
# Generate a complete rate plan for a free + pro + enterprise API
python3 scripts/rate_plan_cli.py generate --name "My API" --base-cost 0.0002 --tiers 3 --output config/plan.yaml

# Compare two pricing models side by side
python3 scripts/rate_plan_cli.py compare --plan-a config/plan.yaml --plan-b config/enterprise_plan.yaml

# Calculate break-even pricing for a given infrastructure cost
python3 scripts/rate_plan_cli.py breakeven --cost-per-request 0.00015 --target-margin 0.75 --monthly-requests 10000000

# Export pricing to OpenAPI extension format
python3 scripts/rate_plan_cli.py export --plan config/plan.yaml --format openapi --output config/pricing-extension.yaml
```

Configuration

The skill reads from `config/plan_config.yaml` which defines the base parameters for plan generation: ```yaml api: name: "My Cloud API" base_cost_per_request: 0.0002 base_cost_per_gb_storage: 0.10 base_cost_per_gb_bandwidth: 0.09 monthly_infra_fixed: 500 target_margin: 0.70 churn_rate_monthly: 0.05 plans: free: requests_per_month: 10000 rate_limit_rpm: 60 storage_gb: 0.1 support: community sla_uptime: "99.5%" pro: requests_per_month: 100000 rate_limit_rpm: 300 storage_gb: 5 support: email sla_uptime: "99.9%" enterprise: requests_per_month: -1 # unlimited rate_limit_rpm: 5000 storage_gb: 500 support: dedicated sla_uptime: "99.99%" ```

Output Format

The CLI produces YAML/JSON output structured for both internal pricing decisions and customer-facing documentation: ```yaml plan_name: Pro monthly_price: 49.99 price_per_request: 0.0005 price_per_storage_gb: 0.08 price_per_bandwidth_gb: 0.05 overage: request_overage: 0.001 storage_overage: 0.15 quota: rate_limit_algorithm: sliding_window rate_limit_rpm: 300 rate_limit_burst: 600 daily_quota: 50000 revenue_projection: expected_mrr: 49.99 infra_cost_per_user: 14.99 gross_margin: 0.70 payback_period_months: 1 ```

Feature Breakdown

### Tier Structure Design Automatically generates 3-tier (free-pro-enterprise) or custom multi-tier plans with price anchoring, feature differentiation, and upgrade path design. Each tier has distinct rate limits, quota dimensions, storage allowances, and support SLAs. The generator uses competitive anchoring to position the pro tier as the value sweet spot. ### Unit Economics Engine Computes per-unit costs from infrastructure inputs: compute per request, storage per GB, bandwidth per GB, egress fees, and database connection costs. Applies target margins, churn-adjusted LTV calculations, and break-even analysis across all tiers. Outputs gross margin per tier, payback period, and recommended prices. ### Overage and Quota Systems Designs four overage models: hard cap (return 429), soft cap (allow with surcharge), auto-scale (promote to next tier), and credit pool (bucket of prepaid overage units). Each model maps to specific HTTP headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) and billing system hooks. ### Rate Limit Algorithm Selector Selects the optimal rate limiting algorithm per tier: token bucket for burst-tolerant tiers (enterprise), sliding window for precise billing tiers (pro), fixed window for free tiers. Includes Redis-backed distributed rate limiting reference architecture with Lua scripts for atomic operations. ### OpenAPI Pricing Extension Generator Appends x-pricing blocks to OpenAPI 3.1 specs, enabling API consumers to discover pricing programmatically via the API specification itself. Follows the Pricing4APIs model with plan definitions, quota limits, rate dimensions, and pricing formulas. ### SLA-to-Tier Mapping Maps each pricing tier to specific SLA commitments: uptime percentage, latency P99 targets, support response times, and data retention periods. Generates SLA 4OAI extensions for OpenAPI specs. ### Competitive Analysis Accepts competitor plan data and computes positioning recommendations: where to undercut, where to premium-price, feature bundling strategies, and feature gap analysis.

Why This Beats Prompting It Yourself

Generic LLM Prompt This Skill --- --- --- Unit economics Guesstimates prices Computes from infrastructure costs and margin targets Rate limit algorithms "Use rate limiting" Selects algorithm per tier with Redis implementation Overage handling "Add overage charges" 4 overage models with billing system hooks OpenAPI integration None Generates x-pricing extensions for OpenAPI 3.1 SLA mapping "Add SLA" Maps uptime/latency/support per tier Multi-dimensional quotas "Limit requests" Requests + tokens + storage + users + connections Competitive positioning "Look at competitors" Accepts competitor data, computes recommendations Production output Text description Deployable YAML/JSON configs and CLI tool

Use Cases

• SaaS API Launch: A startup launching a public REST API needs to design pricing tiers that attract developers while covering infrastructure costs. Generates free (10K req/mo), pro ($49/mo, 100K req/mo), and enterprise ($499/mo, unlimited) tiers with unit economics.
• Platform Migration: An existing flat-rate API ($0.01/request) is losing money on heavy users and scaring away light users. The skill generates a migration plan with grandfathering, phased tier rollout, and customer communication templates.
• Enterprise Sales Negotiation: A sales team needs to price a custom enterprise plan for a large customer. The skill computes break-even pricing from the customer's expected volume, storage needs, and support requirements.
• API Marketplace: An API marketplace operator needs standardized pricing across dozens of third-party APIs. The skill generates a uniform pricing schema with OpenAPI extensions that all providers adopt.
• Internal API Chargeback: A platform team needs to charge internal product teams for API usage. The skill generates cost-based pricing with showback/revealback models, monthly invoices, and budget alerts.