API Updates

OPENAPI_VERSION

@@ -1 +1 @@
-v174
+v183

stripe/api_resources/__init__.py

@@ -40,6 +40,9 @@
 from stripe.api_resources.customer_balance_transaction import (
     CustomerBalanceTransaction,
 )
+from stripe.api_resources.customer_cash_balance_transaction import (
+    CustomerCashBalanceTransaction,
+)
 from stripe.api_resources.dispute import Dispute
 from stripe.api_resources.ephemeral_key import EphemeralKey
 from stripe.api_resources.event import Event

stripe/api_resources/account.py

@@ -32,6 +32,15 @@ class Account(
     ListableAPIResource,
     UpdateableAPIResource,
 ):
+    """
+    This is an object representing a Stripe account. You can retrieve it to see
+    properties on the account like its current e-mail address or if the account is
+    enabled yet to make live charges.
+
+    Some properties, marked below, are available only to platforms that want to
+    [create and manage Express or Custom accounts](https://stripe.com/docs/connect/accounts).
+    """
+
     OBJECT_NAME = "account"
 
     @classmethod

stripe/api_resources/account_link.py

@@ -5,4 +5,11 @@
 
 
 class AccountLink(CreateableAPIResource):
+    """
+    Account Links are the means by which a Connect platform grants a connected account permission to access
+    Stripe-hosted applications, such as Connect Onboarding.
+
+    Related guide: [Connect Onboarding](https://stripe.com/docs/connect/connect-onboarding).
+    """
+
     OBJECT_NAME = "account_link"

stripe/api_resources/application_fee_refund.py

@@ -8,6 +8,14 @@
 
 
 class ApplicationFeeRefund(UpdateableAPIResource):
+    """
+    `Application Fee Refund` objects allow you to refund an application fee that
+    has previously been created but not yet refunded. Funds will be refunded to
+    the Stripe account from which the fee was originally collected.
+
+    Related guide: [Refunding Application Fees](https://stripe.com/docs/connect/destination-charges#refunding-app-fee).
+    """
+
     OBJECT_NAME = "fee_refund"
 
     @classmethod

stripe/api_resources/apps/secret.py

@@ -6,6 +6,18 @@
 
 
 class Secret(CreateableAPIResource, ListableAPIResource):
+    """
+    Secret Store is an API that allows Stripe Apps developers to securely persist secrets for use by UI Extensions and app backends.
+
+    The primary resource in Secret Store is a `secret`. Other apps can't view secrets created by an app. Additionally, secrets are scoped to provide further permission control.
+
+    All Dashboard users and the app backend share `account` scoped secrets. Use the `account` scope for secrets that don't change per-user, like a third-party API key.
+
+    A `user` scoped secret is accessible by the app backend and one specific Dashboard user. Use the `user` scope for per-user secrets like per-user OAuth tokens, where different users might have different permissions.
+
+    Related guide: [Store data between page reloads](https://stripe.com/docs/stripe-apps/store-auth-data-custom-objects).
+    """
+
     OBJECT_NAME = "apps.secret"
 
     @classmethod

stripe/api_resources/balance.py

@@ -5,6 +5,20 @@
 
 
 class Balance(SingletonAPIResource):
+    """
+    This is an object representing your Stripe balance. You can retrieve it to see
+    the balance currently on your Stripe account.
+
+    You can also retrieve the balance history, which contains a list of
+    [transactions](https://stripe.com/docs/reporting/balance-transaction-types) that contributed to the balance
+    (charges, payouts, and so forth).
+
+    The available and pending amounts for each currency are broken down further by
+    payment source types.
+
+    Related guide: [Understanding Connect Account Balances](https://stripe.com/docs/connect/account-balances).
+    """
+
     OBJECT_NAME = "balance"
 
     @classmethod

stripe/api_resources/balance_transaction.py

@@ -5,4 +5,11 @@
 
 
 class BalanceTransaction(ListableAPIResource):
+    """
+    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.
+
+    Related guide: [Balance Transaction Types](https://stripe.com/docs/reports/balance-transaction-types).
+    """
+
     OBJECT_NAME = "balance_transaction"

stripe/api_resources/bank_account.py

@@ -12,6 +12,16 @@
 
 
 class BankAccount(DeletableAPIResource, UpdateableAPIResource, VerifyMixin):
+    """
+    These bank accounts are payment methods on `Customer` objects.
+
+    On the other hand [External Accounts](https://stripe.com/docs/api#external_accounts) are transfer
+    destinations on `Account` objects for [Custom accounts](https://stripe.com/docs/connect/custom-accounts).
+    They can be bank accounts or debit cards as well, and are documented in the links above.
+
+    Related guide: [Bank Debits and Transfers](https://stripe.com/docs/payments/bank-debits-transfers).
+    """
+
     OBJECT_NAME = "bank_account"
 
     def instance_url(self):

