From cb256e8e1ccaec1b589000ca4fab5c5ecec5aeb7 Mon Sep 17 00:00:00 2001
From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com>
Date: Thu, 4 Jan 2024 16:18:11 +0000
Subject: [PATCH 1/3] Update generated code for v742

---
 OPENAPI_VERSION                               |   2 +-
 lib/stripe/resources/account.rb               |   8 ++
 lib/stripe/resources/apps/secret.rb           |   2 +
 .../resources/capital/financing_offer.rb      |   4 +
 lib/stripe/resources/charge.rb                |  10 ++
 lib/stripe/resources/checkout/session.rb      |   8 ++
 lib/stripe/resources/climate/order.rb         |   8 ++
 lib/stripe/resources/credit_note.rb           |   4 +
 lib/stripe/resources/customer.rb              |  16 +++
 lib/stripe/resources/dispute.rb               |   6 +
 .../financial_connections/account.rb          |  10 ++
 lib/stripe/resources/gift_cards/card.rb       |   1 +
 .../resources/gift_cards/transaction.rb       |   4 +
 .../identity/verification_session.rb          |  44 +++++++
 lib/stripe/resources/invoice.rb               |  38 ++++++
 lib/stripe/resources/issuing/authorization.rb |  17 +++
 lib/stripe/resources/issuing/card.rb          |   8 ++
 .../issuing/credit_underwriting_record.rb     |   6 +
 lib/stripe/resources/issuing/dispute.rb       |   2 +
 .../issuing/personalization_design.rb         |   6 +
 lib/stripe/resources/issuing/transaction.rb   |   4 +
 lib/stripe/resources/order.rb                 |   8 ++
 lib/stripe/resources/payment_intent.rb        | 118 ++++++++++++++++++
 lib/stripe/resources/payment_link.rb          |   2 +
 lib/stripe/resources/payment_method.rb        |  28 +++++
 lib/stripe/resources/payment_method_domain.rb |  12 ++
 lib/stripe/resources/payout.rb                |   8 ++
 lib/stripe/resources/quote.rb                 |  22 ++++
 lib/stripe/resources/quote_phase.rb           |   2 +
 lib/stripe/resources/refund.rb                |   8 ++
 lib/stripe/resources/review.rb                |   2 +
 lib/stripe/resources/setup_intent.rb          |  36 ++++++
 lib/stripe/resources/source.rb                |   2 +
 lib/stripe/resources/subscription.rb          |  14 +++
 lib/stripe/resources/subscription_schedule.rb |   6 +
 lib/stripe/resources/tax/calculation.rb       |   2 +
 lib/stripe/resources/tax/form.rb              |   2 +
 lib/stripe/resources/tax/transaction.rb       |   4 +
 lib/stripe/resources/terminal/reader.rb       |  18 +++
 .../resources/test_helpers/test_clock.rb      |   2 +
 lib/stripe/resources/topup.rb                 |   2 +
 .../resources/treasury/financial_account.rb   |   4 +
 .../resources/treasury/inbound_transfer.rb    |   8 ++
 .../resources/treasury/outbound_payment.rb    |   8 ++
 .../resources/treasury/outbound_transfer.rb   |   8 ++
 .../resources/treasury/received_credit.rb     |   1 +
 .../resources/treasury/received_debit.rb      |   1 +
 47 files changed, 535 insertions(+), 1 deletion(-)

diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION
index 8f5da3930..da794494d 100644
--- a/OPENAPI_VERSION
+++ b/OPENAPI_VERSION
@@ -1 +1 @@
-v737
\ No newline at end of file
+v742
\ No newline at end of file
diff --git a/lib/stripe/resources/account.rb b/lib/stripe/resources/account.rb
index 135ebd87e..e094df33f 100644
--- a/lib/stripe/resources/account.rb
+++ b/lib/stripe/resources/account.rb
@@ -25,6 +25,7 @@ class Account < APIResource
                                   resource_plural: "capabilities"
     nested_resource_class_methods :person, operations: %i[create retrieve update delete list]
 
+    # Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
     def persons(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -34,6 +35,9 @@ def persons(params = {}, opts = {})
       )
     end
 
+    # With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious.
+    #
+    # Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero.
     def reject(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -43,6 +47,7 @@ def reject(params = {}, opts = {})
       )
     end
 
+    # Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
     def self.persons(account, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -52,6 +57,9 @@ def self.persons(account, params = {}, opts = {})
       )
     end
 
