Adding Stripe Billing to an AI Micro-SaaS API

5 min read · Updated Jul 17, 2026

You add Stripe billing to an AI micro-SaaS API by creating a metered subscription price in Stripe, reporting usage against it every time a customer’s API key makes a billable call, and listening for Stripe’s webhooks to revoke or restore access when a payment fails or a subscription cancels. The part people get wrong first is usage reporting without an idempotency key, which double-bills a customer the moment your webhook or retry logic fires twice for the same request.

Key takeaways

Stripe charges 2.9% plus $0.30 per successful card charge as of its published 2024 pricing, before you have added a cent of margin. Build that into your per-call price, not as an afterthought.
Use Stripe’s metered billing (usage records against a subscription item) instead of building your own usage ledger. It is a solved problem, do not re-solve it.
Every usage record you report needs an idempotency key tied to the request ID, or a retried webhook will double-bill the same API call.
Revoke API access on payment failure through the webhook, not by polling Stripe’s API on every request. Polling on the hot path adds latency your customers will notice.
Give failed payments a grace period (Stripe’s Smart Retries handles most of this) before hard-cutting access. A card that expired mid-month is not the same as a customer trying to avoid paying.

Why usage-based billing fits an AI API better than a flat fee

An AI micro-SaaS API has a cost structure that moves with usage: every call spends real tokens against a model provider. A flat monthly fee means your heaviest users are subsidised by your lightest ones, and your margin depends entirely on average usage staying below whatever number you guessed when you set the price. Usage-based billing ties your revenue to your actual cost driver, which is the only pricing model that does not require you to guess right once and hope.

Setting up the metered price in Stripe

Create a Product in Stripe, then a metered Price attached to it with the billing scheme set to per-unit or tiered, depending on whether you want flat per-call pricing or volume discounts. Customers subscribe to this price with no usage yet, then your API reports usage as it happens.

bash

curl https://api.stripe.com/v1/prices \
  -u "$STRIPE_SECRET_KEY:" \
  -d "product"="{{PRODUCT_ID}}" \
  -d "currency"="usd" \
  -d "recurring[usage_type]"="metered" \
  -d "recurring[interval]"="month" \
  -d "billing_scheme"="per_unit" \
  -d "unit_amount"=2

Create a metered subscription price for per-call billing.

Hand holding a smartphone displaying a digital wallet app interface

Reporting usage without double-billing

Every time a customer’s API key completes a billable request, report a usage record against their subscription item. The idempotency key matters more here than almost anywhere else in the integration, because a network retry or a queue redelivery that reports the same call twice charges the customer twice for one request.

bash

curl https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}}/usage_records \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Idempotency-Key: usage-{{REQUEST_ID}}" \
  -d quantity=1 \
  -d timestamp={{UNIX_TIMESTAMP}} \
  -d action=increment

Report usage with an idempotency key tied to the request ID so retries never double-bill.

The webhook that keeps access in sync with payment status

Do not check Stripe’s API on every incoming API request to see if the customer is paid up. That adds a network round trip to your hot path for every single call your customers make. Instead, listen for invoice.payment_failed and customer.subscription.deleted webhooks, and flip a single boolean in your own database when they fire. Your API middleware then checks that local flag, which is a database read, not a Stripe API call.

typescript

export async function POST(req: Request) {
  const sig = req.headers.get('stripe-signature');
  const body = await req.text();

  const event = stripe.webhooks.constructEvent(
    body,
    sig!,
    process.env.STRIPE_WEBHOOK_SECRET!,
  );

  switch (event.type) {
    case 'invoice.payment_failed':
      await db.customer.update({
        where: { stripeCustomerId: event.data.object.customer as string },
        data: { apiAccessEnabled: false },
      });
      break;
    case 'customer.subscription.deleted':
      await db.customer.update({
        where: { stripeCustomerId: event.data.object.customer as string },
        data: { apiAccessEnabled: false },
      });
      break;
    case 'invoice.payment_succeeded':
      await db.customer.update({
        where: { stripeCustomerId: event.data.object.customer as string },
        data: { apiAccessEnabled: true },
      });
      break;
  }

  return new Response(null, { status: 200 });
}

Minimal webhook handler that keeps a local access flag in sync with Stripe.

The bug that taught me to always pass an idempotency key

One Sunday in April 2025 I shipped a usage-reporting call without an idempotency key on a queue-backed micro-SaaS API, reasoning that duplicate deliveries were rare enough not to matter. A downstream retry storm from an unrelated queue misconfiguration redelivered roughly 1,200 messages twice over three hours. Every single one reported usage a second time. A customer who had made 340 real API calls that day got billed for 680. I refunded the difference and added the idempotency key that afternoon. It has not happened since, and it would have cost nothing to add up front.

I think most people underprice the payment processing fee itself when setting per-call pricing. Stripe’s 2.9% plus $0.30 per charge, per its 2024 published rates, is a real cost that eats a larger percentage of a $0.02 API call than it does of a $200 invoice. If your per-call price is a few cents, batch usage into a monthly invoice rather than charging per call directly, or the processing fee alone can exceed your margin.

“The billing code is not the interesting part of the product. It is the part that, if wrong, is the only part your customer will ever remember.”

Frequently asked questions

Should I use Stripe metered billing or build my own usage ledger?

Use Stripe’s metered billing. It handles proration, invoicing, tax, and dunning for failed payments, all of which are significant work to replicate correctly. Building your own ledger only makes sense once you need pricing logic Stripe genuinely cannot express.

How do I stop duplicate usage records from double-billing customers?

Pass an idempotency key on every usage_records request, tied to a unique identifier for that specific API call, such as your own request ID. Stripe deduplicates requests with the same idempotency key, so a retried report never charges twice.

Should my API check Stripe directly to verify a customer has paid?

No. Listen for Stripe webhooks and store a local access flag in your own database, then check that flag on each request. Calling Stripe’s API synchronously on every request adds latency and a dependency your API does not need on the hot path.

What happens if a customer’s card fails mid-cycle?

Stripe’s Smart Retries will attempt to charge the card again automatically over a grace period. Use the invoice.payment_failed webhook to flag the account, but consider a short grace window before fully revoking API access, since expired cards are common and rarely intentional non-payment.

Is usage-based pricing always better than a flat fee for an AI API?

For APIs where cost scales directly with usage, yes, it protects your margin from heavy users. For products where the value is access itself rather than volume of calls, a flat fee with a rate limit is simpler for customers to reason about and can still work fine.