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

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

tiers:
  free:
    price: 0
    included_calls: 1000/month
    rate_limit: 10/min
    endpoints: [/v1/basic/*]
    support: community
  pro:
    price: 49/month
    included_calls: 50000/month
    rate_limit: 100/min
    endpoints: [/v1/*]
    support: email
    overage: $0.002/call
  enterprise:
    price: custom
    included_calls: custom
    rate_limit: custom
    endpoints: [/v1/*, /v1/admin/*]
    support: dedicated
    sla: 99.9%

Set up Stripe metered billing

Create a Product and a metered Price, then subscribe a customer.

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

// 1. Create product
const product = await stripe.products.create({
  name: 'API Access - Pro Tier',
});

// 2. Create metered price (per-unit usage)
const meteredPrice = await stripe.prices.create({
  product: product.id,
  currency: 'usd',
  recurring: {
    interval: 'month',
    usage_type: 'metered',
    aggregate_usage: 'sum',
  },
  unit_amount: 0.2, // $0.002 per call (in cents: 0.2)
  billing_scheme: 'per_unit',
});

// 3. Create base price for the tier
const basePrice = await stripe.prices.create({
  product: product.id,
  currency: 'usd',
  recurring: { interval: 'month' },
  unit_amount: 4900, // $49.00
});

// 4. Subscribe the customer to both prices
const subscription = await stripe.subscriptions.create({
  customer: 'cus_xxx',
  items: [
    { price: basePrice.id },
    { price: meteredPrice.id },
  ],
});

Report usage to Stripe

Report API call counts to Stripe periodically (hourly or daily). Always use action: 'increment' for safe idempotent reporting.

// Find the metered subscription item
const subscription = await stripe.subscriptions.retrieve('sub_xxx');
const meteredItem = subscription.items.data.find(
  (item) => item.price.recurring.usage_type === 'metered'
);

// Report usage - increment by the count since last report
await stripe.subscriptionItems.createUsageRecord(meteredItem.id, {
  quantity: 1250, // API calls in this reporting period
  timestamp: Math.floor(Date.now() / 1000),
  action: 'increment',
});

Always use action: 'increment' rather than action: 'set'. With 'set', a retry after a network failure would silently overwrite the correct total.

Implement rate limiting middleware

Express middleware that enforces per-tier rate limits using a sliding window with Redis.

const Redis = require('ioredis');
const redis = new Redis(process.env.REDIS_URL);

const TIER_LIMITS = {
  free: { rpm: 10, window: 60 },
  pro: { rpm: 100, window: 60 },
  enterprise: { rpm: 1000, window: 60 },
};

async function rateLimiter(req, res, next) {
  const apiKey = req.headers['x-api-key'];
  const tier = await getTierForApiKey(apiKey); // your lookup
  const limit = TIER_LIMITS[tier];
  const key = `ratelimit:${apiKey}`;
  const now = Date.now();

  // Sliding window using sorted set
  await redis.zremrangebyscore(key, 0, now - limit.window * 1000);
  const count = await redis.zcard(key);

  if (count >= limit.rpm) {
    res.set('Retry-After', String(limit.window));
    res.set('X-RateLimit-Limit', String(limit.rpm));
    res.set('X-RateLimit-Remaining', '0');
    return res.status(429).json({ error: 'Rate limit exceeded' });
  }

  await redis.zadd(key, now, `${now}-${Math.random()}`);
  await redis.expire(key, limit.window);

  res.set('X-RateLimit-Limit', String(limit.rpm));
  res.set('X-RateLimit-Remaining', String(limit.rpm - count - 1));
  next();
}

Track usage for billing

Middleware that counts API calls per customer and flushes to Stripe on a schedule.

const usageBuffer = new Map(); // apiKey -> count

function usageTracker(req, res, next) {
  const apiKey = req.headers['x-api-key'];
  usageBuffer.set(apiKey, (usageBuffer.get(apiKey) || 0) + 1);
  next();
}

// Flush every hour
setInterval(async () => {
  for (const [apiKey, count] of usageBuffer.entries()) {
    const subItemId = await getMeteredSubItemForKey(apiKey);
    if (subItemId && count > 0) {
      await stripe.subscriptionItems.createUsageRecord(subItemId, {
        quantity: count,
        timestamp: Math.floor(Date.now() / 1000),
        action: 'increment',
      });
    }
  }
  usageBuffer.clear();
}, 60 * 60 * 1000);

In production, use a durable queue (SQS, Kafka) instead of an in-memory buffer to avoid losing usage data on process restarts.

Handle overage notifications

Notify customers when they approach or exceed their included quota.

async function checkUsageThresholds(customerId, currentUsage, includedCalls) {
  const percentage = (currentUsage / includedCalls) * 100;
  const thresholds = [80, 100, 120];

  for (const threshold of thresholds) {
    if (percentage >= threshold) {
      const alreadyNotified = await hasNotifiedThreshold(customerId, threshold);
      if (!alreadyNotified) {
        await sendUsageAlert(customerId, {
          currentUsage,
          includedCalls,
          percentage,
          threshold,
          message: threshold >= 100
            ? `You have exceeded your included ${includedCalls} API calls. Overage billing is active.`
            : `You have used ${percentage.toFixed(0)}% of your included API calls.`,
        });
        await markThresholdNotified(customerId, threshold);
      }
    }
  }
}

---

Anti-patterns / common mistakes

Mistake	Why it's wrong	What to do instead
Billing on gateway logs alone	Gateway logs can be incomplete or delayed; disputes become unresolvable	Use a dedicated metering service with durable event ingestion
Hard-cutting access at quota	Breaks customer production systems, causes churn	Throttle or enable overage billing with clear notifications
Using action: 'set' in Stripe usage records	Retries overwrite the correct total, causing under-billing	Always use action: 'increment' for idempotent reporting
Same rate limit for all endpoints	Expensive endpoints (ML inference) subsidized by cheap ones (health check)	Weight rate limits by endpoint cost or use separate quotas
No rate limit headers in 429 responses	Clients cannot implement proper backoff	Always return Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining
Reporting usage in real-time per request	Creates enormous Stripe API load, risks rate limiting from Stripe itself	Batch usage reports hourly or daily

---

Gotchas

1. 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.

2. 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.

3. 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.

4. 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.

5. 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
• references/rate-limiting-patterns.md - Advanced rate limiting algorithms, Redis implementations, and distributed rate limiting

Only load a references file if the current task requires it - they are long and will consume context.