From 3337e53d8047f22223a9f82dc29e17c4800d3eb9 Mon Sep 17 00:00:00 2001
From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com>
Date: Thu, 14 Sep 2023 23:57:58 +0000
Subject: [PATCH] Update OpenAPI specification

---
 openapi/spec3.beta.sdk.json |  60 +++++------
 openapi/spec3.beta.sdk.yaml | 194 +++++++++++++++++-------------------
 openapi/spec3.json          |  60 +++++------
 openapi/spec3.sdk.json      |  60 +++++------
 openapi/spec3.sdk.yaml      | 194 +++++++++++++++++-------------------
 openapi/spec3.yaml          | 194 +++++++++++++++++-------------------
 6 files changed, 372 insertions(+), 390 deletions(-)

diff --git a/openapi/spec3.beta.sdk.json b/openapi/spec3.beta.sdk.json
index 9a758aaa..6b1037ce 100644
--- a/openapi/spec3.beta.sdk.json
+++ b/openapi/spec3.beta.sdk.json
@@ -2729,14 +2729,14 @@
         }
       },
       "balance_transaction": {
-        "description": "Balance transactions represent funds moving through your Stripe account.\nThey're created for every type of transaction that comes into or flows out of your Stripe account balance.\n\nRelated guide: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)",
+        "description": "Balance transactions represent funds moving through your Stripe account.\nStripe creates them for every type of transaction that enters or leaves your Stripe account balance.\n\nRelated guide: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)",
         "properties": {
           "amount": {
-            "description": "Gross amount of the transaction, in cents (or local equivalent).",
+            "description": "Gross amount of the transaction (in cents (or local equivalent)).",
             "type": "integer"
           },
           "available_on": {
-            "description": "The date the transaction's net funds will become available in the Stripe balance.",
+            "description": "The date that the transaction's net funds become available in the Stripe balance.",
             "format": "unix-time",
             "type": "integer"
           },
@@ -2756,7 +2756,7 @@
             "type": "string"
           },
           "exchange_rate": {
-            "description": "The exchange rate used, if applicable, for this transaction. Specifically, if money was converted from currency A to currency B, then the `amount` in currency A, times `exchange_rate`, would be the `amount` in currency B. For example, suppose you charged a customer 10.00 EUR. Then the PaymentIntent's `amount` would be `1000` and `currency` would be `eur`. Suppose this was converted into 12.34 USD in your Stripe account. Then the BalanceTransaction's `amount` would be `1234`, `currency` would be `usd`, and `exchange_rate` would be `1.234`.",
+            "description": "If applicable, this transaction uses an exchange rate. If money converts from currency A to currency B, then the `amount` in currency A, multipled by the `exchange_rate`, equals the `amount` in currency B. For example, if you charge a customer 10.00 EUR, the PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this converts to 12.34 USD in your Stripe account, the BalanceTransaction's `amount` is `1234`, its `currency` is `usd`, and the `exchange_rate` is `1.234`.",
             "nullable": true,
             "type": "number"
           },
@@ -2777,7 +2777,7 @@
             "type": "string"
           },
           "net": {
-            "description": "Net amount of the transaction, in cents (or local equivalent).",
+            "description": "Net amount of the transaction (in cents (or local equivalent)).",
             "type": "integer"
           },
           "object": {
@@ -2788,7 +2788,7 @@
             "type": "string"
           },
           "reporting_category": {
-            "description": "[Learn more](https://stripe.com/docs/reports/reporting-categories) about how reporting categories can help you understand balance transactions from an accounting perspective.",
+            "description": "Learn more about how [reporting categories] (https://stripe.com/docs/reports/reporting-categories) can help you understand balance transactions from an accounting perspective.",
             "maxLength": 5000,
             "type": "string"
           },
@@ -2802,7 +2802,7 @@
                 "$ref": "#/components/schemas/balance_transaction_source"
               }
             ],
-            "description": "The Stripe object to which this transaction is related.",
+            "description": "This transaction relates to the Stripe object.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -2813,12 +2813,12 @@
             }
           },
           "status": {
-            "description": "If the transaction's net funds are available in the Stripe balance yet. Either `available` or `pending`.",
+            "description": "The transaction's net funds status in the Stripe balance, which are either `available` or `pending`.",
             "maxLength": 5000,
             "type": "string"
           },
           "type": {
-            "description": "Transaction type: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `connect_collection_transfer`, `contribution`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_inbound`, `obligation_outbound`, `obligation_reversal_inbound`, `obligation_reversal_outbound`, `obligation_payout`, `obligation_payout_failure`, `payment`, `payment_failure_refund`, `payment_refund`, `payment_reversal`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, or `transfer_refund`. [Learn more](https://stripe.com/docs/reports/balance-transaction-types) about balance transaction types and what they represent. If you are looking to classify transactions for accounting purposes, you might want to consider `reporting_category` instead.",
+            "description": "Transaction type: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `connect_collection_transfer`, `contribution`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_inbound`, `obligation_outbound`, `obligation_reversal_inbound`, `obligation_reversal_outbound`, `obligation_payout`, `obligation_payout_failure`, `payment`, `payment_failure_refund`, `payment_refund`, `payment_reversal`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, or `transfer_refund`. Learn more about [balance transaction types and what they represent](https://stripe.com/docs/reports/balance-transaction-types). To classify transactions for accounting purposes, consider `reporting_category` instead.",
             "enum": [
               "adjustment",
               "advance",
@@ -8995,7 +8995,7 @@
         }
       },
       "customer": {
-        "description": "This object represents a customer of your business. It lets you create recurring charges and track payments that belong to the same customer.\n\nRelated guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)",
+        "description": "This object represents a customer of your business. Use it to create recurring charges and track payments that belong to the same customer.\n\nRelated guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)",
         "properties": {
           "address": {
             "anyOf": [
@@ -9007,7 +9007,7 @@
             "nullable": true
           },
           "balance": {
-            "description": "Current balance, if any, being stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that will be added to their next invoice. The balance does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied to any invoice. This balance is only taken into account as invoices are finalized.",
+            "description": "The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.",
             "type": "integer"
           },
           "cash_balance": {
@@ -9016,7 +9016,7 @@
                 "$ref": "#/components/schemas/cash_balance"
               }
             ],
-            "description": "The current funds being held by Stripe on behalf of the customer. These funds can be applied towards payment intents with source \"cash_balance\". The settings[reconciliation_mode] field describes whether these funds are applied to such payment intents manually or automatically.",
+            "description": "The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is \"cash_balance\". The `settings[reconciliation_mode]` field describes if these funds apply to these payment intents manually or automatically.",
             "nullable": true
           },
           "created": {
@@ -9040,7 +9040,7 @@
                 "$ref": "#/components/schemas/payment_source"
               }
             ],
-            "description": "ID of the default payment source for the customer.\n\nIf you are using payment methods created via the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.",
+            "description": "ID of the default payment source for the customer.\n\nIf you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -9051,7 +9051,7 @@
             }
           },
           "delinquent": {
-            "description": "When the customer's latest invoice is billed by charging automatically, `delinquent` is `true` if the invoice's latest charge failed. When the customer's latest invoice is billed by sending an invoice, `delinquent` is `true` if the invoice isn't paid by its due date.\n\nIf an invoice is marked uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn't get reset to `false`.",
+            "description": "If Stripe bills the customer's latest invoice by automatically charging and the latest charge fails, it sets `delinquent`` to `true``. If Stripe bills the invoice by sending it, and the invoice isn't paid by the due date, it also sets `delinquent`` to `true`.\n\nIf an invoice becomes uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn't reset to `false`.",
             "nullable": true,
             "type": "boolean"
           },
@@ -9085,7 +9085,7 @@
             "additionalProperties": {
               "type": "integer"
             },
-            "description": "The current multi-currency balances, if any, being stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that will be added to their next invoice denominated in that currency. These balances do not refer to any unpaid invoices. They solely track amounts that have yet to be successfully applied to any invoice. A balance in a particular currency is only applied to any invoice as an invoice in that currency is finalized.",
+            "description": "The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.",
             "type": "object"
           },
           "invoice_prefix": {
@@ -9116,7 +9116,7 @@
             "type": "string"
           },
           "next_invoice_sequence": {
-            "description": "The suffix of the customer's next invoice number, e.g., 0001.",
+            "description": "The suffix of the customer's next invoice number (for example, 0001).",
             "type": "integer"
           },
           "object": {
@@ -9232,7 +9232,7 @@
             "$ref": "#/components/schemas/customer_tax"
           },
           "tax_exempt": {
-            "description": "Describes the customer's tax exemption status. One of `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the text **\"Reverse charge\"**.",
+            "description": "Describes the customer's tax exemption status, which is `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the following text: **\"Reverse charge\"**.",
             "enum": [
               "exempt",
               "none",
@@ -9290,7 +9290,7 @@
                 "$ref": "#/components/schemas/test_helpers.test_clock"
               }
             ],
