Stripe Python

The stripe Python package is Stripe’s officially maintained client library for accessing the Stripe API from Python applications. It ships a typed StripeClient with sync and async request methods, pre-built resource classes for every API object (customers, charges, subscriptions, Connect accounts, and more), and automatic handling of retries, idempotency keys, and pagination.

Beyond simple request wrapping, the library tracks Stripe’s frequent API changes closely: it is regenerated from Stripe’s OpenAPI spec, supports pinning specific API versions per request, and exposes both the stable v1 surface and newer v2 event/thin-object APIs. It is the reference implementation most Python teams reach for when integrating payments, subscription billing, or marketplace payouts with Stripe.

What You Get

• A StripeClient class exposing every Stripe API resource (customers, charges, subscriptions, invoices, Connect accounts, and dozens more) as typed methods
• Both synchronous and _async-suffixed asynchronous variants of every request method, backed by requests or httpx/aiohttp
• Automatic idempotency-key generation and configurable automatic retries for transient network and 409 conflict errors
• Built-in pagination via .auto_paging_iter() for both sync and async iteration over list endpoints
• Type annotations (including Unpack[TypedDict] param typing) validated against Pyright, plus a raw_request escape hatch for undocumented or beta endpoints
• Webhook signature verification and event-notification handler helpers for processing Stripe webhooks safely

Common Use Cases

• Charging customers and processing one-off or recurring payments from a Python backend
• Managing subscription billing lifecycles: creating plans, upgrading/downgrading, prorating, and handling invoices
• Building a Stripe Connect marketplace or platform that onboards sellers and splits payments
• Verifying and reacting to Stripe webhook events (e.g. invoice.paid, charge.refunded) inside a Django/Flask/FastAPI app
• Calling in-preview or undocumented Stripe endpoints via raw_request before they land in the typed SDK surface

Under The Hood

Architecture The library centers on _api_requestor.py, which builds and signs HTTP requests, and a generated resource layer (stripe/_customer.py, _charge.py, _subscription.py, etc., plus per-resource *_service.py files) that the newer StripeClient composes into a namespaced client.v1.<resource> surface, while a legacy global-config pattern (stripe.api_key = ...) remains for backward compatibility. Sync and async code paths are generated in parallel (retrieve / retrieve_async), and cross-cutting concerns like retries, idempotency-key injection, and pagination (auto_paging_iter) live in shared request-handling code rather than per-resource, so most of the surface area is machine-generated from Stripe’s OpenAPI spec with a comparatively small hand-written core (requestor, HTTP client abstraction, error hierarchy).

Tech Stack Written in modern typed Python (3.9+), using typing_extensions for Unpack[TypedDict]-based keyword-argument typing checked against Pyright, requests as the default synchronous HTTP client with pluggable alternatives (httpx, aiohttp, pycurl, urllib), and flit_core as the build backend. Ruff handles linting and formatting, and the project uses just as a task runner wrapping a mise/pyenv-managed virtualenv; CI (GitHub Actions) runs static checks, mypy/pyright type-checking, and a build/test matrix.

Code Quality The repo ships an extensive test suite (60+ test_*.py files under tests/, including generated-example tests, integration tests, and dedicated tests for error handling, request options, and the HTTP client abstraction) that runs against stripe-mock rather than the live API. Errors are modeled as an explicit typed exception hierarchy (StripeError and subclasses in _error.py) carrying HTTP status, body, and Stripe request ID rather than being swallowed, naming is consistent and machine-generated across resources, and CI enforces linting (Ruff), formatting, and strict type-checking (Pyright/mypy) on every change.

What Makes It Unique Unlike a typical REST client, this SDK is regenerated from Stripe’s own OpenAPI specification, keeping its typed surface tightly synchronized with a very large and fast-moving API (open enum types anticipate values Stripe may add later without breaking type checks). It uniquely runs sync and async code from the same generated definitions, exposes a raw_request/beta-version mechanism for calling undocumented or preview endpoints before they’re formally typed, and supports per-request API-version pinning so callers can control exactly which Stripe API version a given call targets independent of the installed SDK version.