Docs: System guides

Read Stripe into Maplith

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.

Payments · Also known as Stripe Payments, Stripe Billing · Checked 2026-10-28

On this page

Best path

Recommended: your agent fetches it. Stripe's connectors in Claude and ChatGPT and its official MCP server let your 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:

Your agent fetches it, with the access you already gave it. Connectors a vendor or client page confirms: Stripe connector in Claude; Stripe plugin in ChatGPT. Your 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.
Maplith reads an MCP server you already run. Stripe runs Stripe MCP server. Its address is https://mcp.stripe.com. Documentation: docs.stripe.com. 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 you connect 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 below; you cannot add it under Data sources › Systems as a server you run.
Export files, the fallback that always works. See the export steps below.
Maplith’s own integration. Built, and switched on per workspace. Ask Maplith at [email protected] 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 its customer record.
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: you decide what goes in.

Joins and identifiers the vendor documents

Stripe’s documentation states these keys. Maplith checks them against the exports you share: a stated join is not a confirmed one.

From	To	How many	Source
Payments, `customer`	Customers, `id`	many to one	docs.stripe.com
Invoices, `customer`	Customers, `id`	many to one	docs.stripe.com
Subscriptions, `customer`	Customers, `id`	many to one	docs.stripe.com

Identifier	Looks like	Source
Payments, `id`	`ch_…`	docs.stripe.com
Customers, `id`	`cus_…`	docs.stripe.com
Invoices, `id`	`in_…`	docs.stripe.com
Subscriptions, `id`	`sub_…`	docs.stripe.com

Structure files

Stripe can describe its structure without any rows. Share structure only: no examples, rows or credentials.

Stripe OpenAPI schema (remove the values before you share it): Have your agent read the vendor-maintained spec with your approval. Keep object fields and references; remove examples and defaults before sharing. Source: github.com.

The access to give

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

Choose the narrowest access that covers the data:

Charges: Read
Customers: Read
Payment Intents: Read
Invoices: Read
Subscriptions: Read
Balance: Read
Payouts: Read
Disputes: Read

Where to click:

Open the Stripe Dashboard and go to Developers, then API keys
Click Create restricted key
Enter a name in the Key name field
Set Read on the resources the map needs (customers, charges, payment intents, invoices, subscriptions, balance, payouts, disputes) and leave the rest at None
Click Create key and complete the two-factor verification
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, never in a chat. Maplith asks for one only under Data sources › Systems in the app.

Export steps

Format: CSV Date range: The last three months

Payments: open the Transactions page, set the date range, click Export, choose the columns (pick all), and download the CSV
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
Payouts: open the Payouts page, click Export, choose time zone, date range and columns, and download the CSV
Balance transactions: open Reports, then Payout reconciliation, pick the date range, click Download and choose the Itemized CSV

How much data

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.

An agent that reads rows through a chat reads every one of them, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, an MCP server or an export is the better path.

Maplith’s integration

Status: Built, and switched on per workspace. Ask Maplith at [email protected] to switch it on for yours.

How to connect

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

The permissions it asks for

Permission	Why
Charges: Read	Payments: one row per charge, with its status and any refund.
Customers: Read	Customers: who paid, by customer id.
Invoices: Read	Invoices: Stripe Billing invoices, by number.
Subscriptions: Read	Subscriptions: each subscription and its status.
Balance: Read	Balance transactions: every movement in the Stripe balance, for payout reconciliation.
Payouts: Read	Payouts: each transfer from Stripe to the bank.

What it reads

Payments, invoices, subscriptions, balance transactions and payouts from the last 90 days, and every customer, from the one Stripe account the key belongs to, at each scan.
Each dataset lands as a CSV table, in the shape Stripe's API returns, and Maplith tries to mask personal details such as email addresses in it, as in any upload.

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.

Choosing what is read: Maplith reads only the datasets the map needs. To read less, remove the connection and upload Stripe's exports on the Scans tab instead.

Always

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

Sources

Written from public documentation, last checked 2026-10-28:

← All system guides · Markdown version · What your agents do with Stripe