Skip to content

Migration guide for v17

Zachary Chua edited this page Nov 11, 2026 · 1 revision

Migration guide for v17

This version of the SDK uses API version 2026-10-28.endive. If the format of this API version looks new to you, see our new API release process.

API keys are no longer preserved in pickled StripeObjects

This affects integrations that persist StripeObjects in caches or queues and then make requests through the restored objects.

Pickling now replaces API keys with a placeholder, including on nested objects. Unpickled objects retain their data, connected-account routing, and API version but have no API key. Before making requests through an unpickled object, call reattach_api_key() with a key from secure configuration:

# Before
customer = pickle.loads(trusted_cached_bytes)
customer.refresh()

# After
customer = pickle.loads(trusted_cached_bytes)
customer.reattach_api_key(api_key)
customer.refresh()

Reattach the API key the same way on unpickled lists and events before making requests through them:

customers = pickle.loads(trusted_cached_list_bytes)
customers.reattach_api_key(api_key)
for customer in customers.auto_paging_iter():
    ...

event = pickle.loads(trusted_cached_event_bytes)
event.reattach_api_key(api_key)
related_object = event.fetch_related_object()

reattach_api_key() also attaches API keys to nested unpickled objects. Each retains its saved API version and connected account. Nested objects that already have an API key keep it. Reattachment does not change stripe.api_key, and pickling the object again omits the reattached key.

Requests before reattachment raise AuthenticationError with instructions to call reattach_api_key(), even if you set a global or per-call API key.

Calling reattach_api_key() more than once, or on an object whose API key wasn't replaced with the serialization placeholder, raises ValueError. Passing an empty key or the serialization placeholder also raises ValueError.

This behavior applies to pickles created with v17. Pickles created with earlier versions can still contain API keys. Remove or replace those stored pickles according to your application's storage policy.

Clone this wiki locally