Skip to content

Migration guide for v21

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

Migration guide for v21

This version 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 Marshal and YAML dumps of StripeObjects

This change affects integrations that store StripeObjects with Marshal or YAML (for example, in Rails.cache) and then make requests through the restored objects.

Marshal and YAML dumps created with v21 replace API keys with a placeholder, including on nested objects. YAML dumps also no longer include the requestor or its configuration. Restored objects keep their data, connected account routing, and API version but have no API key. Before making requests through a restored object, call reattach_api_key with a key from your secure configuration:

# Before
customer = Rails.cache.read("customer")
customer.refresh

# After
# Load api_key from your secure configuration.
customer = Rails.cache.read("customer")
customer.reattach_api_key(api_key)
customer.refresh

Reattach the API key the same way on restored lists before making requests through them:

customers = Marshal.load(trusted_cached_list_bytes)
customers.reattach_api_key(api_key)
customers.auto_paging_each do |customer|
  # ...
end

reattach_api_key also attaches API keys to nested restored objects. Each nested object keeps its saved API version and connected account. Nested objects that already have an API key keep it. Reattachment does not change Stripe.api_key. If you dump the object again, the new dump omits the reattached key.

Requests before reattachment raise Stripe::AuthenticationError with instructions to call reattach_api_key, even if you set a global API key or pass a 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 ArgumentError. Passing an empty key or the serialization placeholder also raises ArgumentError.

This behavior applies to Marshal and YAML dumps created with v21. Dumps created with earlier versions can still contain API keys. Remove or replace those stored dumps according to your application's storage policy.

Clone this wiki locally