Stripe

---
name: stripe
description: How to connect to and query the Stripe API for analytics data.
---

# Stripe Integration

## Connection

- **Base URL**: `https://api.stripe.com`
- **Auth**: Bearer token via the per-user/org `STRIPE_SECRET_KEY` credential
- **Server lib**: `server/lib/stripe.ts`
- **Routes**: `server/routes/stripe.ts`
- **Dashboard**: `app/pages/adhoc/stripe/` (tool page, not metrics dashboard)

## Credential

- `STRIPE_SECRET_KEY` — configure in Settings → Data sources

## Agent Action

Use `stripe` for agent-facing Stripe work. Do not call `/api/stripe/*`
directly from the agent.

| Mode | Args | Description |
| --- | --- | --- |
| `billing` | `email`, `customerId`, `query`, `months` | Invoices for a customer in timeframe |
| `payment-status` | `email`, `customerId`, `query` | Recent charges + payment intents |
| `refunds` | `email`, `customerId`, `query` | Refunds associated with customer |
| `subscriptions` | `email`, `customerId`, `query` | Active subscriptions |
| `billing-by-product` | `email`, `customerId`, `query`, `months` | Billing aggregated by product |

## API Routes

| Route                        | Method | Params                        | Description                           |
| ---------------------------- | ------ | ----------------------------- | ------------------------------------- |
| `/api/stripe/billing`        | GET    | `email`, `months` (default 6) | Invoices for a customer in timeframe  |
| `/api/stripe/payment-status` | GET    | `email`                       | Recent charges + payment intents      |
| `/api/stripe/refunds`        | GET    | `email`                       | Refunds associated with customer      |
| `/api/stripe/subscriptions`  | GET    | `email`                       | All subscriptions (active + inactive) |

All routes resolve email → Stripe customer ID(s) internally.

## Exported Functions (server/lib/stripe.ts)

- `getCustomersByEmail(email)` — lookup customers by email
- `getInvoices(customerId, months?)` — invoices, optionally filtered by timeframe
- `getCharges(customerId, limit?)` — recent charges
- `getPaymentIntents(customerId, limit?)` — recent payment intents
- `getSubscriptions(customerId)` — all subscriptions (status=all)
- `getRefunds(customerId)` — refunds via charge lookup

## Gotchas

- Stripe `/v1/refunds` does NOT support `customer` filter. The lib works around this by fetching customer charges first, then fetching refunds for refunded charges.
- One email can map to multiple Stripe customer objects. All routes handle this by aggregating across all matching customers.
- Amounts in Stripe are in **cents** (smallest currency unit). Divide by 100 for display.
- Cache TTL is 5 minutes (shorter than other integrations since billing data changes more frequently).
- The `expand` parameter is used for invoices (line items) and subscriptions (price details).

## Client Hooks (app/lib/api-hooks.ts)

- `useStripeBilling(email, months, enabled)`
- `useStripePaymentStatus(email, enabled)`
- `useStripeRefunds(email, enabled)`
- `useStripeSubscriptions(email, enabled)`

All hooks use `enabled` flag — data is only fetched when a button is clicked.

## UI Pattern

The Stripe page is a **tool** (not a dashboard). It has:

1. Email input field
2. Four action buttons (Billing History, Payment Status, Refund Status, Subscriptions)
3. Results panel that shows data for whichever action was last triggered