Skip to content
Cloudflare Docs

Stripe integration

AI Gateway can automatically send usage events to your Stripe billing meters, enabling seamless usage-based billing for your AI applications. The integration allows you to track costs, token usage, and other metrics directly in Stripe without manual data handling. You can use this to track per-customer usage and automatically bill customers based on their AI consumption.

  • Automated Billing: Automatically report usage events to Stripe meters for usage-based billing.
  • Real-time Tracking: Send events in real-time as soon as responses are received from AI providers.
  • Cost Visibility: Track detailed cost information per request, including provider and model metadata.
  • Flexible Templates: Use preset templates for common metrics or create custom payloads.

Prerequisites

Before setting up Stripe integration, you need:

Configuration

To configure Stripe integration in the dashboard:

  1. Log into the Cloudflare dashboard ↗ and select your account.
  2. Go to AI > AI Gateway.
  3. Select your gateway.
  4. Select Settings.
  5. Scroll down to Stripe Integration.
  6. Add your Stripe API Key.
  7. Configure one or more JSON payloads for meter events.

Example Setup

  1. On the first payload, select Import a Preset > Input tokens.
  2. On the second payload, select Import a Preset > Output tokens.

This configuration sends two usage events to your Stripe meter: one for input tokens and another for output tokens.

Payload Templates

AI Gateway provides several preset templates for common usage metrics:

Available Presets

  1. Input tokens - Tracks the number of input tokens processed
  2. Output tokens - Tracks the number of output tokens generated
  3. Cached read tokens - Tracks tokens read from cache
  4. Cached write tokens - Tracks tokens written to cache

Each preset template is pre-configured to derive customerId and event values through custom metadata passed in AI Gateway requests.

Custom Payloads

You can create custom JSON payloads beyond the preset templates. The following template variables are available for use in event payloads:

VariableDescription
$costTotal cost of the request in USD
$modelAI model used (e.g., gpt-4o-mini, gpt-5)
$providerProvider name (e.g., openai, anthropic)
$input_tokensNumber of input tokens processed
$output_tokensNumber of output tokens generated
$cached_read_tokensTokens read from cache
$cached_write_tokensTokens written to cache
$metadata_metadataKeyCustom metadata field from cf-aig-metadata header

For custom metadata variables, replace metadataKey with your actual field name. For example, $metadata_customerId retrieves the customerId field from your custom metadata.

Example Custom Payload

{
  "event_name": "ai_request",
  "timestamp": "2024-01-15T10:30:00Z",
  "properties": {
    "cost": "$cost",
    "model": "$model",
    "provider": "$provider",
    "input_tokens": "$input_tokens",
    "output_tokens": "$output_tokens",
    "customer_id": "$metadata_customerId"
  }
}

How It Works

The AI Gateway Stripe integration follows this process:

  1. Token Generation: AI Gateway generates and caches short-lived authentication tokens using Stripe's Create stream authentication session API ↗.

  2. Metadata Processing: AI Gateway calculates cost and token-related metadata for your request, handling edge cases across different APIs and providers.

  3. Template Processing: The system replaces template variables in your configured payloads with actual values from the request.

  4. Event Timing: The timestamp on events is set to the exact time the AI Gateway request was made.

  5. Event Submission: Authentication tokens are used to send configured payloads to Stripe's Create billing meter API ↗.

  6. Real-time Delivery: Events are sent to Stripe in real-time as soon as responses are received from upstream AI providers.

Error Handling

AI Gateway includes robust error handling for Stripe API failures:

  • Retry Logic: Failed requests are automatically retried up to 5 times
  • Exponential Backoff: Retry delays increase exponentially to avoid overwhelming Stripe's API
  • Graceful Degradation: AI Gateway requests continue to function normally even if Stripe integration fails

Usage Requirements

To use Stripe integration effectively:

  • Configure custom metadata in your AI Gateway requests to provide customer identification and event details
  • Ensure your Stripe billing meters are properly configured to receive the events
  • Set up appropriate customer records in Stripe that match your metadata customer IDs