stripe-python

Since version v7.1.0, the library includes type annotations. Note that type annotations are released in minor versions and are not strictly tied to the semantic versioning of the library's runtime behavior. Upgrading a minor version might introduce new type errors in your type checker. To avoid unexpected type errors, you can constrain your version in requirements.txt using specifiers like ~=x.x or x.x.*.

Types describe the Stripe API version that was latest at the time of the library release. If you override stripe.api_version or use a webhook tied to an older version, the runtime data may not match the type annotations.

To run examples located in the examples/ directory, you must set the PYTHONPATH to the parent directory so the Python interpreter can locate the stripe package. Run the following command from within the examples/ folder:

PYTHONPATH=../ python <your_example_file>.py

PYTHONPATH=../ python thinevent_webhook_handler.py

To contribute a new example to the repository, follow these steps:

1. Clone example_template.py.
2. Implement your example logic.
3. Fill out the file comment, including a description and the key steps being demonstrated.
4. Run the script using the PYTHONPATH=../ python <filename>.py pattern from the examples/ directory.

# 1. Environment variable
$ export STRIPE_LOG=debug

# 2. stripe.log attribute
import stripe
stripe.log = 'debug'

# 3. Python logging module
import logging
logging.basicConfig()
logging.getLogger('stripe').setLevel(logging.DEBUG)

Asynchronous versions of request methods are available by appending the _async suffix. This works with both the StripeClient instance and the global stripe module.

To use async features, you should install the async dependencies via pip install stripe[async]. The library uses httpx for async requests. You can explicitly manage the HTTP client to ensure you only use async methods or to provide your own implementation.

You can install the Stripe library via PyPI using pip or install it directly from the source.

Requirements:

• Python 3.9+
• Note: Python 2.7 support ended with version 5.5.0.

pip install --upgrade stripe

Public preview features are available in versions with a bX suffix (e.g., 12.2.0b2). To install a specific preview version, use pip install with the exact version number. Because breaking changes can occur between preview versions without a major version bump, it is recommended to pin the version in your pyproject.toml or requirements.txt.

If a preview feature requires a specific name and version in the Stripe-Version header (e.g., feature_beta=v3), use the stripe.add_beta_version function.

The recommended way to use the library is via the StripeClient class. Initialize it with your secret key to perform API operations like listing or retrieving resources.

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)

A Subscription object has a status field which can be one of the following:

• active: The subscription is active and paying.
• trialing: The subscription is in a trial period.
• past_due: Payment is required but cannot be paid (failed payment or awaiting user action).
• unpaid: The subscription is unpaid; no subsequent invoices will be attempted (invoices are created but immediately closed).
• canceled: The subscription has been canceled.
• incomplete: For collection_method=charge_automatically, the initial payment attempt failed. If not paid within 23 hours, it moves to incomplete_expired.
• incomplete_expired: A terminal status for subscriptions where the initial invoice was not paid.
• paused: A subscription can enter this status when a trial ends without a payment method. A paused subscription doesn't generate invoices but can be resumed.

The pending_update object represents changes to a subscription that will be applied at a future time (defined by expires_at).

Key fields:

• billing_cycle_anchor: The date of the first full invoice if applied.
• subscription_items: The new list of subscription items to be set.
• trial_end: The Unix timestamp for the end of the trial period if applied.
• discounts: Subscription-level discounts to be applied.