[AI Gateway]: documentation for new stripe integration feature

Author: Rishit Bansal

src/content/docs/ai-gateway/features/stripe-integration.mdx

@@ -0,0 +1,142 @@
+---
+pcx_content_type: configuration
+title: Stripe integration
+sidebar:
+  order: 6
+---
+
+import { TabItem, Tabs } from "~/components";
+
+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:
+
+- A Stripe account with [usage-based billing](https://docs.stripe.com/billing/subscriptions/usage-based) configured
+- Stripe API key with appropriate permissions
+- [Billing meters](https://docs.stripe.com/billing/subscriptions/usage-based/meters/create) set up in your Stripe account
+
+## Configuration
+
+<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
+
+To configure Stripe integration in the dashboard:
+
+1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com/) 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.
+
+</TabItem> <TabItem label="API">
+
+To configure Stripe integration using the API:
+
+1. [Create an API token](/fundamentals/api/get-started/create-token/) with the following permissions:
+   - `AI Gateway - Read`
+   - `AI Gateway - Edit`
+
+2. Get your [Account ID](/fundamentals/account/find-account-and-zone-ids/).
+3. Using that API token and Account ID, send a [`PUT` request](/api/resources/ai_gateway/methods/update/) to update your gateway with Stripe integration settings.
+
+</TabItem> </Tabs>
+
+## 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](/ai-gateway/observability/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:
+
+| Variable | Description |
+|----------|-------------|
+| `$cost` | Total cost of the request in USD |
+| `$model` | AI model used (e.g., gpt-4o-mini, gpt-5) |
+| `$provider` | Provider name (e.g., openai, anthropic) |
+| `$input_tokens` | Number of input tokens processed |
+| `$output_tokens` | Number of output tokens generated |
+| `$cached_read_tokens` | Tokens read from cache |
+| `$cached_write_tokens` | Tokens written to cache |
+| `$metadata_metadataKey` | [Custom metadata](/ai-gateway/observability/custom-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
+
+```json
+{
+  "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](https://docs.stripe.com/api/v2/billing/meter-event-stream/session/create).
+
+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](https://docs.stripe.com/api/v2/billing/meter-event-stream/create).
+
+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](/ai-gateway/observability/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
+
+:::note
+
+The Stripe integration sends events based on successful AI provider responses. Failed or blocked requests are not reported to Stripe meters.
+
+:::