> ## Documentation Index > Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt > Use this file to discover all available pages before exploring further. # Stripe > Customers, payments, refunds, subscriptions and Checkout Sessions.

59 tools API key

```python stripe_example.py {7} theme={null} import os from charter.packs import stripe stripe.configure(api_key=os.environ["STRIPE_API_KEY"]) customers = await stripe.customers_list.ainvoke(limit=10) ``` Customers, payments, charges, refunds, the product catalogue, subscriptions, Checkout Sessions and the account balance. Stripe's parameter surface is enormous — `checkout.sessions.create` alone has around fifty parameters with deep nesting — so these schemas model the commonly-used subset exactly rather than claiming completeness badly. Form-encoded bodies, bracket notation for nesting, and a cursor the API never hands back are all declared in [the wire contract](/charter/charter/tools/wire-contract). ## Authenticating This pack takes an API key in `Authorization`, and [`configure()`](/charter/charter/reference/configuration#configure) is optional when `$STRIPE_API_KEY` is set. There is no authorization server, no consent screen and no refresh — [API keys](/charter/charter/auth/api-key-tool-factory) is the whole story. Prefer a [restricted key](https://docs.stripe.com/keys/restricted-api-keys) scoped to what the agent actually needs — an agent that only reads should not hold a key that can issue refunds. ## The client [`api_key_tool_factory`](/charter/charter/reference/factories#api_key_tool_factory) is the whole client: a thin wrapper over `httpx` that attaches your key and these endpoint constants to each request. `stripe` does not enter your dependency tree.

```python Without the pack theme={null} import os from charter import api_key_tool_factory api_key = os.environ["STRIPE_API_KEY"] stripe_api_client = api_key_tool_factory( base_url="https://api.stripe.com/", api_key_headers={"Authorization": f"Bearer {api_key}"}, body_format="form", query_format="bracket", body_case="snake", query_case="snake", path_case="snake", static_headers={"Stripe-Version": "2026-08-26.dahlia"}, # this API reports failure with an HTTP status code envelope=None, ) ``` ```python With the pack theme={null} import os from charter.packs import stripe stripe.configure(api_key=os.environ["STRIPE_API_KEY"]) # The base URL, the casing, the envelope and the pagination are # already declared. 59 tools, ready to hand to a model: tools = stripe.TOOLS ```

### Paging through a list A cursor belongs to the tool that returns it, so it is declared on that tool's builder call: ```python stripe_pagination.py theme={null} customers_list = stripe_api_client( name="customers_list", args_schema=CustomersListRequest, method="GET", url_template="v1/customers", pagination=Pagination( cursor_field="data[-1].id", cursor_param="starting_after", more_field="has_more", ), ) ``` Pagination is declared on `customers_list`, `payment_intents_list`, `charges_list`, `refunds_list`, `products_list`, `prices_list`, `subscriptions_list`, `invoices_list`, `invoice_items_list`, `checkout_sessions_list`, `checkout_sessions_line_items`, `payment_methods_list`, `customer_payment_methods_list`, `disputes_list`, `accounts_list`, `transfers_list`, `payouts_list`, `application_fees_list` and `balance_transactions_list`. The other 40 take no cursor. ## Tools Each is a [`Tool`](/charter/charter/reference/tool), called with [`ainvoke`](/charter/charter/reference/tool#tool-ainvoke) as in the snippet above. The name links to its parameters, its response and what it costs.