stripe/api_resources/billing_portal/configuration.py

@@ -11,4 +11,8 @@ class Configuration(
     ListableAPIResource,
     UpdateableAPIResource,
 ):
+    """
+    A portal configuration describes the functionality and behavior of a portal session.
+    """
+
     OBJECT_NAME = "billing_portal.configuration"

stripe/api_resources/billing_portal/session.py

@@ -5,4 +5,21 @@
 
 
 class Session(CreateableAPIResource):
+    """
+    The Billing customer portal is a Stripe-hosted UI for subscription and
+    billing management.
+
+    A portal configuration describes the functionality and features that you
+    want to provide to your customers through the portal.
+
+    A portal session describes the instantiation of the customer portal for
+    a particular customer. By visiting the session's URL, the customer
+    can manage their subscriptions and billing details. For security reasons,
+    sessions are short-lived and will expire if the customer does not visit the URL.
+    Create sessions on-demand when customers intend to manage their subscriptions
+    and billing details.
+
+    Learn more in the [integration guide](https://stripe.com/docs/billing/subscriptions/integrating-customer-portal).
+    """
+
     OBJECT_NAME = "billing_portal.session"

stripe/api_resources/capability.py

@@ -8,6 +8,12 @@
 
 
 class Capability(UpdateableAPIResource):
+    """
+    This is an object representing a capability for a Stripe account.
+
+    Related guide: [Account capabilities](https://stripe.com/docs/connect/account-capabilities).
+    """
+
     OBJECT_NAME = "capability"
 
     def instance_url(self):

stripe/api_resources/card.py

@@ -11,6 +11,14 @@
 
 
 class Card(DeletableAPIResource, UpdateableAPIResource):
+    """
+    You can store multiple cards on a customer in order to charge the customer
+    later. You can also store multiple debit cards on a recipient in order to
+    transfer to those cards later.
+
+    Related guide: [Card Payments with Sources](https://stripe.com/docs/sources/cards).
+    """
+
     OBJECT_NAME = "card"
 
     def instance_url(self):

stripe/api_resources/cash_balance.py

@@ -8,6 +8,10 @@
 
 
 class CashBalance(APIResource):
+    """
+    A customer's `Cash balance` represents real funds. Customers can add funds to their cash balance by sending a bank transfer. These funds can be used for payment and can eventually be paid out to your bank account.
+    """
+
     OBJECT_NAME = "cash_balance"
 
     def instance_url(self):

stripe/api_resources/charge.py

@@ -14,6 +14,14 @@ class Charge(
     SearchableAPIResource,
     UpdateableAPIResource,
 ):
+    """
+    To charge a credit or a debit card, you create a `Charge` object. You can
+    retrieve and refund individual charges as well as list all charges. Charges
+    are identified by a unique, random ID.
+
+    Related guide: [Accept a payment with the Charges API](https://stripe.com/docs/payments/accept-a-payment-charges).
+    """
+
     OBJECT_NAME = "charge"
 
     @classmethod

stripe/api_resources/checkout/session.py

@@ -7,6 +7,23 @@
 
 
 class Session(CreateableAPIResource, ListableAPIResource):
+    """
+    A Checkout Session represents your customer's session as they pay for
+    one-time purchases or subscriptions through [Checkout](https://stripe.com/docs/payments/checkout)
+    or [Payment Links](https://stripe.com/docs/payments/payment-links). We recommend creating a
+    new Session each time your customer attempts to pay.
+
+    Once payment is successful, the Checkout Session will contain a reference
+    to the [Customer](https://stripe.com/docs/api/customers), and either the successful
+    [PaymentIntent](https://stripe.com/docs/api/payment_intents) or an active
+    [Subscription](https://stripe.com/docs/api/subscriptions).
+
+    You can create a Checkout Session on your server and pass its ID to the
+    client to begin Checkout.
+
+    Related guide: [Checkout Quickstart](https://stripe.com/docs/checkout/quickstart).
+    """
+
     OBJECT_NAME = "checkout.session"
 
     @classmethod

stripe/api_resources/country_spec.py

@@ -5,4 +5,13 @@
 
 
 class CountrySpec(ListableAPIResource):
+    """
+    Stripe needs to collect certain pieces of information about each account
+    created. These requirements can differ depending on the account's country. The
+    Country Specs API makes these rules available to your integration.
+
+    You can also view the information from this API call as [an online
+    guide](/docs/connect/required-verification-information).
+    """
+
     OBJECT_NAME = "country_spec"

stripe/api_resources/coupon.py

@@ -13,4 +13,10 @@ class Coupon(
     ListableAPIResource,
     UpdateableAPIResource,
 ):
