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 emailgetInvoices(customerId, months?) — invoices, optionally filtered by timeframegetCharges(customerId, limit?) — recent chargesgetPaymentIntents(customerId, limit?) — recent payment intentsgetSubscriptions(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:
- Email input field
- Four action buttons (Billing History, Payment Status, Refund Status, Subscriptions)
- Results panel that shows data for whichever action was last triggered
1---2name: stripe3description: How to connect to and query the Stripe API for analytics data.4---56# Stripe Integration78## Connection910- **Base URL**: `https://api.stripe.com`11- **Auth**: Bearer token via the per-user/org `STRIPE_SECRET_KEY` credential12- **Server lib**: `server/lib/stripe.ts`13- **Routes**: `server/routes/stripe.ts`14- **Dashboard**: `app/pages/adhoc/stripe/` (tool page, not metrics dashboard)1516## Credential1718- `STRIPE_SECRET_KEY` — configure in Settings → Data sources1920## Agent Action2122Use `stripe` for agent-facing Stripe work. Do not call `/api/stripe/*`23directly from the agent.2425| Mode | Args | Description |26| -------------------- | ---------------------------------------- | ------------------------------------ |27| `billing` | `email`, `customerId`, `query`, `months` | Invoices for a customer in timeframe |28| `payment-status` | `email`, `customerId`, `query` | Recent charges + payment intents |29| `refunds` | `email`, `customerId`, `query` | Refunds associated with customer |30| `subscriptions` | `email`, `customerId`, `query` | Active subscriptions |31| `billing-by-product` | `email`, `customerId`, `query`, `months` | Billing aggregated by product |3233## API Routes3435| Route | Method | Params | Description |36| ---------------------------- | ------ | ----------------------------- | ------------------------------------- |37| `/api/stripe/billing` | GET | `email`, `months` (default 6) | Invoices for a customer in timeframe |38| `/api/stripe/payment-status` | GET | `email` | Recent charges + payment intents |39| `/api/stripe/refunds` | GET | `email` | Refunds associated with customer |40| `/api/stripe/subscriptions` | GET | `email` | All subscriptions (active + inactive) |4142All routes resolve email → Stripe customer ID(s) internally.4344## Exported Functions (server/lib/stripe.ts)4546- `getCustomersByEmail(email)` — lookup customers by email47- `getInvoices(customerId, months?)` — invoices, optionally filtered by timeframe48- `getCharges(customerId, limit?)` — recent charges49- `getPaymentIntents(customerId, limit?)` — recent payment intents50- `getSubscriptions(customerId)` — all subscriptions (status=all)51- `getRefunds(customerId)` — refunds via charge lookup5253## Gotchas5455- Stripe `/v1/refunds` does NOT support `customer` filter. The lib works around this by fetching customer charges first, then fetching refunds for refunded charges.56- One email can map to multiple Stripe customer objects. All routes handle this by aggregating across all matching customers.57- Amounts in Stripe are in **cents** (smallest currency unit). Divide by 100 for display.58- Cache TTL is 5 minutes (shorter than other integrations since billing data changes more frequently).59- The `expand` parameter is used for invoices (line items) and subscriptions (price details).6061## Client Hooks (app/lib/api-hooks.ts)6263- `useStripeBilling(email, months, enabled)`64- `useStripePaymentStatus(email, enabled)`65- `useStripeRefunds(email, enabled)`66- `useStripeSubscriptions(email, enabled)`6768All hooks use `enabled` flag — data is only fetched when a button is clicked.6970## UI Pattern7172The Stripe page is a **tool** (not a dashboard). It has:73741. Email input field752. Four action buttons (Billing History, Payment Status, Refund Status, Subscriptions)763. Results panel that shows data for whichever action was last triggered
Builder.io