Migration guide for v8 (StripeClient)

"⚠️" symbol highlights breaking changes.

StripeClient

Introduces StripeClient and the service-based call pattern. This new interface allows you to easily call Stripe APIs and has several benefits over the existing resource-based pattern:

• No global config: you can simultaneously use multiple clients with different configuration options (such as API keys)
• No static methods for easier mocking

To migrate from a resource-based to service-based pattern:

1. Initialize a StripeClient instance.

   Before

   stripe.api_key = "sk_test_123"

   After

   client = stripe.StripeClient("sk_test_123")

   You can also pass in previously configurable global options as keyword arguments into the StripeClient constructor:

   Before

   stripe.api_key = "sk_test_123"
   stripe.api_version = "2022-11-15"
   stripe.max_network_retries = 3
   stripe.proxy = "https://user:pass@example.com:1234"

   After

   client = stripe.StripeClient(
     "sk_test_123",
     stripe_version="2022-11-15",
     max_network_retries=3,
     proxy="https://user:pass@example.com:1234",
   )

2. Convert resource method calls to StripeClient calls. On resource-based calls, request parameters and request options were each individually passed in as a mix of positional and keyword arguments. But for service-base calls, request parameters and request options are passed in as separate dictionary arguments.

   Before

   customer = stripe.Customer.create(email="jenny.rosen@example.com", stripe_account="acct_123")

   After

   customer = client.customers.create(params={"email": "jenny.rosen@example.com"}, options={"stripe_account": "acct_123"})

3. When using one of our Update APIs, the StripeClient version is called update() instead of modify()

   Before

   customer = stripe.Customer.modify(
     "cus_123",
     description="new description",
   )

   After

   customer = client.customers.update(
     "cus_123",
     params={
       "description": "new description",
     }
   )

4. Convert nested resource operations to StripeClient calls. As with class and instance calls, request parameters and request options become separate dictionary arguments in the service-based pattern.

   Before

   stripe.Customer.list_balance_transactions(
     "cus_123",
     limit=3,
     stripe_version="2022-11-15",
   )

   After

   customer = client.customers.balance_transactions.list(
     "cus_123",
     params={"limit": 3},
     options={"stripe_version": "2022-11-15"},
   );

5. To construct a webhook event, use the StripeClient.construct_event() method:

   Before

   event = stripe.Webhook.construct_event(
     payload, sig_header, secret
   )

   After

   event = client.construct_event(
     payload, sig_header, secret
   )

Changelog

"⚠️" symbol highlights breaking changes

⚠️ Changed

• ⚠️ Request options like api_key, stripe_account, stripe_version, and idempotency_key can no longer be passed in positionally on resource methods. Please pass these in as keyword arguments.

BEFORE

stripe.Customer.create(
  "sk_test_123",  # api key
  "KG5LxwFBepaKHyUD",  # idempotency key
  "2022-11-15",  # stripe version
  "acct_123",  # stripe account
)

AFTER

stripe.Customer.create(
  api_key="sk_test_123",
  idempotency_key="KG5LxwFBepaKHyUD",
  stripe_version="2022-11-15",
  stripe_account="acct_123",
)

• ⚠️ Methods that turn a response stream (Quote.pdf) now returns a single value of type StripeResponseStream instead of a tuple containing (StripeResponseStream, api_key).
• ⚠️ Removed public access to APIRequestor. APIRequestor's main use is internal, and we don't have a good understanding of its external use cases. We had to make several breaking changes to its interface as part of this update, so rather than leaving it public we made it private. If you have a use case for APIRequestor, please open up a Github issue describing it. We'd rather you rely on something specifically designed for your use case than having to reach into the library's internals.

⚠️ Removed

• ⚠️ Remove api_version from File.create parameters. Please use stripe_version instead.
• ⚠️ Remove util.read_special_variable() utility method (importing directly from stripe.util is deprecated as of v7.8.0)
• ⚠️ Remove StripeError.construct_error_object(). This method was intended for internal stripe-python use only.
• ⚠️ Remove ListObject.empty_list(). This method was intended for internal stripe-python use only.
• ⚠️ Remove SearchResultObject.empty_search_result(). This method was intended for internal stripe-python use only.
• ⚠️ Remove StripeObject.ReprJSONEncoder. This class was intended for internal stripe-python use only.
• ⚠️ Remove StripeObject.api_base. This property was defunct and returned None.