[AI Gateway]: documentation for new stripe integration feature

Author: Rishit Bansal

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

@@ -0,0 +1,143 @@
+---
+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.
+
+## Benefits of Stripe Integration
+
+- **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 **Settings**.
+4. Scroll down to **Stripe Integration**.
+5. Add your **Stripe API Key**.
+6. 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.
+
+:::