# Stripe: how to read it into Maplith

*Payments · also known as Stripe Payments, Stripe Billing · last checked 2026-10-28 · recipe `maplith://systems/stripe`*

Stripe holds every card and online payment, the customers who paid, invoices and subscriptions, and the payouts that land in the bank, so it ties the shop and the accounts together.

## Best path

**Recommended: your agent fetches it.** Stripe's connectors in Claude and ChatGPT and its official MCP server let the customer's own agent read payments, customers, invoices and payouts with access it already has. Payments and balance transactions quickly reach thousands of rows a month, so take the history for a first map as CSV exports and let the agent describe what is in use.

Try the paths in this order (ADR-0031):

1. **Your agent fetches it**, with the access your human already gave you. Connectors a vendor or client page confirms: Stripe connector in Claude; Stripe plugin in ChatGPT. The customer's agent uses the Stripe connector it already has to check which objects are in use (payments, customers, invoices, subscriptions, payouts) and reads a small recent sample of each, read-only.
2. **Maplith reads this system for you.** Official: **Stripe MCP server**. Endpoint to connect to: `https://mcp.stripe.com`. Documentation (a page to read, not an address to connect to): https://docs.stripe.com/mcp. Access: In the Stripe Dashboard, create a restricted key, choose 'Authorizing agent access to your account' when Stripe asks what the key is for, and set every resource the map needs to Read and everything else to None. The key goes into the client your human connects to the server, never into a chat. The server offers tools, including write tools, so the key must only have Read permissions. Stripe's documentation says to migrate by November 30, 2026: starting in December, the Stripe MCP server stops accepting full-access secret keys and restricted keys without the Agent tag. Maplith reads this server through its own integration, described in *Maplith's integration* below; it is not a server your human adds under Data sources › Systems.
3. **Export files**, the fallback that always works: see *Export steps* below.
4. **Maplith's own integration** (built, and switched on per workspace: ask Maplith (suggest_feature) to switch it on for yours): see *Maplith's integration* below.

## Datasets that make a good map

| Dataset | One row is | Key columns | Joins to |
|---|---|---|---|
| Payments | One row per payment (a charge), including its status and any refund. | charge id, payment intent id, customer id, customer email (Maplith tries to mask it), amount, currency, status, order id in the metadata | Shop orders by the order id in the metadata; balance transactions by charge id; invoices by payment intent id. |
| Customers | One row per Stripe customer. | customer id, customer email (Maplith tries to mask it), created date, metadata keys | CRM contacts and shop customers by customer email; payments, invoices and subscriptions by customer id. |
| Invoices | One row per Stripe Billing invoice. | invoice id, invoice number, customer id, subscription id, payment intent id, status, amount due, amount paid | The accounting system's sales invoices by invoice number; payments by payment intent id; subscriptions by subscription id. |
| Subscriptions | One row per subscription, with its price and current status. The price id and product id are columns in Stripe's export; a connected scan finds them nested in the subscription's items. | subscription id, customer id, price id, product id, status, current period start, current period end | Invoices by subscription id; customers by customer id; a CRM or helpdesk by customer email via the customer. |
| Balance transactions | One row per movement in the Stripe balance: payment, refund, dispute, fee, or payout. The automatic payout id, invoice number and order id are columns in Stripe's export only; a connected scan has the source id instead. | balance transaction id, source id, charge id, payment intent id, automatic payout id, invoice number, order id, reporting category, gross, fee, net | Payments by charge id; payouts by automatic payout id; accounting invoices by invoice number; shop orders by order id or payment metadata. |
| Payouts | One row per transfer from Stripe to the company's bank account. | payout id, arrival date, amount, currency, status, trace id | Bank lines in the accounting system by amount, date and trace id; balance transactions by payout id. |

Columns are named, never their values. Maplith tries to mask personal data such as email addresses, but that is best effort: your human decides what goes in.

## Declared joins and identifier formats

Vendor documentation states these keys; Maplith checks them against the shared exports. A declaration is not a confirmation.

- Payments.customer → Customers.id (N:1). Source: https://docs.stripe.com/api/charges/object
- Invoices.customer → Customers.id (N:1). Source: https://docs.stripe.com/api/invoices/object
- Subscriptions.customer → Customers.id (N:1). Source: https://docs.stripe.com/api/subscriptions/object
- charges: prefix ch_ identifies Payments.id. Source: https://docs.stripe.com/api/charges/object
- customers: prefix cus_ identifies Customers.id. Source: https://docs.stripe.com/api/customers/object
- invoices: prefix in_ identifies Invoices.id. Source: https://docs.stripe.com/api/invoices/object
- subscriptions: prefix sub_ identifies Subscriptions.id. Source: https://docs.stripe.com/api/subscriptions/object