+    """
+    A coupon contains information about a percent-off or amount-off discount you
+    might want to apply to a customer. Coupons may be applied to [subscriptions](https://stripe.com/docs/api#subscriptions), [invoices](https://stripe.com/docs/api#invoices),
+    [checkout sessions](https://stripe.com/docs/api/checkout/sessions), [quotes](https://stripe.com/docs/api#quotes), and more. Coupons do not work with conventional one-off [charges](https://stripe.com/docs/api#create_charge) or [payment intents](https://stripe.com/docs/api/payment_intents).
+    """
+
     OBJECT_NAME = "coupon"

stripe/api_resources/credit_note.py

@@ -12,6 +12,12 @@ class CreditNote(
     ListableAPIResource,
     UpdateableAPIResource,
 ):
+    """
+    Issue a credit note to adjust an invoice's amount after the invoice is finalized.
+
+    Related guide: [Credit Notes](https://stripe.com/docs/billing/invoices/credit-notes).
+    """
+
     OBJECT_NAME = "credit_note"
 
     @classmethod

stripe/api_resources/customer.py

@@ -17,6 +17,10 @@
     "balance_transaction",
     operations=["create", "retrieve", "update", "list"],
 )
+@nested_resource_class_methods(
+    "cash_balance_transaction",
+    operations=["retrieve", "list"],
+)
 @nested_resource_class_methods(
     "source",
     operations=["create", "retrieve", "update", "delete", "list"],
@@ -32,6 +36,12 @@ class Customer(
     SearchableAPIResource,
     UpdateableAPIResource,
 ):
+    """
+    This object represents a customer of your business. It lets you create recurring charges and track payments that belong to the same customer.
+
+    Related guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment).
+    """
+
     OBJECT_NAME = "customer"
 
     @classmethod

stripe/api_resources/customer_balance_transaction.py

@@ -8,6 +8,15 @@
 
 
 class CustomerBalanceTransaction(APIResource):
+    """
+    Each customer has a [`balance`](https://stripe.com/docs/api/customers/object#customer_object-balance) value,
+    which denotes a debit or credit that's automatically applied to their next invoice upon finalization.
+    You may modify the value directly by using the [update customer API](https://stripe.com/docs/api/customers/update),
+    or by creating a Customer Balance Transaction, which increments or decrements the customer's `balance` by the specified `amount`.
+
+    Related guide: [Customer Balance](https://stripe.com/docs/billing/customer/balance) to learn more.
+    """
+
     OBJECT_NAME = "customer_balance_transaction"
 
     def instance_url(self):

stripe/api_resources/customer_cash_balance_transaction.py

@@ -0,0 +1,15 @@
+# File generated from our OpenAPI spec
+from __future__ import absolute_import, division, print_function
+
+from stripe.api_resources.abstract import ListableAPIResource
+
+
+class CustomerCashBalanceTransaction(ListableAPIResource):
+    """
+    Customers with certain payments enabled have a cash balance, representing funds that were paid
+    by the customer to a merchant, but have not yet been allocated to a payment. Cash Balance Transactions
+    represent when funds are moved into or out of this balance. This includes funding by the customer, allocation
+    to payments, and refunds to the customer.
+    """
+
+    OBJECT_NAME = "customer_cash_balance_transaction"

stripe/api_resources/dispute.py

@@ -7,6 +7,16 @@
 
 
 class Dispute(ListableAPIResource, UpdateableAPIResource):
+    """
+    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
+    Fraud](/docs/disputes) documentation.
+
+    Related guide: [Disputes and Fraud](https://stripe.com/docs/disputes).
+    """
+
     OBJECT_NAME = "dispute"
 
     @classmethod

stripe/api_resources/event.py

@@ -5,4 +5,36 @@
 
 
 class Event(ListableAPIResource):
+    """
+    Events are our way of letting you know when something interesting happens in
+    your account. When an interesting event occurs, we create a new `Event`
+    object. For example, when a charge succeeds, we create a `charge.succeeded`
+    event; and when an invoice payment attempt fails, we create an
+    `invoice.payment_failed` event. Note that many API requests may cause multiple
+    events to be created. For example, if you create a new subscription for a
+    customer, you will 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
+    resource at the time of the change is embedded in the event's data field. For
+    example, a `charge.succeeded` event will contain a charge, and an
+    `invoice.payment_failed` event will contain an invoice.
+
+    As with other API resources, you can use endpoints to retrieve an
+    [individual event](https://stripe.com/docs/api#retrieve_event) or a [list of events](https://stripe.com/docs/api#list_events)
+    from the API. We also have a separate
+    [webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the
+    `Event` objects directly to an endpoint on your server. Webhooks are managed
+    in your
+    [account settings](https://dashboard.stripe.com/account/webhooks),
+    and our [Using Webhooks](https://stripe.com/docs/webhooks) guide will help you get set up.
+
+    When using [Connect](https://stripe.com/docs/connect), you can also receive notifications of
+    events that occur in connected accounts. For these events, there will be 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
+    guaranteed only for 30 days.
+    """
+
     OBJECT_NAME = "event"