This release is a pre-release and may not be stable for production use.
Stripe Python Library
The Stripe Python library provides convenient access to the Stripe API from applications written in the Python language. It includes a pre-defined set of classes for API resources that initialize themselves dynamically from API responses which makes it compatible with a wide range of versions of the Stripe API.
API Documentation
See the Python API docs.
Installation
This package is available on PyPI:
pip install --upgrade stripe
Alternatively, install from source with:
python -m pip install .
Requirements
Per our Language Version Support Policy, we currently support Python 3.9+.
Read more and see the full schedule in the docs: https://docs.stripe.com/sdks/versioning?lang=python#stripe-sdk-language-version-support-policy
Extended Support
Python 2.7 deprecation
The Python Software Foundation (PSF) community announced the end of support of Python 2 on 01 January 2020. Starting with version 6.0.0 Stripe SDK Python packages will no longer support Python 2.7. To continue to get new features and security updates, please make sure to update your Python runtime to Python 3.6+.
The last version of the Stripe SDK that supported Python 2.7 was 5.5.0.
Usage
The library needs to be configured with your account's secret key which is
available in your Stripe Dashboard. Set stripe.api_key to its
value:
from stripe import StripeClient
client = StripeClient("sk_test_...")
# list customers
customers = client.v1.customers.list()
# print the first customer's email
print(customers.data[0].email)
# retrieve specific Customer
customer = client.v1.customers.retrieve("cus_123456789")
# print that customer's email
print(customer.email)
Working with API resources
Every API resource is a subclass of StripeObject. It is not a dict, even though printing one shows a dict-like representation. Having our own class means property names (like subscription.items) never collide with builtin methods.
You can access properties in a variety of ways:
customer = client.v1.customers.retrieve("cus_123456789")
customer.email # attribute access
customer["email"] # subscript access
"email" in customer # membership
getattr(customer, "discount", None) # tolerate a field that may be absent
Though StripeObject is not a dict, there are helper methods to let you do operations you'd commonly do with a dict. Say you have the following (example) object:
obj = Customer(id='cus_123', subscription=Subscription(id='sub_456', amount=Decimal('7.89'))
Here's how to accomplish each of these use cases:
| Use Case | Method | Result |
|---|---|---|
Recursively iterate over a StripeObject where are values are native Python classes |
obj.to_dict() |
{"id": "cus_123", "subscription": {"id": "sub_456", 'amount': Decimal('7.89')}} |
Iterate over the top-level of a StripeObject |
obj.to_dict(recursive=False) |
{"id": "cus_123", "subscription": Subscription(id="sub_456", amount=Decimal("7.89"))} |
Get a plain dict where all values (in the entire tree) are JSON-serializable |
obj.to_dict(for_json=True) |
{"id": "cus_123", "subscription": {"id": "sub_456", "amount": "7.89"}} |
| Dump the object to a json string | str(obj) |
'{"id": "cus_123", "subscription": {"id": "sub_456", "amount": "7.89"}}' |
In each case, .to_dict() returns a copy of the original object, so changes to the dict are not reflected in obj.
StripeClient vs legacy pattern
We introduced the StripeClient class in v8 of the Python SDK. The legacy pattern used prior to that version is still available to use but will be marked as deprecated soon. Review the migration guide to use StripeClient to move from the legacy pattern.
Once the legacy pattern is deprecated, new API endpoints will only be accessible in the StripeClient. While there are no current plans to remove the legacy pattern for existing API endpoints, this may change in the future.
Handling exceptions
Unsuccessful requests raise exceptions. The class of the exception will reflect the sort of error that occurred. Please see the Api Reference for a description of the error classes you should handle, and for information on how to inspect these errors.
Per-request Configuration
Configure individual requests with the options argument. For example, you can make
requests with a specific Stripe Version
or as a connected account:
from stripe import StripeClient
client = StripeClient("sk_test_...")
# list customers
client.v1.customers.list(
options={
"api_key": "sk_test_...",
"stripe_account": "acct_...",
"stripe_version": "2019-02-19",
}
)
# retrieve single customer
client.v1.customers.retrieve(
"cus_123456789",
options={
"api_key": "sk_test_...",
"stripe_account": "acct_...",
"stripe_version": "2019-02-19",
}
)
Configuring an HTTP Client
You can configure your StripeClient to use urlfetch, requests, pycurl, or
urllib with the http_client option:
client = StripeClient("sk_test_...", http_client=stripe.UrlFetchClient())
client = StripeClient("sk_test_...", http_client=stripe.RequestsClient())
client = StripeClient("sk_test_...", http_client=stripe.PycurlClient())
client = StripeClient("sk_test_...", http_client=stripe.UrllibClient())
Without a configured client, by default the library will attempt to load
libraries in the order above (i.e. urlfetch is preferred with urllib used
as a last resort). We usually recommend that people use requests.
Configuring a Proxy
A proxy can be configured with the proxy client option:
client = StripeClient("sk_test_...", proxy="https://user:pass@example.com:1234")
Configuring Automatic Retries
You can enable automatic retries on requests that fail due to a transient problem by configuring the maximum number of retries:
client = StripeClient("sk_test_...", max_network_retries=2)
Various errors can trigger a retry, like a connection error or a timeout, and
also certain API responses like HTTP status 409 Conflict.
Idempotency keys are automatically generated and added to requests, when not given, to guarantee that retries are safe.
Logging
The library can be configured to emit logging that will give you better insight
into what it's doing. The info logging level is usually most appropriate for
production use, but debug is also available for more verbosity.
There are a few options for enabling it:
-
Set the environment variable
STRIPE_LOGto the valuedebugorinfo$ export STRIPE_LOG=debug
-
Set
stripe.log:import stripe stripe.log = 'debug'
-
Enable it through Python's logging module:
import logging logging.basicConfig() logging.getLogger('stripe').setLevel(logging.DEBUG)
Accessing response code and headers
You can access the HTTP response code and headers using the last_response property of the returned resource.
customer = client.v1.customers.retrieve(
"cus_123456789"
)
print(customer.last_response.code)
print(customer.last_response.headers)
How to use undocumented parameters and properties
In some cases, you might encounter parameters on an API request or fields on an API response that aren’t available in the SDKs. This might happen when they’re undocumented or when they’re in preview and you aren’t using a preview SDK. See undocumented params and properties to send those parameters or access those fields.
Writing a Plugin
If you're writing a plugin that uses the library, we'd appreciate it if you
identified using stripe.set_app_info():
stripe.set_app_info("MyAwesomePlugin", version="1.2.34", url="https://myawesomeplugin.info")
This information is passed along when the library makes calls to the Stripe API.
Telemetry
By default, the library sends telemetry to Stripe regarding request latency and feature usage. These numbers help Stripe improve the overall latency of its API for all users, and improve popular features.
You can disable this behavior if you prefer:
stripe.enable_telemetry = False
Types
In v7.1.0 and newer, the library includes type annotations. See the wiki for a detailed guide.
Please note that some annotations use features that were only fairly recently accepted,
such as Unpack[TypedDict] that was
accepted
in January 2023. We have tested that these types are recognized properly by Pyright.
Support for Unpack in MyPy is still experimental, but appears to degrade gracefully.
Please report an issue if there
is anything we can do to improve the types for your type checker of choice.
Types and the Versioning Policy
We release type changes in minor releases. While stripe-python follows semantic
versioning, our semantic versions describe the runtime behavior of the
library alone. Our type annotations are not reflected in the semantic
version. That is, upgrading to a new minor version of stripe-python might
result in your type checker producing a type error that it didn't before. You
can use a ~=x.x or x.x.* version specifier
in your requirements.txt to constrain pip to a certain minor range of stripe-python.
Types and API Versions
The types describe the Stripe API version
that was the latest at the time of release. This is the version that your library
sends by default. If you are overriding stripe.api_version / stripe_version on the StripeClient, or using a
webhook endpoint tied to an older version,
be aware that the data you see at runtime may not match the types.
Open and Closed Enums
Many of Stripe API enums are open, meaning Stripe may add new values even on older API versions.
To reflect this, open enum fields are typed as Union[Literal[...], str] rather than a plain Literal[...].
This ensures the field has the correct type for both values known at SDK release time and other values that may be added later.
A small number of enums are closed, meaning Stripe guarantees no new values will be added without an API version change.
Refer to the API Reference for the latest set of allowed values.
Public Preview SDKs
Stripe has features in the public preview phase that can be accessed via versions of this package that have the bX suffix like 12.2.0b2.
We would love for you to try these as we incrementally release new features and improve them based on your feedback.
To install, pick the latest version with the bX suffix by reviewing the releases page and then use it in the pip install command:
pip install stripe==<replace-with-the-version-of-your-choice>
Note There can be breaking changes between two versions of the public preview SDKs without a bump in the major version. Therefore we recommend pinning the package version to a specific version in your pyproject.toml or requirements file. This way you can install the same version each time without breaking changes unless you are intentionally looking for the latest public preview SDK.
Some preview features require a name and version to be set in the Stripe-Version header like feature_beta=v3. If your preview feature has this requirement, use the stripe.add_beta_version function (available only in the public preview SDKs):
stripe.add_beta_version("feature_beta", "v3")
Private Preview SDKs
Stripe has features in the private preview phase that can be accessed via versions of this package that have the aX suffix like 12.2.0a2. You can install the private preview SDKs by following the same instructions as for the public preview SDKs above and replacing the suffix b with a in package versions. Note that access to specific private preview API features may require separate approval.
Custom requests
This feature is only available from version 11 of this SDK.
If you would like to send a request to an undocumented API (for example you are in a private beta), or if you prefer to bypass the method definitions in the library and specify your request details directly, you can use the raw_request method on StripeClient.
client = StripeClient("sk_test_...")
response = client.raw_request(
"post", "/v1/beta_endpoint", param=123, stripe_version="2022-11-15; feature_beta=v3"
)
# (Optional) response is a StripeResponse. You can use `client.deserialize` to get a StripeObject.
deserialized_resp = client.deserialize(response, api_mode='V1')
Async
Asynchronous versions of request-making methods are available by suffixing the method name
with _async.
# With StripeClient
client = StripeClient("sk_test_...")
customer = await client.v1.customers.retrieve_async("cus_xyz")
# With global client
stripe.api_key = "sk_test_..."
customer = await stripe.Customer.retrieve_async("cus_xyz")
# .auto_paging_iter() implements both AsyncIterable and Iterable
async for c in await stripe.Customer.list_async().auto_paging_iter():
...
There is no .save_async as .save is deprecated since stripe-python v5. Please migrate to .modify_async.
The default HTTP client uses requests for making synchronous requests but
httpx for making async requests. If you're migrating to async, we recommend
you to explicitly initialize your own http client and pass it to StripeClient
or set it as the global default.
If you don't already have a dependency on an async-compatible HTTP library, pip install stripe[async] will install one for you (new in v13.0.1).
# By default, an explicitly initialized HTTPXClient will raise an exception if you
# attempt to call a sync method. If you intend to only use async, this is useful to
# make sure you don't unintentionally make a synchronous request.
my_http_client = stripe.HTTPXClient()
# If you want to use httpx to make sync requests, you can disable this
# behavior.
my_http_client = stripe.HTTPXClient(allow_sync_methods=True)
# aiohttp is also available (does not support sync requests)
my_http_client = stripe.AIOHTTPClient()
# With StripeClient
client = StripeClient("sk_test_...", http_client=my_http_client)
# With the global client
stripe.default_http_client = my_http_client
You can also subclass stripe.HTTPClient and provide your own instance.
Support
New features and bug fixes are released on the latest major version of the Stripe Python library. If you are on an older major version, we recommend that you upgrade to the latest in order to use the new features and bug fixes including those for security vulnerabilities. Older major versions of the package will continue to be available for use, but will not be receiving any updates.
Development
Contribution guidelines for this project
The test suite depends on stripe-mock, so make sure to fetch and run it from a background terminal (stripe-mock's README also contains instructions for installing via Homebrew and other methods):
go install github.com/stripe/stripe-mock@latest
stripe-mock
We use just for conveniently running development tasks. You can use them directly, or copy the commands out of the justfile. To our help docs, run just. By default, all commands will use an virtualenv created by your default python version (whatever comes out of python --version). We recommend using mise or pyenv to control that version.
Run the following command to set up the development virtualenv:
just venv
# or: python -m venv venv && venv/bin/python -I -m pip install -e .
Run all tests:
just test
# or: venv/bin/pytest
Run all tests in a single file:
just test tests/api_resources/abstract/test_updateable_api_resource.py
# or: venv/bin/pytest tests/api_resources/abstract/test_updateable_api_resource.py
Run a single test suite:
just test tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource
# or: venv/bin/pytest tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource
Run a single test:
just test tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource::test_save
# or: venv/bin/pytest tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource::test_save
Run the linter with:
just lint
# or: venv/bin/python -m flake8 --show-source stripe tests
The library uses Ruff for code formatting. Code must be formatted with Black before PRs are submitted, otherwise CI will fail. Run the formatter with:
just format
# or: venv/bin/ruff format . --quiet
Update bundled CA certificates from the [Mozilla cURL release][curl]:
just update-certs
1 maintainer
Release files for stripe 15.7.0a4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| stripe-15.7.0a4.tar.gz | 2.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stripe-15.7.0a4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 6.5 MB
Release files / stripe-15.7.0a4.tar.gz
| Download URL | stripe-15.7.0a4.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
671e9298b0afc1aef97945b5c9f2b6ceab10a2abad5383698f9a10e07aeeb6ab
|
|
BLAKE2b-256 checksum How to use checksums |
337b98d23361ddf8df941b5dbcc5676d2cedaf39dbcf71787beeadbec5b94df1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / stripe-15.7.0a4-py3-none-any.whl
| Download URL | stripe-15.7.0a4-py3-none-any.whl |
|---|---|
| Size | 4.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
de320e7042a61c4c34b2e3956abb5d8c568c87563ed08be4487475c6f834c9d8
|
|
BLAKE2b-256 checksum How to use checksums |
af49cf85d0d097028005f2936b7fe3d5961d1ac1355c802d426346587ac7894b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency log