## Structure artefacts

- **Stripe OpenAPI schema** (api_spec; remove values before sharing): Have your agent read the vendor-maintained spec with your approval. Keep object fields and references; remove examples and defaults before sharing. Source: https://github.com/stripe/openapi

Share structure only: no examples, rows, credentials or pinned data. Your human chooses what to send.

## Read-only access

**Who usually has the rights:** The account owner or an Administrator in Stripe; in small companies often the founder or the finance person.

**For the key your own agent's client uses, choose only these read permissions:** `Charges: Read`, `Customers: Read`, `Payment Intents: Read`, `Invoices: Read`, `Subscriptions: Read`, `Balance: Read`, `Payouts: Read`, `Disputes: Read`

**Where to click:**

1. Open the Stripe Dashboard and go to Developers, then API keys
2. Click Create restricted key
3. Enter a name in the Key name field
4. Set Read on the resources the map needs (customers, charges, payment intents, invoices, subscriptions, balance, payouts, disputes) and leave the rest at None
5. Click Create key and complete the two-factor verification
6. Copy the key once and keep it in the client that connects to Stripe; never paste it into a chat.

A key or token made here stays in the tool that reads the system for your human, never in a chat. Maplith asks for one only under Data sources › Systems in the app: for an MCP server it can read, or for its own integration below.

## Export steps

**Format:** CSV · **Date range:** The last three months

1. Payments: open the Transactions page, set the date range, click Export, choose the columns (pick all), and download the CSV
2. Customers: open the Customers page, click the export button in the upper-right corner, choose time zone, date range and columns, and start the export
3. Payouts: open the Payouts page, click Export, choose time zone, date range and columns, and download the CSV
4. Balance transactions: open Reports, then Payout reconciliation, pick the date range, click Download and choose the Itemized CSV

## Volume hint

**About 200–5,000 payments, with a similar number of balance transactions a month** (an estimate). Estimate for a small company, not a measured figure: depends on whether Stripe takes every web shop order or only some invoices.

Every row an agent reads passes through its context, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, prefer an MCP server or an export over fetching through the chat.

## Maplith's integration

**Status:** built, and switched on per workspace: ask Maplith (suggest_feature) to switch it on for yours.

**How to connect:** a person makes a read-only restricted key for agent access in Stripe and pastes it into the Maplith app when connecting, never into a chat. In Stripe:

1. In the Stripe Dashboard, open the API keys page and click Create restricted key.
2. When Stripe asks what the key is for, choose Authorizing agent access to your account.
3. Enter a name in the Key name field.
4. Set Read on Charges, Customers, Invoices, Subscriptions, Balance and Payouts, and leave everything else at None.
5. Click Create key, complete the two-factor verification, and click the key value to copy it. Stripe shows it only once.

**What it reads:** Payments · Customers · Invoices · Subscriptions · Balance transactions · Payouts.

**When:** at each scan; nothing arrives between scans. **How far back:** the last 90 days (customers: all). **Which account:** the one Stripe account the key belongs to.

**What it never reads or does:**

- Anything that creates, changes, schedules or deletes: only the reads Maplith needs for the map are called, whatever else Stripe's server offers.
- Another Stripe account: Maplith never reads a connected account.
- The key itself after it is stored: it is sealed and never shown again.

## Always

- Read-only, and never a credential sent to Maplith through the chat.
- The same recent period, a few months, from every system.
- Your human decides what goes in.

## Sources

Written from the vendor's public documentation, last checked 2026-10-28:

- https://docs.stripe.com/mcp
- https://docs.stripe.com/keys
- https://docs.stripe.com/keys/restricted-api-keys
- https://docs.stripe.com/reports/payout-reconciliation
- https://support.stripe.com/questions/exporting-payment-data
- https://support.stripe.com/questions/exporting-payout-reports
- https://docs.stripe.com/api/charges/object
- https://docs.stripe.com/api/customers/object
- https://docs.stripe.com/api/invoices/object
- https://docs.stripe.com/api/subscriptions/object
- https://github.com/stripe/openapi