From 7df42c05176f64cdc938fa3a1d214f50efbc9362 Mon Sep 17 00:00:00 2001 From: Zachary Chua Date: Thu, 13 Aug 2026 14:56:30 -0700 Subject: [PATCH 1/2] Add open vs closed enum section to README --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 0f2b8c940..1da70514a 100644 --- a/README.md +++ b/README.md @@ -258,6 +258,17 @@ sends by default. If you are overriding `stripe.api_version` / `stripe_version` [webhook endpoint](https://stripe.com/docs/webhooks#api-versions) tied to an older version, be aware that the data you see at runtime may not match the types. +### Open and Closed Enums + +Many of Stripe API enums are open, meaning Stripe may add new values even on older API versions. +To reflect this, open enum fields are typed as Union[Literal[...], str] rather than a plain Literal[...]. +This ensures the field has the correct type for both values known at SDK release time and other values that may be added later. + +A small number of enums are closed, meaning Stripe guarantees no new values will be added without an API version change. + +Refer to the [API Reference](https://docs.stripe.com) for the latest set of allowed values. + + ### Public Preview SDKs Stripe has features in the [public preview phase](https://docs.stripe.com/release-phases) that can be accessed via versions of this package that have the `bX` suffix like `12.2.0b2`. From ee53aedcf86d4f9590cd64e835b9384a03c9649b Mon Sep 17 00:00:00 2001 From: Zachary Chua Date: Thu, 13 Aug 2026 15:02:32 -0700 Subject: [PATCH 2/2] Put type sig in code block --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1da70514a..e5298bfd5 100644 --- a/README.md +++ b/README.md @@ -261,7 +261,7 @@ be aware that the data you see at runtime may not match the types. ### Open and Closed Enums Many of Stripe API enums are open, meaning Stripe may add new values even on older API versions. -To reflect this, open enum fields are typed as Union[Literal[...], str] rather than a plain Literal[...]. +To reflect this, open enum fields are typed as `Union[Literal[...], str]` rather than a plain `Literal[...]`. This ensures the field has the correct type for both values known at SDK release time and other values that may be added later. A small number of enums are closed, meaning Stripe guarantees no new values will be added without an API version change.