stripe 10.5.0.pre.beta.1 → 10.6.0.pre.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53a312be8b3ec863d48ced7662fdff781b4d44eb86d8dbf4f6d977252106aff2
-  data.tar.gz: 1c0482941ccbf53abb17d584449a2ddddba22d2f4766893d10c02c5fac887aec
+  metadata.gz: 4dd553363be8cc8d8a5f06ff9d6772935def2baa681c7be37e49bf5b4433a10c
+  data.tar.gz: cb3b1684976ad90db8973c871db910ab7eb22e0a3705893bc4ae62fd19a293c7
 SHA512:
-  metadata.gz: 916287bb73f70d3dad8701d4383421baf47731ab8eeac53f41afd9144e6dada784f4de89b3f12c6cafaeffd28c8874a93632ceeb08dbcb858d4af7f35140e2e7
-  data.tar.gz: de3cfc90d53b5f4224995b67693197cceb0addd3138913eac8a7ca56b104a608760c40b87341149f13274fbbbc0871fce8244d14cf5b14313a0a07683ec8c87f
+  metadata.gz: 5944cccbb0b5680830e66b306dca977bf4ee0963e85faeae0392df0cd4dfb795942ee1069b1a45c8cb79621d78756975f5c1ed672bd3d1fec6e4e6338a481334
+  data.tar.gz: c8563e4b7ce2bb6ac372ac50cd3644969f901137ff352538df1abb1b849e402d48873005cbcee6f9cc3c34e6bc19dc8fc9e124c95d837b15cfac5fd80fd725af

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 10.6.0-beta.1 - 2024-01-04
+* [#1302](https://github.com/stripe/stripe-ruby/pull/1302) Update generated code for beta
+  * Updated stable APIs to the latest version
+
+
+## 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.5.0-beta.1 - 2023-12-22
 * [#1302](https://github.com/stripe/stripe-ruby/pull/1302) Update generated code for beta
 

data/OPENAPI_VERSION

@@ -1 +1 @@
-v737
+v742

data/VERSION

@@ -1 +1 @@
-10.5.0-beta.1
+10.6.0-beta.1

data/lib/stripe/resources/account.rb

@@ -25,6 +25,7 @@ module Stripe
                                   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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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,

data/lib/stripe/resources/apps/secret.rb

@@ -18,6 +18,7 @@ module Stripe
 
       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 @@ module Stripe
         )
       end
 
+      # Finds a secret in the secret store by name and scope.
       def self.find(params = {}, opts = {})
         request_stripe_object(
           method: :get,

data/lib/stripe/resources/capital/financing_offer.rb

@@ -10,6 +10,8 @@ module Stripe
 
       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 @@ module Stripe
         )
       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,

data/lib/stripe/resources/charge.rb

@@ -14,6 +14,11 @@ module Stripe
 
     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 @@ module Stripe
       )
     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,

data/lib/stripe/resources/checkout/session.rb

@@ -23,6 +23,9 @@ module Stripe
 
       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 @@ module Stripe
         )
       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 @@ module Stripe
         )
       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 @@ module Stripe
         )
       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,

data/lib/stripe/resources/climate/order.rb

@@ -12,6 +12,10 @@ module Stripe
 
       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 @@ module Stripe
         )
       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,

data/lib/stripe/resources/credit_note.rb

@@ -12,6 +12,7 @@ module Stripe
 
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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,

data/lib/stripe/resources/customer.rb

@@ -19,6 +19,9 @@ module Stripe
     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 @@ module Stripe
       )
     end
 
+    # Removes the currently applied discount on a customer.
     def delete_discount(params = {}, opts = {})
       request_stripe_object(
         method: :delete,
@@ -37,6 +41,7 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       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 @@ module Stripe
       )
     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 @@ module Stripe
     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 @@ module Stripe
         )
       end
 
+      # Create an incoming testmode bank transfer
       def fund_cash_balance(params = {}, opts = {})
         @resource.request_stripe_object(
           method: :post,

data/lib/stripe/resources/dispute.rb

@@ -13,6 +13,9 @@ module Stripe
 
     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 @@ module Stripe
       )
     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,

data/lib/stripe/resources/financial_connections/account.rb

@@ -12,6 +12,7 @@ module Stripe
 
       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 @@ module Stripe
         )
       end
 
+      # Lists all owners for a given Account
       def list_owners(params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -30,6 +32,7 @@ module Stripe
         )
       end
 
+      # Refreshes the data associated with a Financial Connections Account.
       def refresh_account(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -39,6 +42,7 @@ module Stripe
         )
       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 @@ module Stripe
         )
       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 @@ module Stripe
         )
       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 @@ module Stripe
         )
       end
 
+      # Lists all owners for a given Account
       def self.list_owners(account, params = {}, opts = {})
         request_stripe_object(
           method: :get,
@@ -75,6 +82,7 @@ module Stripe
         )
       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 @@ module Stripe
         )
       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 @@ module Stripe
         )
       end
 
+      # Unsubscribes from periodic refreshes of data associated with a Financial Connections Account.
       def self.unsubscribe(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,

data/lib/stripe/resources/gift_cards/card.rb

@@ -12,6 +12,7 @@ module Stripe
 
       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,

data/lib/stripe/resources/gift_cards/transaction.rb

@@ -16,6 +16,7 @@ module Stripe
 
       OBJECT_NAME = "gift_cards.transaction"
 
+      # Cancel a gift card transaction
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -25,6 +26,7 @@ module Stripe
         )
       end
 
+      # Confirm a gift card transaction
       def confirm(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -34,6 +36,7 @@ module Stripe
         )
       end
 
+      # Cancel a gift card transaction
       def self.cancel(id, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -43,6 +46,7 @@ module Stripe
         )
       end
 
+      # Confirm a gift card transaction
       def self.confirm(id, params = {}, opts = {})
         request_stripe_object(
           method: :post,

data/lib/stripe/resources/identity/verification_session.rb

@@ -21,6 +21,9 @@ module Stripe
 
       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 @@ module Stripe
         )
       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 @@ module Stripe
         )
       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 @@ module Stripe
         )
       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,

data/lib/stripe/resources/invoice.rb

@@ -46,6 +46,15 @@ module Stripe
 
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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 @@ module Stripe
       )
     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,