StripeCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Stripe](https://modelsatlas.com/skills/builderio/stripe/badge.svg)](https://modelsatlas.com/skills/builderio/stripe/)

Not your listing, or something out of date? Claim or update your listing.