-            "description": "ID of the test clock this customer belongs to.",
+            "description": "ID of the test clock that this customer belongs to.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -11636,10 +11636,10 @@
         }
       },
       "dispute": {
-        "description": "A dispute occurs when a customer questions your charge with their card issuer.\nWhen this happens, you're given the opportunity to respond to the dispute with\nevidence that shows that the charge is legitimate. You can find more\ninformation about the dispute process in our [Disputes and\nFraud](/docs/disputes) documentation.\n\nRelated guide: [Disputes and fraud](https://stripe.com/docs/disputes)",
+        "description": "A dispute occurs when a customer questions your charge with their card issuer.\nWhen this happens, you have the opportunity to respond to the dispute with\nevidence that shows that the charge is legitimate.\n\nRelated guide: [Disputes and fraud](https://stripe.com/docs/disputes)",
         "properties": {
           "amount": {
-            "description": "Disputed amount. Usually the amount of the charge, but can differ (usually because of currency fluctuation or because only part of the order is disputed).",
+            "description": "Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).",
             "type": "integer"
           },
           "balance_transactions": {
@@ -11659,7 +11659,7 @@
                 "$ref": "#/components/schemas/charge"
               }
             ],
-            "description": "ID of the charge that was disputed.",
+            "description": "ID of the charge that's disputed.",
             "x-expansionResources": {
               "oneOf": [
                 {
@@ -11689,7 +11689,7 @@
             "type": "string"
           },
           "is_charge_refundable": {
-            "description": "If true, it is still possible to refund the disputed payment. Once the payment has been fully refunded, no further funds will be withdrawn from your Stripe account as a result of this dispute.",
+            "description": "If true, it's still possible to refund the disputed payment. After the payment has been fully refunded, no further funds are withdrawn from your Stripe account as a result of this dispute.",
             "type": "boolean"
           },
           "livemode": {
@@ -11727,7 +11727,7 @@
                 "$ref": "#/components/schemas/payment_intent"
               }
             ],
-            "description": "ID of the PaymentIntent that was disputed.",
+            "description": "ID of the PaymentIntent that's disputed.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -11741,7 +11741,7 @@
             "$ref": "#/components/schemas/dispute_payment_method_details"
           },
           "reason": {
-            "description": "Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Read more about [dispute reasons](https://stripe.com/docs/disputes/categories).",
+            "description": "Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Learn more about [dispute reasons](https://stripe.com/docs/disputes/categories).",
             "maxLength": 5000,
             "type": "string"
           },
@@ -12372,15 +12372,15 @@
         }
       },
       "event": {
-        "description": "Events are our way of letting you know when something interesting happens in\nyour account. When an interesting event occurs, we create a new `Event`\nobject. For example, when a charge succeeds, we create a `charge.succeeded`\nevent; and when an invoice payment attempt fails, we create an\n`invoice.payment_failed` event. Note that many API requests may cause multiple\nevents to be created. For example, if you create a new subscription for a\ncustomer, you will receive both a `customer.subscription.created` event and a\n`charge.succeeded` event.\n\nEvents occur when the state of another API resource changes. The state of that\nresource at the time of the change is embedded in the event's data field. For\nexample, a `charge.succeeded` event will contain a charge, and an\n`invoice.payment_failed` event will contain an invoice.\n\nAs with other API resources, you can use endpoints to retrieve an\n[individual event](https://stripe.com/docs/api#retrieve_event) or a [list of events](https://stripe.com/docs/api#list_events)\nfrom the API. We also have a separate\n[webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the\n`Event` objects directly to an endpoint on your server. Webhooks are managed\nin your\n[account settings](https://dashboard.stripe.com/account/webhooks),\nand our [Using Webhooks](https://stripe.com/docs/webhooks) guide will help you get set up.\n\nWhen using [Connect](https://stripe.com/docs/connect), you can also receive notifications of\nevents that occur in connected accounts. For these events, there will be an\nadditional `account` attribute in the received `Event` object.\n\n**NOTE:** Right now, access to events through the [Retrieve Event API](https://stripe.com/docs/api#retrieve_event) is\nguaranteed only for 30 days.",
+        "description": "Events are our way of letting you know when something interesting happens in\nyour account. When an interesting event occurs, we create a new `Event`\nobject. For example, when a charge succeeds, we create a `charge.succeeded`\nevent, and when an invoice payment attempt fails, we create an\n`invoice.payment_failed` event. Certain API requests might create multiple\nevents. For example, if you create a new subscription for a\ncustomer, you receive both a `customer.subscription.created` event and a\n`charge.succeeded` event.\n\nEvents occur when the state of another API resource changes. The event's data\nfield embeds the resource's state at the time of the change. For\nexample, a `charge.succeeded` event contains a charge, and an\n`invoice.payment_failed` event contains an invoice.\n\nAs with other API resources, you can use endpoints to retrieve an\n[individual event](https://stripe.com/docs/api#retrieve_event) or a [list of events](https://stripe.com/docs/api#list_events)\nfrom the API. We also have a separate\n[webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the\n`Event` objects directly to an endpoint on your server. You can manage\nwebhooks in your\n[account settings](https://dashboard.stripe.com/account/webhooks). Learn how\nto [listen for events]\n(/docs/webhooks) so that your integration can automatically trigger reactions.\n\nWhen using [Connect](https://stripe.com/docs/connect), you can also receive event notifications\nthat occur in connected accounts. For these events, there's an\nadditional `account` attribute in the received `Event` object.\n\nWe only guarantee access to events through the [Retrieve Event API](https://stripe.com/docs/api#retrieve_event)\nfor 30 days.",
         "properties": {
           "account": {
-            "description": "The connected account that originated the event.",
+            "description": "The connected account that originates the event.",
             "maxLength": 5000,
             "type": "string"
           },
           "api_version": {
-            "description": "The Stripe API version used to render `data`. *Note: This property is populated only for events on or after October 31, 2014*.",
+            "description": "The Stripe API version used to render `data`. This property is populated only for events on or after October 31, 2014.",
             "maxLength": 5000,
             "nullable": true,
             "type": "string"
@@ -12410,7 +12410,7 @@
             "type": "string"
           },
           "pending_webhooks": {
-            "description": "Number of webhooks that have yet to be successfully delivered (i.e., to return a 20x response) to the URLs you've specified.",
+            "description": "Number of webhooks that haven't been successfully delivered (for example, to return a 20x response) to the URLs you specify.",
             "type": "integer"
           },
           "request": {
@@ -12419,11 +12419,11 @@
                 "$ref": "#/components/schemas/notification_event_request"
               }
             ],
-            "description": "Information on the API request that instigated the event.",
+            "description": "Information on the API request that triggers the event.",
             "nullable": true
           },
           "type": {
-            "description": "Description of the event (e.g., `invoice.created` or `charge.refunded`).",
+            "description": "Description of the event (for example, `invoice.created` or `charge.refunded`).",
             "enum": [
               "account.application.authorized",
               "account.application.deauthorized",
diff --git a/openapi/spec3.beta.sdk.yaml b/openapi/spec3.beta.sdk.yaml
index 09030f03..ba812eab 100644
--- a/openapi/spec3.beta.sdk.yaml
+++ b/openapi/spec3.beta.sdk.yaml
@@ -2638,19 +2638,19 @@ components:
       description: >-
         Balance transactions represent funds moving through your Stripe account.
 
-        They're created for every type of transaction that comes into or flows
-        out of your Stripe account balance.
+        Stripe creates them for every type of transaction that enters or leaves
+        your Stripe account balance.
 
 
         Related guide: [Balance transaction
         types](https://stripe.com/docs/reports/balance-transaction-types)
       properties:
         amount:
-          description: 'Gross amount of the transaction, in cents (or local equivalent).'
+          description: Gross amount of the transaction (in cents (or local equivalent)).
           type: integer
         available_on:
           description: >-
-            The date the transaction's net funds will become available in the
+            The date that the transaction's net funds become available in the
             Stripe balance.
           format: unix-time
           type: integer
@@ -2676,15 +2676,14 @@ components:
           type: string
         exchange_rate:
           description: >-
-            The exchange rate used, if applicable, for this transaction.
-            Specifically, if money was converted from currency A to currency B,
-            then the `amount` in currency A, times `exchange_rate`, would be the
-            `amount` in currency B. For example, suppose you charged a customer
-            10.00 EUR. Then the PaymentIntent's `amount` would be `1000` and
-            `currency` would be `eur`. Suppose this was converted into 12.34 USD
-            in your Stripe account. Then the BalanceTransaction's `amount` would
-            be `1234`, `currency` would be `usd`, and `exchange_rate` would be
-            `1.234`.
+            If applicable, this transaction uses an exchange rate. If money
+            converts from currency A to currency B, then the `amount` in
+            currency A, multipled by the `exchange_rate`, equals the `amount` in
+            currency B. For example, if you charge a customer 10.00 EUR, the
+            PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this
+            converts to 12.34 USD in your Stripe account, the
+            BalanceTransaction's `amount` is `1234`, its `currency` is `usd`,
+            and the `exchange_rate` is `1.234`.
           nullable: true
           type: number
         fee:
@@ -2702,7 +2701,7 @@ components:
           maxLength: 5000
           type: string
         net:
-          description: 'Net amount of the transaction, in cents (or local equivalent).'
+          description: Net amount of the transaction (in cents (or local equivalent)).
           type: integer
         object:
           description: >-
@@ -2713,9 +2712,9 @@ components:
           type: string
         reporting_category:
           description: >-
-            [Learn more](https://stripe.com/docs/reports/reporting-categories)
-            about how reporting categories can help you understand balance
-            transactions from an accounting perspective.
+            Learn more about how [reporting categories]
+            (https://stripe.com/docs/reports/reporting-categories) can help you
+            understand balance transactions from an accounting perspective.
           maxLength: 5000
           type: string
         source:
@@ -2723,15 +2722,15 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/balance_transaction_source'
-          description: The Stripe object to which this transaction is related.
+          description: This transaction relates to the Stripe object.
           nullable: true
           x-expansionResources:
             oneOf:
               - $ref: '#/components/schemas/balance_transaction_source'
         status:
           description: >-
-            If the transaction's net funds are available in the Stripe balance
-            yet. Either `available` or `pending`.
+            The transaction's net funds status in the Stripe balance, which are
+            either `available` or `pending`.
           maxLength: 5000
           type: string
         type:
@@ -2749,11 +2748,11 @@ components:
             `refund_failure`, `reserve_transaction`, `reserved_funds`,
             `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`,
             `transfer`, `transfer_cancel`, `transfer_failure`, or
-            `transfer_refund`. [Learn
-            more](https://stripe.com/docs/reports/balance-transaction-types)
-            about balance transaction types and what they represent. If you are
-            looking to classify transactions for accounting purposes, you might
-            want to consider `reporting_category` instead.
+            `transfer_refund`. Learn more about [balance transaction types and
+            what they
+            represent](https://stripe.com/docs/reports/balance-transaction-types).
+            To classify transactions for accounting purposes, consider
+            `reporting_category` instead.
           enum:
             - adjustment
             - advance
@@ -8694,7 +8693,7 @@ components:
         in_package: ''
     customer:
       description: >-
-        This object represents a customer of your business. It lets you create
+        This object represents a customer of your business. Use it to create
         recurring charges and track payments that belong to the same customer.
 
 
@@ -8708,22 +8707,22 @@ components:
           nullable: true
         balance:
           description: >-
-            Current balance, if any, being stored on the customer. If negative,
-            the customer has credit to apply to their next invoice. If positive,
-            the customer has an amount owed that will be added to their next
-            invoice. The balance does not refer to any unpaid invoices; it
-            solely takes into account amounts that have yet to be successfully
-            applied to any invoice. This balance is only taken into account as
-            invoices are finalized.
+            The current balance, if any, that's stored on the customer. If
+            negative, the customer has credit to apply to their next invoice. If
+            positive, the customer has an amount owed that's added to their next
+            invoice. The balance only considers amounts that Stripe hasn't
+            successfully applied to any invoice. It doesn't reflect unpaid
+            invoices. This balance is only taken into account after invoices
+            finalize.
           type: integer
         cash_balance:
           anyOf:
             - $ref: '#/components/schemas/cash_balance'
           description: >-
             The current funds being held by Stripe on behalf of the customer.
-            These funds can be applied towards payment intents with source
-            "cash_balance". The settings[reconciliation_mode] field describes
-            whether these funds are applied to such payment intents manually or
+            You can apply these funds towards payment intents when the source is
+            "cash_balance". The `settings[reconciliation_mode]` field describes
+            if these funds apply to these payment intents manually or
             automatically.
           nullable: true
         created:
@@ -8749,7 +8748,7 @@ components:
             ID of the default payment source for the customer.
 
 
-            If you are using payment methods created via the PaymentMethods API,
+            If you use payment methods created through the PaymentMethods API,
             see the
             [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method)
             field instead.
@@ -8759,16 +8758,15 @@ components:
               - $ref: '#/components/schemas/payment_source'
         delinquent:
           description: >-
-            When the customer's latest invoice is billed by charging
-            automatically, `delinquent` is `true` if the invoice's latest charge
-            failed. When the customer's latest invoice is billed by sending an
-            invoice, `delinquent` is `true` if the invoice isn't paid by its due
-            date.
+            If Stripe bills the customer's latest invoice by automatically
+            charging and the latest charge fails, it sets `delinquent`` to
+            `true``. If Stripe bills the invoice by sending it, and the invoice
+            isn't paid by the due date, it also sets `delinquent`` to `true`.
 
 
-            If an invoice is marked uncollectible by
+            If an invoice becomes uncollectible by
             [dunning](https://stripe.com/docs/billing/automatic-collection),
-            `delinquent` doesn't get reset to `false`.
+            `delinquent` doesn't reset to `false`.
           nullable: true
           type: boolean
         description:
@@ -8798,15 +8796,15 @@ components:
           additionalProperties:
             type: integer
           description: >-
-            The current multi-currency balances, if any, being stored on the
+            The current multi-currency balances, if any, that's stored on the
             customer. If positive in a currency, the customer has a credit to
             apply to their next invoice denominated in that currency. If
-            negative, the customer has an amount owed that will be added to
-            their next invoice denominated in that currency. These balances do
-            not refer to any unpaid invoices. They solely track amounts that
-            have yet to be successfully applied to any invoice. A balance in a
-            particular currency is only applied to any invoice as an invoice in
-            that currency is finalized.
+            negative, the customer has an amount owed that's added to their next
+            invoice denominated in that currency. These balances don't apply to
+            unpaid invoices. They solely track amounts that Stripe hasn't
+            successfully applied to any invoice. Stripe only applies a balance
+            in a specific currency to an invoice after that invoice (which is in
+            the same currency) finalizes.
           type: object
         invoice_prefix:
           description: The prefix for the customer used to generate unique invoice numbers.
@@ -8835,7 +8833,9 @@ components:
           nullable: true
           type: string
         next_invoice_sequence:
-          description: 'The suffix of the customer''s next invoice number, e.g., 0001.'
+          description: >-
+            The suffix of the customer's next invoice number (for example,
+            0001).
           type: integer
         object:
           description: >-
@@ -8933,9 +8933,9 @@ components:
           $ref: '#/components/schemas/customer_tax'
         tax_exempt:
           description: >-
-            Describes the customer's tax exemption status. One of `none`,
+            Describes the customer's tax exemption status, which is `none`,
             `exempt`, or `reverse`. When set to `reverse`, invoice and receipt
-            PDFs include the text **"Reverse charge"**.
+            PDFs include the following text: **"Reverse charge"**.
           enum:
             - exempt
             - none
@@ -8980,7 +8980,7 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/test_helpers.test_clock'
-          description: ID of the test clock this customer belongs to.
+          description: ID of the test clock that this customer belongs to.
           nullable: true
           x-expansionResources:
             oneOf:
@@ -10909,21 +10909,17 @@ components:
         A dispute occurs when a customer questions your charge with their card
         issuer.
 
-        When this happens, you're given the opportunity to respond to the
-        dispute with
-
-        evidence that shows that the charge is legitimate. You can find more
-
-        information about the dispute process in our [Disputes and
+        When this happens, you have the opportunity to respond to the dispute
+        with
 
-        Fraud](/docs/disputes) documentation.
+        evidence that shows that the charge is legitimate.
 
 
         Related guide: [Disputes and fraud](https://stripe.com/docs/disputes)
       properties:
         amount:
           description: >-
-            Disputed amount. Usually the amount of the charge, but can differ
+            Disputed amount. Usually the amount of the charge, but it can differ
             (usually because of currency fluctuation or because only part of the
             order is disputed).
           type: integer
@@ -10940,7 +10936,7 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/charge'
-          description: ID of the charge that was disputed.
+          description: ID of the charge that's disputed.
           x-expansionResources:
             oneOf:
               - $ref: '#/components/schemas/charge'
@@ -10967,9 +10963,9 @@ components:
           type: string
         is_charge_refundable:
           description: >-
-            If true, it is still possible to refund the disputed payment. Once
-            the payment has been fully refunded, no further funds will be
-            withdrawn from your Stripe account as a result of this dispute.
+            If true, it's still possible to refund the disputed payment. After
+            the payment has been fully refunded, no further funds are withdrawn
+            from your Stripe account as a result of this dispute.
           type: boolean
         livemode:
           description: >-
@@ -11002,7 +10998,7 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/payment_intent'
-          description: ID of the PaymentIntent that was disputed.
+          description: ID of the PaymentIntent that's disputed.
           nullable: true
           x-expansionResources:
             oneOf:
@@ -11017,7 +11013,7 @@ components:
             `fraudulent`, `general`, `incorrect_account_details`,
             `insufficient_funds`, `product_not_received`,
             `product_unacceptable`, `subscription_canceled`, or `unrecognized`.
-            Read more about [dispute
+            Learn more about [dispute
             reasons](https://stripe.com/docs/disputes/categories).
           maxLength: 5000
           type: string
@@ -11559,29 +11555,26 @@ components:
         object. For example, when a charge succeeds, we create a
         `charge.succeeded`
 
-        event; and when an invoice payment attempt fails, we create an
+        event, and when an invoice payment attempt fails, we create an
 
-        `invoice.payment_failed` event. Note that many API requests may cause
+        `invoice.payment_failed` event. Certain API requests might create
         multiple
 
-        events to be created. For example, if you create a new subscription for
-        a
+        events. For example, if you create a new subscription for a
 
-        customer, you will receive both a `customer.subscription.created` event
-        and a
+        customer, you receive both a `customer.subscription.created` event and a
 
         `charge.succeeded` event.
 
 
-        Events occur when the state of another API resource changes. The state
-        of that
+        Events occur when the state of another API resource changes. The event's
+        data
 
-        resource at the time of the change is embedded in the event's data
-        field. For
+        field embeds the resource's state at the time of the change. For
 
-        example, a `charge.succeeded` event will contain a charge, and an
+        example, a `charge.succeeded` event contains a charge, and an
 
-        `invoice.payment_failed` event will contain an invoice.
+        `invoice.payment_failed` event contains an invoice.
 
 
         As with other API resources, you can use endpoints to retrieve an
@@ -11593,39 +11586,40 @@ components:
 
         [webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the
 
-        `Event` objects directly to an endpoint on your server. Webhooks are
-        managed
+        `Event` objects directly to an endpoint on your server. You can manage
+
+        webhooks in your
 
-        in your
+        [account settings](https://dashboard.stripe.com/account/webhooks). Learn
+        how
 
-        [account settings](https://dashboard.stripe.com/account/webhooks),
+        to [listen for events]
 
-        and our [Using Webhooks](https://stripe.com/docs/webhooks) guide will
-        help you get set up.
+        (/docs/webhooks) so that your integration can automatically trigger
+        reactions.
 
 
         When using [Connect](https://stripe.com/docs/connect), you can also
-        receive notifications of
+        receive event notifications
 
-        events that occur in connected accounts. For these events, there will be
-        an
+        that occur in connected accounts. For these events, there's an
 
         additional `account` attribute in the received `Event` object.
 
 
-        **NOTE:** Right now, access to events through the [Retrieve Event
-        API](https://stripe.com/docs/api#retrieve_event) is
+        We only guarantee access to events through the [Retrieve Event
+        API](https://stripe.com/docs/api#retrieve_event)
 
-        guaranteed only for 30 days.
+        for 30 days.
       properties:
         account:
-          description: The connected account that originated the event.
+          description: The connected account that originates the event.
           maxLength: 5000
           type: string
         api_version:
           description: >-
-            The Stripe API version used to render `data`. *Note: This property
-            is populated only for events on or after October 31, 2014*.
+            The Stripe API version used to render `data`. This property is
+            populated only for events on or after October 31, 2014.
           maxLength: 5000
           nullable: true
           type: string
@@ -11655,17 +11649,17 @@ components:
           type: string
         pending_webhooks:
           description: >-
-            Number of webhooks that have yet to be successfully delivered (i.e.,
-            to return a 20x response) to the URLs you've specified.
+            Number of webhooks that haven't been successfully delivered (for
+            example, to return a 20x response) to the URLs you specify.
           type: integer
         request:
           anyOf:
             - $ref: '#/components/schemas/notification_event_request'
-          description: Information on the API request that instigated the event.
+          description: Information on the API request that triggers the event.
           nullable: true
         type:
           description: >-
-            Description of the event (e.g., `invoice.created` or
+            Description of the event (for example, `invoice.created` or
             `charge.refunded`).
           enum:
             - account.application.authorized
diff --git a/openapi/spec3.json b/openapi/spec3.json
index 4cb26106..d1b4cb10 100644
--- a/openapi/spec3.json
+++ b/openapi/spec3.json
@@ -2108,14 +2108,14 @@
         ]
       },
       "balance_transaction": {
-        "description": "Balance transactions represent funds moving through your Stripe account.\nThey're created for every type of transaction that comes into or flows out of your Stripe account balance.\n\nRelated guide: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)",
+        "description": "Balance transactions represent funds moving through your Stripe account.\nStripe creates them for every type of transaction that enters or leaves your Stripe account balance.\n\nRelated guide: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)",
         "properties": {
           "amount": {
-            "description": "Gross amount of the transaction, in cents (or local equivalent).",
+            "description": "Gross amount of the transaction (in cents (or local equivalent)).",
             "type": "integer"
           },
           "available_on": {
-            "description": "The date the transaction's net funds will become available in the Stripe balance.",
+            "description": "The date that the transaction's net funds become available in the Stripe balance.",
             "format": "unix-time",
             "type": "integer"
           },
@@ -2135,7 +2135,7 @@
             "type": "string"
           },
           "exchange_rate": {
-            "description": "The exchange rate used, if applicable, for this transaction. Specifically, if money was converted from currency A to currency B, then the `amount` in currency A, times `exchange_rate`, would be the `amount` in currency B. For example, suppose you charged a customer 10.00 EUR. Then the PaymentIntent's `amount` would be `1000` and `currency` would be `eur`. Suppose this was converted into 12.34 USD in your Stripe account. Then the BalanceTransaction's `amount` would be `1234`, `currency` would be `usd`, and `exchange_rate` would be `1.234`.",
+            "description": "If applicable, this transaction uses an exchange rate. If money converts from currency A to currency B, then the `amount` in currency A, multipled by the `exchange_rate`, equals the `amount` in currency B. For example, if you charge a customer 10.00 EUR, the PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this converts to 12.34 USD in your Stripe account, the BalanceTransaction's `amount` is `1234`, its `currency` is `usd`, and the `exchange_rate` is `1.234`.",
             "nullable": true,
             "type": "number"
           },
@@ -2156,7 +2156,7 @@
             "type": "string"
           },
           "net": {
-            "description": "Net amount of the transaction, in cents (or local equivalent).",
+            "description": "Net amount of the transaction (in cents (or local equivalent)).",
             "type": "integer"
           },
           "object": {
@@ -2167,7 +2167,7 @@
             "type": "string"
           },
           "reporting_category": {
-            "description": "[Learn more](https://stripe.com/docs/reports/reporting-categories) about how reporting categories can help you understand balance transactions from an accounting perspective.",
+            "description": "Learn more about how [reporting categories] (https://stripe.com/docs/reports/reporting-categories) can help you understand balance transactions from an accounting perspective.",
             "maxLength": 5000,
             "type": "string"
           },
@@ -2229,7 +2229,7 @@
                 "$ref": "#/components/schemas/transfer_reversal"
               }
             ],
-            "description": "The Stripe object to which this transaction is related.",
+            "description": "This transaction relates to the Stripe object.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -2289,12 +2289,12 @@
             "x-stripeBypassValidation": true
           },
           "status": {
-            "description": "If the transaction's net funds are available in the Stripe balance yet. Either `available` or `pending`.",
+            "description": "The transaction's net funds status in the Stripe balance, which are either `available` or `pending`.",
             "maxLength": 5000,
             "type": "string"
           },
           "type": {
-            "description": "Transaction type: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `connect_collection_transfer`, `contribution`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_inbound`, `obligation_outbound`, `obligation_reversal_inbound`, `obligation_reversal_outbound`, `obligation_payout`, `obligation_payout_failure`, `payment`, `payment_failure_refund`, `payment_refund`, `payment_reversal`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, or `transfer_refund`. [Learn more](https://stripe.com/docs/reports/balance-transaction-types) about balance transaction types and what they represent. If you are looking to classify transactions for accounting purposes, you might want to consider `reporting_category` instead.",
+            "description": "Transaction type: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `connect_collection_transfer`, `contribution`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_inbound`, `obligation_outbound`, `obligation_reversal_inbound`, `obligation_reversal_outbound`, `obligation_payout`, `obligation_payout_failure`, `payment`, `payment_failure_refund`, `payment_refund`, `payment_reversal`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, or `transfer_refund`. Learn more about [balance transaction types and what they represent](https://stripe.com/docs/reports/balance-transaction-types). To classify transactions for accounting purposes, consider `reporting_category` instead.",
             "enum": [
               "adjustment",
               "advance",
@@ -6293,7 +6293,7 @@
         "x-expandableFields": []
       },
       "customer": {
-        "description": "This object represents a customer of your business. It lets you create recurring charges and track payments that belong to the same customer.\n\nRelated guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)",
+        "description": "This object represents a customer of your business. Use it to create recurring charges and track payments that belong to the same customer.\n\nRelated guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)",
         "properties": {
           "address": {
             "anyOf": [
@@ -6305,7 +6305,7 @@
             "nullable": true
           },
           "balance": {
-            "description": "Current balance, if any, being stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that will be added to their next invoice. The balance does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied to any invoice. This balance is only taken into account as invoices are finalized.",
+            "description": "The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.",
             "type": "integer"
           },
           "cash_balance": {
@@ -6314,7 +6314,7 @@
                 "$ref": "#/components/schemas/cash_balance"
               }
             ],
-            "description": "The current funds being held by Stripe on behalf of the customer. These funds can be applied towards payment intents with source \"cash_balance\". The settings[reconciliation_mode] field describes whether these funds are applied to such payment intents manually or automatically.",
+            "description": "The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is \"cash_balance\". The `settings[reconciliation_mode]` field describes if these funds apply to these payment intents manually or automatically.",
             "nullable": true
           },
           "created": {
@@ -6344,7 +6344,7 @@
                 "$ref": "#/components/schemas/source"
               }
             ],
-            "description": "ID of the default payment source for the customer.\n\nIf you are using payment methods created via the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.",
+            "description": "ID of the default payment source for the customer.\n\nIf you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -6362,7 +6362,7 @@
             "x-stripeBypassValidation": true
           },
           "delinquent": {
-            "description": "When the customer's latest invoice is billed by charging automatically, `delinquent` is `true` if the invoice's latest charge failed. When the customer's latest invoice is billed by sending an invoice, `delinquent` is `true` if the invoice isn't paid by its due date.\n\nIf an invoice is marked uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn't get reset to `false`.",
+            "description": "If Stripe bills the customer's latest invoice by automatically charging and the latest charge fails, it sets `delinquent`` to `true``. If Stripe bills the invoice by sending it, and the invoice isn't paid by the due date, it also sets `delinquent`` to `true`.\n\nIf an invoice becomes uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn't reset to `false`.",
             "nullable": true,
             "type": "boolean"
           },
@@ -6396,7 +6396,7 @@
             "additionalProperties": {
               "type": "integer"
             },
-            "description": "The current multi-currency balances, if any, being stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that will be added to their next invoice denominated in that currency. These balances do not refer to any unpaid invoices. They solely track amounts that have yet to be successfully applied to any invoice. A balance in a particular currency is only applied to any invoice as an invoice in that currency is finalized.",
+            "description": "The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.",
             "type": "object"
           },
           "invoice_prefix": {
@@ -6427,7 +6427,7 @@
             "type": "string"
           },
           "next_invoice_sequence": {
-            "description": "The suffix of the customer's next invoice number, e.g., 0001.",
+            "description": "The suffix of the customer's next invoice number (for example, 0001).",
             "type": "integer"
           },
           "object": {
@@ -6555,7 +6555,7 @@
             "$ref": "#/components/schemas/customer_tax"
           },
           "tax_exempt": {
-            "description": "Describes the customer's tax exemption status. One of `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the text **\"Reverse charge\"**.",
+            "description": "Describes the customer's tax exemption status, which is `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the following text: **\"Reverse charge\"**.",
             "enum": [
               "exempt",
               "none",
@@ -6613,7 +6613,7 @@
                 "$ref": "#/components/schemas/test_helpers.test_clock"
               }
             ],
-            "description": "ID of the test clock this customer belongs to.",
+            "description": "ID of the test clock that this customer belongs to.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -8386,10 +8386,10 @@
         ]
       },
       "dispute": {
-        "description": "A dispute occurs when a customer questions your charge with their card issuer.\nWhen this happens, you're given the opportunity to respond to the dispute with\nevidence that shows that the charge is legitimate. You can find more\ninformation about the dispute process in our [Disputes and\nFraud](/docs/disputes) documentation.\n\nRelated guide: [Disputes and fraud](https://stripe.com/docs/disputes)",
+        "description": "A dispute occurs when a customer questions your charge with their card issuer.\nWhen this happens, you have the opportunity to respond to the dispute with\nevidence that shows that the charge is legitimate.\n\nRelated guide: [Disputes and fraud](https://stripe.com/docs/disputes)",
         "properties": {
           "amount": {
-            "description": "Disputed amount. Usually the amount of the charge, but can differ (usually because of currency fluctuation or because only part of the order is disputed).",
+            "description": "Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).",
             "type": "integer"
           },
           "balance_transactions": {
@@ -8409,7 +8409,7 @@
                 "$ref": "#/components/schemas/charge"
               }
             ],
-            "description": "ID of the charge that was disputed.",
+            "description": "ID of the charge that's disputed.",
             "x-expansionResources": {
               "oneOf": [
                 {
@@ -8439,7 +8439,7 @@
             "type": "string"
           },
           "is_charge_refundable": {
-            "description": "If true, it is still possible to refund the disputed payment. Once the payment has been fully refunded, no further funds will be withdrawn from your Stripe account as a result of this dispute.",
+            "description": "If true, it's still possible to refund the disputed payment. After the payment has been fully refunded, no further funds are withdrawn from your Stripe account as a result of this dispute.",
             "type": "boolean"
           },
           "livemode": {
@@ -8471,7 +8471,7 @@
                 "$ref": "#/components/schemas/payment_intent"
               }
             ],
-            "description": "ID of the PaymentIntent that was disputed.",
+            "description": "ID of the PaymentIntent that's disputed.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -8485,7 +8485,7 @@
             "$ref": "#/components/schemas/dispute_payment_method_details"
           },
           "reason": {
-            "description": "Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Read more about [dispute reasons](https://stripe.com/docs/disputes/categories).",
+            "description": "Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Learn more about [dispute reasons](https://stripe.com/docs/disputes/categories).",
             "maxLength": 5000,
             "type": "string"
           },
@@ -9001,15 +9001,15 @@
         "type": "object"
       },
       "event": {
-        "description": "Events are our way of letting you know when something interesting happens in\nyour account. When an interesting event occurs, we create a new `Event`\nobject. For example, when a charge succeeds, we create a `charge.succeeded`\nevent; and when an invoice payment attempt fails, we create an\n`invoice.payment_failed` event. Note that many API requests may cause multiple\nevents to be created. For example, if you create a new subscription for a\ncustomer, you will receive both a `customer.subscription.created` event and a\n`charge.succeeded` event.\n\nEvents occur when the state of another API resource changes. The state of that\nresource at the time of the change is embedded in the event's data field. For\nexample, a `charge.succeeded` event will contain a charge, and an\n`invoice.payment_failed` event will contain an invoice.\n\nAs with other API resources, you can use endpoints to retrieve an\n[individual event](https://stripe.com/docs/api#retrieve_event) or a [list of events](https://stripe.com/docs/api#list_events)\nfrom the API. We also have a separate\n[webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the\n`Event` objects directly to an endpoint on your server. Webhooks are managed\nin your\n[account settings](https://dashboard.stripe.com/account/webhooks),\nand our [Using Webhooks](https://stripe.com/docs/webhooks) guide will help you get set up.\n\nWhen using [Connect](https://stripe.com/docs/connect), you can also receive notifications of\nevents that occur in connected accounts. For these events, there will be an\nadditional `account` attribute in the received `Event` object.\n\n**NOTE:** Right now, access to events through the [Retrieve Event API](https://stripe.com/docs/api#retrieve_event) is\nguaranteed only for 30 days.",
+        "description": "Events are our way of letting you know when something interesting happens in\nyour account. When an interesting event occurs, we create a new `Event`\nobject. For example, when a charge succeeds, we create a `charge.succeeded`\nevent, and when an invoice payment attempt fails, we create an\n`invoice.payment_failed` event. Certain API requests might create multiple\nevents. For example, if you create a new subscription for a\ncustomer, you receive both a `customer.subscription.created` event and a\n`charge.succeeded` event.\n\nEvents occur when the state of another API resource changes. The event's data\nfield embeds the resource's state at the time of the change. For\nexample, a `charge.succeeded` event contains a charge, and an\n`invoice.payment_failed` event contains an invoice.\n\nAs with other API resources, you can use endpoints to retrieve an\n[individual event](https://stripe.com/docs/api#retrieve_event) or a [list of events](https://stripe.com/docs/api#list_events)\nfrom the API. We also have a separate\n[webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the\n`Event` objects directly to an endpoint on your server. You can manage\nwebhooks in your\n[account settings](https://dashboard.stripe.com/account/webhooks). Learn how\nto [listen for events]\n(/docs/webhooks) so that your integration can automatically trigger reactions.\n\nWhen using [Connect](https://stripe.com/docs/connect), you can also receive event notifications\nthat occur in connected accounts. For these events, there's an\nadditional `account` attribute in the received `Event` object.\n\nWe only guarantee access to events through the [Retrieve Event API](https://stripe.com/docs/api#retrieve_event)\nfor 30 days.",
         "properties": {
           "account": {
-            "description": "The connected account that originated the event.",
+            "description": "The connected account that originates the event.",
             "maxLength": 5000,
             "type": "string"
           },
           "api_version": {
-            "description": "The Stripe API version used to render `data`. *Note: This property is populated only for events on or after October 31, 2014*.",
+            "description": "The Stripe API version used to render `data`. This property is populated only for events on or after October 31, 2014.",
             "maxLength": 5000,
             "nullable": true,
             "type": "string"
@@ -9039,7 +9039,7 @@
             "type": "string"
           },
           "pending_webhooks": {
-            "description": "Number of webhooks that have yet to be successfully delivered (i.e., to return a 20x response) to the URLs you've specified.",
+            "description": "Number of webhooks that haven't been successfully delivered (for example, to return a 20x response) to the URLs you specify.",
             "type": "integer"
           },
           "request": {
@@ -9048,11 +9048,11 @@
                 "$ref": "#/components/schemas/notification_event_request"
               }
             ],
-            "description": "Information on the API request that instigated the event.",
+            "description": "Information on the API request that triggers the event.",
             "nullable": true
           },
           "type": {
-            "description": "Description of the event (e.g., `invoice.created` or `charge.refunded`).",
+            "description": "Description of the event (for example, `invoice.created` or `charge.refunded`).",
             "maxLength": 5000,
             "type": "string"
           }
diff --git a/openapi/spec3.sdk.json b/openapi/spec3.sdk.json
index bbe5a565..84db3a73 100644
--- a/openapi/spec3.sdk.json
+++ b/openapi/spec3.sdk.json
@@ -2650,14 +2650,14 @@
         }
       },
       "balance_transaction": {
-        "description": "Balance transactions represent funds moving through your Stripe account.\nThey're created for every type of transaction that comes into or flows out of your Stripe account balance.\n\nRelated guide: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)",
+        "description": "Balance transactions represent funds moving through your Stripe account.\nStripe creates them for every type of transaction that enters or leaves your Stripe account balance.\n\nRelated guide: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)",
         "properties": {
           "amount": {
-            "description": "Gross amount of the transaction, in cents (or local equivalent).",
+            "description": "Gross amount of the transaction (in cents (or local equivalent)).",
             "type": "integer"
           },
           "available_on": {
-            "description": "The date the transaction's net funds will become available in the Stripe balance.",
+            "description": "The date that the transaction's net funds become available in the Stripe balance.",
             "format": "unix-time",
             "type": "integer"
           },
@@ -2677,7 +2677,7 @@
             "type": "string"
           },
           "exchange_rate": {
-            "description": "The exchange rate used, if applicable, for this transaction. Specifically, if money was converted from currency A to currency B, then the `amount` in currency A, times `exchange_rate`, would be the `amount` in currency B. For example, suppose you charged a customer 10.00 EUR. Then the PaymentIntent's `amount` would be `1000` and `currency` would be `eur`. Suppose this was converted into 12.34 USD in your Stripe account. Then the BalanceTransaction's `amount` would be `1234`, `currency` would be `usd`, and `exchange_rate` would be `1.234`.",
+            "description": "If applicable, this transaction uses an exchange rate. If money converts from currency A to currency B, then the `amount` in currency A, multipled by the `exchange_rate`, equals the `amount` in currency B. For example, if you charge a customer 10.00 EUR, the PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this converts to 12.34 USD in your Stripe account, the BalanceTransaction's `amount` is `1234`, its `currency` is `usd`, and the `exchange_rate` is `1.234`.",
             "nullable": true,
             "type": "number"
           },
@@ -2698,7 +2698,7 @@
             "type": "string"
           },
           "net": {
-            "description": "Net amount of the transaction, in cents (or local equivalent).",
+            "description": "Net amount of the transaction (in cents (or local equivalent)).",
             "type": "integer"
           },
           "object": {
@@ -2709,7 +2709,7 @@
             "type": "string"
           },
           "reporting_category": {
-            "description": "[Learn more](https://stripe.com/docs/reports/reporting-categories) about how reporting categories can help you understand balance transactions from an accounting perspective.",
+            "description": "Learn more about how [reporting categories] (https://stripe.com/docs/reports/reporting-categories) can help you understand balance transactions from an accounting perspective.",
             "maxLength": 5000,
             "type": "string"
           },
@@ -2723,7 +2723,7 @@
                 "$ref": "#/components/schemas/balance_transaction_source"
               }
             ],
-            "description": "The Stripe object to which this transaction is related.",
+            "description": "This transaction relates to the Stripe object.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -2734,12 +2734,12 @@
             }
           },
           "status": {
-            "description": "If the transaction's net funds are available in the Stripe balance yet. Either `available` or `pending`.",
+            "description": "The transaction's net funds status in the Stripe balance, which are either `available` or `pending`.",
             "maxLength": 5000,
             "type": "string"
           },
           "type": {
-            "description": "Transaction type: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `connect_collection_transfer`, `contribution`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_inbound`, `obligation_outbound`, `obligation_reversal_inbound`, `obligation_reversal_outbound`, `obligation_payout`, `obligation_payout_failure`, `payment`, `payment_failure_refund`, `payment_refund`, `payment_reversal`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, or `transfer_refund`. [Learn more](https://stripe.com/docs/reports/balance-transaction-types) about balance transaction types and what they represent. If you are looking to classify transactions for accounting purposes, you might want to consider `reporting_category` instead.",
+            "description": "Transaction type: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `connect_collection_transfer`, `contribution`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_inbound`, `obligation_outbound`, `obligation_reversal_inbound`, `obligation_reversal_outbound`, `obligation_payout`, `obligation_payout_failure`, `payment`, `payment_failure_refund`, `payment_refund`, `payment_reversal`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, or `transfer_refund`. Learn more about [balance transaction types and what they represent](https://stripe.com/docs/reports/balance-transaction-types). To classify transactions for accounting purposes, consider `reporting_category` instead.",
             "enum": [
               "adjustment",
               "advance",
@@ -7661,7 +7661,7 @@
         }
       },
       "customer": {
-        "description": "This object represents a customer of your business. It lets you create recurring charges and track payments that belong to the same customer.\n\nRelated guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)",
+        "description": "This object represents a customer of your business. Use it to create recurring charges and track payments that belong to the same customer.\n\nRelated guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)",
         "properties": {
           "address": {
             "anyOf": [
@@ -7673,7 +7673,7 @@
             "nullable": true
           },
           "balance": {
-            "description": "Current balance, if any, being stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that will be added to their next invoice. The balance does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied to any invoice. This balance is only taken into account as invoices are finalized.",
+            "description": "The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.",
             "type": "integer"
           },
           "cash_balance": {
@@ -7682,7 +7682,7 @@
                 "$ref": "#/components/schemas/cash_balance"
               }
             ],
-            "description": "The current funds being held by Stripe on behalf of the customer. These funds can be applied towards payment intents with source \"cash_balance\". The settings[reconciliation_mode] field describes whether these funds are applied to such payment intents manually or automatically.",
+            "description": "The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is \"cash_balance\". The `settings[reconciliation_mode]` field describes if these funds apply to these payment intents manually or automatically.",
             "nullable": true
           },
           "created": {
@@ -7706,7 +7706,7 @@
                 "$ref": "#/components/schemas/payment_source"
               }
             ],
-            "description": "ID of the default payment source for the customer.\n\nIf you are using payment methods created via the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.",
+            "description": "ID of the default payment source for the customer.\n\nIf you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -7717,7 +7717,7 @@
             }
           },
           "delinquent": {
-            "description": "When the customer's latest invoice is billed by charging automatically, `delinquent` is `true` if the invoice's latest charge failed. When the customer's latest invoice is billed by sending an invoice, `delinquent` is `true` if the invoice isn't paid by its due date.\n\nIf an invoice is marked uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn't get reset to `false`.",
+            "description": "If Stripe bills the customer's latest invoice by automatically charging and the latest charge fails, it sets `delinquent`` to `true``. If Stripe bills the invoice by sending it, and the invoice isn't paid by the due date, it also sets `delinquent`` to `true`.\n\nIf an invoice becomes uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn't reset to `false`.",
             "nullable": true,
             "type": "boolean"
           },
@@ -7751,7 +7751,7 @@
             "additionalProperties": {
               "type": "integer"
             },
-            "description": "The current multi-currency balances, if any, being stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that will be added to their next invoice denominated in that currency. These balances do not refer to any unpaid invoices. They solely track amounts that have yet to be successfully applied to any invoice. A balance in a particular currency is only applied to any invoice as an invoice in that currency is finalized.",
+            "description": "The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.",
             "type": "object"
           },
           "invoice_prefix": {
@@ -7782,7 +7782,7 @@
             "type": "string"
           },
           "next_invoice_sequence": {
-            "description": "The suffix of the customer's next invoice number, e.g., 0001.",
+            "description": "The suffix of the customer's next invoice number (for example, 0001).",
             "type": "integer"
           },
           "object": {
@@ -7898,7 +7898,7 @@
             "$ref": "#/components/schemas/customer_tax"
           },
           "tax_exempt": {
-            "description": "Describes the customer's tax exemption status. One of `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the text **\"Reverse charge\"**.",
+            "description": "Describes the customer's tax exemption status, which is `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the following text: **\"Reverse charge\"**.",
             "enum": [
               "exempt",
               "none",
@@ -7956,7 +7956,7 @@
                 "$ref": "#/components/schemas/test_helpers.test_clock"
               }
             ],
-            "description": "ID of the test clock this customer belongs to.",
+            "description": "ID of the test clock that this customer belongs to.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -10121,10 +10121,10 @@
         }
       },
       "dispute": {
-        "description": "A dispute occurs when a customer questions your charge with their card issuer.\nWhen this happens, you're given the opportunity to respond to the dispute with\nevidence that shows that the charge is legitimate. You can find more\ninformation about the dispute process in our [Disputes and\nFraud](/docs/disputes) documentation.\n\nRelated guide: [Disputes and fraud](https://stripe.com/docs/disputes)",
+        "description": "A dispute occurs when a customer questions your charge with their card issuer.\nWhen this happens, you have the opportunity to respond to the dispute with\nevidence that shows that the charge is legitimate.\n\nRelated guide: [Disputes and fraud](https://stripe.com/docs/disputes)",
         "properties": {
           "amount": {
-            "description": "Disputed amount. Usually the amount of the charge, but can differ (usually because of currency fluctuation or because only part of the order is disputed).",
+            "description": "Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).",
             "type": "integer"
           },
           "balance_transactions": {
@@ -10144,7 +10144,7 @@
                 "$ref": "#/components/schemas/charge"
               }
             ],
-            "description": "ID of the charge that was disputed.",
+            "description": "ID of the charge that's disputed.",
             "x-expansionResources": {
               "oneOf": [
                 {
@@ -10174,7 +10174,7 @@
             "type": "string"
           },
           "is_charge_refundable": {
-            "description": "If true, it is still possible to refund the disputed payment. Once the payment has been fully refunded, no further funds will be withdrawn from your Stripe account as a result of this dispute.",
+            "description": "If true, it's still possible to refund the disputed payment. After the payment has been fully refunded, no further funds are withdrawn from your Stripe account as a result of this dispute.",
             "type": "boolean"
           },
           "livemode": {
@@ -10212,7 +10212,7 @@
                 "$ref": "#/components/schemas/payment_intent"
               }
             ],
-            "description": "ID of the PaymentIntent that was disputed.",
+            "description": "ID of the PaymentIntent that's disputed.",
             "nullable": true,
             "x-expansionResources": {
               "oneOf": [
@@ -10226,7 +10226,7 @@
             "$ref": "#/components/schemas/dispute_payment_method_details"
           },
           "reason": {
-            "description": "Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Read more about [dispute reasons](https://stripe.com/docs/disputes/categories).",
+            "description": "Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Learn more about [dispute reasons](https://stripe.com/docs/disputes/categories).",
             "maxLength": 5000,
             "type": "string"
           },
@@ -10857,15 +10857,15 @@
         }
       },
       "event": {
-        "description": "Events are our way of letting you know when something interesting happens in\nyour account. When an interesting event occurs, we create a new `Event`\nobject. For example, when a charge succeeds, we create a `charge.succeeded`\nevent; and when an invoice payment attempt fails, we create an\n`invoice.payment_failed` event. Note that many API requests may cause multiple\nevents to be created. For example, if you create a new subscription for a\ncustomer, you will receive both a `customer.subscription.created` event and a\n`charge.succeeded` event.\n\nEvents occur when the state of another API resource changes. The state of that\nresource at the time of the change is embedded in the event's data field. For\nexample, a `charge.succeeded` event will contain a charge, and an\n`invoice.payment_failed` event will contain an invoice.\n\nAs with other API resources, you can use endpoints to retrieve an\n[individual event](https://stripe.com/docs/api#retrieve_event) or a [list of events](https://stripe.com/docs/api#list_events)\nfrom the API. We also have a separate\n[webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the\n`Event` objects directly to an endpoint on your server. Webhooks are managed\nin your\n[account settings](https://dashboard.stripe.com/account/webhooks),\nand our [Using Webhooks](https://stripe.com/docs/webhooks) guide will help you get set up.\n\nWhen using [Connect](https://stripe.com/docs/connect), you can also receive notifications of\nevents that occur in connected accounts. For these events, there will be an\nadditional `account` attribute in the received `Event` object.\n\n**NOTE:** Right now, access to events through the [Retrieve Event API](https://stripe.com/docs/api#retrieve_event) is\nguaranteed only for 30 days.",
+        "description": "Events are our way of letting you know when something interesting happens in\nyour account. When an interesting event occurs, we create a new `Event`\nobject. For example, when a charge succeeds, we create a `charge.succeeded`\nevent, and when an invoice payment attempt fails, we create an\n`invoice.payment_failed` event. Certain API requests might create multiple\nevents. For example, if you create a new subscription for a\ncustomer, you receive both a `customer.subscription.created` event and a\n`charge.succeeded` event.\n\nEvents occur when the state of another API resource changes. The event's data\nfield embeds the resource's state at the time of the change. For\nexample, a `charge.succeeded` event contains a charge, and an\n`invoice.payment_failed` event contains an invoice.\n\nAs with other API resources, you can use endpoints to retrieve an\n[individual event](https://stripe.com/docs/api#retrieve_event) or a [list of events](https://stripe.com/docs/api#list_events)\nfrom the API. We also have a separate\n[webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the\n`Event` objects directly to an endpoint on your server. You can manage\nwebhooks in your\n[account settings](https://dashboard.stripe.com/account/webhooks). Learn how\nto [listen for events]\n(/docs/webhooks) so that your integration can automatically trigger reactions.\n\nWhen using [Connect](https://stripe.com/docs/connect), you can also receive event notifications\nthat occur in connected accounts. For these events, there's an\nadditional `account` attribute in the received `Event` object.\n\nWe only guarantee access to events through the [Retrieve Event API](https://stripe.com/docs/api#retrieve_event)\nfor 30 days.",
         "properties": {
           "account": {
-            "description": "The connected account that originated the event.",
+            "description": "The connected account that originates the event.",
             "maxLength": 5000,
             "type": "string"
           },
           "api_version": {
-            "description": "The Stripe API version used to render `data`. *Note: This property is populated only for events on or after October 31, 2014*.",
+            "description": "The Stripe API version used to render `data`. This property is populated only for events on or after October 31, 2014.",
             "maxLength": 5000,
             "nullable": true,
             "type": "string"
@@ -10895,7 +10895,7 @@
             "type": "string"
           },
           "pending_webhooks": {
-            "description": "Number of webhooks that have yet to be successfully delivered (i.e., to return a 20x response) to the URLs you've specified.",
+            "description": "Number of webhooks that haven't been successfully delivered (for example, to return a 20x response) to the URLs you specify.",
             "type": "integer"
           },
           "request": {
@@ -10904,11 +10904,11 @@
                 "$ref": "#/components/schemas/notification_event_request"
               }
             ],
-            "description": "Information on the API request that instigated the event.",
+            "description": "Information on the API request that triggers the event.",
             "nullable": true
           },
           "type": {
-            "description": "Description of the event (e.g., `invoice.created` or `charge.refunded`).",
+            "description": "Description of the event (for example, `invoice.created` or `charge.refunded`).",
             "enum": [
               "account.application.authorized",
               "account.application.deauthorized",
diff --git a/openapi/spec3.sdk.yaml b/openapi/spec3.sdk.yaml
index 59ab339b..348a886b 100644
--- a/openapi/spec3.sdk.yaml
+++ b/openapi/spec3.sdk.yaml
@@ -2564,19 +2564,19 @@ components:
       description: >-
         Balance transactions represent funds moving through your Stripe account.
 
-        They're created for every type of transaction that comes into or flows
-        out of your Stripe account balance.
+        Stripe creates them for every type of transaction that enters or leaves
+        your Stripe account balance.
 
 
         Related guide: [Balance transaction
         types](https://stripe.com/docs/reports/balance-transaction-types)
       properties:
         amount:
-          description: 'Gross amount of the transaction, in cents (or local equivalent).'
+          description: Gross amount of the transaction (in cents (or local equivalent)).
           type: integer
         available_on:
           description: >-
-            The date the transaction's net funds will become available in the
+            The date that the transaction's net funds become available in the
             Stripe balance.
           format: unix-time
           type: integer
@@ -2602,15 +2602,14 @@ components:
           type: string
         exchange_rate:
           description: >-
-            The exchange rate used, if applicable, for this transaction.
-            Specifically, if money was converted from currency A to currency B,
-            then the `amount` in currency A, times `exchange_rate`, would be the
-            `amount` in currency B. For example, suppose you charged a customer
-            10.00 EUR. Then the PaymentIntent's `amount` would be `1000` and
-            `currency` would be `eur`. Suppose this was converted into 12.34 USD
-            in your Stripe account. Then the BalanceTransaction's `amount` would
-            be `1234`, `currency` would be `usd`, and `exchange_rate` would be
-            `1.234`.
+            If applicable, this transaction uses an exchange rate. If money
+            converts from currency A to currency B, then the `amount` in
+            currency A, multipled by the `exchange_rate`, equals the `amount` in
+            currency B. For example, if you charge a customer 10.00 EUR, the
+            PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this
+            converts to 12.34 USD in your Stripe account, the
+            BalanceTransaction's `amount` is `1234`, its `currency` is `usd`,
+            and the `exchange_rate` is `1.234`.
           nullable: true
           type: number
         fee:
@@ -2628,7 +2627,7 @@ components:
           maxLength: 5000
           type: string
         net:
-          description: 'Net amount of the transaction, in cents (or local equivalent).'
+          description: Net amount of the transaction (in cents (or local equivalent)).
           type: integer
         object:
           description: >-
@@ -2639,9 +2638,9 @@ components:
           type: string
         reporting_category:
           description: >-
-            [Learn more](https://stripe.com/docs/reports/reporting-categories)
-            about how reporting categories can help you understand balance
-            transactions from an accounting perspective.
+            Learn more about how [reporting categories]
+            (https://stripe.com/docs/reports/reporting-categories) can help you
+            understand balance transactions from an accounting perspective.
           maxLength: 5000
           type: string
         source:
@@ -2649,15 +2648,15 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/balance_transaction_source'
-          description: The Stripe object to which this transaction is related.
+          description: This transaction relates to the Stripe object.
           nullable: true
           x-expansionResources:
             oneOf:
               - $ref: '#/components/schemas/balance_transaction_source'
         status:
           description: >-
-            If the transaction's net funds are available in the Stripe balance
-            yet. Either `available` or `pending`.
+            The transaction's net funds status in the Stripe balance, which are
+            either `available` or `pending`.
           maxLength: 5000
           type: string
         type:
@@ -2675,11 +2674,11 @@ components:
             `refund_failure`, `reserve_transaction`, `reserved_funds`,
             `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`,
             `transfer`, `transfer_cancel`, `transfer_failure`, or
-            `transfer_refund`. [Learn
-            more](https://stripe.com/docs/reports/balance-transaction-types)
-            about balance transaction types and what they represent. If you are
-            looking to classify transactions for accounting purposes, you might
-            want to consider `reporting_category` instead.
+            `transfer_refund`. Learn more about [balance transaction types and
+            what they
+            represent](https://stripe.com/docs/reports/balance-transaction-types).
+            To classify transactions for accounting purposes, consider
+            `reporting_category` instead.
           enum:
             - adjustment
             - advance
@@ -7493,7 +7492,7 @@ components:
         in_package: ''
     customer:
       description: >-
-        This object represents a customer of your business. It lets you create
+        This object represents a customer of your business. Use it to create
         recurring charges and track payments that belong to the same customer.
 
 
@@ -7507,22 +7506,22 @@ components:
           nullable: true
         balance:
           description: >-
-            Current balance, if any, being stored on the customer. If negative,
-            the customer has credit to apply to their next invoice. If positive,
-            the customer has an amount owed that will be added to their next
-            invoice. The balance does not refer to any unpaid invoices; it
-            solely takes into account amounts that have yet to be successfully
-            applied to any invoice. This balance is only taken into account as
-            invoices are finalized.
+            The current balance, if any, that's stored on the customer. If
+            negative, the customer has credit to apply to their next invoice. If
+            positive, the customer has an amount owed that's added to their next
+            invoice. The balance only considers amounts that Stripe hasn't
+            successfully applied to any invoice. It doesn't reflect unpaid
+            invoices. This balance is only taken into account after invoices
+            finalize.
           type: integer
         cash_balance:
           anyOf:
             - $ref: '#/components/schemas/cash_balance'
           description: >-
             The current funds being held by Stripe on behalf of the customer.
-            These funds can be applied towards payment intents with source
-            "cash_balance". The settings[reconciliation_mode] field describes
-            whether these funds are applied to such payment intents manually or
+            You can apply these funds towards payment intents when the source is
+            "cash_balance". The `settings[reconciliation_mode]` field describes
+            if these funds apply to these payment intents manually or
             automatically.
           nullable: true
         created:
@@ -7548,7 +7547,7 @@ components:
             ID of the default payment source for the customer.
 
 
-            If you are using payment methods created via the PaymentMethods API,
+            If you use payment methods created through the PaymentMethods API,
             see the
             [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method)
             field instead.
@@ -7558,16 +7557,15 @@ components:
               - $ref: '#/components/schemas/payment_source'
         delinquent:
           description: >-
-            When the customer's latest invoice is billed by charging
-            automatically, `delinquent` is `true` if the invoice's latest charge
-            failed. When the customer's latest invoice is billed by sending an
-            invoice, `delinquent` is `true` if the invoice isn't paid by its due
-            date.
+            If Stripe bills the customer's latest invoice by automatically
+            charging and the latest charge fails, it sets `delinquent`` to
+            `true``. If Stripe bills the invoice by sending it, and the invoice
+            isn't paid by the due date, it also sets `delinquent`` to `true`.
 
 
-            If an invoice is marked uncollectible by
+            If an invoice becomes uncollectible by
             [dunning](https://stripe.com/docs/billing/automatic-collection),
-            `delinquent` doesn't get reset to `false`.
+            `delinquent` doesn't reset to `false`.
           nullable: true
           type: boolean
         description:
@@ -7597,15 +7595,15 @@ components:
           additionalProperties:
             type: integer
           description: >-
-            The current multi-currency balances, if any, being stored on the
+            The current multi-currency balances, if any, that's stored on the
             customer. If positive in a currency, the customer has a credit to
             apply to their next invoice denominated in that currency. If
-            negative, the customer has an amount owed that will be added to
-            their next invoice denominated in that currency. These balances do
-            not refer to any unpaid invoices. They solely track amounts that
-            have yet to be successfully applied to any invoice. A balance in a
-            particular currency is only applied to any invoice as an invoice in
-            that currency is finalized.
+            negative, the customer has an amount owed that's added to their next
+            invoice denominated in that currency. These balances don't apply to
+            unpaid invoices. They solely track amounts that Stripe hasn't
+            successfully applied to any invoice. Stripe only applies a balance
+            in a specific currency to an invoice after that invoice (which is in
+            the same currency) finalizes.
           type: object
         invoice_prefix:
           description: The prefix for the customer used to generate unique invoice numbers.
@@ -7634,7 +7632,9 @@ components:
           nullable: true
           type: string
         next_invoice_sequence:
-          description: 'The suffix of the customer''s next invoice number, e.g., 0001.'
+          description: >-
+            The suffix of the customer's next invoice number (for example,
+            0001).
           type: integer
         object:
           description: >-
@@ -7732,9 +7732,9 @@ components:
           $ref: '#/components/schemas/customer_tax'
         tax_exempt:
           description: >-
-            Describes the customer's tax exemption status. One of `none`,
+            Describes the customer's tax exemption status, which is `none`,
             `exempt`, or `reverse`. When set to `reverse`, invoice and receipt
-            PDFs include the text **"Reverse charge"**.
+            PDFs include the following text: **"Reverse charge"**.
           enum:
             - exempt
             - none
@@ -7779,7 +7779,7 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/test_helpers.test_clock'
-          description: ID of the test clock this customer belongs to.
+          description: ID of the test clock that this customer belongs to.
           nullable: true
           x-expansionResources:
             oneOf:
@@ -9566,21 +9566,17 @@ components:
         A dispute occurs when a customer questions your charge with their card
         issuer.
 
-        When this happens, you're given the opportunity to respond to the
-        dispute with
-
-        evidence that shows that the charge is legitimate. You can find more
-
-        information about the dispute process in our [Disputes and
+        When this happens, you have the opportunity to respond to the dispute
+        with
 
-        Fraud](/docs/disputes) documentation.
+        evidence that shows that the charge is legitimate.
 
 
         Related guide: [Disputes and fraud](https://stripe.com/docs/disputes)
       properties:
         amount:
           description: >-
-            Disputed amount. Usually the amount of the charge, but can differ
+            Disputed amount. Usually the amount of the charge, but it can differ
             (usually because of currency fluctuation or because only part of the
             order is disputed).
           type: integer
@@ -9597,7 +9593,7 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/charge'
-          description: ID of the charge that was disputed.
+          description: ID of the charge that's disputed.
           x-expansionResources:
             oneOf:
               - $ref: '#/components/schemas/charge'
@@ -9624,9 +9620,9 @@ components:
           type: string
         is_charge_refundable:
           description: >-
-            If true, it is still possible to refund the disputed payment. Once
-            the payment has been fully refunded, no further funds will be
-            withdrawn from your Stripe account as a result of this dispute.
+            If true, it's still possible to refund the disputed payment. After
+            the payment has been fully refunded, no further funds are withdrawn
+            from your Stripe account as a result of this dispute.
           type: boolean
         livemode:
           description: >-
@@ -9659,7 +9655,7 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/payment_intent'
-          description: ID of the PaymentIntent that was disputed.
+          description: ID of the PaymentIntent that's disputed.
           nullable: true
           x-expansionResources:
             oneOf:
@@ -9674,7 +9670,7 @@ components:
             `fraudulent`, `general`, `incorrect_account_details`,
             `insufficient_funds`, `product_not_received`,
             `product_unacceptable`, `subscription_canceled`, or `unrecognized`.
-            Read more about [dispute
+            Learn more about [dispute
             reasons](https://stripe.com/docs/disputes/categories).
           maxLength: 5000
           type: string
@@ -10216,29 +10212,26 @@ components:
         object. For example, when a charge succeeds, we create a
         `charge.succeeded`
 
-        event; and when an invoice payment attempt fails, we create an
+        event, and when an invoice payment attempt fails, we create an
 
-        `invoice.payment_failed` event. Note that many API requests may cause
+        `invoice.payment_failed` event. Certain API requests might create
         multiple
 
-        events to be created. For example, if you create a new subscription for
-        a
+        events. For example, if you create a new subscription for a
 
-        customer, you will receive both a `customer.subscription.created` event
-        and a
+        customer, you receive both a `customer.subscription.created` event and a
 
         `charge.succeeded` event.
 
 
-        Events occur when the state of another API resource changes. The state
-        of that
+        Events occur when the state of another API resource changes. The event's
+        data
 
-        resource at the time of the change is embedded in the event's data
-        field. For
+        field embeds the resource's state at the time of the change. For
 
-        example, a `charge.succeeded` event will contain a charge, and an
+        example, a `charge.succeeded` event contains a charge, and an
 
-        `invoice.payment_failed` event will contain an invoice.
+        `invoice.payment_failed` event contains an invoice.
 
 
         As with other API resources, you can use endpoints to retrieve an
@@ -10250,39 +10243,40 @@ components:
 
         [webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the
 
-        `Event` objects directly to an endpoint on your server. Webhooks are
-        managed
+        `Event` objects directly to an endpoint on your server. You can manage
+
+        webhooks in your
 
-        in your
+        [account settings](https://dashboard.stripe.com/account/webhooks). Learn
+        how
 
-        [account settings](https://dashboard.stripe.com/account/webhooks),
+        to [listen for events]
 
-        and our [Using Webhooks](https://stripe.com/docs/webhooks) guide will
-        help you get set up.
+        (/docs/webhooks) so that your integration can automatically trigger
+        reactions.
 
 
         When using [Connect](https://stripe.com/docs/connect), you can also
-        receive notifications of
+        receive event notifications
 
-        events that occur in connected accounts. For these events, there will be
-        an
+        that occur in connected accounts. For these events, there's an
 
         additional `account` attribute in the received `Event` object.
 
 
-        **NOTE:** Right now, access to events through the [Retrieve Event
-        API](https://stripe.com/docs/api#retrieve_event) is
+        We only guarantee access to events through the [Retrieve Event
+        API](https://stripe.com/docs/api#retrieve_event)
 
-        guaranteed only for 30 days.
+        for 30 days.
       properties:
         account:
-          description: The connected account that originated the event.
+          description: The connected account that originates the event.
           maxLength: 5000
           type: string
         api_version:
           description: >-
-            The Stripe API version used to render `data`. *Note: This property
-            is populated only for events on or after October 31, 2014*.
+            The Stripe API version used to render `data`. This property is
+            populated only for events on or after October 31, 2014.
           maxLength: 5000
           nullable: true
           type: string
@@ -10312,17 +10306,17 @@ components:
           type: string
         pending_webhooks:
           description: >-
-            Number of webhooks that have yet to be successfully delivered (i.e.,
-            to return a 20x response) to the URLs you've specified.
+            Number of webhooks that haven't been successfully delivered (for
+            example, to return a 20x response) to the URLs you specify.
           type: integer
         request:
           anyOf:
             - $ref: '#/components/schemas/notification_event_request'
-          description: Information on the API request that instigated the event.
+          description: Information on the API request that triggers the event.
           nullable: true
         type:
           description: >-
-            Description of the event (e.g., `invoice.created` or
+            Description of the event (for example, `invoice.created` or
             `charge.refunded`).
           enum:
             - account.application.authorized
diff --git a/openapi/spec3.yaml b/openapi/spec3.yaml
index e17c40b8..5b9219c9 100644
--- a/openapi/spec3.yaml
+++ b/openapi/spec3.yaml
@@ -2112,19 +2112,19 @@ components:
       description: >-
         Balance transactions represent funds moving through your Stripe account.
 
-        They're created for every type of transaction that comes into or flows
-        out of your Stripe account balance.
+        Stripe creates them for every type of transaction that enters or leaves
+        your Stripe account balance.
 
 
         Related guide: [Balance transaction
         types](https://stripe.com/docs/reports/balance-transaction-types)
       properties:
         amount:
-          description: 'Gross amount of the transaction, in cents (or local equivalent).'
+          description: Gross amount of the transaction (in cents (or local equivalent)).
           type: integer
         available_on:
           description: >-
-            The date the transaction's net funds will become available in the
+            The date that the transaction's net funds become available in the
             Stripe balance.
           format: unix-time
           type: integer
@@ -2150,15 +2150,14 @@ components:
           type: string
         exchange_rate:
           description: >-
-            The exchange rate used, if applicable, for this transaction.
-            Specifically, if money was converted from currency A to currency B,
-            then the `amount` in currency A, times `exchange_rate`, would be the
-            `amount` in currency B. For example, suppose you charged a customer
-            10.00 EUR. Then the PaymentIntent's `amount` would be `1000` and
-            `currency` would be `eur`. Suppose this was converted into 12.34 USD
-            in your Stripe account. Then the BalanceTransaction's `amount` would
-            be `1234`, `currency` would be `usd`, and `exchange_rate` would be
-            `1.234`.
+            If applicable, this transaction uses an exchange rate. If money
+            converts from currency A to currency B, then the `amount` in
+            currency A, multipled by the `exchange_rate`, equals the `amount` in
+            currency B. For example, if you charge a customer 10.00 EUR, the
+            PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this
+            converts to 12.34 USD in your Stripe account, the
+            BalanceTransaction's `amount` is `1234`, its `currency` is `usd`,
+            and the `exchange_rate` is `1.234`.
           nullable: true
           type: number
         fee:
@@ -2176,7 +2175,7 @@ components:
           maxLength: 5000
           type: string
         net:
-          description: 'Net amount of the transaction, in cents (or local equivalent).'
+          description: Net amount of the transaction (in cents (or local equivalent)).
           type: integer
         object:
           description: >-
@@ -2187,9 +2186,9 @@ components:
           type: string
         reporting_category:
           description: >-
-            [Learn more](https://stripe.com/docs/reports/reporting-categories)
-            about how reporting categories can help you understand balance
-            transactions from an accounting perspective.
+            Learn more about how [reporting categories]
+            (https://stripe.com/docs/reports/reporting-categories) can help you
+            understand balance transactions from an accounting perspective.
           maxLength: 5000
           type: string
         source:
@@ -2213,7 +2212,7 @@ components:
             - $ref: '#/components/schemas/topup'
             - $ref: '#/components/schemas/transfer'
             - $ref: '#/components/schemas/transfer_reversal'
-          description: The Stripe object to which this transaction is related.
+          description: This transaction relates to the Stripe object.
           nullable: true
           x-expansionResources:
             oneOf:
@@ -2237,8 +2236,8 @@ components:
           x-stripeBypassValidation: true
         status:
           description: >-
-            If the transaction's net funds are available in the Stripe balance
-            yet. Either `available` or `pending`.
+            The transaction's net funds status in the Stripe balance, which are
+            either `available` or `pending`.
           maxLength: 5000
           type: string
         type:
@@ -2256,11 +2255,11 @@ components:
             `refund_failure`, `reserve_transaction`, `reserved_funds`,
             `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`,
             `transfer`, `transfer_cancel`, `transfer_failure`, or
-            `transfer_refund`. [Learn
-            more](https://stripe.com/docs/reports/balance-transaction-types)
-            about balance transaction types and what they represent. If you are
-            looking to classify transactions for accounting purposes, you might
-            want to consider `reporting_category` instead.
+            `transfer_refund`. Learn more about [balance transaction types and
+            what they
+            represent](https://stripe.com/docs/reports/balance-transaction-types).
+            To classify transactions for accounting purposes, consider
+            `reporting_category` instead.
           enum:
             - adjustment
             - advance
@@ -6380,7 +6379,7 @@ components:
       x-expandableFields: []
     customer:
       description: >-
-        This object represents a customer of your business. It lets you create
+        This object represents a customer of your business. Use it to create
         recurring charges and track payments that belong to the same customer.
 
 
@@ -6394,22 +6393,22 @@ components:
           nullable: true
         balance:
           description: >-
-            Current balance, if any, being stored on the customer. If negative,
-            the customer has credit to apply to their next invoice. If positive,
-            the customer has an amount owed that will be added to their next
-            invoice. The balance does not refer to any unpaid invoices; it
-            solely takes into account amounts that have yet to be successfully
-            applied to any invoice. This balance is only taken into account as
-            invoices are finalized.
+            The current balance, if any, that's stored on the customer. If
+            negative, the customer has credit to apply to their next invoice. If
+            positive, the customer has an amount owed that's added to their next
+            invoice. The balance only considers amounts that Stripe hasn't
+            successfully applied to any invoice. It doesn't reflect unpaid
+            invoices. This balance is only taken into account after invoices
+            finalize.
           type: integer
         cash_balance:
           anyOf:
             - $ref: '#/components/schemas/cash_balance'
           description: >-
             The current funds being held by Stripe on behalf of the customer.
-            These funds can be applied towards payment intents with source
-            "cash_balance". The settings[reconciliation_mode] field describes
-            whether these funds are applied to such payment intents manually or
+            You can apply these funds towards payment intents when the source is
+            "cash_balance". The `settings[reconciliation_mode]` field describes
+            if these funds apply to these payment intents manually or
             automatically.
           nullable: true
         created:
@@ -6437,7 +6436,7 @@ components:
             ID of the default payment source for the customer.
 
 
-            If you are using payment methods created via the PaymentMethods API,
+            If you use payment methods created through the PaymentMethods API,
             see the
             [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method)
             field instead.
@@ -6450,16 +6449,15 @@ components:
           x-stripeBypassValidation: true
         delinquent:
           description: >-
-            When the customer's latest invoice is billed by charging
-            automatically, `delinquent` is `true` if the invoice's latest charge
-            failed. When the customer's latest invoice is billed by sending an
-            invoice, `delinquent` is `true` if the invoice isn't paid by its due
-            date.
+            If Stripe bills the customer's latest invoice by automatically
+            charging and the latest charge fails, it sets `delinquent`` to
+            `true``. If Stripe bills the invoice by sending it, and the invoice
+            isn't paid by the due date, it also sets `delinquent`` to `true`.
 
 
-            If an invoice is marked uncollectible by
+            If an invoice becomes uncollectible by
             [dunning](https://stripe.com/docs/billing/automatic-collection),
-            `delinquent` doesn't get reset to `false`.
+            `delinquent` doesn't reset to `false`.
           nullable: true
           type: boolean
         description:
@@ -6489,15 +6487,15 @@ components:
           additionalProperties:
             type: integer
           description: >-
-            The current multi-currency balances, if any, being stored on the
+            The current multi-currency balances, if any, that's stored on the
             customer. If positive in a currency, the customer has a credit to
             apply to their next invoice denominated in that currency. If
-            negative, the customer has an amount owed that will be added to
-            their next invoice denominated in that currency. These balances do
-            not refer to any unpaid invoices. They solely track amounts that
-            have yet to be successfully applied to any invoice. A balance in a
-            particular currency is only applied to any invoice as an invoice in
-            that currency is finalized.
+            negative, the customer has an amount owed that's added to their next
+            invoice denominated in that currency. These balances don't apply to
+            unpaid invoices. They solely track amounts that Stripe hasn't
+            successfully applied to any invoice. Stripe only applies a balance
+            in a specific currency to an invoice after that invoice (which is in
+            the same currency) finalizes.
           type: object
         invoice_prefix:
           description: The prefix for the customer used to generate unique invoice numbers.
@@ -6526,7 +6524,9 @@ components:
           nullable: true
           type: string
         next_invoice_sequence:
-          description: 'The suffix of the customer''s next invoice number, e.g., 0001.'
+          description: >-
+            The suffix of the customer's next invoice number (for example,
+            0001).
           type: integer
         object:
           description: >-
@@ -6629,9 +6629,9 @@ components:
           $ref: '#/components/schemas/customer_tax'
         tax_exempt:
           description: >-
-            Describes the customer's tax exemption status. One of `none`,
+            Describes the customer's tax exemption status, which is `none`,
             `exempt`, or `reverse`. When set to `reverse`, invoice and receipt
-            PDFs include the text **"Reverse charge"**.
+            PDFs include the following text: **"Reverse charge"**.
           enum:
             - exempt
             - none
@@ -6676,7 +6676,7 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/test_helpers.test_clock'
-          description: ID of the test clock this customer belongs to.
+          description: ID of the test clock that this customer belongs to.
           nullable: true
           x-expansionResources:
             oneOf:
@@ -8169,21 +8169,17 @@ components:
         A dispute occurs when a customer questions your charge with their card
         issuer.
 
-        When this happens, you're given the opportunity to respond to the
-        dispute with
-
-        evidence that shows that the charge is legitimate. You can find more
-
-        information about the dispute process in our [Disputes and
+        When this happens, you have the opportunity to respond to the dispute
+        with
 
-        Fraud](/docs/disputes) documentation.
+        evidence that shows that the charge is legitimate.
 
 
         Related guide: [Disputes and fraud](https://stripe.com/docs/disputes)
       properties:
         amount:
           description: >-
-            Disputed amount. Usually the amount of the charge, but can differ
+            Disputed amount. Usually the amount of the charge, but it can differ
             (usually because of currency fluctuation or because only part of the
             order is disputed).
           type: integer
@@ -8200,7 +8196,7 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/charge'
-          description: ID of the charge that was disputed.
+          description: ID of the charge that's disputed.
           x-expansionResources:
             oneOf:
               - $ref: '#/components/schemas/charge'
@@ -8227,9 +8223,9 @@ components:
           type: string
         is_charge_refundable:
           description: >-
-            If true, it is still possible to refund the disputed payment. Once
-            the payment has been fully refunded, no further funds will be
-            withdrawn from your Stripe account as a result of this dispute.
+            If true, it's still possible to refund the disputed payment. After
+            the payment has been fully refunded, no further funds are withdrawn
+            from your Stripe account as a result of this dispute.
           type: boolean
         livemode:
           description: >-
@@ -8257,7 +8253,7 @@ components:
             - maxLength: 5000
               type: string
             - $ref: '#/components/schemas/payment_intent'
-          description: ID of the PaymentIntent that was disputed.
+          description: ID of the PaymentIntent that's disputed.
           nullable: true
           x-expansionResources:
             oneOf:
@@ -8272,7 +8268,7 @@ components:
             `fraudulent`, `general`, `incorrect_account_details`,
             `insufficient_funds`, `product_not_received`,
             `product_unacceptable`, `subscription_canceled`, or `unrecognized`.
-            Read more about [dispute
+            Learn more about [dispute
             reasons](https://stripe.com/docs/disputes/categories).
           maxLength: 5000
           type: string
@@ -8723,29 +8719,26 @@ components:
         object. For example, when a charge succeeds, we create a
         `charge.succeeded`
 
-        event; and when an invoice payment attempt fails, we create an
+        event, and when an invoice payment attempt fails, we create an
 
-        `invoice.payment_failed` event. Note that many API requests may cause
+        `invoice.payment_failed` event. Certain API requests might create
         multiple
 
-        events to be created. For example, if you create a new subscription for
-        a
+        events. For example, if you create a new subscription for a
 
-        customer, you will receive both a `customer.subscription.created` event
-        and a
+        customer, you receive both a `customer.subscription.created` event and a
 
         `charge.succeeded` event.
 
 
-        Events occur when the state of another API resource changes. The state
-        of that
+        Events occur when the state of another API resource changes. The event's
+        data
 
-        resource at the time of the change is embedded in the event's data
-        field. For
+        field embeds the resource's state at the time of the change. For
 
-        example, a `charge.succeeded` event will contain a charge, and an
+        example, a `charge.succeeded` event contains a charge, and an
 
-        `invoice.payment_failed` event will contain an invoice.
+        `invoice.payment_failed` event contains an invoice.
 
 
         As with other API resources, you can use endpoints to retrieve an
@@ -8757,39 +8750,40 @@ components:
 
         [webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the
 
-        `Event` objects directly to an endpoint on your server. Webhooks are
-        managed
+        `Event` objects directly to an endpoint on your server. You can manage
+
+        webhooks in your
 
-        in your
+        [account settings](https://dashboard.stripe.com/account/webhooks). Learn
+        how
 
-        [account settings](https://dashboard.stripe.com/account/webhooks),
+        to [listen for events]
 
-        and our [Using Webhooks](https://stripe.com/docs/webhooks) guide will
-        help you get set up.
+        (/docs/webhooks) so that your integration can automatically trigger
+        reactions.
 
 
         When using [Connect](https://stripe.com/docs/connect), you can also
-        receive notifications of
+        receive event notifications
 
-        events that occur in connected accounts. For these events, there will be
-        an
+        that occur in connected accounts. For these events, there's an
 
         additional `account` attribute in the received `Event` object.
 
 
-        **NOTE:** Right now, access to events through the [Retrieve Event
-        API](https://stripe.com/docs/api#retrieve_event) is
+        We only guarantee access to events through the [Retrieve Event
+        API](https://stripe.com/docs/api#retrieve_event)
 
-        guaranteed only for 30 days.
+        for 30 days.
       properties:
         account:
-          description: The connected account that originated the event.
+          description: The connected account that originates the event.
           maxLength: 5000
           type: string
         api_version:
           description: >-
-            The Stripe API version used to render `data`. *Note: This property
-            is populated only for events on or after October 31, 2014*.
+            The Stripe API version used to render `data`. This property is
+            populated only for events on or after October 31, 2014.
           maxLength: 5000
           nullable: true
           type: string
@@ -8819,17 +8813,17 @@ components:
           type: string
         pending_webhooks:
           description: >-
-            Number of webhooks that have yet to be successfully delivered (i.e.,
-            to return a 20x response) to the URLs you've specified.
+            Number of webhooks that haven't been successfully delivered (for
+            example, to return a 20x response) to the URLs you specify.
           type: integer
         request:
           anyOf:
             - $ref: '#/components/schemas/notification_event_request'
-          description: Information on the API request that instigated the event.
+          description: Information on the API request that triggers the event.
           nullable: true
         type:
           description: >-
-            Description of the event (e.g., `invoice.created` or
+            Description of the event (for example, `invoice.created` or
             `charge.refunded`).
           maxLength: 5000
           type: string