-
Notifications
You must be signed in to change notification settings - Fork 418
Migration guide for v8 (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:
-
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:[email protected]:1234"
After
client = stripe.StripeClient( "sk_test_123", stripe_version="2022-11-15", max_network_retries=3, proxy="https://user:[email protected]:1234", )
-
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="[email protected]", stripe_account="acct_123")
After
customer = client.customers.create(params={"email": "[email protected]"}, options={"stripe_account": "acct_123"})
-
When using one of our Update APIs, the StripeClient version is called
update()
instead ofmodify()
Before
customer = stripe.Customer.modify( "cus_123", description="new description", )
After
customer = client.customers.update( "cus_123", params={ "description": "new description", } )
-
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"}, );
-
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 )
"
⚠️ Request options likeapi_key
,stripe_account
,stripe_version
, andidempotency_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 typeStripeResponseStream
instead of a tuple containing(StripeResponseStream, api_key)
.⚠️ Removed public access toAPIRequestor
.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 forAPIRequestor
, 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.
⚠️ Removeapi_version
fromFile.create
parameters. Please usestripe_version
instead.⚠️ Removeutil.read_special_variable()
utility method (importing directly fromstripe.util
is deprecated as of v7.8.0)⚠️ RemoveStripeError.construct_error_object()
. This method was intended for internal stripe-python use only.⚠️ RemoveListObject.empty_list()
. This method was intended for internal stripe-python use only.⚠️ RemoveSearchResultObject.empty_search_result()
. This method was intended for internal stripe-python use only.⚠️ RemoveStripeObject.ReprJSONEncoder
. This class was intended for internal stripe-python use only.⚠️ RemoveStripeObject.api_base
. This property was defunct and returnedNone
.