## Form-encoded, in both directions Stripe speaks `application/x-www-form-urlencoded` with bracket notation. `body_format="form"` and `query_format="bracket"` say so once on the factory, and a nested schema serialises the way Stripe expects: | Schema value | On the wire | | ----------------------------------- | ------------------------- | | `{"amount": 2000}` | `amount=2000` | | `{"metadata": {"order_id": "x1"}}` | `metadata[order_id]=x1` | | `{"line_items": [{"price": "p1"}]}` | `line_items[0][price]=p1` | | `{"expand": ["customer"]}` | `expand[0]=customer` | | `{"capture": False}` | `capture=false` | | `{"note": None}` | *omitted* | The bracket form applies to the query too, which is what `created[gte]=1700000000` needs. ## A cursor that is derived, not returned Where Slack and Google hand back an opaque token, Stripe's `starting_after` takes the **last object's id**. The declaration reads it straight out of the page: ```python stripe_derived_cursor.py theme={null} from charter import Pagination Pagination(cursor_field="data[-1].id", cursor_param="starting_after", more_field="has_more") ``` `has_more` is declared because a derived cursor is *always* present — there is always a last object — so without it the walk would never terminate. This is the constraint the trimming handlers work under: they must keep each object's `id` and they must keep `has_more`, or paging breaks. It is stated in the pack source next to the handlers for exactly that reason. ## No envelope Stripe uses real HTTP status codes and puts the detail in `error.message`, which the runtime already understands. Nothing to declare — worth saying out loud, because the right amount of configuration for a well-behaved API is none. ## A pinned API version An unpinned Stripe request does not use the latest version. It uses whichever version the *account* defaults to, set in a dashboard this library cannot see — so the same code answers differently for two callers, and a schema written against one of them is correct by luck. `stripe.API_VERSION` goes out as a `Stripe-Version` header on every request, declared once as `static_headers` on the factory. It never appears in a tool's LLM schema, so it costs nothing in context and the model has no path to changing it. The cost of not doing this is not hypothetical. Stripe moved `current_period_start` and `current_period_end` off the Subscription object and onto each subscription item; a handler still projecting them from the subscription finds nothing, drops both, and hands the model an active subscription with no renewal date and no indication that anything is missing. `trim_subscriptions` reads them from the items, and the pin is what keeps that true. ## Idempotency and Connect Both are values your application decides and the model never sees, so they go through the [per-call header channel](/charter/charter/tools/wire-contract) rather than onto the tool: ```python stripe_idempotent_refund.py theme={null} key = f"refund-{order_id}" # yours, and stable across your retries await stripe.refunds_create.ainvoke( {"charge": charge_id}, headers={"Idempotency-Key": key} ) await stripe.balance_retrieve.ainvoke( headers={"Stripe-Account": "acct_1032D82eZvKYlo2C"} ) ``` Charter never mints the idempotency key. A key generated per call defeats the purpose — the point is that *your* retry sends the same one — and Charter does not own retries, so it does not own the key. `headers` is keyword-only and is never merged into `args`, so it cannot appear in a tool's LLM schema. ## Gotchas `amount=2000` is €20.00, not €2,000. Zero-decimal currencies such as JPY are the exception, where `amount=2000` is ¥2000. Stripe applies this to refunds too, so a partial refund of "ten euros" is `amount=1000`. So do `products_list` and `balance_retrieve`. The other nine tools run a handler that projects each object down to the fields an agent can act on. A raw PaymentIntent carries around forty fields, most of them null or infrastructural. `customers_update` is `POST /v1/customers/{customer}`, not PATCH — that is Stripe's convention. Parameters you do not send are unchanged; sending `metadata` replaces the whole metadata object rather than merging into it. Both `starting_after` and `ending_before` are on the list schemas because Stripe accepts both. The `Pagination` declares the forward direction only, so `next_page_args` walks forwards; `ending_before` is there for you to use directly. They are the two directions of one cursor, so sending both is refused locally. `current_period_start` and `current_period_end` used to be fields on the Subscription; they now live on each subscription item, which can be on different schedules. `trim_subscriptions` lifts the period back to the top level when every item agrees, which is nearly always, and reports it per item when they do not. Nothing is averaged and nothing is guessed. A refund names exactly one of `charge` or `payment_intent`; a Checkout Session in `payment` or `subscription` mode needs `line_items`; one in `setup` mode needs `currency`; and `success_url` and `cancel_url` are refused when `ui_mode` is `embedded_page` or `elements`, where the customer never leaves your page. Each is a documented 400 turned into a local validation error — worth doing here because a Checkout Session is usually created with a customer waiting on it. Conditions that depend on parameters these schemas do not model are left to Stripe and named in the field descriptions instead. `return_url` is the one to know: it is required for the in-page modes only when redirect-based payment methods are enabled on the session, which is not visible from here. A schema with exactly one `Body()` field unwraps to its bare value, which for a list would produce `[0][price]=…` — meaningless to any server. That raises a clear error rather than sending it. No tool in this pack trips it; a tool you add might. ## Related * [The wire contract](/charter/charter/tools/wire-contract) — form bodies, bracket queries, per-call headers * [The API-key factory](/charter/charter/auth/api-key-tool-factory) — what an API-key pack does not have