Skip to content

BuilderIO/agent-native / templates/analytics/.builder/skills/stripe

stripe

Verified

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.

ModeArgsDescription
billingemail, customerId, query, monthsInvoices for a customer in timeframe
payment-statusemail, customerId, queryRecent charges + payment intents
refundsemail, customerId, queryRefunds associated with customer
subscriptionsemail, customerId, queryActive subscriptions
billing-by-productemail, customerId, query, monthsBilling aggregated by product

API Routes

RouteMethodParamsDescription
/api/stripe/billingGETemail, months (default 6)Invoices for a customer in timeframe
/api/stripe/payment-statusGETemailRecent charges + payment intents
/api/stripe/refundsGETemailRefunds associated with customer
/api/stripe/subscriptionsGETemailAll 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
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall