trycourier · stainless-app · Jul 23, 2026 · Jul 23, 2026
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "4.21.0"
+  ".": "4.21.1"
 }
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 134
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-b053468fefe6d757f86f3233ebbc52d80329ed2a6e7a6740fee01e4028a4c3b9.yml
-openapi_spec_hash: 416835e693de0fe19945be90a787d3f3
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-0630b37ff5ba795185e1e189b0f24d233ecd51681b6ebb7748cad8f0e8c4fcc0.yml
+openapi_spec_hash: b9a8c66633e914c9a2f7b3bf275c7349
 config_hash: 8d28dbeabe9d4dcc7d5b8c021a4cbbd7
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.21.1 (2026-07-23)
+
+Full Changelog: [v4.21.0...v4.21.1](https://github.com/trycourier/courier-ruby/compare/v4.21.0...v4.21.1)
+
+### Documentation
+
+* **openapi:** describe user topic-preference fields explicitly ([#172](https://github.com/trycourier/courier-ruby/issues/172)) ([c540bdb](https://github.com/trycourier/courier-ruby/commit/c540bdb855f180d850feeabf1a30ed4394092b50))
+
 ## 4.21.0 (2026-07-23)
 
 Full Changelog: [v4.20.0...v4.21.0](https://github.com/trycourier/courier-ruby/compare/v4.20.0...v4.21.0)

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -11,7 +11,7 @@ GIT
 PATH
   remote: .
   specs:
-    trycourier (4.21.0)
+    trycourier (4.21.1)
       cgi
       connection_pool
 

diff --git a/lib/courier/models/users/preference_update_or_create_topic_params.rb b/lib/courier/models/users/preference_update_or_create_topic_params.rb
@@ -42,29 +42,39 @@ class PreferenceUpdateOrCreateTopicParams < Courier::Internal::Type::BaseModel
 
         class Topic < Courier::Internal::Type::BaseModel
           # @!attribute status
+          #   The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level
+          #   default, not a user choice; the API rejects opting a user out of a REQUIRED
+          #   topic.
           #
           #   @return [Symbol, Courier::Models::PreferenceStatus]
           required :status, enum: -> { Courier::PreferenceStatus }
 
           # @!attribute custom_routing
-          #   The Channels a user has chosen to receive notifications through for this topic
+          #   The channels to deliver this topic on when has_custom_routing is true. One or
+          #   more of: direct_message, email, push, sms, webhook, inbox.
           #
           #   @return [Array<Symbol, Courier::Models::ChannelClassification>, nil]
           optional :custom_routing,
                    -> { Courier::Internal::Type::ArrayOf[enum: Courier::ChannelClassification] },
                    nil?: true
 
           # @!attribute has_custom_routing
+          #   Set to true to route this topic to the channels in custom_routing instead of the
+          #   topic's default routing.
           #
           #   @return [Boolean, nil]
           optional :has_custom_routing, Courier::Internal::Type::Boolean, nil?: true
 
           # @!method initialize(status:, custom_routing: nil, has_custom_routing: nil)
-          #   @param status [Symbol, Courier::Models::PreferenceStatus]
+          #   Some parameter documentations has been truncated, see
+          #   {Courier::Models::Users::PreferenceUpdateOrCreateTopicParams::Topic} for more
+          #   details.
           #
-          #   @param custom_routing [Array<Symbol, Courier::Models::ChannelClassification>, nil] The Channels a user has chosen to receive notifications through for this topic
+          #   @param status [Symbol, Courier::Models::PreferenceStatus] The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level
           #
-          #   @param has_custom_routing [Boolean, nil]
+          #   @param custom_routing [Array<Symbol, Courier::Models::ChannelClassification>, nil] The channels to deliver this topic on when has_custom_routing is true. One or mo
+          #
+          #   @param has_custom_routing [Boolean, nil] Set to true to route this topic to the channels in custom_routing instead of the
         end
       end
     end

diff --git a/lib/courier/models/users/topic_preference.rb b/lib/courier/models/users/topic_preference.rb
@@ -5,50 +5,64 @@ module Models
     module Users
       class TopicPreference < Courier::Internal::Type::BaseModel
         # @!attribute default_status
+        #   The topic's default status, returned on reads. It applies whenever the user has
+        #   no override of their own (status equals this value).
         #
         #   @return [Symbol, Courier::Models::PreferenceStatus]
         required :default_status, enum: -> { Courier::PreferenceStatus }
 
         # @!attribute status
+        #   The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the
+        #   user's own choice; REQUIRED is a topic-level default set in the preferences
+        #   editor, not a user choice.
         #
         #   @return [Symbol, Courier::Models::PreferenceStatus]
         required :status, enum: -> { Courier::PreferenceStatus }
 
         # @!attribute topic_id
+        #   The unique identifier of the subscription topic this preference applies to.
         #
         #   @return [String]
         required :topic_id, String
 
         # @!attribute topic_name
+        #   The display name of the subscription topic, returned on reads.
         #
         #   @return [String]
         required :topic_name, String
 
         # @!attribute custom_routing
-        #   The Channels a user has chosen to receive notifications through for this topic
+        #   The channels the user has chosen to receive this topic on, present only when
+        #   has_custom_routing is true. One or more of: direct_message, email, push, sms,
+        #   webhook, inbox.
         #
         #   @return [Array<Symbol, Courier::Models::ChannelClassification>, nil]
         optional :custom_routing,
                  -> { Courier::Internal::Type::ArrayOf[enum: Courier::ChannelClassification] },
                  nil?: true
 
         # @!attribute has_custom_routing
+        #   Whether the user has chosen specific delivery channels for this topic (listed in
+        #   custom_routing) rather than the topic's default routing.
         #
         #   @return [Boolean, nil]
         optional :has_custom_routing, Courier::Internal::Type::Boolean, nil?: true
 
         # @!method initialize(default_status:, status:, topic_id:, topic_name:, custom_routing: nil, has_custom_routing: nil)
-        #   @param default_status [Symbol, Courier::Models::PreferenceStatus]
+        #   Some parameter documentations has been truncated, see
+        #   {Courier::Models::Users::TopicPreference} for more details.
         #
-        #   @param status [Symbol, Courier::Models::PreferenceStatus]
+        #   @param default_status [Symbol, Courier::Models::PreferenceStatus] The topic's default status, returned on reads. It applies whenever the user has
         #
-        #   @param topic_id [String]
+        #   @param status [Symbol, Courier::Models::PreferenceStatus] The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the
         #
-        #   @param topic_name [String]
+        #   @param topic_id [String] The unique identifier of the subscription topic this preference applies to.
         #
-        #   @param custom_routing [Array<Symbol, Courier::Models::ChannelClassification>, nil] The Channels a user has chosen to receive notifications through for this topic
+        #   @param topic_name [String] The display name of the subscription topic, returned on reads.
         #
-        #   @param has_custom_routing [Boolean, nil]
+        #   @param custom_routing [Array<Symbol, Courier::Models::ChannelClassification>, nil] The channels the user has chosen to receive this topic on, present only when has
+        #
+        #   @param has_custom_routing [Boolean, nil] Whether the user has chosen specific delivery channels for this topic (listed in
       end
     end
   end

diff --git a/lib/courier/version.rb b/lib/courier/version.rb
@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Courier
-  VERSION = "4.21.0"
+  VERSION = "4.21.1"
 end
diff --git a/rbi/courier/models/users/preference_update_or_create_topic_params.rbi b/rbi/courier/models/users/preference_update_or_create_topic_params.rbi
@@ -81,17 +81,23 @@ module Courier
               )
             end
 
+          # The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level
+          # default, not a user choice; the API rejects opting a user out of a REQUIRED
+          # topic.
           sig { returns(Courier::PreferenceStatus::OrSymbol) }
           attr_accessor :status
 
-          # The Channels a user has chosen to receive notifications through for this topic
+          # The channels to deliver this topic on when has_custom_routing is true. One or
+          # more of: direct_message, email, push, sms, webhook, inbox.
           sig do
             returns(
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol])
             )
           end
           attr_accessor :custom_routing
 
+          # Set to true to route this topic to the channels in custom_routing instead of the
+          # topic's default routing.
           sig { returns(T.nilable(T::Boolean)) }
           attr_accessor :has_custom_routing
 
@@ -104,9 +110,15 @@ module Courier
             ).returns(T.attached_class)
           end
           def self.new(
+            # The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level
+            # default, not a user choice; the API rejects opting a user out of a REQUIRED
+            # topic.
             status:,
-            # The Channels a user has chosen to receive notifications through for this topic
+            # The channels to deliver this topic on when has_custom_routing is true. One or
+            # more of: direct_message, email, push, sms, webhook, inbox.
             custom_routing: nil,
+            # Set to true to route this topic to the channels in custom_routing instead of the
+            # topic's default routing.
             has_custom_routing: nil
           )
           end

