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