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. 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"},
   );

4. 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).
• ⚠️ APIRequestor.request() and APIRequestor.request_stream() parameter changes:
  • Remove headers positional parameter
  • Add optional options positional parameter
  • Add required base_address and api_mode keyword-only parameter
• ⚠️ Update APIRequestor.request() to return a StripeObject (previously Tuple[StripeResponse, str])
• ⚠️ Update APIRequestor.request_stream() to return a StripeResponseStream (previously Tuple[StripeStreamResponse, str])
• ⚠️ APIRequestor.request_headers() parameters list changed from def request_headers(self, api_key, method) to def request_headers(self, method, options: RequestOptions). Please migrate any existing calls by passing in an API key via a RequestOptions dict: self.request_headers(method, {"api_key": api_key}).

⚠️ Removed

• ⚠️ Remove api_version from File.create parameters. Please use stripe_version instead.
• ⚠️ Remove api_base and api_version attributes on APIRequestor
• ⚠️ Remove util.read_special_variable() utility method (importing directly from stripe.util is deprecated as of v7.8.0)
• ⚠️ Remove APIRequestor.interpret_response() and APIRequestor.interpret_streaming_response() - these are now private methods.
• ⚠️ Remove APIRequestor.format_app_info(). This method was intended for internal stripe-python use only.
• ⚠️ 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.