diff --git a/rbi/courier/models/users/topic_preference.rbi b/rbi/courier/models/users/topic_preference.rbi
@@ -9,26 +9,37 @@ module Courier
             T.any(Courier::Users::TopicPreference, Courier::Internal::AnyHash)
           end
 
+        # The topic's default status, returned on reads. It applies whenever the user has
+        # no override of their own (status equals this value).
         sig { returns(Courier::PreferenceStatus::TaggedSymbol) }
         attr_accessor :default_status
 
+        # The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the
+        # user's own choice; REQUIRED is a topic-level default set in the preferences
+        # editor, not a user choice.
         sig { returns(Courier::PreferenceStatus::TaggedSymbol) }
         attr_accessor :status
 
+        # The unique identifier of the subscription topic this preference applies to.
         sig { returns(String) }
         attr_accessor :topic_id
 
+        # The display name of the subscription topic, returned on reads.
         sig { returns(String) }
         attr_accessor :topic_name
 
-        # The Channels a user has chosen to receive notifications through for this topic
+        # The channels the user has chosen to receive this topic on, present only when
+        # has_custom_routing is true. One or more of: direct_message, email, push, sms,
+        # webhook, inbox.
         sig do
           returns(
             T.nilable(T::Array[Courier::ChannelClassification::TaggedSymbol])
           )
         end
         attr_accessor :custom_routing
 
+        # Whether the user has chosen specific delivery channels for this topic (listed in
+        # custom_routing) rather than the topic's default routing.
         sig { returns(T.nilable(T::Boolean)) }
         attr_accessor :has_custom_routing
 
@@ -44,12 +55,23 @@ module Courier
           ).returns(T.attached_class)
         end
         def self.new(
+          # The topic's default status, returned on reads. It applies whenever the user has
+          # no override of their own (status equals this value).
           default_status:,
+          # The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the
+          # user's own choice; REQUIRED is a topic-level default set in the preferences
+          # editor, not a user choice.
           status:,
+          # The unique identifier of the subscription topic this preference applies to.
           topic_id:,
+          # The display name of the subscription topic, returned on reads.
           topic_name:,
-          # The Channels a user has chosen to receive notifications through for this topic
+          # The channels the user has chosen to receive this topic on, present only when
+          # has_custom_routing is true. One or more of: direct_message, email, push, sms,
+          # webhook, inbox.
           custom_routing: nil,
+          # Whether the user has chosen specific delivery channels for this topic (listed in
+          # custom_routing) rather than the topic's default routing.
           has_custom_routing: nil
         )
         end