+    # With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious.
+    #
+    # Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero.
     def self.reject(account, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/apps/secret.rb b/lib/stripe/resources/apps/secret.rb
index 28da6388f..345171415 100644
--- a/lib/stripe/resources/apps/secret.rb
+++ b/lib/stripe/resources/apps/secret.rb
@@ -18,6 +18,7 @@ class Secret < APIResource
 
       OBJECT_NAME = "apps.secret"
 
+      # Deletes a secret from the secret store by name and scope.
       def self.delete_where(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -27,6 +28,7 @@ def self.delete_where(params = {}, opts = {})
         )
       end
 
+      # Finds a secret in the secret store by name and scope.
       def self.find(params = {}, opts = {})
         request_stripe_object(
           method: :get,
diff --git a/lib/stripe/resources/capital/financing_offer.rb b/lib/stripe/resources/capital/financing_offer.rb
index 736a11d2a..3a29931fb 100644
--- a/lib/stripe/resources/capital/financing_offer.rb
+++ b/lib/stripe/resources/capital/financing_offer.rb
@@ -10,6 +10,8 @@ class FinancingOffer < APIResource
 
       OBJECT_NAME = "capital.financing_offer"
 
+      # Acknowledges that platform has received and delivered the financing_offer to
+      # the intended merchant recipient.
       def mark_delivered(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -19,6 +21,8 @@ def mark_delivered(params = {}, opts = {})
         )
       end
 
+      # Acknowledges that platform has received and delivered the financing_offer to
+      # the intended merchant recipient.
       def self.mark_delivered(financing_offer, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/charge.rb b/lib/stripe/resources/charge.rb
index c8ca474b9..8a31e357c 100644
--- a/lib/stripe/resources/charge.rb
+++ b/lib/stripe/resources/charge.rb
@@ -14,6 +14,11 @@ class Charge < APIResource
 
     OBJECT_NAME = "charge"
 
+    # Capture the payment of an existing, uncaptured charge that was created with the capture option set to false.
+    #
+    # Uncaptured payments expire a set number of days after they are created ([7 by default](https://stripe.com/docs/charges/placing-a-hold)), after which they are marked as refunded and capture attempts will fail.
+    #
+    # Don't use this method to capture a PaymentIntent-initiated charge. Use [Capture a PaymentIntent](https://stripe.com/docs/api/payment_intents/capture).
     def capture(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +28,11 @@ def capture(params = {}, opts = {})
       )
     end
 
+    # Capture the payment of an existing, uncaptured charge that was created with the capture option set to false.
+    #
+    # Uncaptured payments expire a set number of days after they are created ([7 by default](https://stripe.com/docs/charges/placing-a-hold)), after which they are marked as refunded and capture attempts will fail.
+    #
+    # Don't use this method to capture a PaymentIntent-initiated charge. Use [Capture a PaymentIntent](https://stripe.com/docs/api/payment_intents/capture).
     def self.capture(charge, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/checkout/session.rb b/lib/stripe/resources/checkout/session.rb
index 0d8005447..e911dd38e 100644
--- a/lib/stripe/resources/checkout/session.rb
+++ b/lib/stripe/resources/checkout/session.rb
@@ -23,6 +23,9 @@ class Session < APIResource
 
       OBJECT_NAME = "checkout.session"
 
+      # A Session can be expired when it is in one of these statuses: open
+      #
+      # After it expires, a customer can't complete a Session and customers loading the Session see a message saying the Session is expired.
       def expire(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -32,6 +35,7 @@ def expire(params = {}, opts = {})
         )
       end
 
+      # When retrieving a Checkout Session, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
       def list_line_items(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -41,6 +45,9 @@ def list_line_items(params = {}, opts = {})
         )
       end
 
+      # A Session can be expired when it is in one of these statuses: open
+      #
+      # After it expires, a customer can't complete a Session and customers loading the Session see a message saying the Session is expired.
       def self.expire(session, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -50,6 +57,7 @@ def self.expire(session, params = {}, opts = {})
         )
       end
 
+      # When retrieving a Checkout Session, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
       def self.list_line_items(session, params = {}, opts = {})
         request_stripe_object(
           method: :get,
diff --git a/lib/stripe/resources/climate/order.rb b/lib/stripe/resources/climate/order.rb
index 1e2b850e8..874f1eaf3 100644
--- a/lib/stripe/resources/climate/order.rb
+++ b/lib/stripe/resources/climate/order.rb
@@ -12,6 +12,10 @@ class Order < APIResource
 
       OBJECT_NAME = "climate.order"
 
+      # Cancels a Climate order. You can cancel an order within 30 days of creation. Stripe refunds the
+      # reservation amount_subtotal, but not the amount_fees for user-triggered cancellations. Frontier
+      # might cancel reservations if suppliers fail to deliver. If Frontier cancels the reservation, Stripe
+      # provides 90 days advance notice and refunds the amount_total.
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -21,6 +25,10 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # Cancels a Climate order. You can cancel an order within 30 days of creation. Stripe refunds the
+      # reservation amount_subtotal, but not the amount_fees for user-triggered cancellations. Frontier
+      # might cancel reservations if suppliers fail to deliver. If Frontier cancels the reservation, Stripe
+      # provides 90 days advance notice and refunds the amount_total.
       def self.cancel(order, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/credit_note.rb b/lib/stripe/resources/credit_note.rb
index 6cc81b198..ed4ed6835 100644
--- a/lib/stripe/resources/credit_note.rb
+++ b/lib/stripe/resources/credit_note.rb
@@ -12,6 +12,7 @@ class CreditNote < APIResource
 
     OBJECT_NAME = "credit_note"
 
+    # Marks a credit note as void. Learn more about [voiding credit notes](https://stripe.com/docs/billing/invoices/credit-notes#voiding).
     def void_credit_note(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -21,6 +22,7 @@ def void_credit_note(params = {}, opts = {})
       )
     end
 
+    # When retrieving a credit note preview, you'll get a lines property containing the first handful of those items. This URL you can retrieve the full (paginated) list of line items.
     def self.list_preview_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -30,6 +32,7 @@ def self.list_preview_line_items(params = {}, opts = {})
       )
     end
 
+    # Get a preview of a credit note without creating it.
     def self.preview(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -39,6 +42,7 @@ def self.preview(params = {}, opts = {})
       )
     end
 
+    # Marks a credit note as void. Learn more about [voiding credit notes](https://stripe.com/docs/billing/invoices/credit-notes#voiding).
     def self.void_credit_note(id, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/customer.rb b/lib/stripe/resources/customer.rb
index 7b643fb76..d92221e5d 100644
--- a/lib/stripe/resources/customer.rb
+++ b/lib/stripe/resources/customer.rb
@@ -19,6 +19,9 @@ class Customer < APIResource
     nested_resource_class_methods :cash_balance_transaction, operations: %i[retrieve list]
     nested_resource_class_methods :tax_id, operations: %i[create retrieve delete list]
 
+    # Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new
+    # funding instructions will be created. If funding instructions have already been created for a given customer, the same
+    # funding instructions will be retrieved. In other words, we will return the same funding instructions each time.
     def create_funding_instructions(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -28,6 +31,7 @@ def create_funding_instructions(params = {}, opts = {})
       )
     end
 
+    # Removes the currently applied discount on a customer.
     def delete_discount(params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -37,6 +41,7 @@ def delete_discount(params = {}, opts = {})
       )
     end
 
+    # Returns a list of PaymentMethods for a given Customer
     def list_payment_methods(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -46,6 +51,7 @@ def list_payment_methods(params = {}, opts = {})
       )
     end
 
+    # Retrieves a PaymentMethod object for a given Customer.
     def retrieve_payment_method(payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -55,6 +61,9 @@ def retrieve_payment_method(payment_method, params = {}, opts = {})
       )
     end
 
+    # Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new
+    # funding instructions will be created. If funding instructions have already been created for a given customer, the same
+    # funding instructions will be retrieved. In other words, we will return the same funding instructions each time.
     def self.create_funding_instructions(customer, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -64,6 +73,7 @@ def self.create_funding_instructions(customer, params = {}, opts = {})
       )
     end
 
+    # Removes the currently applied discount on a customer.
     def self.delete_discount(customer, params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -73,6 +83,7 @@ def self.delete_discount(customer, params = {}, opts = {})
       )
     end
 
+    # Returns a list of PaymentMethods for a given Customer
     def self.list_payment_methods(customer, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -82,6 +93,7 @@ def self.list_payment_methods(customer, params = {}, opts = {})
       )
     end
 
+    # Retrieves a PaymentMethod object for a given Customer.
     def self.retrieve_payment_method(customer, payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -109,6 +121,7 @@ def self.search_auto_paging_each(params = {}, opts = {}, &blk)
       search(params, opts).auto_paging_each(&blk)
     end
 
+    # Retrieves a customer's cash balance.
     def self.retrieve_cash_balance(customer, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -118,6 +131,7 @@ def self.retrieve_cash_balance(customer, params = {}, opts = {})
       )
     end
 
+    # Changes the settings on a customer's cash balance.
     def self.update_cash_balance(customer, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -134,6 +148,7 @@ def test_helpers
     class TestHelpers < APIResourceTestHelpers
       RESOURCE_CLASS = Customer
 
+      # Create an incoming testmode bank transfer
       def self.fund_cash_balance(customer, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -143,6 +158,7 @@ def self.fund_cash_balance(customer, params = {}, opts = {})
         )
       end
 
+      # Create an incoming testmode bank transfer
       def fund_cash_balance(params = {}, opts = {})
         @resource.request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/dispute.rb b/lib/stripe/resources/dispute.rb
index 55e687726..b4f7f1c95 100644
--- a/lib/stripe/resources/dispute.rb
+++ b/lib/stripe/resources/dispute.rb
@@ -13,6 +13,9 @@ class Dispute < APIResource
 
     OBJECT_NAME = "dispute"
 
+    # Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially dismissing the dispute, acknowledging it as lost.
+    #
+    # The status of the dispute will change from needs_response to lost. Closing a dispute is irreversible.
     def close(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -22,6 +25,9 @@ def close(params = {}, opts = {})
       )
     end
 
+    # Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially dismissing the dispute, acknowledging it as lost.
+    #
+    # The status of the dispute will change from needs_response to lost. Closing a dispute is irreversible.
     def self.close(dispute, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/financial_connections/account.rb b/lib/stripe/resources/financial_connections/account.rb
index 221ef443a..ef0871182 100644
--- a/lib/stripe/resources/financial_connections/account.rb
+++ b/lib/stripe/resources/financial_connections/account.rb
@@ -12,6 +12,7 @@ class Account < APIResource
 
       nested_resource_class_methods :inferred_balance, operations: %i[list]
 
+      # Disables your access to a Financial Connections Account. You will no longer be able to access data associated with the account (e.g. balances, transactions).
       def disconnect(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -21,6 +22,7 @@ def disconnect(params = {}, opts = {})
         )
       end
 
+      # Lists all owners for a given Account
       def list_owners(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -30,6 +32,7 @@ def list_owners(params = {}, opts = {})
         )
       end
 
+      # Refreshes the data associated with a Financial Connections Account.
       def refresh_account(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -39,6 +42,7 @@ def refresh_account(params = {}, opts = {})
         )
       end
 
+      # Subscribes to periodic refreshes of data associated with a Financial Connections Account.
       def subscribe(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -48,6 +52,7 @@ def subscribe(params = {}, opts = {})
         )
       end
 
+      # Unsubscribes from periodic refreshes of data associated with a Financial Connections Account.
       def unsubscribe(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -57,6 +62,7 @@ def unsubscribe(params = {}, opts = {})
         )
       end
 
+      # Disables your access to a Financial Connections Account. You will no longer be able to access data associated with the account (e.g. balances, transactions).
       def self.disconnect(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -66,6 +72,7 @@ def self.disconnect(account, params = {}, opts = {})
         )
       end
 
+      # Lists all owners for a given Account
       def self.list_owners(account, params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -75,6 +82,7 @@ def self.list_owners(account, params = {}, opts = {})
         )
       end
 
+      # Refreshes the data associated with a Financial Connections Account.
       def self.refresh_account(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -84,6 +92,7 @@ def self.refresh_account(account, params = {}, opts = {})
         )
       end
 
+      # Subscribes to periodic refreshes of data associated with a Financial Connections Account.
       def self.subscribe(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -93,6 +102,7 @@ def self.subscribe(account, params = {}, opts = {})
         )
       end
 
+      # Unsubscribes from periodic refreshes of data associated with a Financial Connections Account.
       def self.unsubscribe(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/gift_cards/card.rb b/lib/stripe/resources/gift_cards/card.rb
index 3d1dae626..4f5871124 100644
--- a/lib/stripe/resources/gift_cards/card.rb
+++ b/lib/stripe/resources/gift_cards/card.rb
@@ -12,6 +12,7 @@ class Card < APIResource
 
       OBJECT_NAME = "gift_cards.card"
 
+      # Validates a gift card code, returning the matching gift card object if it exists.
       def self.validate(params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/gift_cards/transaction.rb b/lib/stripe/resources/gift_cards/transaction.rb
index 6592ccb66..9574e65fd 100644
--- a/lib/stripe/resources/gift_cards/transaction.rb
+++ b/lib/stripe/resources/gift_cards/transaction.rb
@@ -16,6 +16,7 @@ class Transaction < APIResource
 
       OBJECT_NAME = "gift_cards.transaction"
 
+      # Cancel a gift card transaction
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -25,6 +26,7 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # Confirm a gift card transaction
       def confirm(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -34,6 +36,7 @@ def confirm(params = {}, opts = {})
         )
       end
 
+      # Cancel a gift card transaction
       def self.cancel(id, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -43,6 +46,7 @@ def self.cancel(id, params = {}, opts = {})
         )
       end
 
+      # Confirm a gift card transaction
       def self.confirm(id, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/identity/verification_session.rb b/lib/stripe/resources/identity/verification_session.rb
index e9fcf9126..9854f11ab 100644
--- a/lib/stripe/resources/identity/verification_session.rb
+++ b/lib/stripe/resources/identity/verification_session.rb
@@ -21,6 +21,9 @@ class VerificationSession < APIResource
 
       OBJECT_NAME = "identity.verification_session"
 
+      # A VerificationSession object can be canceled when it is in requires_input [status](https://stripe.com/docs/identity/how-sessions-work).
+      #
+      # Once canceled, future submission attempts are disabled. This cannot be undone. [Learn more](https://stripe.com/docs/identity/verification-sessions#cancel).
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -30,6 +33,25 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # Redact a VerificationSession to remove all collected information from Stripe. This will redact
+      # the VerificationSession and all objects related to it, including VerificationReports, Events,
+      # request logs, etc.
+      #
+      # A VerificationSession object can be redacted when it is in requires_input or verified
+      # [status](https://stripe.com/docs/identity/how-sessions-work). Redacting a VerificationSession in requires_action
+      # state will automatically cancel it.
+      #
+      # The redaction process may take up to four days. When the redaction process is in progress, the
+      # VerificationSession's redaction.status field will be set to processing; when the process is
+      # finished, it will change to redacted and an identity.verification_session.redacted event
+      # will be emitted.
+      #
+      # Redaction is irreversible. Redacted objects are still accessible in the Stripe API, but all the
+      # fields that contain personal data will be replaced by the string [redacted] or a similar
+      # placeholder. The metadata field will also be erased. Redacted objects cannot be updated or
+      # used for any purpose.
+      #
+      # [Learn more](https://stripe.com/docs/identity/verification-sessions#redact).
       def redact(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -39,6 +61,9 @@ def redact(params = {}, opts = {})
         )
       end
 
+      # A VerificationSession object can be canceled when it is in requires_input [status](https://stripe.com/docs/identity/how-sessions-work).
+      #
+      # Once canceled, future submission attempts are disabled. This cannot be undone. [Learn more](https://stripe.com/docs/identity/verification-sessions#cancel).
       def self.cancel(session, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -48,6 +73,25 @@ def self.cancel(session, params = {}, opts = {})
         )
       end
 
+      # Redact a VerificationSession to remove all collected information from Stripe. This will redact
+      # the VerificationSession and all objects related to it, including VerificationReports, Events,
+      # request logs, etc.
+      #
+      # A VerificationSession object can be redacted when it is in requires_input or verified
+      # [status](https://stripe.com/docs/identity/how-sessions-work). Redacting a VerificationSession in requires_action
+      # state will automatically cancel it.
+      #
+      # The redaction process may take up to four days. When the redaction process is in progress, the
+      # VerificationSession's redaction.status field will be set to processing; when the process is
+      # finished, it will change to redacted and an identity.verification_session.redacted event
+      # will be emitted.
+      #
+      # Redaction is irreversible. Redacted objects are still accessible in the Stripe API, but all the
+      # fields that contain personal data will be replaced by the string [redacted] or a similar
+      # placeholder. The metadata field will also be erased. Redacted objects cannot be updated or
+      # used for any purpose.
+      #
+      # [Learn more](https://stripe.com/docs/identity/verification-sessions#redact).
       def self.redact(session, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/invoice.rb b/lib/stripe/resources/invoice.rb
index 6ce60323f..62ae13559 100644
--- a/lib/stripe/resources/invoice.rb
+++ b/lib/stripe/resources/invoice.rb
@@ -46,6 +46,15 @@ class Invoice < APIResource
 
     nested_resource_class_methods :payment, operations: %i[retrieve list]
 
+    # Attaches a PaymentIntent to the invoice, adding it to the list of payments.
+    # When the PaymentIntent's status changes to succeeded, the payment is credited
+    # to the invoice, increasing its amount_paid. When the invoice is fully paid, the
+    # invoice's status becomes paid.
+    #
+    # If the PaymentIntent's status is already succeeded when it is attached, it is
+    # credited to the invoice immediately.
+    #
+    # Related guide: [Create an invoice payment](https://stripe.com/docs/invoicing/payments/create)
     def attach_payment_intent(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -55,6 +64,7 @@ def attach_payment_intent(params = {}, opts = {})
       )
     end
 
+    # Stripe automatically finalizes drafts before sending and attempting payment on invoices. However, if you'd like to finalize a draft invoice manually, you can do so using this method.
     def finalize_invoice(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -64,6 +74,7 @@ def finalize_invoice(params = {}, opts = {})
       )
     end
 
+    # Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.
     def mark_uncollectible(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -73,6 +84,7 @@ def mark_uncollectible(params = {}, opts = {})
       )
     end
 
+    # Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions according to your [subscriptions settings](https://dashboard.stripe.com/account/billing/automatic). However, if you'd like to attempt payment on an invoice out of the normal collection schedule or for some other reason, you can do so.
     def pay(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -82,6 +94,9 @@ def pay(params = {}, opts = {})
       )
     end
 
+    # Stripe will automatically send invoices to customers according to your [subscriptions settings](https://dashboard.stripe.com/account/billing/automatic). However, if you'd like to manually send an invoice to your customer out of the normal schedule, you can do so. When sending invoices that have already been paid, there will be no reference to the payment in the email.
+    #
+    # Requests made in test-mode result in no emails being sent, despite sending an invoice.sent event.
     def send_invoice(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -91,6 +106,7 @@ def send_invoice(params = {}, opts = {})
       )
     end
 
+    # Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to [deletion](https://stripe.com/docs/api#delete_invoice), however it only applies to finalized invoices and maintains a papertrail where the invoice can still be found.
     def void_invoice(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -100,6 +116,15 @@ def void_invoice(params = {}, opts = {})
       )
     end
 
+    # Attaches a PaymentIntent to the invoice, adding it to the list of payments.
+    # When the PaymentIntent's status changes to succeeded, the payment is credited
+    # to the invoice, increasing its amount_paid. When the invoice is fully paid, the
+    # invoice's status becomes paid.
+    #
+    # If the PaymentIntent's status is already succeeded when it is attached, it is
+    # credited to the invoice immediately.
+    #
+    # Related guide: [Create an invoice payment](https://stripe.com/docs/invoicing/payments/create)
     def self.attach_payment_intent(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -109,6 +134,7 @@ def self.attach_payment_intent(invoice, params = {}, opts = {})
       )
     end
 
+    # Stripe automatically finalizes drafts before sending and attempting payment on invoices. However, if you'd like to finalize a draft invoice manually, you can do so using this method.
     def self.finalize_invoice(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -118,6 +144,7 @@ def self.finalize_invoice(invoice, params = {}, opts = {})
       )
     end
 
+    # When retrieving an upcoming invoice, you'll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_upcoming_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -127,6 +154,7 @@ def self.list_upcoming_line_items(params = {}, opts = {})
       )
     end
 
+    # Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.
     def self.mark_uncollectible(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -136,6 +164,7 @@ def self.mark_uncollectible(invoice, params = {}, opts = {})
       )
     end
 
+    # Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions according to your [subscriptions settings](https://dashboard.stripe.com/account/billing/automatic). However, if you'd like to attempt payment on an invoice out of the normal collection schedule or for some other reason, you can do so.
     def self.pay(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -145,6 +174,9 @@ def self.pay(invoice, params = {}, opts = {})
       )
     end
 
+    # Stripe will automatically send invoices to customers according to your [subscriptions settings](https://dashboard.stripe.com/account/billing/automatic). However, if you'd like to manually send an invoice to your customer out of the normal schedule, you can do so. When sending invoices that have already been paid, there will be no reference to the payment in the email.
+    #
+    # Requests made in test-mode result in no emails being sent, despite sending an invoice.sent event.
     def self.send_invoice(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -154,10 +186,16 @@ def self.send_invoice(invoice, params = {}, opts = {})
       )
     end
 
+    # At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice.
+    #
+    # Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer's discount.
+    #
+    # You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass a proration_date parameter when doing the actual subscription update. The value passed in should be the same as the subscription_proration_date returned on the upcoming invoice resource. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_proration_date on the upcoming invoice resource.
     def self.upcoming(params = {}, opts = {})
       request_stripe_object(method: :get, path: "/v1/invoices/upcoming", params: params, opts: opts)
     end
 
+    # Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to [deletion](https://stripe.com/docs/api#delete_invoice), however it only applies to finalized invoices and maintains a papertrail where the invoice can still be found.
     def self.void_invoice(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/issuing/authorization.rb b/lib/stripe/resources/issuing/authorization.rb
index fa250792b..7dee5772b 100644
--- a/lib/stripe/resources/issuing/authorization.rb
+++ b/lib/stripe/resources/issuing/authorization.rb
@@ -14,6 +14,8 @@ class Authorization < APIResource
 
       OBJECT_NAME = "issuing.authorization"
 
+      # [Deprecated] Approves a pending Issuing Authorization object. This request should be made within the timeout window of the [real-time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to approve an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def approve(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -23,6 +25,8 @@ def approve(params = {}, opts = {})
         )
       end
 
+      # [Deprecated] Declines a pending Issuing Authorization object. This request should be made within the timeout window of the [real time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to decline an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def decline(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -32,6 +36,8 @@ def decline(params = {}, opts = {})
         )
       end
 
+      # [Deprecated] Approves a pending Issuing Authorization object. This request should be made within the timeout window of the [real-time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to approve an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def self.approve(authorization, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -41,6 +47,8 @@ def self.approve(authorization, params = {}, opts = {})
         )
       end
 
+      # [Deprecated] Declines a pending Issuing Authorization object. This request should be made within the timeout window of the [real time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to decline an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def self.decline(authorization, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -57,6 +65,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Authorization
 
+        # Capture a test-mode authorization.
         def self.capture(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -66,6 +75,7 @@ def self.capture(authorization, params = {}, opts = {})
           )
         end
 
+        # Create a test-mode authorization.
         def self.create(params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -75,6 +85,7 @@ def self.create(params = {}, opts = {})
           )
         end
 
+        # Expire a test-mode Authorization.
         def self.expire(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -84,6 +95,7 @@ def self.expire(authorization, params = {}, opts = {})
           )
         end
 
+        # Increment a test-mode Authorization.
         def self.increment(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -93,6 +105,7 @@ def self.increment(authorization, params = {}, opts = {})
           )
         end
 
+        # Reverse a test-mode Authorization.
         def self.reverse(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -102,6 +115,7 @@ def self.reverse(authorization, params = {}, opts = {})
           )
         end
 
+        # Capture a test-mode authorization.
         def capture(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -111,6 +125,7 @@ def capture(params = {}, opts = {})
           )
         end
 
+        # Expire a test-mode Authorization.
         def expire(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -120,6 +135,7 @@ def expire(params = {}, opts = {})
           )
         end
 
+        # Increment a test-mode Authorization.
         def increment(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -129,6 +145,7 @@ def increment(params = {}, opts = {})
           )
         end
 
+        # Reverse a test-mode Authorization.
         def reverse(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/issuing/card.rb b/lib/stripe/resources/issuing/card.rb
index 88764b666..1775b6497 100644
--- a/lib/stripe/resources/issuing/card.rb
+++ b/lib/stripe/resources/issuing/card.rb
@@ -18,6 +18,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Card
 
+        # Updates the shipping status of the specified Issuing Card object to delivered.
         def self.deliver_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -27,6 +28,7 @@ def self.deliver_card(card, params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to failure.
         def self.fail_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -36,6 +38,7 @@ def self.fail_card(card, params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to returned.
         def self.return_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -45,6 +48,7 @@ def self.return_card(card, params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to shipped.
         def self.ship_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -54,6 +58,7 @@ def self.ship_card(card, params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to delivered.
         def deliver_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -63,6 +68,7 @@ def deliver_card(params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to failure.
         def fail_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -72,6 +78,7 @@ def fail_card(params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to returned.
         def return_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -81,6 +88,7 @@ def return_card(params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to shipped.
         def ship_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/issuing/credit_underwriting_record.rb b/lib/stripe/resources/issuing/credit_underwriting_record.rb
index afceb71a9..d044d36fa 100644
--- a/lib/stripe/resources/issuing/credit_underwriting_record.rb
+++ b/lib/stripe/resources/issuing/credit_underwriting_record.rb
@@ -11,6 +11,7 @@ class CreditUnderwritingRecord < APIResource
 
       OBJECT_NAME = "issuing.credit_underwriting_record"
 
+      # Update a CreditUnderwritingRecord object to correct mistakes.
       def correct(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -20,6 +21,7 @@ def correct(params = {}, opts = {})
         )
       end
 
+      # Update a CreditUnderwritingRecord object from a decision made on a credit application.
       def report_decision(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -29,6 +31,7 @@ def report_decision(params = {}, opts = {})
         )
       end
 
+      # Update a CreditUnderwritingRecord object to correct mistakes.
       def self.correct(credit_underwriting_record, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -38,6 +41,7 @@ def self.correct(credit_underwriting_record, params = {}, opts = {})
         )
       end
 
+      # Creates a CreditUnderwritingRecord object with information about a credit application submission.
       def self.create_from_application(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -47,6 +51,7 @@ def self.create_from_application(params = {}, opts = {})
         )
       end
 
+      # Creates a CreditUnderwritingRecord object from an underwriting decision coming from a proactive review of an existing accountholder.
       def self.create_from_proactive_review(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -56,6 +61,7 @@ def self.create_from_proactive_review(params = {}, opts = {})
         )
       end
 
+      # Update a CreditUnderwritingRecord object from a decision made on a credit application.
       def self.report_decision(credit_underwriting_record, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/issuing/dispute.rb b/lib/stripe/resources/issuing/dispute.rb
index 3b1e880d7..057aa57a0 100644
--- a/lib/stripe/resources/issuing/dispute.rb
+++ b/lib/stripe/resources/issuing/dispute.rb
@@ -13,6 +13,7 @@ class Dispute < APIResource
 
       OBJECT_NAME = "issuing.dispute"
 
+      # Submits an Issuing Dispute to the card network. Stripe validates that all evidence fields required for the dispute's reason are present. For more details, see [Dispute reasons and evidence](https://stripe.com/docs/issuing/purchases/disputes#dispute-reasons-and-evidence).
       def submit(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -22,6 +23,7 @@ def submit(params = {}, opts = {})
         )
       end
 
+      # Submits an Issuing Dispute to the card network. Stripe validates that all evidence fields required for the dispute's reason are present. For more details, see [Dispute reasons and evidence](https://stripe.com/docs/issuing/purchases/disputes#dispute-reasons-and-evidence).
       def self.submit(dispute, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/issuing/personalization_design.rb b/lib/stripe/resources/issuing/personalization_design.rb
index 260c73bd9..edc7fa6cd 100644
--- a/lib/stripe/resources/issuing/personalization_design.rb
+++ b/lib/stripe/resources/issuing/personalization_design.rb
@@ -18,6 +18,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = PersonalizationDesign
 
+        # Updates the status of the specified testmode personalization design object to active.
         def self.activate(personalization_design, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -27,6 +28,7 @@ def self.activate(personalization_design, params = {}, opts = {})
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to inactive.
         def self.deactivate(personalization_design, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -36,6 +38,7 @@ def self.deactivate(personalization_design, params = {}, opts = {})
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to rejected.
         def self.reject(personalization_design, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -45,6 +48,7 @@ def self.reject(personalization_design, params = {}, opts = {})
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to active.
         def activate(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -54,6 +58,7 @@ def activate(params = {}, opts = {})
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to inactive.
         def deactivate(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -63,6 +68,7 @@ def deactivate(params = {}, opts = {})
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to rejected.
         def reject(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/issuing/transaction.rb b/lib/stripe/resources/issuing/transaction.rb
index 9fc7e6a4f..a3bc14a8b 100644
--- a/lib/stripe/resources/issuing/transaction.rb
+++ b/lib/stripe/resources/issuing/transaction.rb
@@ -21,6 +21,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Transaction
 
+        # Allows the user to capture an arbitrary amount, also known as a forced capture.
         def self.create_force_capture(params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -30,6 +31,7 @@ def self.create_force_capture(params = {}, opts = {})
           )
         end
 
+        # Allows the user to refund an arbitrary amount, also known as a unlinked refund.
         def self.create_unlinked_refund(params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -39,6 +41,7 @@ def self.create_unlinked_refund(params = {}, opts = {})
           )
         end
 
+        # Refund a test-mode Transaction.
         def self.refund(transaction, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -48,6 +51,7 @@ def self.refund(transaction, params = {}, opts = {})
           )
         end
 
+        # Refund a test-mode Transaction.
         def refund(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/order.rb b/lib/stripe/resources/order.rb
index 0ca6e75df..8e11fbf41 100644
--- a/lib/stripe/resources/order.rb
+++ b/lib/stripe/resources/order.rb
@@ -14,6 +14,7 @@ class Order < APIResource
 
     OBJECT_NAME = "order"
 
+    # Cancels the order as well as the payment intent if one is attached.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +24,7 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # When retrieving an order, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def list_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -32,6 +34,7 @@ def list_line_items(params = {}, opts = {})
       )
     end
 
+    # Reopens a submitted order.
     def reopen(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -41,6 +44,7 @@ def reopen(params = {}, opts = {})
       )
     end
 
+    # Submitting an Order transitions the status to processing and creates a PaymentIntent object so the order can be paid. If the Order has an amount_total of 0, no PaymentIntent object will be created. Once the order is submitted, its contents cannot be changed, unless the [reopen](https://stripe.com/docs/api#reopen_order) method is called.
     def submit(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -50,6 +54,7 @@ def submit(params = {}, opts = {})
       )
     end
 
+    # Cancels the order as well as the payment intent if one is attached.
     def self.cancel(id, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -59,6 +64,7 @@ def self.cancel(id, params = {}, opts = {})
       )
     end
 
+    # When retrieving an order, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_line_items(id, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -68,6 +74,7 @@ def self.list_line_items(id, params = {}, opts = {})
       )
     end
 
+    # Reopens a submitted order.
     def self.reopen(id, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -77,6 +84,7 @@ def self.reopen(id, params = {}, opts = {})
       )
     end
 
+    # Submitting an Order transitions the status to processing and creates a PaymentIntent object so the order can be paid. If the Order has an amount_total of 0, no PaymentIntent object will be created. Once the order is submitted, its contents cannot be changed, unless the [reopen](https://stripe.com/docs/api#reopen_order) method is called.
     def self.submit(id, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/payment_intent.rb b/lib/stripe/resources/payment_intent.rb
index 723098e01..3dd1a25f0 100644
--- a/lib/stripe/resources/payment_intent.rb
+++ b/lib/stripe/resources/payment_intent.rb
@@ -21,6 +21,7 @@ class PaymentIntent < APIResource
 
     OBJECT_NAME = "payment_intent"
 
+    # Manually reconcile the remaining amount for a customer_balance PaymentIntent.
     def apply_customer_balance(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -30,6 +31,11 @@ def apply_customer_balance(params = {}, opts = {})
       )
     end
 
+    # You can cancel a PaymentIntent object when it's in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_action or, [in rare cases](https://stripe.com/docs/payments/intents), processing.
+    #
+    # After it's canceled, no additional charges are made by the PaymentIntent and any operations on the PaymentIntent fail with an error. For PaymentIntents with a status of requires_capture, the remaining amount_capturable is automatically refunded.
+    #
+    # You can't cancel the PaymentIntent for a Checkout Session. [Expire the Checkout Session](https://stripe.com/docs/api/checkout/sessions/expire) instead.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -39,6 +45,11 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Capture the funds of an existing uncaptured PaymentIntent when its status is requires_capture.
+    #
+    # Uncaptured PaymentIntents are cancelled a set number of days (7 by default) after their creation.
+    #
+    # Learn more about [separate authorization and capture](https://stripe.com/docs/payments/capture-later).
     def capture(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -48,6 +59,29 @@ def capture(params = {}, opts = {})
       )
     end
 
+    # Confirm that your customer intends to pay with current or provided
+    # payment method. Upon confirmation, the PaymentIntent will attempt to initiate
+    # a payment.
+    # If the selected payment method requires additional authentication steps, the
+    # PaymentIntent will transition to the requires_action status and
+    # suggest additional actions via next_action. If payment fails,
+    # the PaymentIntent transitions to the requires_payment_method status or the
+    # canceled status if the confirmation limit is reached. If
+    # payment succeeds, the PaymentIntent will transition to the succeeded
+    # status (or requires_capture, if capture_method is set to manual).
+    # If the confirmation_method is automatic, payment may be attempted
+    # using our [client SDKs](https://stripe.com/docs/stripe-js/reference#stripe-handle-card-payment)
+    # and the PaymentIntent's [client_secret](https://stripe.com/docs/api#payment_intent_object-client_secret).
+    # After next_actions are handled by the client, no additional
+    # confirmation is required to complete the payment.
+    # If the confirmation_method is manual, all payment attempts must be
+    # initiated using a secret key.
+    # If any actions are required for the payment, the PaymentIntent will
+    # return to the requires_confirmation state
+    # after those actions are completed. Your server needs to then
+    # explicitly re-confirm the PaymentIntent to initiate the next payment
+    # attempt. Read the [expanded documentation](https://stripe.com/docs/payments/payment-intents/web-manual)
+    # to learn more about manual confirmation.
     def confirm(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -57,6 +91,30 @@ def confirm(params = {}, opts = {})
       )
     end
 
+    # Perform an incremental authorization on an eligible
+    # [PaymentIntent](https://stripe.com/docs/api/payment_intents/object). To be eligible, the
+    # PaymentIntent's status must be requires_capture and
+    # [incremental_authorization_supported](https://stripe.com/docs/api/charges/object#charge_object-payment_method_details-card_present-incremental_authorization_supported)
+    # must be true.
+    #
+    # Incremental authorizations attempt to increase the authorized amount on
+    # your customer's card to the new, higher amount provided. Similar to the
+    # initial authorization, incremental authorizations can be declined. A
+    # single PaymentIntent can call this endpoint multiple times to further
+    # increase the authorized amount.
+    #
+    # If the incremental authorization succeeds, the PaymentIntent object
+    # returns with the updated
+    # [amount](https://stripe.com/docs/api/payment_intents/object#payment_intent_object-amount).
+    # If the incremental authorization fails, a
+    # [card_declined](https://stripe.com/docs/error-codes#card-declined) error returns, and no other
+    # fields on the PaymentIntent or Charge update. The PaymentIntent
+    # object remains capturable for the previously authorized amount.
+    #
+    # Each PaymentIntent can have a maximum of 10 incremental authorization attempts, including declines.
+    # After it's captured, a PaymentIntent can no longer be incremented.
+    #
+    # Learn more about [incremental authorizations](https://stripe.com/docs/terminal/features/incremental-authorizations).
     def increment_authorization(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -66,6 +124,7 @@ def increment_authorization(params = {}, opts = {})
       )
     end
 
+    # Verifies microdeposits on a PaymentIntent object.
     def verify_microdeposits(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -75,6 +134,7 @@ def verify_microdeposits(params = {}, opts = {})
       )
     end
 
+    # Manually reconcile the remaining amount for a customer_balance PaymentIntent.
     def self.apply_customer_balance(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -84,6 +144,11 @@ def self.apply_customer_balance(intent, params = {}, opts = {})
       )
     end
 
+    # You can cancel a PaymentIntent object when it's in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_action or, [in rare cases](https://stripe.com/docs/payments/intents), processing.
+    #
+    # After it's canceled, no additional charges are made by the PaymentIntent and any operations on the PaymentIntent fail with an error. For PaymentIntents with a status of requires_capture, the remaining amount_capturable is automatically refunded.
+    #
+    # You can't cancel the PaymentIntent for a Checkout Session. [Expire the Checkout Session](https://stripe.com/docs/api/checkout/sessions/expire) instead.
     def self.cancel(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -93,6 +158,11 @@ def self.cancel(intent, params = {}, opts = {})
       )
     end
 
+    # Capture the funds of an existing uncaptured PaymentIntent when its status is requires_capture.
+    #
+    # Uncaptured PaymentIntents are cancelled a set number of days (7 by default) after their creation.
+    #
+    # Learn more about [separate authorization and capture](https://stripe.com/docs/payments/capture-later).
     def self.capture(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -102,6 +172,29 @@ def self.capture(intent, params = {}, opts = {})
       )
     end
 
+    # Confirm that your customer intends to pay with current or provided
+    # payment method. Upon confirmation, the PaymentIntent will attempt to initiate
+    # a payment.
+    # If the selected payment method requires additional authentication steps, the
+    # PaymentIntent will transition to the requires_action status and
+    # suggest additional actions via next_action. If payment fails,
+    # the PaymentIntent transitions to the requires_payment_method status or the
+    # canceled status if the confirmation limit is reached. If
+    # payment succeeds, the PaymentIntent will transition to the succeeded
+    # status (or requires_capture, if capture_method is set to manual).
+    # If the confirmation_method is automatic, payment may be attempted
+    # using our [client SDKs](https://stripe.com/docs/stripe-js/reference#stripe-handle-card-payment)
+    # and the PaymentIntent's [client_secret](https://stripe.com/docs/api#payment_intent_object-client_secret).
+    # After next_actions are handled by the client, no additional
+    # confirmation is required to complete the payment.
+    # If the confirmation_method is manual, all payment attempts must be
+    # initiated using a secret key.
+    # If any actions are required for the payment, the PaymentIntent will
+    # return to the requires_confirmation state
+    # after those actions are completed. Your server needs to then
+    # explicitly re-confirm the PaymentIntent to initiate the next payment
+    # attempt. Read the [expanded documentation](https://stripe.com/docs/payments/payment-intents/web-manual)
+    # to learn more about manual confirmation.
     def self.confirm(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -111,6 +204,30 @@ def self.confirm(intent, params = {}, opts = {})
       )
     end
 
+    # Perform an incremental authorization on an eligible
+    # [PaymentIntent](https://stripe.com/docs/api/payment_intents/object). To be eligible, the
+    # PaymentIntent's status must be requires_capture and
+    # [incremental_authorization_supported](https://stripe.com/docs/api/charges/object#charge_object-payment_method_details-card_present-incremental_authorization_supported)
+    # must be true.
+    #
+    # Incremental authorizations attempt to increase the authorized amount on
+    # your customer's card to the new, higher amount provided. Similar to the
+    # initial authorization, incremental authorizations can be declined. A
+    # single PaymentIntent can call this endpoint multiple times to further
+    # increase the authorized amount.
+    #
+    # If the incremental authorization succeeds, the PaymentIntent object
+    # returns with the updated
+    # [amount](https://stripe.com/docs/api/payment_intents/object#payment_intent_object-amount).
+    # If the incremental authorization fails, a
+    # [card_declined](https://stripe.com/docs/error-codes#card-declined) error returns, and no other
+    # fields on the PaymentIntent or Charge update. The PaymentIntent
+    # object remains capturable for the previously authorized amount.
+    #
+    # Each PaymentIntent can have a maximum of 10 incremental authorization attempts, including declines.
+    # After it's captured, a PaymentIntent can no longer be incremented.
+    #
+    # Learn more about [incremental authorizations](https://stripe.com/docs/terminal/features/incremental-authorizations).
     def self.increment_authorization(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -120,6 +237,7 @@ def self.increment_authorization(intent, params = {}, opts = {})
       )
     end
 
+    # Verifies microdeposits on a PaymentIntent object.
     def self.verify_microdeposits(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/payment_link.rb b/lib/stripe/resources/payment_link.rb
index c4a4b77fb..fd41aa18c 100644
--- a/lib/stripe/resources/payment_link.rb
+++ b/lib/stripe/resources/payment_link.rb
@@ -14,6 +14,7 @@ class PaymentLink < APIResource
 
     OBJECT_NAME = "payment_link"
 
+    # When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def list_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -23,6 +24,7 @@ def list_line_items(params = {}, opts = {})
       )
     end
 
+    # When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_line_items(payment_link, params = {}, opts = {})
       request_stripe_object(
         method: :get,
diff --git a/lib/stripe/resources/payment_method.rb b/lib/stripe/resources/payment_method.rb
index 31798a955..9a280132b 100644
--- a/lib/stripe/resources/payment_method.rb
+++ b/lib/stripe/resources/payment_method.rb
@@ -14,6 +14,19 @@ class PaymentMethod < APIResource
 
     OBJECT_NAME = "payment_method"
 
+    # Attaches a PaymentMethod object to a Customer.
+    #
+    # To attach a new PaymentMethod to a customer for future payments, we recommend you use a [SetupIntent](https://stripe.com/docs/api/setup_intents)
+    # or a PaymentIntent with [setup_future_usage](https://stripe.com/docs/api/payment_intents/create#create_payment_intent-setup_future_usage).
+    # These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the /v1/payment_methods/:id/attach
+    # endpoint without first using a SetupIntent or PaymentIntent with setup_future_usage does not optimize the PaymentMethod for
+    # future use, which makes later declines and payment friction more likely.
+    # See [Optimizing cards for future payments](https://stripe.com/docs/payments/payment-intents#future-usage) for more information about setting up
+    # future payments.
+    #
+    # To use this PaymentMethod as the default for invoice or subscription payments,
+    # set [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method),
+    # on the Customer to the PaymentMethod's ID.
     def attach(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +36,7 @@ def attach(params = {}, opts = {})
       )
     end
 
+    # Detaches a PaymentMethod object from a Customer. After a PaymentMethod is detached, it can no longer be used for a payment or re-attached to a Customer.
     def detach(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -32,6 +46,19 @@ def detach(params = {}, opts = {})
       )
     end
 
+    # Attaches a PaymentMethod object to a Customer.
+    #
+    # To attach a new PaymentMethod to a customer for future payments, we recommend you use a [SetupIntent](https://stripe.com/docs/api/setup_intents)
+    # or a PaymentIntent with [setup_future_usage](https://stripe.com/docs/api/payment_intents/create#create_payment_intent-setup_future_usage).
+    # These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the /v1/payment_methods/:id/attach
+    # endpoint without first using a SetupIntent or PaymentIntent with setup_future_usage does not optimize the PaymentMethod for
+    # future use, which makes later declines and payment friction more likely.
+    # See [Optimizing cards for future payments](https://stripe.com/docs/payments/payment-intents#future-usage) for more information about setting up
+    # future payments.
+    #
+    # To use this PaymentMethod as the default for invoice or subscription payments,
+    # set [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method),
+    # on the Customer to the PaymentMethod's ID.
     def self.attach(payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -41,6 +68,7 @@ def self.attach(payment_method, params = {}, opts = {})
       )
     end
 
+    # Detaches a PaymentMethod object from a Customer. After a PaymentMethod is detached, it can no longer be used for a payment or re-attached to a Customer.
     def self.detach(payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/payment_method_domain.rb b/lib/stripe/resources/payment_method_domain.rb
index 184784336..49cfe03ce 100644
--- a/lib/stripe/resources/payment_method_domain.rb
+++ b/lib/stripe/resources/payment_method_domain.rb
@@ -13,6 +13,12 @@ class PaymentMethodDomain < APIResource
 
     OBJECT_NAME = "payment_method_domain"
 
+    # Some payment methods such as Apple Pay require additional steps to verify a domain. If the requirements weren't satisfied when the domain was created, the payment method will be inactive on the domain.
+    # The payment method doesn't appear in Elements for this domain until it is active.
+    #
+    # To activate a payment method on an existing payment method domain, complete the required validation steps specific to the payment method, and then validate the payment method domain with this endpoint.
+    #
+    # Related guides: [Payment method domains](https://stripe.com/docs/payments/payment-methods/pmd-registration).
     def validate(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -22,6 +28,12 @@ def validate(params = {}, opts = {})
       )
     end
 
+    # Some payment methods such as Apple Pay require additional steps to verify a domain. If the requirements weren't satisfied when the domain was created, the payment method will be inactive on the domain.
+    # The payment method doesn't appear in Elements for this domain until it is active.
+    #
+    # To activate a payment method on an existing payment method domain, complete the required validation steps specific to the payment method, and then validate the payment method domain with this endpoint.
+    #
+    # Related guides: [Payment method domains](https://stripe.com/docs/payments/payment-methods/pmd-registration).
     def self.validate(payment_method_domain, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/payout.rb b/lib/stripe/resources/payout.rb
index cccba9eb4..e50de02e4 100644
--- a/lib/stripe/resources/payout.rb
+++ b/lib/stripe/resources/payout.rb
@@ -17,6 +17,7 @@ class Payout < APIResource
 
     OBJECT_NAME = "payout"
 
+    # You can cancel a previously created payout if it hasn't been paid out yet. Stripe refunds the funds to your available balance. You can't cancel automatic Stripe payouts.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -26,6 +27,9 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Reverses a payout by debiting the destination bank account. At this time, you can only reverse payouts for connected accounts to US bank accounts. If the payout is in the pending status, use /v1/payouts/:id/cancel instead.
+    #
+    # By requesting a reversal through /v1/payouts/:id/reverse, you confirm that the authorized signatory of the selected bank account authorizes the debit on the bank account and that no other authorization is required.
     def reverse(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -35,6 +39,7 @@ def reverse(params = {}, opts = {})
       )
     end
 
+    # You can cancel a previously created payout if it hasn't been paid out yet. Stripe refunds the funds to your available balance. You can't cancel automatic Stripe payouts.
     def self.cancel(payout, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -44,6 +49,9 @@ def self.cancel(payout, params = {}, opts = {})
       )
     end
 
+    # Reverses a payout by debiting the destination bank account. At this time, you can only reverse payouts for connected accounts to US bank accounts. If the payout is in the pending status, use /v1/payouts/:id/cancel instead.
+    #
+    # By requesting a reversal through /v1/payouts/:id/reverse, you confirm that the authorized signatory of the selected bank account authorizes the debit on the bank account and that no other authorization is required.
     def self.reverse(payout, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/quote.rb b/lib/stripe/resources/quote.rb
index 97ffc9f8b..c6dd8ef72 100644
--- a/lib/stripe/resources/quote.rb
+++ b/lib/stripe/resources/quote.rb
@@ -15,6 +15,7 @@ class Quote < APIResource
     nested_resource_class_methods :preview_invoice, operations: %i[list]
     nested_resource_class_methods :preview_subscription_schedule, operations: %i[list]
 
+    # Accepts the specified quote.
     def accept(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -24,6 +25,7 @@ def accept(params = {}, opts = {})
       )
     end
 
+    # Cancels the quote.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -33,6 +35,7 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Finalizes the quote.
     def finalize_quote(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -42,6 +45,7 @@ def finalize_quote(params = {}, opts = {})
       )
     end
 
+    # When retrieving a quote, there is an includable [computed.upfront.line_items](https://stripe.com/docs/api/quotes/object#quote_object-computed-upfront-line_items) property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of upfront line items.
     def list_computed_upfront_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -51,6 +55,7 @@ def list_computed_upfront_line_items(params = {}, opts = {})
       )
     end
 
+    # When retrieving a quote, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def list_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -60,6 +65,7 @@ def list_line_items(params = {}, opts = {})
       )
     end
 
+    # Retrieves a paginated list of lines for a quote. These lines describe changes that will be used to create new subscription schedules or update existing subscription schedules when the quote is accepted.
     def list_lines(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -69,6 +75,7 @@ def list_lines(params = {}, opts = {})
       )
     end
 
+    # Preview the invoice line items that would be generated by accepting the quote.
     def list_preview_invoice_lines(preview_invoice, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -78,6 +85,7 @@ def list_preview_invoice_lines(preview_invoice, params = {}, opts = {})
       )
     end
 
+    # Converts a stale quote to draft.
     def mark_draft(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -87,6 +95,7 @@ def mark_draft(params = {}, opts = {})
       )
     end
 
+    # Converts a draft or open quote to stale.
     def mark_stale(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -96,6 +105,7 @@ def mark_stale(params = {}, opts = {})
       )
     end
 
+    # Download the PDF for a finalized quote
     def pdf(params = {}, opts = {}, &read_body_chunk_block)
       config = opts[:client]&.config || Stripe.config
       opts = { api_base: config.uploads_base }.merge(opts)
@@ -108,6 +118,7 @@ def pdf(params = {}, opts = {}, &read_body_chunk_block)
       )
     end
 
+    # Recompute the upcoming invoice estimate for the quote.
     def reestimate(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -117,6 +128,7 @@ def reestimate(params = {}, opts = {})
       )
     end
 
+    # Accepts the specified quote.
     def self.accept(quote, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -126,6 +138,7 @@ def self.accept(quote, params = {}, opts = {})
       )
     end
 
+    # Cancels the quote.
     def self.cancel(quote, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -135,6 +148,7 @@ def self.cancel(quote, params = {}, opts = {})
       )
     end
 
+    # Finalizes the quote.
     def self.finalize_quote(quote, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -144,6 +158,7 @@ def self.finalize_quote(quote, params = {}, opts = {})
       )
     end
 
+    # When retrieving a quote, there is an includable [computed.upfront.line_items](https://stripe.com/docs/api/quotes/object#quote_object-computed-upfront-line_items) property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of upfront line items.
     def self.list_computed_upfront_line_items(quote, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -153,6 +168,7 @@ def self.list_computed_upfront_line_items(quote, params = {}, opts = {})
       )
     end
 
+    # When retrieving a quote, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_line_items(quote, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -162,6 +178,7 @@ def self.list_line_items(quote, params = {}, opts = {})
       )
     end
 
+    # Retrieves a paginated list of lines for a quote. These lines describe changes that will be used to create new subscription schedules or update existing subscription schedules when the quote is accepted.
     def self.list_lines(quote, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -171,6 +188,7 @@ def self.list_lines(quote, params = {}, opts = {})
       )
     end
 
+    # Preview the invoice line items that would be generated by accepting the quote.
     def self.list_preview_invoice_lines(quote, preview_invoice, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -180,6 +198,7 @@ def self.list_preview_invoice_lines(quote, preview_invoice, params = {}, opts =
       )
     end
 
+    # Converts a stale quote to draft.
     def self.mark_draft(quote, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -189,6 +208,7 @@ def self.mark_draft(quote, params = {}, opts = {})
       )
     end
 
+    # Converts a draft or open quote to stale.
     def self.mark_stale(quote, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -198,6 +218,7 @@ def self.mark_stale(quote, params = {}, opts = {})
       )
     end
 
+    # Download the PDF for a finalized quote
     def self.pdf(quote, params = {}, opts = {}, &read_body_chunk_block)
       config = opts[:client]&.config || Stripe.config
       opts = { api_base: config.uploads_base }.merge(opts)
@@ -210,6 +231,7 @@ def self.pdf(quote, params = {}, opts = {}, &read_body_chunk_block)
       )
     end
 
+    # Recompute the upcoming invoice estimate for the quote.
     def self.reestimate(quote, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/quote_phase.rb b/lib/stripe/resources/quote_phase.rb
index 03454039f..5386a1642 100644
--- a/lib/stripe/resources/quote_phase.rb
+++ b/lib/stripe/resources/quote_phase.rb
@@ -8,6 +8,7 @@ class QuotePhase < APIResource
 
     OBJECT_NAME = "quote_phase"
 
+    # When retrieving a quote phase, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def list_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -17,6 +18,7 @@ def list_line_items(params = {}, opts = {})
       )
     end
 
+    # When retrieving a quote phase, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_line_items(quote_phase, params = {}, opts = {})
       request_stripe_object(
         method: :get,
diff --git a/lib/stripe/resources/refund.rb b/lib/stripe/resources/refund.rb
index 2bd7cf574..6d88999bb 100644
--- a/lib/stripe/resources/refund.rb
+++ b/lib/stripe/resources/refund.rb
@@ -14,6 +14,9 @@ class Refund < APIResource
 
     OBJECT_NAME = "refund"
 
+    # Cancels a refund with a status of requires_action.
+    #
+    # You can't cancel refunds in other states. Only refunds for payment methods that require customer action can enter the requires_action state.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +26,9 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Cancels a refund with a status of requires_action.
+    #
+    # You can't cancel refunds in other states. Only refunds for payment methods that require customer action can enter the requires_action state.
     def self.cancel(refund, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -39,6 +45,7 @@ def test_helpers
     class TestHelpers < APIResourceTestHelpers
       RESOURCE_CLASS = Refund
 
+      # Expire a refund with a status of requires_action.
       def self.expire(refund, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -48,6 +55,7 @@ def self.expire(refund, params = {}, opts = {})
         )
       end
 
+      # Expire a refund with a status of requires_action.
       def expire(params = {}, opts = {})
         @resource.request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/review.rb b/lib/stripe/resources/review.rb
index e3c55be0b..1650c3db7 100644
--- a/lib/stripe/resources/review.rb
+++ b/lib/stripe/resources/review.rb
@@ -11,6 +11,7 @@ class Review < APIResource
 
     OBJECT_NAME = "review"
 
+    # Approves a Review object, closing it and removing it from the list of reviews.
     def approve(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -20,6 +21,7 @@ def approve(params = {}, opts = {})
       )
     end
 
+    # Approves a Review object, closing it and removing it from the list of reviews.
     def self.approve(review, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/setup_intent.rb b/lib/stripe/resources/setup_intent.rb
index f494b8601..b7ac8cf82 100644
--- a/lib/stripe/resources/setup_intent.rb
+++ b/lib/stripe/resources/setup_intent.rb
@@ -30,6 +30,9 @@ class SetupIntent < APIResource
 
     OBJECT_NAME = "setup_intent"
 
+    # You can cancel a SetupIntent object when it's in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.
+    #
+    # After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -39,6 +42,20 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Confirm that your customer intends to set up the current or
+    # provided payment method. For example, you would confirm a SetupIntent
+    # when a customer hits the “Save” button on a payment method management
+    # page on your website.
+    #
+    # If the selected payment method does not require any additional
+    # steps from the customer, the SetupIntent will transition to the
+    # succeeded status.
+    #
+    # Otherwise, it will transition to the requires_action status and
+    # suggest additional actions via next_action. If setup fails,
+    # the SetupIntent will transition to the
+    # requires_payment_method status or the canceled status if the
+    # confirmation limit is reached.
     def confirm(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -48,6 +65,7 @@ def confirm(params = {}, opts = {})
       )
     end
 
+    # Verifies microdeposits on a SetupIntent object.
     def verify_microdeposits(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -57,6 +75,9 @@ def verify_microdeposits(params = {}, opts = {})
       )
     end
 
+    # You can cancel a SetupIntent object when it's in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.
+    #
+    # After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error.
     def self.cancel(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -66,6 +87,20 @@ def self.cancel(intent, params = {}, opts = {})
       )
     end
 
+    # Confirm that your customer intends to set up the current or
+    # provided payment method. For example, you would confirm a SetupIntent
+    # when a customer hits the “Save” button on a payment method management
+    # page on your website.
+    #
+    # If the selected payment method does not require any additional
+    # steps from the customer, the SetupIntent will transition to the
+    # succeeded status.
+    #
+    # Otherwise, it will transition to the requires_action status and
+    # suggest additional actions via next_action. If setup fails,
+    # the SetupIntent will transition to the
+    # requires_payment_method status or the canceled status if the
+    # confirmation limit is reached.
     def self.confirm(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -75,6 +110,7 @@ def self.confirm(intent, params = {}, opts = {})
       )
     end
 
+    # Verifies microdeposits on a SetupIntent object.
     def self.verify_microdeposits(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/source.rb b/lib/stripe/resources/source.rb
index 425b3a229..05701d501 100644
--- a/lib/stripe/resources/source.rb
+++ b/lib/stripe/resources/source.rb
@@ -21,6 +21,7 @@ class Source < APIResource
 
     nested_resource_class_methods :source_transaction, operations: %i[retrieve list]
 
+    # Verify a given source.
     def verify(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -30,6 +31,7 @@ def verify(params = {}, opts = {})
       )
     end
 
+    # Verify a given source.
     def self.verify(source, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/subscription.rb b/lib/stripe/resources/subscription.rb
index 3f56e2483..487e599e9 100644
--- a/lib/stripe/resources/subscription.rb
+++ b/lib/stripe/resources/subscription.rb
@@ -13,6 +13,11 @@ class Subscription < APIResource
 
     OBJECT_NAME = "subscription"
 
+    # Cancels a customer's subscription immediately. The customer will not be charged again for the subscription.
+    #
+    # Note, however, that any pending invoice items that you've created will still be charged for at the end of the period, unless manually [deleted](https://stripe.com/docs/api#delete_invoiceitem). If you've set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed.
+    #
+    # By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -22,6 +27,7 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Removes the currently applied discount on a subscription.
     def delete_discount(params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -31,6 +37,7 @@ def delete_discount(params = {}, opts = {})
       )
     end
 
+    # Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. If a resumption invoice is generated, it must be paid or marked uncollectible before the subscription will be unpaused. If payment succeeds the subscription will become active, and if payment fails the subscription will be past_due. The resumption invoice will void automatically if not paid by the expiration date.
     def resume(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -40,6 +47,11 @@ def resume(params = {}, opts = {})
       )
     end
 
+    # Cancels a customer's subscription immediately. The customer will not be charged again for the subscription.
+    #
+    # Note, however, that any pending invoice items that you've created will still be charged for at the end of the period, unless manually [deleted](https://stripe.com/docs/api#delete_invoiceitem). If you've set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed.
+    #
+    # By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.
     def self.cancel(subscription_exposed_id, params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -49,6 +61,7 @@ def self.cancel(subscription_exposed_id, params = {}, opts = {})
       )
     end
 
+    # Removes the currently applied discount on a subscription.
     def self.delete_discount(subscription_exposed_id, params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -58,6 +71,7 @@ def self.delete_discount(subscription_exposed_id, params = {}, opts = {})
       )
     end
 
+    # Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. If a resumption invoice is generated, it must be paid or marked uncollectible before the subscription will be unpaused. If payment succeeds the subscription will become active, and if payment fails the subscription will be past_due. The resumption invoice will void automatically if not paid by the expiration date.
     def self.resume(subscription, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/subscription_schedule.rb b/lib/stripe/resources/subscription_schedule.rb
index b385f9e88..5ed422b73 100644
--- a/lib/stripe/resources/subscription_schedule.rb
+++ b/lib/stripe/resources/subscription_schedule.rb
@@ -12,6 +12,7 @@ class SubscriptionSchedule < APIResource
 
     OBJECT_NAME = "subscription_schedule"
 
+    # Amends an existing subscription schedule.
     def amend(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -21,6 +22,7 @@ def amend(params = {}, opts = {})
       )
     end
 
+    # Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_started or active.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -30,6 +32,7 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Releases the subscription schedule immediately, which will stop scheduling of its phases, but leave any existing subscription in place. A schedule can only be released if its status is not_started or active. If the subscription schedule is currently associated with a subscription, releasing it will remove its subscription property and set the subscription's ID to the released_subscription property.
     def release(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -39,6 +42,7 @@ def release(params = {}, opts = {})
       )
     end
 
+    # Amends an existing subscription schedule.
     def self.amend(schedule, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -48,6 +52,7 @@ def self.amend(schedule, params = {}, opts = {})
       )
     end
 
+    # Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_started or active.
     def self.cancel(schedule, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -57,6 +62,7 @@ def self.cancel(schedule, params = {}, opts = {})
       )
     end
 
+    # Releases the subscription schedule immediately, which will stop scheduling of its phases, but leave any existing subscription in place. A schedule can only be released if its status is not_started or active. If the subscription schedule is currently associated with a subscription, releasing it will remove its subscription property and set the subscription's ID to the released_subscription property.
     def self.release(schedule, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/tax/calculation.rb b/lib/stripe/resources/tax/calculation.rb
index 054218b57..b453a668f 100644
--- a/lib/stripe/resources/tax/calculation.rb
+++ b/lib/stripe/resources/tax/calculation.rb
@@ -11,6 +11,7 @@ class Calculation < APIResource
 
       OBJECT_NAME = "tax.calculation"
 
+      # Retrieves the line items of a persisted tax calculation as a collection.
       def list_line_items(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -20,6 +21,7 @@ def list_line_items(params = {}, opts = {})
         )
       end
 
+      # Retrieves the line items of a persisted tax calculation as a collection.
       def self.list_line_items(calculation, params = {}, opts = {})
         request_stripe_object(
           method: :get,
diff --git a/lib/stripe/resources/tax/form.rb b/lib/stripe/resources/tax/form.rb
index 788b6889a..badaca804 100644
--- a/lib/stripe/resources/tax/form.rb
+++ b/lib/stripe/resources/tax/form.rb
@@ -11,6 +11,7 @@ class Form < APIResource
 
       OBJECT_NAME = "tax.form"
 
+      # Download the PDF for a tax form.
       def pdf(params = {}, opts = {}, &read_body_chunk_block)
         config = opts[:client]&.config || Stripe.config
         opts = { api_base: config.uploads_base }.merge(opts)
@@ -23,6 +24,7 @@ def pdf(params = {}, opts = {}, &read_body_chunk_block)
         )
       end
 
+      # Download the PDF for a tax form.
       def self.pdf(id, params = {}, opts = {}, &read_body_chunk_block)
         config = opts[:client]&.config || Stripe.config
         opts = { api_base: config.uploads_base }.merge(opts)
diff --git a/lib/stripe/resources/tax/transaction.rb b/lib/stripe/resources/tax/transaction.rb
index e9469d7c1..09aeeeb87 100644
--- a/lib/stripe/resources/tax/transaction.rb
+++ b/lib/stripe/resources/tax/transaction.rb
@@ -9,6 +9,7 @@ module Tax
     class Transaction < APIResource
       OBJECT_NAME = "tax.transaction"
 
+      # Retrieves the line items of a committed standalone transaction as a collection.
       def list_line_items(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -18,6 +19,7 @@ def list_line_items(params = {}, opts = {})
         )
       end
 
+      # Creates a Tax Transaction from a calculation.
       def self.create_from_calculation(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -27,6 +29,7 @@ def self.create_from_calculation(params = {}, opts = {})
         )
       end
 
+      # Partially or fully reverses a previously created Transaction.
       def self.create_reversal(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -36,6 +39,7 @@ def self.create_reversal(params = {}, opts = {})
         )
       end
 
+      # Retrieves the line items of a committed standalone transaction as a collection.
       def self.list_line_items(transaction, params = {}, opts = {})
         request_stripe_object(
           method: :get,
diff --git a/lib/stripe/resources/terminal/reader.rb b/lib/stripe/resources/terminal/reader.rb
index bcbd4d9e1..48fe1d5f4 100644
--- a/lib/stripe/resources/terminal/reader.rb
+++ b/lib/stripe/resources/terminal/reader.rb
@@ -14,6 +14,7 @@ class Reader < APIResource
 
       OBJECT_NAME = "terminal.reader"
 
+      # Cancels the current reader action.
       def cancel_action(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -23,6 +24,7 @@ def cancel_action(params = {}, opts = {})
         )
       end
 
+      # Initiates an input collection flow on a Reader.
       def collect_inputs(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -32,6 +34,7 @@ def collect_inputs(params = {}, opts = {})
         )
       end
 
+      # Initiates a payment flow on a Reader and updates the PaymentIntent with card details before manual confirmation.
       def collect_payment_method(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -41,6 +44,7 @@ def collect_payment_method(params = {}, opts = {})
         )
       end
 
+      # Finalizes a payment on a Reader.
       def confirm_payment_intent(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -50,6 +54,7 @@ def confirm_payment_intent(params = {}, opts = {})
         )
       end
 
+      # Initiates a payment flow on a Reader.
       def process_payment_intent(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -59,6 +64,7 @@ def process_payment_intent(params = {}, opts = {})
         )
       end
 
+      # Initiates a setup intent flow on a Reader.
       def process_setup_intent(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -68,6 +74,7 @@ def process_setup_intent(params = {}, opts = {})
         )
       end
 
+      # Initiates a refund on a Reader
       def refund_payment(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -77,6 +84,7 @@ def refund_payment(params = {}, opts = {})
         )
       end
 
+      # Sets reader display to show cart details.
       def set_reader_display(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -86,6 +94,7 @@ def set_reader_display(params = {}, opts = {})
         )
       end
 
+      # Cancels the current reader action.
       def self.cancel_action(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -95,6 +104,7 @@ def self.cancel_action(reader, params = {}, opts = {})
         )
       end
 
+      # Initiates an input collection flow on a Reader.
       def self.collect_inputs(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -104,6 +114,7 @@ def self.collect_inputs(reader, params = {}, opts = {})
         )
       end
 
+      # Initiates a payment flow on a Reader and updates the PaymentIntent with card details before manual confirmation.
       def self.collect_payment_method(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -113,6 +124,7 @@ def self.collect_payment_method(reader, params = {}, opts = {})
         )
       end
 
+      # Finalizes a payment on a Reader.
       def self.confirm_payment_intent(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -122,6 +134,7 @@ def self.confirm_payment_intent(reader, params = {}, opts = {})
         )
       end
 
+      # Initiates a payment flow on a Reader.
       def self.process_payment_intent(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -131,6 +144,7 @@ def self.process_payment_intent(reader, params = {}, opts = {})
         )
       end
 
+      # Initiates a setup intent flow on a Reader.
       def self.process_setup_intent(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -140,6 +154,7 @@ def self.process_setup_intent(reader, params = {}, opts = {})
         )
       end
 
+      # Initiates a refund on a Reader
       def self.refund_payment(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -149,6 +164,7 @@ def self.refund_payment(reader, params = {}, opts = {})
         )
       end
 
+      # Sets reader display to show cart details.
       def self.set_reader_display(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -165,6 +181,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Reader
 
+        # Presents a payment method on a simulated reader. Can be used to simulate accepting a payment, saving a card or refunding a transaction.
         def self.present_payment_method(reader, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -174,6 +191,7 @@ def self.present_payment_method(reader, params = {}, opts = {})
           )
         end
 
+        # Presents a payment method on a simulated reader. Can be used to simulate accepting a payment, saving a card or refunding a transaction.
         def present_payment_method(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/test_helpers/test_clock.rb b/lib/stripe/resources/test_helpers/test_clock.rb
index c2fd34ddb..b81bbbc5f 100644
--- a/lib/stripe/resources/test_helpers/test_clock.rb
+++ b/lib/stripe/resources/test_helpers/test_clock.rb
@@ -13,6 +13,7 @@ class TestClock < APIResource
 
       OBJECT_NAME = "test_helpers.test_clock"
 
+      # Starts advancing a test clock to a specified time in the future. Advancement is done when status changes to Ready.
       def advance(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -22,6 +23,7 @@ def advance(params = {}, opts = {})
         )
       end
 
+      # Starts advancing a test clock to a specified time in the future. Advancement is done when status changes to Ready.
       def self.advance(test_clock, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/topup.rb b/lib/stripe/resources/topup.rb
index d3569bb31..da98f361b 100644
--- a/lib/stripe/resources/topup.rb
+++ b/lib/stripe/resources/topup.rb
@@ -14,6 +14,7 @@ class Topup < APIResource
 
     OBJECT_NAME = "topup"
 
+    # Cancels a top-up. Only pending top-ups can be canceled.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +24,7 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Cancels a top-up. Only pending top-ups can be canceled.
     def self.cancel(topup, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/treasury/financial_account.rb b/lib/stripe/resources/treasury/financial_account.rb
index 24c4b3014..b386e5812 100644
--- a/lib/stripe/resources/treasury/financial_account.rb
+++ b/lib/stripe/resources/treasury/financial_account.rb
@@ -12,6 +12,7 @@ class FinancialAccount < APIResource
 
       OBJECT_NAME = "treasury.financial_account"
 
+      # Retrieves Features information associated with the FinancialAccount.
       def retrieve_features(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -21,6 +22,7 @@ def retrieve_features(params = {}, opts = {})
         )
       end
 
+      # Updates the Features associated with a FinancialAccount.
       def update_features(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -30,6 +32,7 @@ def update_features(params = {}, opts = {})
         )
       end
 
+      # Retrieves Features information associated with the FinancialAccount.
       def self.retrieve_features(financial_account, params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -39,6 +42,7 @@ def self.retrieve_features(financial_account, params = {}, opts = {})
         )
       end
 
+      # Updates the Features associated with a FinancialAccount.
       def self.update_features(financial_account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/treasury/inbound_transfer.rb b/lib/stripe/resources/treasury/inbound_transfer.rb
index 659c74f48..c3627492b 100644
--- a/lib/stripe/resources/treasury/inbound_transfer.rb
+++ b/lib/stripe/resources/treasury/inbound_transfer.rb
@@ -10,6 +10,7 @@ class InboundTransfer < APIResource
 
       OBJECT_NAME = "treasury.inbound_transfer"
 
+      # Cancels an InboundTransfer.
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -19,6 +20,7 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # Cancels an InboundTransfer.
       def self.cancel(inbound_transfer, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -35,6 +37,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = InboundTransfer
 
+        # Transitions a test mode created InboundTransfer to the failed status. The InboundTransfer must already be in the processing state.
         def self.fail(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -44,6 +47,7 @@ def self.fail(id, params = {}, opts = {})
           )
         end
 
+        # Marks the test mode InboundTransfer object as returned and links the InboundTransfer to a ReceivedDebit. The InboundTransfer must already be in the succeeded state.
         def self.return_inbound_transfer(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -53,6 +57,7 @@ def self.return_inbound_transfer(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created InboundTransfer to the succeeded status. The InboundTransfer must already be in the processing state.
         def self.succeed(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -62,6 +67,7 @@ def self.succeed(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created InboundTransfer to the failed status. The InboundTransfer must already be in the processing state.
         def fail(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -71,6 +77,7 @@ def fail(params = {}, opts = {})
           )
         end
 
+        # Marks the test mode InboundTransfer object as returned and links the InboundTransfer to a ReceivedDebit. The InboundTransfer must already be in the succeeded state.
         def return_inbound_transfer(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -80,6 +87,7 @@ def return_inbound_transfer(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created InboundTransfer to the succeeded status. The InboundTransfer must already be in the processing state.
         def succeed(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/treasury/outbound_payment.rb b/lib/stripe/resources/treasury/outbound_payment.rb
index aaa116a53..afdece66a 100644
--- a/lib/stripe/resources/treasury/outbound_payment.rb
+++ b/lib/stripe/resources/treasury/outbound_payment.rb
@@ -12,6 +12,7 @@ class OutboundPayment < APIResource
 
       OBJECT_NAME = "treasury.outbound_payment"
 
+      # Cancel an OutboundPayment.
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -21,6 +22,7 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # Cancel an OutboundPayment.
       def self.cancel(id, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -37,6 +39,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = OutboundPayment
 
+        # Transitions a test mode created OutboundPayment to the failed status. The OutboundPayment must already be in the processing state.
         def self.fail(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -46,6 +49,7 @@ def self.fail(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the posted status. The OutboundPayment must already be in the processing state.
         def self.post(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -55,6 +59,7 @@ def self.post(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the returned status. The OutboundPayment must already be in the processing state.
         def self.return_outbound_payment(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -64,6 +69,7 @@ def self.return_outbound_payment(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the failed status. The OutboundPayment must already be in the processing state.
         def fail(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -73,6 +79,7 @@ def fail(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the posted status. The OutboundPayment must already be in the processing state.
         def post(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -82,6 +89,7 @@ def post(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the returned status. The OutboundPayment must already be in the processing state.
         def return_outbound_payment(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/treasury/outbound_transfer.rb b/lib/stripe/resources/treasury/outbound_transfer.rb
index 728c63e95..149f3cd3b 100644
--- a/lib/stripe/resources/treasury/outbound_transfer.rb
+++ b/lib/stripe/resources/treasury/outbound_transfer.rb
@@ -12,6 +12,7 @@ class OutboundTransfer < APIResource
 
       OBJECT_NAME = "treasury.outbound_transfer"
 
+      # An OutboundTransfer can be canceled if the funds have not yet been paid out.
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -21,6 +22,7 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # An OutboundTransfer can be canceled if the funds have not yet been paid out.
       def self.cancel(outbound_transfer, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -37,6 +39,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = OutboundTransfer
 
+        # Transitions a test mode created OutboundTransfer to the failed status. The OutboundTransfer must already be in the processing state.
         def self.fail(outbound_transfer, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -46,6 +49,7 @@ def self.fail(outbound_transfer, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the posted status. The OutboundTransfer must already be in the processing state.
         def self.post(outbound_transfer, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -55,6 +59,7 @@ def self.post(outbound_transfer, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the returned status. The OutboundTransfer must already be in the processing state.
         def self.return_outbound_transfer(outbound_transfer, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -64,6 +69,7 @@ def self.return_outbound_transfer(outbound_transfer, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the failed status. The OutboundTransfer must already be in the processing state.
         def fail(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -73,6 +79,7 @@ def fail(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the posted status. The OutboundTransfer must already be in the processing state.
         def post(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -82,6 +89,7 @@ def post(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the returned status. The OutboundTransfer must already be in the processing state.
         def return_outbound_transfer(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/treasury/received_credit.rb b/lib/stripe/resources/treasury/received_credit.rb
index 1f39ae301..d92a0027b 100644
--- a/lib/stripe/resources/treasury/received_credit.rb
+++ b/lib/stripe/resources/treasury/received_credit.rb
@@ -16,6 +16,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = ReceivedCredit
 
+        # Use this endpoint to simulate a test mode ReceivedCredit initiated by a third party. In live mode, you can't directly create ReceivedCredits initiated by third parties.
         def self.create(params = {}, opts = {})
           request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/treasury/received_debit.rb b/lib/stripe/resources/treasury/received_debit.rb
index 343301b55..d4ad8e216 100644
--- a/lib/stripe/resources/treasury/received_debit.rb
+++ b/lib/stripe/resources/treasury/received_debit.rb
@@ -16,6 +16,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = ReceivedDebit
 
+        # Use this endpoint to simulate a test mode ReceivedDebit initiated by a third party. In live mode, you can't directly create ReceivedDebits initiated by third parties.
         def self.create(params = {}, opts = {})
           request_stripe_object(
             method: :post,

From 8875698b96f1cca4e597d3dc51675d113d5d222b Mon Sep 17 00:00:00 2001
From: "stripe-openapi[bot]"
 <105521251+stripe-openapi[bot]@users.noreply.github.com>
Date: Thu, 4 Jan 2024 11:40:30 -0800
Subject: [PATCH 2/3] Update generated code for v742 (#1306)

Co-authored-by: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com>
---
 OPENAPI_VERSION                               |   2 +-
 lib/stripe/resources/account.rb               |   8 ++
 lib/stripe/resources/apps/secret.rb           |   2 +
 lib/stripe/resources/charge.rb                |  10 ++
 lib/stripe/resources/checkout/session.rb      |   8 ++
 lib/stripe/resources/climate/order.rb         |   8 ++
 lib/stripe/resources/credit_note.rb           |   4 +
 lib/stripe/resources/customer.rb              |  16 +++
 lib/stripe/resources/dispute.rb               |   6 +
 .../financial_connections/account.rb          |  10 ++
 .../identity/verification_session.rb          |  44 +++++++
 lib/stripe/resources/invoice.rb               |  20 +++
 lib/stripe/resources/issuing/authorization.rb |  17 +++
 lib/stripe/resources/issuing/card.rb          |   8 ++
 lib/stripe/resources/issuing/dispute.rb       |   2 +
 lib/stripe/resources/issuing/transaction.rb   |   4 +
 lib/stripe/resources/payment_intent.rb        | 118 ++++++++++++++++++
 lib/stripe/resources/payment_link.rb          |   2 +
 lib/stripe/resources/payment_method.rb        |  28 +++++
 lib/stripe/resources/payment_method_domain.rb |  12 ++
 lib/stripe/resources/payout.rb                |   8 ++
 lib/stripe/resources/quote.rb                 |  12 ++
 lib/stripe/resources/refund.rb                |   8 ++
 lib/stripe/resources/review.rb                |   2 +
 lib/stripe/resources/setup_intent.rb          |  36 ++++++
 lib/stripe/resources/source.rb                |   2 +
 lib/stripe/resources/subscription.rb          |  14 +++
 lib/stripe/resources/subscription_schedule.rb |   4 +
 lib/stripe/resources/tax/calculation.rb       |   2 +
 lib/stripe/resources/tax/transaction.rb       |   4 +
 lib/stripe/resources/terminal/reader.rb       |  12 ++
 .../resources/test_helpers/test_clock.rb      |   2 +
 lib/stripe/resources/topup.rb                 |   2 +
 .../resources/treasury/financial_account.rb   |   4 +
 .../resources/treasury/inbound_transfer.rb    |   8 ++
 .../resources/treasury/outbound_payment.rb    |   8 ++
 .../resources/treasury/outbound_transfer.rb   |   8 ++
 .../resources/treasury/received_credit.rb     |   1 +
 .../resources/treasury/received_debit.rb      |   1 +
 39 files changed, 466 insertions(+), 1 deletion(-)

diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION
index 409300d1c..da794494d 100644
--- a/OPENAPI_VERSION
+++ b/OPENAPI_VERSION
@@ -1 +1 @@
-v734
\ No newline at end of file
+v742
\ No newline at end of file
diff --git a/lib/stripe/resources/account.rb b/lib/stripe/resources/account.rb
index 135ebd87e..e094df33f 100644
--- a/lib/stripe/resources/account.rb
+++ b/lib/stripe/resources/account.rb
@@ -25,6 +25,7 @@ class Account < APIResource
                                   resource_plural: "capabilities"
     nested_resource_class_methods :person, operations: %i[create retrieve update delete list]
 
+    # Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
     def persons(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -34,6 +35,9 @@ def persons(params = {}, opts = {})
       )
     end
 
+    # With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious.
+    #
+    # Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero.
     def reject(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -43,6 +47,7 @@ def reject(params = {}, opts = {})
       )
     end
 
+    # Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
     def self.persons(account, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -52,6 +57,9 @@ def self.persons(account, params = {}, opts = {})
       )
     end
 
+    # With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious.
+    #
+    # Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero.
     def self.reject(account, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/apps/secret.rb b/lib/stripe/resources/apps/secret.rb
index 28da6388f..345171415 100644
--- a/lib/stripe/resources/apps/secret.rb
+++ b/lib/stripe/resources/apps/secret.rb
@@ -18,6 +18,7 @@ class Secret < APIResource
 
       OBJECT_NAME = "apps.secret"
 
+      # Deletes a secret from the secret store by name and scope.
       def self.delete_where(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -27,6 +28,7 @@ def self.delete_where(params = {}, opts = {})
         )
       end
 
+      # Finds a secret in the secret store by name and scope.
       def self.find(params = {}, opts = {})
         request_stripe_object(
           method: :get,
diff --git a/lib/stripe/resources/charge.rb b/lib/stripe/resources/charge.rb
index c8ca474b9..8a31e357c 100644
--- a/lib/stripe/resources/charge.rb
+++ b/lib/stripe/resources/charge.rb
@@ -14,6 +14,11 @@ class Charge < APIResource
 
     OBJECT_NAME = "charge"
 
+    # Capture the payment of an existing, uncaptured charge that was created with the capture option set to false.
+    #
+    # Uncaptured payments expire a set number of days after they are created ([7 by default](https://stripe.com/docs/charges/placing-a-hold)), after which they are marked as refunded and capture attempts will fail.
+    #
+    # Don't use this method to capture a PaymentIntent-initiated charge. Use [Capture a PaymentIntent](https://stripe.com/docs/api/payment_intents/capture).
     def capture(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +28,11 @@ def capture(params = {}, opts = {})
       )
     end
 
+    # Capture the payment of an existing, uncaptured charge that was created with the capture option set to false.
+    #
+    # Uncaptured payments expire a set number of days after they are created ([7 by default](https://stripe.com/docs/charges/placing-a-hold)), after which they are marked as refunded and capture attempts will fail.
+    #
+    # Don't use this method to capture a PaymentIntent-initiated charge. Use [Capture a PaymentIntent](https://stripe.com/docs/api/payment_intents/capture).
     def self.capture(charge, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/checkout/session.rb b/lib/stripe/resources/checkout/session.rb
index 0d8005447..e911dd38e 100644
--- a/lib/stripe/resources/checkout/session.rb
+++ b/lib/stripe/resources/checkout/session.rb
@@ -23,6 +23,9 @@ class Session < APIResource
 
       OBJECT_NAME = "checkout.session"
 
+      # A Session can be expired when it is in one of these statuses: open
+      #
+      # After it expires, a customer can't complete a Session and customers loading the Session see a message saying the Session is expired.
       def expire(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -32,6 +35,7 @@ def expire(params = {}, opts = {})
         )
       end
 
+      # When retrieving a Checkout Session, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
       def list_line_items(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -41,6 +45,9 @@ def list_line_items(params = {}, opts = {})
         )
       end
 
+      # A Session can be expired when it is in one of these statuses: open
+      #
+      # After it expires, a customer can't complete a Session and customers loading the Session see a message saying the Session is expired.
       def self.expire(session, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -50,6 +57,7 @@ def self.expire(session, params = {}, opts = {})
         )
       end
 
+      # When retrieving a Checkout Session, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
       def self.list_line_items(session, params = {}, opts = {})
         request_stripe_object(
           method: :get,
diff --git a/lib/stripe/resources/climate/order.rb b/lib/stripe/resources/climate/order.rb
index 1e2b850e8..874f1eaf3 100644
--- a/lib/stripe/resources/climate/order.rb
+++ b/lib/stripe/resources/climate/order.rb
@@ -12,6 +12,10 @@ class Order < APIResource
 
       OBJECT_NAME = "climate.order"
 
+      # Cancels a Climate order. You can cancel an order within 30 days of creation. Stripe refunds the
+      # reservation amount_subtotal, but not the amount_fees for user-triggered cancellations. Frontier
+      # might cancel reservations if suppliers fail to deliver. If Frontier cancels the reservation, Stripe
+      # provides 90 days advance notice and refunds the amount_total.
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -21,6 +25,10 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # Cancels a Climate order. You can cancel an order within 30 days of creation. Stripe refunds the
+      # reservation amount_subtotal, but not the amount_fees for user-triggered cancellations. Frontier
+      # might cancel reservations if suppliers fail to deliver. If Frontier cancels the reservation, Stripe
+      # provides 90 days advance notice and refunds the amount_total.
       def self.cancel(order, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/credit_note.rb b/lib/stripe/resources/credit_note.rb
index 6cc81b198..ed4ed6835 100644
--- a/lib/stripe/resources/credit_note.rb
+++ b/lib/stripe/resources/credit_note.rb
@@ -12,6 +12,7 @@ class CreditNote < APIResource
 
     OBJECT_NAME = "credit_note"
 
+    # Marks a credit note as void. Learn more about [voiding credit notes](https://stripe.com/docs/billing/invoices/credit-notes#voiding).
     def void_credit_note(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -21,6 +22,7 @@ def void_credit_note(params = {}, opts = {})
       )
     end
 
+    # When retrieving a credit note preview, you'll get a lines property containing the first handful of those items. This URL you can retrieve the full (paginated) list of line items.
     def self.list_preview_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -30,6 +32,7 @@ def self.list_preview_line_items(params = {}, opts = {})
       )
     end
 
+    # Get a preview of a credit note without creating it.
     def self.preview(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -39,6 +42,7 @@ def self.preview(params = {}, opts = {})
       )
     end
 
+    # Marks a credit note as void. Learn more about [voiding credit notes](https://stripe.com/docs/billing/invoices/credit-notes#voiding).
     def self.void_credit_note(id, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/customer.rb b/lib/stripe/resources/customer.rb
index 7b643fb76..d92221e5d 100644
--- a/lib/stripe/resources/customer.rb
+++ b/lib/stripe/resources/customer.rb
@@ -19,6 +19,9 @@ class Customer < APIResource
     nested_resource_class_methods :cash_balance_transaction, operations: %i[retrieve list]
     nested_resource_class_methods :tax_id, operations: %i[create retrieve delete list]
 
+    # Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new
+    # funding instructions will be created. If funding instructions have already been created for a given customer, the same
+    # funding instructions will be retrieved. In other words, we will return the same funding instructions each time.
     def create_funding_instructions(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -28,6 +31,7 @@ def create_funding_instructions(params = {}, opts = {})
       )
     end
 
+    # Removes the currently applied discount on a customer.
     def delete_discount(params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -37,6 +41,7 @@ def delete_discount(params = {}, opts = {})
       )
     end
 
+    # Returns a list of PaymentMethods for a given Customer
     def list_payment_methods(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -46,6 +51,7 @@ def list_payment_methods(params = {}, opts = {})
       )
     end
 
+    # Retrieves a PaymentMethod object for a given Customer.
     def retrieve_payment_method(payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -55,6 +61,9 @@ def retrieve_payment_method(payment_method, params = {}, opts = {})
       )
     end
 
+    # Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new
+    # funding instructions will be created. If funding instructions have already been created for a given customer, the same
+    # funding instructions will be retrieved. In other words, we will return the same funding instructions each time.
     def self.create_funding_instructions(customer, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -64,6 +73,7 @@ def self.create_funding_instructions(customer, params = {}, opts = {})
       )
     end
 
+    # Removes the currently applied discount on a customer.
     def self.delete_discount(customer, params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -73,6 +83,7 @@ def self.delete_discount(customer, params = {}, opts = {})
       )
     end
 
+    # Returns a list of PaymentMethods for a given Customer
     def self.list_payment_methods(customer, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -82,6 +93,7 @@ def self.list_payment_methods(customer, params = {}, opts = {})
       )
     end
 
+    # Retrieves a PaymentMethod object for a given Customer.
     def self.retrieve_payment_method(customer, payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -109,6 +121,7 @@ def self.search_auto_paging_each(params = {}, opts = {}, &blk)
       search(params, opts).auto_paging_each(&blk)
     end
 
+    # Retrieves a customer's cash balance.
     def self.retrieve_cash_balance(customer, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -118,6 +131,7 @@ def self.retrieve_cash_balance(customer, params = {}, opts = {})
       )
     end
 
+    # Changes the settings on a customer's cash balance.
     def self.update_cash_balance(customer, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -134,6 +148,7 @@ def test_helpers
     class TestHelpers < APIResourceTestHelpers
       RESOURCE_CLASS = Customer
 
+      # Create an incoming testmode bank transfer
       def self.fund_cash_balance(customer, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -143,6 +158,7 @@ def self.fund_cash_balance(customer, params = {}, opts = {})
         )
       end
 
+      # Create an incoming testmode bank transfer
       def fund_cash_balance(params = {}, opts = {})
         @resource.request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/dispute.rb b/lib/stripe/resources/dispute.rb
index 55e687726..b4f7f1c95 100644
--- a/lib/stripe/resources/dispute.rb
+++ b/lib/stripe/resources/dispute.rb
@@ -13,6 +13,9 @@ class Dispute < APIResource
 
     OBJECT_NAME = "dispute"
 
+    # Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially dismissing the dispute, acknowledging it as lost.
+    #
+    # The status of the dispute will change from needs_response to lost. Closing a dispute is irreversible.
     def close(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -22,6 +25,9 @@ def close(params = {}, opts = {})
       )
     end
 
+    # Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially dismissing the dispute, acknowledging it as lost.
+    #
+    # The status of the dispute will change from needs_response to lost. Closing a dispute is irreversible.
     def self.close(dispute, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/financial_connections/account.rb b/lib/stripe/resources/financial_connections/account.rb
index 2186ab849..4039f2beb 100644
--- a/lib/stripe/resources/financial_connections/account.rb
+++ b/lib/stripe/resources/financial_connections/account.rb
@@ -9,6 +9,7 @@ class Account < APIResource
 
       OBJECT_NAME = "financial_connections.account"
 
+      # Disables your access to a Financial Connections Account. You will no longer be able to access data associated with the account (e.g. balances, transactions).
       def disconnect(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -18,6 +19,7 @@ def disconnect(params = {}, opts = {})
         )
       end
 
+      # Lists all owners for a given Account
       def list_owners(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -27,6 +29,7 @@ def list_owners(params = {}, opts = {})
         )
       end
 
+      # Refreshes the data associated with a Financial Connections Account.
       def refresh_account(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -36,6 +39,7 @@ def refresh_account(params = {}, opts = {})
         )
       end
 
+      # Subscribes to periodic refreshes of data associated with a Financial Connections Account.
       def subscribe(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -45,6 +49,7 @@ def subscribe(params = {}, opts = {})
         )
       end
 
+      # Unsubscribes from periodic refreshes of data associated with a Financial Connections Account.
       def unsubscribe(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -54,6 +59,7 @@ def unsubscribe(params = {}, opts = {})
         )
       end
 
+      # Disables your access to a Financial Connections Account. You will no longer be able to access data associated with the account (e.g. balances, transactions).
       def self.disconnect(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -63,6 +69,7 @@ def self.disconnect(account, params = {}, opts = {})
         )
       end
 
+      # Lists all owners for a given Account
       def self.list_owners(account, params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -72,6 +79,7 @@ def self.list_owners(account, params = {}, opts = {})
         )
       end
 
+      # Refreshes the data associated with a Financial Connections Account.
       def self.refresh_account(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -81,6 +89,7 @@ def self.refresh_account(account, params = {}, opts = {})
         )
       end
 
+      # Subscribes to periodic refreshes of data associated with a Financial Connections Account.
       def self.subscribe(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -90,6 +99,7 @@ def self.subscribe(account, params = {}, opts = {})
         )
       end
 
+      # Unsubscribes from periodic refreshes of data associated with a Financial Connections Account.
       def self.unsubscribe(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/identity/verification_session.rb b/lib/stripe/resources/identity/verification_session.rb
index e9fcf9126..9854f11ab 100644
--- a/lib/stripe/resources/identity/verification_session.rb
+++ b/lib/stripe/resources/identity/verification_session.rb
@@ -21,6 +21,9 @@ class VerificationSession < APIResource
 
       OBJECT_NAME = "identity.verification_session"
 
+      # A VerificationSession object can be canceled when it is in requires_input [status](https://stripe.com/docs/identity/how-sessions-work).
+      #
+      # Once canceled, future submission attempts are disabled. This cannot be undone. [Learn more](https://stripe.com/docs/identity/verification-sessions#cancel).
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -30,6 +33,25 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # Redact a VerificationSession to remove all collected information from Stripe. This will redact
+      # the VerificationSession and all objects related to it, including VerificationReports, Events,
+      # request logs, etc.
+      #
+      # A VerificationSession object can be redacted when it is in requires_input or verified
+      # [status](https://stripe.com/docs/identity/how-sessions-work). Redacting a VerificationSession in requires_action
+      # state will automatically cancel it.
+      #
+      # The redaction process may take up to four days. When the redaction process is in progress, the
+      # VerificationSession's redaction.status field will be set to processing; when the process is
+      # finished, it will change to redacted and an identity.verification_session.redacted event
+      # will be emitted.
+      #
+      # Redaction is irreversible. Redacted objects are still accessible in the Stripe API, but all the
+      # fields that contain personal data will be replaced by the string [redacted] or a similar
+      # placeholder. The metadata field will also be erased. Redacted objects cannot be updated or
+      # used for any purpose.
+      #
+      # [Learn more](https://stripe.com/docs/identity/verification-sessions#redact).
       def redact(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -39,6 +61,9 @@ def redact(params = {}, opts = {})
         )
       end
 
+      # A VerificationSession object can be canceled when it is in requires_input [status](https://stripe.com/docs/identity/how-sessions-work).
+      #
+      # Once canceled, future submission attempts are disabled. This cannot be undone. [Learn more](https://stripe.com/docs/identity/verification-sessions#cancel).
       def self.cancel(session, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -48,6 +73,25 @@ def self.cancel(session, params = {}, opts = {})
         )
       end
 
+      # Redact a VerificationSession to remove all collected information from Stripe. This will redact
+      # the VerificationSession and all objects related to it, including VerificationReports, Events,
+      # request logs, etc.
+      #
+      # A VerificationSession object can be redacted when it is in requires_input or verified
+      # [status](https://stripe.com/docs/identity/how-sessions-work). Redacting a VerificationSession in requires_action
+      # state will automatically cancel it.
+      #
+      # The redaction process may take up to four days. When the redaction process is in progress, the
+      # VerificationSession's redaction.status field will be set to processing; when the process is
+      # finished, it will change to redacted and an identity.verification_session.redacted event
+      # will be emitted.
+      #
+      # Redaction is irreversible. Redacted objects are still accessible in the Stripe API, but all the
+      # fields that contain personal data will be replaced by the string [redacted] or a similar
+      # placeholder. The metadata field will also be erased. Redacted objects cannot be updated or
+      # used for any purpose.
+      #
+      # [Learn more](https://stripe.com/docs/identity/verification-sessions#redact).
       def self.redact(session, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/invoice.rb b/lib/stripe/resources/invoice.rb
index eb6484638..965545ee3 100644
--- a/lib/stripe/resources/invoice.rb
+++ b/lib/stripe/resources/invoice.rb
@@ -43,6 +43,7 @@ class Invoice < APIResource
 
     OBJECT_NAME = "invoice"
 
+    # Stripe automatically finalizes drafts before sending and attempting payment on invoices. However, if you'd like to finalize a draft invoice manually, you can do so using this method.
     def finalize_invoice(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -52,6 +53,7 @@ def finalize_invoice(params = {}, opts = {})
       )
     end
 
+    # Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.
     def mark_uncollectible(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -61,6 +63,7 @@ def mark_uncollectible(params = {}, opts = {})
       )
     end
 
+    # Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions according to your [subscriptions settings](https://dashboard.stripe.com/account/billing/automatic). However, if you'd like to attempt payment on an invoice out of the normal collection schedule or for some other reason, you can do so.
     def pay(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -70,6 +73,9 @@ def pay(params = {}, opts = {})
       )
     end
 
+    # Stripe will automatically send invoices to customers according to your [subscriptions settings](https://dashboard.stripe.com/account/billing/automatic). However, if you'd like to manually send an invoice to your customer out of the normal schedule, you can do so. When sending invoices that have already been paid, there will be no reference to the payment in the email.
+    #
+    # Requests made in test-mode result in no emails being sent, despite sending an invoice.sent event.
     def send_invoice(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -79,6 +85,7 @@ def send_invoice(params = {}, opts = {})
       )
     end
 
+    # Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to [deletion](https://stripe.com/docs/api#delete_invoice), however it only applies to finalized invoices and maintains a papertrail where the invoice can still be found.
     def void_invoice(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -88,6 +95,7 @@ def void_invoice(params = {}, opts = {})
       )
     end
 
+    # Stripe automatically finalizes drafts before sending and attempting payment on invoices. However, if you'd like to finalize a draft invoice manually, you can do so using this method.
     def self.finalize_invoice(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -97,6 +105,7 @@ def self.finalize_invoice(invoice, params = {}, opts = {})
       )
     end
 
+    # When retrieving an upcoming invoice, you'll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_upcoming_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -106,6 +115,7 @@ def self.list_upcoming_line_items(params = {}, opts = {})
       )
     end
 
+    # Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.
     def self.mark_uncollectible(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -115,6 +125,7 @@ def self.mark_uncollectible(invoice, params = {}, opts = {})
       )
     end
 
+    # Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions according to your [subscriptions settings](https://dashboard.stripe.com/account/billing/automatic). However, if you'd like to attempt payment on an invoice out of the normal collection schedule or for some other reason, you can do so.
     def self.pay(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -124,6 +135,9 @@ def self.pay(invoice, params = {}, opts = {})
       )
     end
 
+    # Stripe will automatically send invoices to customers according to your [subscriptions settings](https://dashboard.stripe.com/account/billing/automatic). However, if you'd like to manually send an invoice to your customer out of the normal schedule, you can do so. When sending invoices that have already been paid, there will be no reference to the payment in the email.
+    #
+    # Requests made in test-mode result in no emails being sent, despite sending an invoice.sent event.
     def self.send_invoice(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -133,10 +147,16 @@ def self.send_invoice(invoice, params = {}, opts = {})
       )
     end
 
+    # At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice.
+    #
+    # Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer's discount.
+    #
+    # You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass a proration_date parameter when doing the actual subscription update. The value passed in should be the same as the subscription_proration_date returned on the upcoming invoice resource. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_proration_date on the upcoming invoice resource.
     def self.upcoming(params = {}, opts = {})
       request_stripe_object(method: :get, path: "/v1/invoices/upcoming", params: params, opts: opts)
     end
 
+    # Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to [deletion](https://stripe.com/docs/api#delete_invoice), however it only applies to finalized invoices and maintains a papertrail where the invoice can still be found.
     def self.void_invoice(invoice, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/issuing/authorization.rb b/lib/stripe/resources/issuing/authorization.rb
index fa250792b..7dee5772b 100644
--- a/lib/stripe/resources/issuing/authorization.rb
+++ b/lib/stripe/resources/issuing/authorization.rb
@@ -14,6 +14,8 @@ class Authorization < APIResource
 
       OBJECT_NAME = "issuing.authorization"
 
+      # [Deprecated] Approves a pending Issuing Authorization object. This request should be made within the timeout window of the [real-time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to approve an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def approve(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -23,6 +25,8 @@ def approve(params = {}, opts = {})
         )
       end
 
+      # [Deprecated] Declines a pending Issuing Authorization object. This request should be made within the timeout window of the [real time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to decline an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def decline(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -32,6 +36,8 @@ def decline(params = {}, opts = {})
         )
       end
 
+      # [Deprecated] Approves a pending Issuing Authorization object. This request should be made within the timeout window of the [real-time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to approve an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def self.approve(authorization, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -41,6 +47,8 @@ def self.approve(authorization, params = {}, opts = {})
         )
       end
 
+      # [Deprecated] Declines a pending Issuing Authorization object. This request should be made within the timeout window of the [real time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to decline an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def self.decline(authorization, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -57,6 +65,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Authorization
 
+        # Capture a test-mode authorization.
         def self.capture(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -66,6 +75,7 @@ def self.capture(authorization, params = {}, opts = {})
           )
         end
 
+        # Create a test-mode authorization.
         def self.create(params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -75,6 +85,7 @@ def self.create(params = {}, opts = {})
           )
         end
 
+        # Expire a test-mode Authorization.
         def self.expire(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -84,6 +95,7 @@ def self.expire(authorization, params = {}, opts = {})
           )
         end
 
+        # Increment a test-mode Authorization.
         def self.increment(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -93,6 +105,7 @@ def self.increment(authorization, params = {}, opts = {})
           )
         end
 
+        # Reverse a test-mode Authorization.
         def self.reverse(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -102,6 +115,7 @@ def self.reverse(authorization, params = {}, opts = {})
           )
         end
 
+        # Capture a test-mode authorization.
         def capture(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -111,6 +125,7 @@ def capture(params = {}, opts = {})
           )
         end
 
+        # Expire a test-mode Authorization.
         def expire(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -120,6 +135,7 @@ def expire(params = {}, opts = {})
           )
         end
 
+        # Increment a test-mode Authorization.
         def increment(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -129,6 +145,7 @@ def increment(params = {}, opts = {})
           )
         end
 
+        # Reverse a test-mode Authorization.
         def reverse(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/issuing/card.rb b/lib/stripe/resources/issuing/card.rb
index 88764b666..1775b6497 100644
--- a/lib/stripe/resources/issuing/card.rb
+++ b/lib/stripe/resources/issuing/card.rb
@@ -18,6 +18,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Card
 
+        # Updates the shipping status of the specified Issuing Card object to delivered.
         def self.deliver_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -27,6 +28,7 @@ def self.deliver_card(card, params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to failure.
         def self.fail_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -36,6 +38,7 @@ def self.fail_card(card, params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to returned.
         def self.return_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -45,6 +48,7 @@ def self.return_card(card, params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to shipped.
         def self.ship_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -54,6 +58,7 @@ def self.ship_card(card, params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to delivered.
         def deliver_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -63,6 +68,7 @@ def deliver_card(params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to failure.
         def fail_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -72,6 +78,7 @@ def fail_card(params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to returned.
         def return_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -81,6 +88,7 @@ def return_card(params = {}, opts = {})
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to shipped.
         def ship_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/issuing/dispute.rb b/lib/stripe/resources/issuing/dispute.rb
index 3b1e880d7..057aa57a0 100644
--- a/lib/stripe/resources/issuing/dispute.rb
+++ b/lib/stripe/resources/issuing/dispute.rb
@@ -13,6 +13,7 @@ class Dispute < APIResource
 
       OBJECT_NAME = "issuing.dispute"
 
+      # Submits an Issuing Dispute to the card network. Stripe validates that all evidence fields required for the dispute's reason are present. For more details, see [Dispute reasons and evidence](https://stripe.com/docs/issuing/purchases/disputes#dispute-reasons-and-evidence).
       def submit(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -22,6 +23,7 @@ def submit(params = {}, opts = {})
         )
       end
 
+      # Submits an Issuing Dispute to the card network. Stripe validates that all evidence fields required for the dispute's reason are present. For more details, see [Dispute reasons and evidence](https://stripe.com/docs/issuing/purchases/disputes#dispute-reasons-and-evidence).
       def self.submit(dispute, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/issuing/transaction.rb b/lib/stripe/resources/issuing/transaction.rb
index 9fc7e6a4f..a3bc14a8b 100644
--- a/lib/stripe/resources/issuing/transaction.rb
+++ b/lib/stripe/resources/issuing/transaction.rb
@@ -21,6 +21,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Transaction
 
+        # Allows the user to capture an arbitrary amount, also known as a forced capture.
         def self.create_force_capture(params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -30,6 +31,7 @@ def self.create_force_capture(params = {}, opts = {})
           )
         end
 
+        # Allows the user to refund an arbitrary amount, also known as a unlinked refund.
         def self.create_unlinked_refund(params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -39,6 +41,7 @@ def self.create_unlinked_refund(params = {}, opts = {})
           )
         end
 
+        # Refund a test-mode Transaction.
         def self.refund(transaction, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -48,6 +51,7 @@ def self.refund(transaction, params = {}, opts = {})
           )
         end
 
+        # Refund a test-mode Transaction.
         def refund(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/payment_intent.rb b/lib/stripe/resources/payment_intent.rb
index 723098e01..3dd1a25f0 100644
--- a/lib/stripe/resources/payment_intent.rb
+++ b/lib/stripe/resources/payment_intent.rb
@@ -21,6 +21,7 @@ class PaymentIntent < APIResource
 
     OBJECT_NAME = "payment_intent"
 
+    # Manually reconcile the remaining amount for a customer_balance PaymentIntent.
     def apply_customer_balance(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -30,6 +31,11 @@ def apply_customer_balance(params = {}, opts = {})
       )
     end
 
+    # You can cancel a PaymentIntent object when it's in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_action or, [in rare cases](https://stripe.com/docs/payments/intents), processing.
+    #
+    # After it's canceled, no additional charges are made by the PaymentIntent and any operations on the PaymentIntent fail with an error. For PaymentIntents with a status of requires_capture, the remaining amount_capturable is automatically refunded.
+    #
+    # You can't cancel the PaymentIntent for a Checkout Session. [Expire the Checkout Session](https://stripe.com/docs/api/checkout/sessions/expire) instead.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -39,6 +45,11 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Capture the funds of an existing uncaptured PaymentIntent when its status is requires_capture.
+    #
+    # Uncaptured PaymentIntents are cancelled a set number of days (7 by default) after their creation.
+    #
+    # Learn more about [separate authorization and capture](https://stripe.com/docs/payments/capture-later).
     def capture(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -48,6 +59,29 @@ def capture(params = {}, opts = {})
       )
     end
 
+    # Confirm that your customer intends to pay with current or provided
+    # payment method. Upon confirmation, the PaymentIntent will attempt to initiate
+    # a payment.
+    # If the selected payment method requires additional authentication steps, the
+    # PaymentIntent will transition to the requires_action status and
+    # suggest additional actions via next_action. If payment fails,
+    # the PaymentIntent transitions to the requires_payment_method status or the
+    # canceled status if the confirmation limit is reached. If
+    # payment succeeds, the PaymentIntent will transition to the succeeded
+    # status (or requires_capture, if capture_method is set to manual).
+    # If the confirmation_method is automatic, payment may be attempted
+    # using our [client SDKs](https://stripe.com/docs/stripe-js/reference#stripe-handle-card-payment)
+    # and the PaymentIntent's [client_secret](https://stripe.com/docs/api#payment_intent_object-client_secret).
+    # After next_actions are handled by the client, no additional
+    # confirmation is required to complete the payment.
+    # If the confirmation_method is manual, all payment attempts must be
+    # initiated using a secret key.
+    # If any actions are required for the payment, the PaymentIntent will
+    # return to the requires_confirmation state
+    # after those actions are completed. Your server needs to then
+    # explicitly re-confirm the PaymentIntent to initiate the next payment
+    # attempt. Read the [expanded documentation](https://stripe.com/docs/payments/payment-intents/web-manual)
+    # to learn more about manual confirmation.
     def confirm(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -57,6 +91,30 @@ def confirm(params = {}, opts = {})
       )
     end
 
+    # Perform an incremental authorization on an eligible
+    # [PaymentIntent](https://stripe.com/docs/api/payment_intents/object). To be eligible, the
+    # PaymentIntent's status must be requires_capture and
+    # [incremental_authorization_supported](https://stripe.com/docs/api/charges/object#charge_object-payment_method_details-card_present-incremental_authorization_supported)
+    # must be true.
+    #
+    # Incremental authorizations attempt to increase the authorized amount on
+    # your customer's card to the new, higher amount provided. Similar to the
+    # initial authorization, incremental authorizations can be declined. A
+    # single PaymentIntent can call this endpoint multiple times to further
+    # increase the authorized amount.
+    #
+    # If the incremental authorization succeeds, the PaymentIntent object
+    # returns with the updated
+    # [amount](https://stripe.com/docs/api/payment_intents/object#payment_intent_object-amount).
+    # If the incremental authorization fails, a
+    # [card_declined](https://stripe.com/docs/error-codes#card-declined) error returns, and no other
+    # fields on the PaymentIntent or Charge update. The PaymentIntent
+    # object remains capturable for the previously authorized amount.
+    #
+    # Each PaymentIntent can have a maximum of 10 incremental authorization attempts, including declines.
+    # After it's captured, a PaymentIntent can no longer be incremented.
+    #
+    # Learn more about [incremental authorizations](https://stripe.com/docs/terminal/features/incremental-authorizations).
     def increment_authorization(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -66,6 +124,7 @@ def increment_authorization(params = {}, opts = {})
       )
     end
 
+    # Verifies microdeposits on a PaymentIntent object.
     def verify_microdeposits(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -75,6 +134,7 @@ def verify_microdeposits(params = {}, opts = {})
       )
     end
 
+    # Manually reconcile the remaining amount for a customer_balance PaymentIntent.
     def self.apply_customer_balance(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -84,6 +144,11 @@ def self.apply_customer_balance(intent, params = {}, opts = {})
       )
     end
 
+    # You can cancel a PaymentIntent object when it's in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_action or, [in rare cases](https://stripe.com/docs/payments/intents), processing.
+    #
+    # After it's canceled, no additional charges are made by the PaymentIntent and any operations on the PaymentIntent fail with an error. For PaymentIntents with a status of requires_capture, the remaining amount_capturable is automatically refunded.
+    #
+    # You can't cancel the PaymentIntent for a Checkout Session. [Expire the Checkout Session](https://stripe.com/docs/api/checkout/sessions/expire) instead.
     def self.cancel(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -93,6 +158,11 @@ def self.cancel(intent, params = {}, opts = {})
       )
     end
 
+    # Capture the funds of an existing uncaptured PaymentIntent when its status is requires_capture.
+    #
+    # Uncaptured PaymentIntents are cancelled a set number of days (7 by default) after their creation.
+    #
+    # Learn more about [separate authorization and capture](https://stripe.com/docs/payments/capture-later).
     def self.capture(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -102,6 +172,29 @@ def self.capture(intent, params = {}, opts = {})
       )
     end
 
+    # Confirm that your customer intends to pay with current or provided
+    # payment method. Upon confirmation, the PaymentIntent will attempt to initiate
+    # a payment.
+    # If the selected payment method requires additional authentication steps, the
+    # PaymentIntent will transition to the requires_action status and
+    # suggest additional actions via next_action. If payment fails,
+    # the PaymentIntent transitions to the requires_payment_method status or the
+    # canceled status if the confirmation limit is reached. If
+    # payment succeeds, the PaymentIntent will transition to the succeeded
+    # status (or requires_capture, if capture_method is set to manual).
+    # If the confirmation_method is automatic, payment may be attempted
+    # using our [client SDKs](https://stripe.com/docs/stripe-js/reference#stripe-handle-card-payment)
+    # and the PaymentIntent's [client_secret](https://stripe.com/docs/api#payment_intent_object-client_secret).
+    # After next_actions are handled by the client, no additional
+    # confirmation is required to complete the payment.
+    # If the confirmation_method is manual, all payment attempts must be
+    # initiated using a secret key.
+    # If any actions are required for the payment, the PaymentIntent will
+    # return to the requires_confirmation state
+    # after those actions are completed. Your server needs to then
+    # explicitly re-confirm the PaymentIntent to initiate the next payment
+    # attempt. Read the [expanded documentation](https://stripe.com/docs/payments/payment-intents/web-manual)
+    # to learn more about manual confirmation.
     def self.confirm(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -111,6 +204,30 @@ def self.confirm(intent, params = {}, opts = {})
       )
     end
 
+    # Perform an incremental authorization on an eligible
+    # [PaymentIntent](https://stripe.com/docs/api/payment_intents/object). To be eligible, the
+    # PaymentIntent's status must be requires_capture and
+    # [incremental_authorization_supported](https://stripe.com/docs/api/charges/object#charge_object-payment_method_details-card_present-incremental_authorization_supported)
+    # must be true.
+    #
+    # Incremental authorizations attempt to increase the authorized amount on
+    # your customer's card to the new, higher amount provided. Similar to the
+    # initial authorization, incremental authorizations can be declined. A
+    # single PaymentIntent can call this endpoint multiple times to further
+    # increase the authorized amount.
+    #
+    # If the incremental authorization succeeds, the PaymentIntent object
+    # returns with the updated
+    # [amount](https://stripe.com/docs/api/payment_intents/object#payment_intent_object-amount).
+    # If the incremental authorization fails, a
+    # [card_declined](https://stripe.com/docs/error-codes#card-declined) error returns, and no other
+    # fields on the PaymentIntent or Charge update. The PaymentIntent
+    # object remains capturable for the previously authorized amount.
+    #
+    # Each PaymentIntent can have a maximum of 10 incremental authorization attempts, including declines.
+    # After it's captured, a PaymentIntent can no longer be incremented.
+    #
+    # Learn more about [incremental authorizations](https://stripe.com/docs/terminal/features/incremental-authorizations).
     def self.increment_authorization(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -120,6 +237,7 @@ def self.increment_authorization(intent, params = {}, opts = {})
       )
     end
 
+    # Verifies microdeposits on a PaymentIntent object.
     def self.verify_microdeposits(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/payment_link.rb b/lib/stripe/resources/payment_link.rb
index c4a4b77fb..fd41aa18c 100644
--- a/lib/stripe/resources/payment_link.rb
+++ b/lib/stripe/resources/payment_link.rb
@@ -14,6 +14,7 @@ class PaymentLink < APIResource
 
     OBJECT_NAME = "payment_link"
 
+    # When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def list_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -23,6 +24,7 @@ def list_line_items(params = {}, opts = {})
       )
     end
 
+    # When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_line_items(payment_link, params = {}, opts = {})
       request_stripe_object(
         method: :get,
diff --git a/lib/stripe/resources/payment_method.rb b/lib/stripe/resources/payment_method.rb
index 31798a955..9a280132b 100644
--- a/lib/stripe/resources/payment_method.rb
+++ b/lib/stripe/resources/payment_method.rb
@@ -14,6 +14,19 @@ class PaymentMethod < APIResource
 
     OBJECT_NAME = "payment_method"
 
+    # Attaches a PaymentMethod object to a Customer.
+    #
+    # To attach a new PaymentMethod to a customer for future payments, we recommend you use a [SetupIntent](https://stripe.com/docs/api/setup_intents)
+    # or a PaymentIntent with [setup_future_usage](https://stripe.com/docs/api/payment_intents/create#create_payment_intent-setup_future_usage).
+    # These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the /v1/payment_methods/:id/attach
+    # endpoint without first using a SetupIntent or PaymentIntent with setup_future_usage does not optimize the PaymentMethod for
+    # future use, which makes later declines and payment friction more likely.
+    # See [Optimizing cards for future payments](https://stripe.com/docs/payments/payment-intents#future-usage) for more information about setting up
+    # future payments.
+    #
+    # To use this PaymentMethod as the default for invoice or subscription payments,
+    # set [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method),
+    # on the Customer to the PaymentMethod's ID.
     def attach(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +36,7 @@ def attach(params = {}, opts = {})
       )
     end
 
+    # Detaches a PaymentMethod object from a Customer. After a PaymentMethod is detached, it can no longer be used for a payment or re-attached to a Customer.
     def detach(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -32,6 +46,19 @@ def detach(params = {}, opts = {})
       )
     end
 
+    # Attaches a PaymentMethod object to a Customer.
+    #
+    # To attach a new PaymentMethod to a customer for future payments, we recommend you use a [SetupIntent](https://stripe.com/docs/api/setup_intents)
+    # or a PaymentIntent with [setup_future_usage](https://stripe.com/docs/api/payment_intents/create#create_payment_intent-setup_future_usage).
+    # These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the /v1/payment_methods/:id/attach
+    # endpoint without first using a SetupIntent or PaymentIntent with setup_future_usage does not optimize the PaymentMethod for
+    # future use, which makes later declines and payment friction more likely.
+    # See [Optimizing cards for future payments](https://stripe.com/docs/payments/payment-intents#future-usage) for more information about setting up
+    # future payments.
+    #
+    # To use this PaymentMethod as the default for invoice or subscription payments,
+    # set [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method),
+    # on the Customer to the PaymentMethod's ID.
     def self.attach(payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -41,6 +68,7 @@ def self.attach(payment_method, params = {}, opts = {})
       )
     end
 
+    # Detaches a PaymentMethod object from a Customer. After a PaymentMethod is detached, it can no longer be used for a payment or re-attached to a Customer.
     def self.detach(payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/payment_method_domain.rb b/lib/stripe/resources/payment_method_domain.rb
index 184784336..49cfe03ce 100644
--- a/lib/stripe/resources/payment_method_domain.rb
+++ b/lib/stripe/resources/payment_method_domain.rb
@@ -13,6 +13,12 @@ class PaymentMethodDomain < APIResource
 
     OBJECT_NAME = "payment_method_domain"
 
+    # Some payment methods such as Apple Pay require additional steps to verify a domain. If the requirements weren't satisfied when the domain was created, the payment method will be inactive on the domain.
+    # The payment method doesn't appear in Elements for this domain until it is active.
+    #
+    # To activate a payment method on an existing payment method domain, complete the required validation steps specific to the payment method, and then validate the payment method domain with this endpoint.
+    #
+    # Related guides: [Payment method domains](https://stripe.com/docs/payments/payment-methods/pmd-registration).
     def validate(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -22,6 +28,12 @@ def validate(params = {}, opts = {})
       )
     end
 
+    # Some payment methods such as Apple Pay require additional steps to verify a domain. If the requirements weren't satisfied when the domain was created, the payment method will be inactive on the domain.
+    # The payment method doesn't appear in Elements for this domain until it is active.
+    #
+    # To activate a payment method on an existing payment method domain, complete the required validation steps specific to the payment method, and then validate the payment method domain with this endpoint.
+    #
+    # Related guides: [Payment method domains](https://stripe.com/docs/payments/payment-methods/pmd-registration).
     def self.validate(payment_method_domain, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/payout.rb b/lib/stripe/resources/payout.rb
index cccba9eb4..e50de02e4 100644
--- a/lib/stripe/resources/payout.rb
+++ b/lib/stripe/resources/payout.rb
@@ -17,6 +17,7 @@ class Payout < APIResource
 
     OBJECT_NAME = "payout"
 
+    # You can cancel a previously created payout if it hasn't been paid out yet. Stripe refunds the funds to your available balance. You can't cancel automatic Stripe payouts.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -26,6 +27,9 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Reverses a payout by debiting the destination bank account. At this time, you can only reverse payouts for connected accounts to US bank accounts. If the payout is in the pending status, use /v1/payouts/:id/cancel instead.
+    #
+    # By requesting a reversal through /v1/payouts/:id/reverse, you confirm that the authorized signatory of the selected bank account authorizes the debit on the bank account and that no other authorization is required.
     def reverse(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -35,6 +39,7 @@ def reverse(params = {}, opts = {})
       )
     end
 
+    # You can cancel a previously created payout if it hasn't been paid out yet. Stripe refunds the funds to your available balance. You can't cancel automatic Stripe payouts.
     def self.cancel(payout, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -44,6 +49,9 @@ def self.cancel(payout, params = {}, opts = {})
       )
     end
 
+    # Reverses a payout by debiting the destination bank account. At this time, you can only reverse payouts for connected accounts to US bank accounts. If the payout is in the pending status, use /v1/payouts/:id/cancel instead.
+    #
+    # By requesting a reversal through /v1/payouts/:id/reverse, you confirm that the authorized signatory of the selected bank account authorizes the debit on the bank account and that no other authorization is required.
     def self.reverse(payout, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/quote.rb b/lib/stripe/resources/quote.rb
index 93fd0b652..b68c89568 100644
--- a/lib/stripe/resources/quote.rb
+++ b/lib/stripe/resources/quote.rb
@@ -11,6 +11,7 @@ class Quote < APIResource
 
     OBJECT_NAME = "quote"
 
+    # Accepts the specified quote.
     def accept(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -20,6 +21,7 @@ def accept(params = {}, opts = {})
       )
     end
 
+    # Cancels the quote.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -29,6 +31,7 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Finalizes the quote.
     def finalize_quote(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -38,6 +41,7 @@ def finalize_quote(params = {}, opts = {})
       )
     end
 
+    # When retrieving a quote, there is an includable [computed.upfront.line_items](https://stripe.com/docs/api/quotes/object#quote_object-computed-upfront-line_items) property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of upfront line items.
     def list_computed_upfront_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -47,6 +51,7 @@ def list_computed_upfront_line_items(params = {}, opts = {})
       )
     end
 
+    # When retrieving a quote, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def list_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -56,6 +61,7 @@ def list_line_items(params = {}, opts = {})
       )
     end
 
+    # Download the PDF for a finalized quote
     def pdf(params = {}, opts = {}, &read_body_chunk_block)
       config = opts[:client]&.config || Stripe.config
       opts = { api_base: config.uploads_base }.merge(opts)
@@ -68,6 +74,7 @@ def pdf(params = {}, opts = {}, &read_body_chunk_block)
       )
     end
 
+    # Accepts the specified quote.
     def self.accept(quote, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -77,6 +84,7 @@ def self.accept(quote, params = {}, opts = {})
       )
     end
 
+    # Cancels the quote.
     def self.cancel(quote, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -86,6 +94,7 @@ def self.cancel(quote, params = {}, opts = {})
       )
     end
 
+    # Finalizes the quote.
     def self.finalize_quote(quote, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -95,6 +104,7 @@ def self.finalize_quote(quote, params = {}, opts = {})
       )
     end
 
+    # When retrieving a quote, there is an includable [computed.upfront.line_items](https://stripe.com/docs/api/quotes/object#quote_object-computed-upfront-line_items) property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of upfront line items.
     def self.list_computed_upfront_line_items(quote, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -104,6 +114,7 @@ def self.list_computed_upfront_line_items(quote, params = {}, opts = {})
       )
     end
 
+    # When retrieving a quote, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_line_items(quote, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -113,6 +124,7 @@ def self.list_line_items(quote, params = {}, opts = {})
       )
     end
 
+    # Download the PDF for a finalized quote
     def self.pdf(quote, params = {}, opts = {}, &read_body_chunk_block)
       config = opts[:client]&.config || Stripe.config
       opts = { api_base: config.uploads_base }.merge(opts)
diff --git a/lib/stripe/resources/refund.rb b/lib/stripe/resources/refund.rb
index 2bd7cf574..6d88999bb 100644
--- a/lib/stripe/resources/refund.rb
+++ b/lib/stripe/resources/refund.rb
@@ -14,6 +14,9 @@ class Refund < APIResource
 
     OBJECT_NAME = "refund"
 
+    # Cancels a refund with a status of requires_action.
+    #
+    # You can't cancel refunds in other states. Only refunds for payment methods that require customer action can enter the requires_action state.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +26,9 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Cancels a refund with a status of requires_action.
+    #
+    # You can't cancel refunds in other states. Only refunds for payment methods that require customer action can enter the requires_action state.
     def self.cancel(refund, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -39,6 +45,7 @@ def test_helpers
     class TestHelpers < APIResourceTestHelpers
       RESOURCE_CLASS = Refund
 
+      # Expire a refund with a status of requires_action.
       def self.expire(refund, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -48,6 +55,7 @@ def self.expire(refund, params = {}, opts = {})
         )
       end
 
+      # Expire a refund with a status of requires_action.
       def expire(params = {}, opts = {})
         @resource.request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/review.rb b/lib/stripe/resources/review.rb
index e3c55be0b..1650c3db7 100644
--- a/lib/stripe/resources/review.rb
+++ b/lib/stripe/resources/review.rb
@@ -11,6 +11,7 @@ class Review < APIResource
 
     OBJECT_NAME = "review"
 
+    # Approves a Review object, closing it and removing it from the list of reviews.
     def approve(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -20,6 +21,7 @@ def approve(params = {}, opts = {})
       )
     end
 
+    # Approves a Review object, closing it and removing it from the list of reviews.
     def self.approve(review, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/setup_intent.rb b/lib/stripe/resources/setup_intent.rb
index f494b8601..b7ac8cf82 100644
--- a/lib/stripe/resources/setup_intent.rb
+++ b/lib/stripe/resources/setup_intent.rb
@@ -30,6 +30,9 @@ class SetupIntent < APIResource
 
     OBJECT_NAME = "setup_intent"
 
+    # You can cancel a SetupIntent object when it's in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.
+    #
+    # After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -39,6 +42,20 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Confirm that your customer intends to set up the current or
+    # provided payment method. For example, you would confirm a SetupIntent
+    # when a customer hits the “Save” button on a payment method management
+    # page on your website.
+    #
+    # If the selected payment method does not require any additional
+    # steps from the customer, the SetupIntent will transition to the
+    # succeeded status.
+    #
+    # Otherwise, it will transition to the requires_action status and
+    # suggest additional actions via next_action. If setup fails,
+    # the SetupIntent will transition to the
+    # requires_payment_method status or the canceled status if the
+    # confirmation limit is reached.
     def confirm(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -48,6 +65,7 @@ def confirm(params = {}, opts = {})
       )
     end
 
+    # Verifies microdeposits on a SetupIntent object.
     def verify_microdeposits(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -57,6 +75,9 @@ def verify_microdeposits(params = {}, opts = {})
       )
     end
 
+    # You can cancel a SetupIntent object when it's in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.
+    #
+    # After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error.
     def self.cancel(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -66,6 +87,20 @@ def self.cancel(intent, params = {}, opts = {})
       )
     end
 
+    # Confirm that your customer intends to set up the current or
+    # provided payment method. For example, you would confirm a SetupIntent
+    # when a customer hits the “Save” button on a payment method management
+    # page on your website.
+    #
+    # If the selected payment method does not require any additional
+    # steps from the customer, the SetupIntent will transition to the
+    # succeeded status.
+    #
+    # Otherwise, it will transition to the requires_action status and
+    # suggest additional actions via next_action. If setup fails,
+    # the SetupIntent will transition to the
+    # requires_payment_method status or the canceled status if the
+    # confirmation limit is reached.
     def self.confirm(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -75,6 +110,7 @@ def self.confirm(intent, params = {}, opts = {})
       )
     end
 
+    # Verifies microdeposits on a SetupIntent object.
     def self.verify_microdeposits(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/source.rb b/lib/stripe/resources/source.rb
index 425b3a229..05701d501 100644
--- a/lib/stripe/resources/source.rb
+++ b/lib/stripe/resources/source.rb
@@ -21,6 +21,7 @@ class Source < APIResource
 
     nested_resource_class_methods :source_transaction, operations: %i[retrieve list]
 
+    # Verify a given source.
     def verify(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -30,6 +31,7 @@ def verify(params = {}, opts = {})
       )
     end
 
+    # Verify a given source.
     def self.verify(source, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/subscription.rb b/lib/stripe/resources/subscription.rb
index 3f56e2483..487e599e9 100644
--- a/lib/stripe/resources/subscription.rb
+++ b/lib/stripe/resources/subscription.rb
@@ -13,6 +13,11 @@ class Subscription < APIResource
 
     OBJECT_NAME = "subscription"
 
+    # Cancels a customer's subscription immediately. The customer will not be charged again for the subscription.
+    #
+    # Note, however, that any pending invoice items that you've created will still be charged for at the end of the period, unless manually [deleted](https://stripe.com/docs/api#delete_invoiceitem). If you've set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed.
+    #
+    # By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -22,6 +27,7 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Removes the currently applied discount on a subscription.
     def delete_discount(params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -31,6 +37,7 @@ def delete_discount(params = {}, opts = {})
       )
     end
 
+    # Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. If a resumption invoice is generated, it must be paid or marked uncollectible before the subscription will be unpaused. If payment succeeds the subscription will become active, and if payment fails the subscription will be past_due. The resumption invoice will void automatically if not paid by the expiration date.
     def resume(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -40,6 +47,11 @@ def resume(params = {}, opts = {})
       )
     end
 
+    # Cancels a customer's subscription immediately. The customer will not be charged again for the subscription.
+    #
+    # Note, however, that any pending invoice items that you've created will still be charged for at the end of the period, unless manually [deleted](https://stripe.com/docs/api#delete_invoiceitem). If you've set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed.
+    #
+    # By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.
     def self.cancel(subscription_exposed_id, params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -49,6 +61,7 @@ def self.cancel(subscription_exposed_id, params = {}, opts = {})
       )
     end
 
+    # Removes the currently applied discount on a subscription.
     def self.delete_discount(subscription_exposed_id, params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -58,6 +71,7 @@ def self.delete_discount(subscription_exposed_id, params = {}, opts = {})
       )
     end
 
+    # Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. If a resumption invoice is generated, it must be paid or marked uncollectible before the subscription will be unpaused. If payment succeeds the subscription will become active, and if payment fails the subscription will be past_due. The resumption invoice will void automatically if not paid by the expiration date.
     def self.resume(subscription, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/subscription_schedule.rb b/lib/stripe/resources/subscription_schedule.rb
index 577a7ffc5..4ddd0beea 100644
--- a/lib/stripe/resources/subscription_schedule.rb
+++ b/lib/stripe/resources/subscription_schedule.rb
@@ -12,6 +12,7 @@ class SubscriptionSchedule < APIResource
 
     OBJECT_NAME = "subscription_schedule"
 
+    # Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_started or active.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -21,6 +22,7 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Releases the subscription schedule immediately, which will stop scheduling of its phases, but leave any existing subscription in place. A schedule can only be released if its status is not_started or active. If the subscription schedule is currently associated with a subscription, releasing it will remove its subscription property and set the subscription's ID to the released_subscription property.
     def release(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -30,6 +32,7 @@ def release(params = {}, opts = {})
       )
     end
 
+    # Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_started or active.
     def self.cancel(schedule, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -39,6 +42,7 @@ def self.cancel(schedule, params = {}, opts = {})
       )
     end
 
+    # Releases the subscription schedule immediately, which will stop scheduling of its phases, but leave any existing subscription in place. A schedule can only be released if its status is not_started or active. If the subscription schedule is currently associated with a subscription, releasing it will remove its subscription property and set the subscription's ID to the released_subscription property.
     def self.release(schedule, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/tax/calculation.rb b/lib/stripe/resources/tax/calculation.rb
index 054218b57..b453a668f 100644
--- a/lib/stripe/resources/tax/calculation.rb
+++ b/lib/stripe/resources/tax/calculation.rb
@@ -11,6 +11,7 @@ class Calculation < APIResource
 
       OBJECT_NAME = "tax.calculation"
 
+      # Retrieves the line items of a persisted tax calculation as a collection.
       def list_line_items(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -20,6 +21,7 @@ def list_line_items(params = {}, opts = {})
         )
       end
 
+      # Retrieves the line items of a persisted tax calculation as a collection.
       def self.list_line_items(calculation, params = {}, opts = {})
         request_stripe_object(
           method: :get,
diff --git a/lib/stripe/resources/tax/transaction.rb b/lib/stripe/resources/tax/transaction.rb
index e9469d7c1..09aeeeb87 100644
--- a/lib/stripe/resources/tax/transaction.rb
+++ b/lib/stripe/resources/tax/transaction.rb
@@ -9,6 +9,7 @@ module Tax
     class Transaction < APIResource
       OBJECT_NAME = "tax.transaction"
 
+      # Retrieves the line items of a committed standalone transaction as a collection.
       def list_line_items(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -18,6 +19,7 @@ def list_line_items(params = {}, opts = {})
         )
       end
 
+      # Creates a Tax Transaction from a calculation.
       def self.create_from_calculation(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -27,6 +29,7 @@ def self.create_from_calculation(params = {}, opts = {})
         )
       end
 
+      # Partially or fully reverses a previously created Transaction.
       def self.create_reversal(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -36,6 +39,7 @@ def self.create_reversal(params = {}, opts = {})
         )
       end
 
+      # Retrieves the line items of a committed standalone transaction as a collection.
       def self.list_line_items(transaction, params = {}, opts = {})
         request_stripe_object(
           method: :get,
diff --git a/lib/stripe/resources/terminal/reader.rb b/lib/stripe/resources/terminal/reader.rb
index ad6b7f611..9e6be560c 100644
--- a/lib/stripe/resources/terminal/reader.rb
+++ b/lib/stripe/resources/terminal/reader.rb
@@ -14,6 +14,7 @@ class Reader < APIResource
 
       OBJECT_NAME = "terminal.reader"
 
+      # Cancels the current reader action.
       def cancel_action(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -23,6 +24,7 @@ def cancel_action(params = {}, opts = {})
         )
       end
 
+      # Initiates a payment flow on a Reader.
       def process_payment_intent(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -32,6 +34,7 @@ def process_payment_intent(params = {}, opts = {})
         )
       end
 
+      # Initiates a setup intent flow on a Reader.
       def process_setup_intent(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -41,6 +44,7 @@ def process_setup_intent(params = {}, opts = {})
         )
       end
 
+      # Initiates a refund on a Reader
       def refund_payment(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -50,6 +54,7 @@ def refund_payment(params = {}, opts = {})
         )
       end
 
+      # Sets reader display to show cart details.
       def set_reader_display(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -59,6 +64,7 @@ def set_reader_display(params = {}, opts = {})
         )
       end
 
+      # Cancels the current reader action.
       def self.cancel_action(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -68,6 +74,7 @@ def self.cancel_action(reader, params = {}, opts = {})
         )
       end
 
+      # Initiates a payment flow on a Reader.
       def self.process_payment_intent(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -77,6 +84,7 @@ def self.process_payment_intent(reader, params = {}, opts = {})
         )
       end
 
+      # Initiates a setup intent flow on a Reader.
       def self.process_setup_intent(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -86,6 +94,7 @@ def self.process_setup_intent(reader, params = {}, opts = {})
         )
       end
 
+      # Initiates a refund on a Reader
       def self.refund_payment(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -95,6 +104,7 @@ def self.refund_payment(reader, params = {}, opts = {})
         )
       end
 
+      # Sets reader display to show cart details.
       def self.set_reader_display(reader, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -111,6 +121,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Reader
 
+        # Presents a payment method on a simulated reader. Can be used to simulate accepting a payment, saving a card or refunding a transaction.
         def self.present_payment_method(reader, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -120,6 +131,7 @@ def self.present_payment_method(reader, params = {}, opts = {})
           )
         end
 
+        # Presents a payment method on a simulated reader. Can be used to simulate accepting a payment, saving a card or refunding a transaction.
         def present_payment_method(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/test_helpers/test_clock.rb b/lib/stripe/resources/test_helpers/test_clock.rb
index c2fd34ddb..b81bbbc5f 100644
--- a/lib/stripe/resources/test_helpers/test_clock.rb
+++ b/lib/stripe/resources/test_helpers/test_clock.rb
@@ -13,6 +13,7 @@ class TestClock < APIResource
 
       OBJECT_NAME = "test_helpers.test_clock"
 
+      # Starts advancing a test clock to a specified time in the future. Advancement is done when status changes to Ready.
       def advance(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -22,6 +23,7 @@ def advance(params = {}, opts = {})
         )
       end
 
+      # Starts advancing a test clock to a specified time in the future. Advancement is done when status changes to Ready.
       def self.advance(test_clock, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/topup.rb b/lib/stripe/resources/topup.rb
index d3569bb31..da98f361b 100644
--- a/lib/stripe/resources/topup.rb
+++ b/lib/stripe/resources/topup.rb
@@ -14,6 +14,7 @@ class Topup < APIResource
 
     OBJECT_NAME = "topup"
 
+    # Cancels a top-up. Only pending top-ups can be canceled.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +24,7 @@ def cancel(params = {}, opts = {})
       )
     end
 
+    # Cancels a top-up. Only pending top-ups can be canceled.
     def self.cancel(topup, params = {}, opts = {})
       request_stripe_object(
         method: :post,
diff --git a/lib/stripe/resources/treasury/financial_account.rb b/lib/stripe/resources/treasury/financial_account.rb
index 24c4b3014..b386e5812 100644
--- a/lib/stripe/resources/treasury/financial_account.rb
+++ b/lib/stripe/resources/treasury/financial_account.rb
@@ -12,6 +12,7 @@ class FinancialAccount < APIResource
 
       OBJECT_NAME = "treasury.financial_account"
 
+      # Retrieves Features information associated with the FinancialAccount.
       def retrieve_features(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -21,6 +22,7 @@ def retrieve_features(params = {}, opts = {})
         )
       end
 
+      # Updates the Features associated with a FinancialAccount.
       def update_features(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -30,6 +32,7 @@ def update_features(params = {}, opts = {})
         )
       end
 
+      # Retrieves Features information associated with the FinancialAccount.
       def self.retrieve_features(financial_account, params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -39,6 +42,7 @@ def self.retrieve_features(financial_account, params = {}, opts = {})
         )
       end
 
+      # Updates the Features associated with a FinancialAccount.
       def self.update_features(financial_account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
diff --git a/lib/stripe/resources/treasury/inbound_transfer.rb b/lib/stripe/resources/treasury/inbound_transfer.rb
index 659c74f48..c3627492b 100644
--- a/lib/stripe/resources/treasury/inbound_transfer.rb
+++ b/lib/stripe/resources/treasury/inbound_transfer.rb
@@ -10,6 +10,7 @@ class InboundTransfer < APIResource
 
       OBJECT_NAME = "treasury.inbound_transfer"
 
+      # Cancels an InboundTransfer.
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -19,6 +20,7 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # Cancels an InboundTransfer.
       def self.cancel(inbound_transfer, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -35,6 +37,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = InboundTransfer
 
+        # Transitions a test mode created InboundTransfer to the failed status. The InboundTransfer must already be in the processing state.
         def self.fail(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -44,6 +47,7 @@ def self.fail(id, params = {}, opts = {})
           )
         end
 
+        # Marks the test mode InboundTransfer object as returned and links the InboundTransfer to a ReceivedDebit. The InboundTransfer must already be in the succeeded state.
         def self.return_inbound_transfer(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -53,6 +57,7 @@ def self.return_inbound_transfer(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created InboundTransfer to the succeeded status. The InboundTransfer must already be in the processing state.
         def self.succeed(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -62,6 +67,7 @@ def self.succeed(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created InboundTransfer to the failed status. The InboundTransfer must already be in the processing state.
         def fail(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -71,6 +77,7 @@ def fail(params = {}, opts = {})
           )
         end
 
+        # Marks the test mode InboundTransfer object as returned and links the InboundTransfer to a ReceivedDebit. The InboundTransfer must already be in the succeeded state.
         def return_inbound_transfer(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -80,6 +87,7 @@ def return_inbound_transfer(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created InboundTransfer to the succeeded status. The InboundTransfer must already be in the processing state.
         def succeed(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/treasury/outbound_payment.rb b/lib/stripe/resources/treasury/outbound_payment.rb
index aaa116a53..afdece66a 100644
--- a/lib/stripe/resources/treasury/outbound_payment.rb
+++ b/lib/stripe/resources/treasury/outbound_payment.rb
@@ -12,6 +12,7 @@ class OutboundPayment < APIResource
 
       OBJECT_NAME = "treasury.outbound_payment"
 
+      # Cancel an OutboundPayment.
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -21,6 +22,7 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # Cancel an OutboundPayment.
       def self.cancel(id, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -37,6 +39,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = OutboundPayment
 
+        # Transitions a test mode created OutboundPayment to the failed status. The OutboundPayment must already be in the processing state.
         def self.fail(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -46,6 +49,7 @@ def self.fail(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the posted status. The OutboundPayment must already be in the processing state.
         def self.post(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -55,6 +59,7 @@ def self.post(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the returned status. The OutboundPayment must already be in the processing state.
         def self.return_outbound_payment(id, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -64,6 +69,7 @@ def self.return_outbound_payment(id, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the failed status. The OutboundPayment must already be in the processing state.
         def fail(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -73,6 +79,7 @@ def fail(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the posted status. The OutboundPayment must already be in the processing state.
         def post(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -82,6 +89,7 @@ def post(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundPayment to the returned status. The OutboundPayment must already be in the processing state.
         def return_outbound_payment(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/treasury/outbound_transfer.rb b/lib/stripe/resources/treasury/outbound_transfer.rb
index 728c63e95..149f3cd3b 100644
--- a/lib/stripe/resources/treasury/outbound_transfer.rb
+++ b/lib/stripe/resources/treasury/outbound_transfer.rb
@@ -12,6 +12,7 @@ class OutboundTransfer < APIResource
 
       OBJECT_NAME = "treasury.outbound_transfer"
 
+      # An OutboundTransfer can be canceled if the funds have not yet been paid out.
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -21,6 +22,7 @@ def cancel(params = {}, opts = {})
         )
       end
 
+      # An OutboundTransfer can be canceled if the funds have not yet been paid out.
       def self.cancel(outbound_transfer, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -37,6 +39,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = OutboundTransfer
 
+        # Transitions a test mode created OutboundTransfer to the failed status. The OutboundTransfer must already be in the processing state.
         def self.fail(outbound_transfer, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -46,6 +49,7 @@ def self.fail(outbound_transfer, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the posted status. The OutboundTransfer must already be in the processing state.
         def self.post(outbound_transfer, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -55,6 +59,7 @@ def self.post(outbound_transfer, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the returned status. The OutboundTransfer must already be in the processing state.
         def self.return_outbound_transfer(outbound_transfer, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -64,6 +69,7 @@ def self.return_outbound_transfer(outbound_transfer, params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the failed status. The OutboundTransfer must already be in the processing state.
         def fail(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -73,6 +79,7 @@ def fail(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the posted status. The OutboundTransfer must already be in the processing state.
         def post(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -82,6 +89,7 @@ def post(params = {}, opts = {})
           )
         end
 
+        # Transitions a test mode created OutboundTransfer to the returned status. The OutboundTransfer must already be in the processing state.
         def return_outbound_transfer(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/treasury/received_credit.rb b/lib/stripe/resources/treasury/received_credit.rb
index 1f39ae301..d92a0027b 100644
--- a/lib/stripe/resources/treasury/received_credit.rb
+++ b/lib/stripe/resources/treasury/received_credit.rb
@@ -16,6 +16,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = ReceivedCredit
 
+        # Use this endpoint to simulate a test mode ReceivedCredit initiated by a third party. In live mode, you can't directly create ReceivedCredits initiated by third parties.
         def self.create(params = {}, opts = {})
           request_stripe_object(
             method: :post,
diff --git a/lib/stripe/resources/treasury/received_debit.rb b/lib/stripe/resources/treasury/received_debit.rb
index 343301b55..d4ad8e216 100644
--- a/lib/stripe/resources/treasury/received_debit.rb
+++ b/lib/stripe/resources/treasury/received_debit.rb
@@ -16,6 +16,7 @@ def test_helpers
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = ReceivedDebit
 
+        # Use this endpoint to simulate a test mode ReceivedDebit initiated by a third party. In live mode, you can't directly create ReceivedDebits initiated by third parties.
         def self.create(params = {}, opts = {})
           request_stripe_object(
             method: :post,

From 36dc37db5e870b936d4475b1aba9dc54c914d601 Mon Sep 17 00:00:00 2001
From: Richard Marmorstein <richardm@stripe.com>
Date: Thu, 4 Jan 2024 13:52:23 -0600
Subject: [PATCH 3/3] Bump version to 10.5.0

---
 CHANGELOG.md          | 4 ++++
 VERSION               | 2 +-
 lib/stripe/version.rb | 2 +-
 3 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4270d5e9e..9d429364e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,8 @@
 # Changelog
+## 10.5.0 - 2024-01-04
+* [#1306](https://github.com/stripe/stripe-ruby/pull/1306) Update generated code
+  * Add support for `retrieve` method on resource `Tax.Registration`
+
 ## 10.4.0 - 2023-12-22
 * [#1303](https://github.com/stripe/stripe-ruby/pull/1303) Update generated code
   * Add support for new resource `FinancialConnections.Transaction`
diff --git a/VERSION b/VERSION
index 816c0711a..2cf514e36 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-10.4.0
+10.5.0
diff --git a/lib/stripe/version.rb b/lib/stripe/version.rb
index f96dc0af0..9cbac6bd0 100644
--- a/lib/stripe/version.rb
+++ b/lib/stripe/version.rb
@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stripe
-  VERSION = "10.4.0"
+  VERSION = "10.5.0"
 end