[Proposal]: Monetization support for API Platform

[nisan-abeywickrama]

Background

The API Platform lets API providers publish APIs and control access to them through subscription plans, but it provides no way to charge for that access. API providers who want to sell their APIs need pricing on plans, a checkout for subscribers, usage-based billing and invoicing

Scope

Initial scope

• HTTP APIs: REST APIs and GraphQL APIs.
• Moesif integration: Moesif meters usage and manages the billing catalog, and Stripe handles checkout, invoices and payments.

Future work

• Async APIs, AI APIs, MCP and agents, with usage measures that suit them, such as tokens.
• Other connectors: A Stripe connector managing the billing directly, and connectors for other billing providers.
• A gateway usage publisher that sends usage directly to Stripe or to a custom billing service.

Architecture

• Platform API (control plane): Holds subscription plans with their pricing (price per request, currency, billing period) and the plans enabled for each API. Publishes plans and pricing to the API Portals, receives subscription and payment status through the existing subscription webhook, and sends billing metadata to the gateways. It holds no billing credentials and never calls a billing provider.

• API Portal: Introduce a new monetization module with four parts:

  • Billing settings: The API Portal administrator enters the Moesif and Stripe credentials, separately for test and live, and chooses which setup the portal uses by default.
  • Billing catalog: When a paid plan is enabled for an API version, the module creates the matching plan, price and billing meter in Moesif.
  • Checkout and payment events: The module sends subscribers to Stripe to pay, receives Stripe's payment notifications, and passes the subscription and payment status to the Platform API.
  • Usage and revenue reports: Subscribers see their own usage, and the API Portal administrator sees usage and revenue across all subscribers.

The module communicates with billing providers through a billing provider interface.

• Gateways:
  • Usage publisher: sends API usage to Billing provider with the subscriber's details. (Only applicable is monetization is used without Moesif)

Proposed Flow

Monetization Setup, API publishing and subscription

sequenceDiagram
    actor Admin as Platform Administrator
    actor PortalAdmin as API Portal Administrator
    actor Publisher as API Publisher
    actor Subscriber
    participant PAPI as Platform API
    participant Portal as API Portal
    participant GW as Gateway
    participant Moesif
    participant Stripe

    Admin->>PAPI: Define the pricing of a subscription plan
    PortalAdmin->>Portal: Connect Moesif and Stripe (test or live)
    Publisher->>PAPI: Enable the paid plan for an API version and publish
    PAPI->>Portal: Publish the API version, plans and pricing
    Portal->>Moesif: Create plan, price and billing meter
    Moesif->>Stripe: Create product and price
    Subscriber->>Portal: Subscribe to the paid plan
    Portal->>Stripe: Create a checkout session
    Subscriber->>Stripe: Pay
    Stripe-->>Portal: Payment event
    Stripe-->>Moesif: Subscription synchronized
    Portal->>PAPI: Subscription and payment status
    PAPI->>GW: Subscription with billing metadata

Loading

Usage, invoicing and payment failure

sequenceDiagram
    actor Subscriber
    participant GW as Gateway
    participant Moesif
    participant Stripe
    participant Portal as API Portal
    participant PAPI as Platform API

    Subscriber->>GW: API request
    GW->>GW: Check subscription and payment status
    GW-->>Subscriber: Response
    GW->>Moesif: Request usage with billing customer ID
    Moesif->>Stripe: Usage totals from the billing meter
    Stripe->>Subscriber: Invoice and charge
    alt Payment fails or subscription is cancelled
        Stripe-->>Portal: Payment failed or subscription cancelled
        Portal->>PAPI: Updated subscription and payment status
        PAPI->>GW: Block access for the subscription
        Subscriber->>GW: API request
        GW-->>Subscriber: Rejected, payment required
    end

Loading

API Platform to Moesif Model Mapping

• Moesif catalog objects are created when a paid subscription plan is enabled for an API
• Customers and subscriptions are created in Stripe at checkout, and Moesif synchronizes them as companies and subscriptions.

Test and Live Billing Mode

• A billing setup links an API Portal to a billing account in either test or live mode.
• Each API Portal can hold separate test and live billing setups. Going live means adding a live setup and making it the portal's default.
• New subscriptions use the default setup. Existing subscriptions stay on the setup they started on, because Stripe keeps test and live data fully separate.

Discussion Points

1. Billing credentials live only in the API Portal. The control plane defines what is sold, but never communicates with a billing provider.

2. Usage goes from the gateways directly to the billing provider, never through the control plane. The analytics collector must stay enabled while monetization is enabled. Calls that the gateway blocks are not counted.

3. Only requests are metered in the initial scope. Custom counting rules, such as counting only successful responses or weighting requests, are not covered.

4. Customizable meters (possible extension). Let API providers define their own meters. A meter counts the usage events that match a filter on request details, such as the response status code or the API operation, and a plan sets a price for each meter, with an optional recurring fee.

   Example:

   Meter "Successful calls"  counts calls with a 2xx response  →  the subscriber made 2,800 such calls
                             (another 200 calls failed with a 4xx or 5xx response and are not counted)
   Plan:     $0.01 per successful call + $99 per month
   Invoice:  2,800 × $0.01 + $99 = $127

5. Prepaid credits (possible extension). Subscribers pay in advance, and their usage is deducted from that balance.

   Example for one subscriber:

   Top-up:   the subscriber pays $50 through Stripe       →  balance $50
   Usage:    3,000 calls × $0.01 = $30 this month         →  balance $20
   Invoice:  the $30 is covered by the balance, so the invoice is $0
             (usage beyond the balance would be invoiced as usual)

Moesif supports prepaid credits: it keeps a balance for each subscription, deducts usage in near real time using the billing meters, and applies the balance as credits on the Stripe invoice. This works only with Stripe, and only for per-unit and package pricing