Stripe Billing Read

skill

Read Stripe billing, invoices, and MRR via API and normalize into a working file.

Download .md

Stripe Billing Read

Read billing data, invoices, and MRR (monthly recurring revenue) directly from Stripe's REST API and normalize it into a working file for downstream reporting.

When to use

  • A human or agent asks for current MRR, revenue trend, or subscription counts.
  • You need to reconcile invoices, payment statuses, or customer billing history.
  • A revenue report, board update, or GTM (go-to-market) task requires fresh Stripe numbers rather than stale cached figures.
  • You need a normalized CSV/JSON snapshot of billing data for another agent or human to consume.

Tools

  • http-get: calls the Stripe REST API to read customers, subscriptions, invoices, and charges.
  • shell-execute: runs small scripts to parse, dedupe, and compute metrics (e.g. MRR, churn, invoice totals) from the raw API responses.
  • write-file: saves the normalized billing data and computed metrics to a working file.

Playbook

  1. Confirm the exact metric or dataset requested (MRR, invoice list, dunning status, customer lifetime value) before calling any endpoint.
  2. Call the Stripe REST API with http-get (e.g. GET https://api.stripe.com/v1/subscriptions or /v1/invoices). Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. If the call returns 401/403 or no Integration row exists, stop and message a human via send-message asking them to create the Integration, naming the service and required scopes.
  3. Paginate through results with http-get using the starting_after cursor until all relevant records for the requested window are retrieved.
  4. Use shell-execute to parse the raw JSON responses into flat records (customer, plan, amount, currency, status, period).
  5. Use shell-execute to compute the requested metric — MRR by summing active subscription amounts normalized to monthly, churn by comparing period-over-period customer counts, or invoice totals by status.
  6. Cross-check computed totals against a second lightweight query (e.g. Stripe's /v1/balance or a filtered invoice count) via http-get to catch pagination or currency-conversion errors.
  7. Write the normalized dataset and computed metrics to a working file with write-file, including the query window, currency assumptions, and timestamp of the pull.
  8. If the request implies changing a record — refunding a charge, canceling a subscription, updating a customer — this is NOT POSSIBLE with this skill's read-only tools. Compile the requested change into the working file and hand off to a human via send-message; never imply the change was made.
  9. Summarize the key figures (MRR, invoice count, notable anomalies) in plain language alongside the file path when reporting back.

Failure modes

  • 401/403 response -> missing or invalid Integration for Stripe; stop and escalate via send-message naming the required scopes.
  • Empty result set -> verify the endpoint path, date-range filters, and pagination cursor before concluding there is no data.
  • Rate limit (429) response -> back off and retry after a delay; note the rate limit in memory so future runs pace requests.
  • Stripe API response shape changed or fields are missing -> fall back to browser-search to check Stripe's current API documentation before continuing.

Done when

  • A working file exists (via write-file) containing normalized billing records and the computed metric(s) requested.
  • The file states the query window, currency handling, and pull timestamp so the numbers are auditable.
  • Any requested write/update action was correctly identified as out of scope and routed to a human via send-message instead of silently skipped.