API Updates (#1497)

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -66,7 +66,7 @@ body:
     attributes:
       label: API version
       description: See [Versioning](https://stripe.com/docs/api/versioning) in the API Reference to find which version you're using
-      placeholder: "2020-08-27"
+      placeholder: "2022-08-01"
     validations:
       required: true
   - type: textarea

API_VERSION

@@ -1 +1 @@
-2020-08-27
+2022-08-01

OPENAPI_VERSION

@@ -1 +1 @@
-v173
+v174

README.md

@@ -86,7 +86,7 @@ and instantiate it as `new Stripe()` with the latest API version.
 ```ts
 import Stripe from 'stripe';
 const stripe = new Stripe('sk_test_...', {
-  apiVersion: '2020-08-27',
+  apiVersion: '2022-08-01',
 });
 
 const createCustomer = async () => {

examples/webhook-signing/typescript-node-express/express-ts.ts

@@ -5,7 +5,7 @@ import env from 'dotenv';
 env.config();
 
 const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
-  apiVersion: '2020-08-27',
+  apiVersion: '2022-08-01',
 });
 
 const webhookSecret: string = process.env.STRIPE_WEBHOOK_SECRET;

lib/apiVersion.js

@@ -1,3 +1,3 @@
 // File generated from our OpenAPI spec
 
-module.exports = {ApiVersion: '2020-08-27'};
+module.exports = {ApiVersion: '2022-08-01'};

package.json

@@ -25,7 +25,7 @@
     "node": "^8.1 || >=10.*"
   },
   "main": "lib/stripe.js",
-  "types": "types/2020-08-27/index.d.ts",
+  "types": "types/2022-08-01/index.d.ts",
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^2.13.0",
     "@typescript-eslint/parser": "^2.13.0",

types/2020-08-27/Accounts.d.ts → types/2022-08-01/Accounts.d.ts

@@ -704,6 +704,7 @@ declare module 'stripe' {
           type Code =
             | 'invalid_address_city_state_postal_code'
             | 'invalid_street_address'
+            | 'invalid_tos_acceptance'
             | 'invalid_value_other'
             | 'verification_document_address_mismatch'
             | 'verification_document_address_missing'
@@ -826,6 +827,7 @@ declare module 'stripe' {
           type Code =
             | 'invalid_address_city_state_postal_code'
             | 'invalid_street_address'
+            | 'invalid_tos_acceptance'
             | 'invalid_value_other'
             | 'verification_document_address_mismatch'
             | 'verification_document_address_missing'

types/2020-08-27/Capabilities.d.ts → types/2022-08-01/Capabilities.d.ts

@@ -118,6 +118,7 @@ declare module 'stripe' {
           type Code =
             | 'invalid_address_city_state_postal_code'
             | 'invalid_street_address'
+            | 'invalid_tos_acceptance'
             | 'invalid_value_other'
             | 'verification_document_address_mismatch'
             | 'verification_document_address_missing'
@@ -246,6 +247,7 @@ declare module 'stripe' {
           type Code =
             | 'invalid_address_city_state_postal_code'
             | 'invalid_street_address'
+            | 'invalid_tos_acceptance'
             | 'invalid_value_other'
             | 'verification_document_address_mismatch'
             | 'verification_document_address_missing'

types/2020-08-27/Checkout/Sessions.d.ts → types/2022-08-01/Checkout/Sessions.d.ts

@@ -170,24 +170,24 @@ declare module 'stripe' {
         setup_intent: string | Stripe.SetupIntent | null;
 
         /**
-         * Shipping information for this Checkout Session.
+         * When set, provides configuration for Checkout to collect a shipping address from a customer.
          */
-        shipping: Session.Shipping | null;
+        shipping_address_collection: Session.ShippingAddressCollection | null;
 
         /**
-         * When set, provides configuration for Checkout to collect a shipping address from a customer.
+         * The details of the customer cost of shipping, including the customer chosen ShippingRate.
          */
-        shipping_address_collection: Session.ShippingAddressCollection | null;
+        shipping_cost: Session.ShippingCost | null;
 
         /**
-         * The shipping rate options applied to this Session.
+         * Shipping information for this Checkout Session.
          */
-        shipping_options: Array<Session.ShippingOption>;
+        shipping_details: Session.ShippingDetails | null;
 
         /**
-         * The ID of the ShippingRate for Checkout Sessions in `payment` mode.
+         * The shipping rate options applied to this Session.
          */
-        shipping_rate: string | Stripe.ShippingRate | null;
+        shipping_options: Array<Session.ShippingOption>;
 
         /**
          * The status of the Checkout Session, one of `open`, `complete`, or `expired`.
@@ -957,30 +957,6 @@ declare module 'stripe' {
           enabled: boolean;
         }
 
-        interface Shipping {
-          address?: Stripe.Address;
-
-          /**
-           * The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.
-           */
-          carrier?: string | null;
-
-          /**
-           * Recipient name.
-           */
-          name?: string;
-
-          /**
-           * Recipient phone (including extension).
-           */
-          phone?: string | null;
-
-          /**
-           * The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.
-           */
-          tracking_number?: string | null;
-        }
-
         interface ShippingAddressCollection {
           /**
            * An array of two-letter ISO country codes representing which countries Checkout should provide as options for
@@ -1230,6 +1206,73 @@ declare module 'stripe' {
             | 'ZZ';
         }
 
+        interface ShippingCost {
+          /**
+           * Total shipping cost before any discounts or taxes are applied.
+           */
+          amount_subtotal: number;
+
+          /**
+           * Total tax amount applied due to shipping costs. If no tax was applied, defaults to 0.
+           */
+          amount_tax: number;
+
+          /**
+           * Total shipping cost after discounts and taxes are applied.
+           */
+          amount_total: number;
+
+          /**
+           * The ID of the ShippingRate for this order.
+           */
+          shipping_rate: string | Stripe.ShippingRate | null;
+
+          /**
+           * The taxes applied to the shipping rate.
+           */
+          taxes?: Array<ShippingCost.Tax>;
+        }
+
+        namespace ShippingCost {
+          interface Tax {
+            /**
+             * Amount of tax applied for this rate.
+             */
+            amount: number;
+
+            /**
+             * Tax rates can be applied to [invoices](https://stripe.com/docs/billing/invoices/tax-rates), [subscriptions](https://stripe.com/docs/billing/subscriptions/taxes) and [Checkout Sessions](https://stripe.com/docs/payments/checkout/set-up-a-subscription#tax-rates) to collect tax.
+             *
+             * Related guide: [Tax Rates](https://stripe.com/docs/billing/taxes/tax-rates).
+             */
+            rate: Stripe.TaxRate;
+          }
+        }
+
+        interface ShippingDetails {
+          address?: Stripe.Address;
+
+          /**
+           * The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.
+           */
+          carrier?: string | null;
+
+          /**
+           * Recipient name.
+           */
+          name?: string;
+
+          /**
+           * Recipient phone (including extension).
+           */
+          phone?: string | null;
+
+          /**
+           * The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.
+           */
+          tracking_number?: string | null;
+        }
+
         interface ShippingOption {
           /**
            * A non-negative integer in cents representing how much to charge.
@@ -2320,6 +2363,9 @@ declare module 'stripe' {
 
           namespace CustomerBalance {
             interface BankTransfer {
+              /**
+               * Configuration for eu_bank_transfer funding type.
+               */
               eu_bank_transfer?: BankTransfer.EuBankTransfer;
 
               /**

types/2020-08-27/Customers.d.ts → types/2022-08-01/Customers.d.ts

@@ -41,11 +41,6 @@ declare module 'stripe' {
        */
       currency?: string | null;
 
-      /**
-       * The default three-letter [ISO code for the currency](https://stripe.com/docs/currencies) that the customer will be charged in for billing purposes.
-       */
-      default_currency?: string | null;
-
       /**
        * ID of the default payment source for the customer.
        *

types/2020-08-27/Invoices.d.ts → types/2022-08-01/Invoices.d.ts

@@ -1026,7 +1026,7 @@ declare module 'stripe' {
       payment_settings?: InvoiceCreateParams.PaymentSettings;
 
       /**
-       * How to handle pending invoice items on invoice creation. One of `include`, `exclude`, or `include_and_require`. `include` will include any pending invoice items, and will create an empty draft invoice if no pending invoice items exist. `include_and_require` will include any pending invoice items, if no pending invoice items exist then the request will fail. `exclude` will always create an empty invoice draft regardless if there are pending invoice items or not. Defaults to `include_and_require` if the parameter is omitted.
+       * How to handle pending invoice items on invoice creation. One of `include` or `exclude`. `include` will include any pending invoice items, and will create an empty draft invoice if no pending invoice items exist. `exclude` will always create an empty invoice draft regardless if there are pending invoice items or not. Defaults to `exclude` if the parameter is omitted.
        */
       pending_invoice_items_behavior?: InvoiceCreateParams.PendingInvoiceItemsBehavior;
 
@@ -1043,7 +1043,7 @@ declare module 'stripe' {
       statement_descriptor?: string;
 
       /**
-       * The ID of the subscription to invoice, if any. If not set, the created invoice will include all pending invoice items for the customer. If set, the created invoice will only include pending invoice items for that subscription and pending invoice items not associated with any subscription. The subscription's billing cycle and regular subscription events won't be affected.
+       * The ID of the subscription to invoice, if any. If set, the created invoice will only include pending invoice items for that subscription and pending invoice items not associated with any subscription if `pending_invoice_items_behavior` is `include`. The subscription's billing cycle and regular subscription events won't be affected.
        */
       subscription?: string;
 

types/2020-08-27/Issuing/Cardholders.d.ts → types/2022-08-01/Issuing/Cardholders.d.ts

@@ -1109,7 +1109,7 @@ declare module 'stripe' {
         billing: CardholderCreateParams.Billing;
 
         /**
-         * The cardholder's name. This will be printed on cards issued to them. The maximum length of this field is 24 characters.
+         * The cardholder's name. This will be printed on cards issued to them. The maximum length of this field is 24 characters. This field cannot contain any special characters or numbers.
          */
         name: string;
 
@@ -1215,12 +1215,12 @@ declare module 'stripe' {
           dob?: Individual.Dob;
 
           /**
-           * The first name of this cardholder.
+           * The first name of this cardholder. This field cannot contain any special characters or numbers.
            */
           first_name: string;
 
           /**
-           * The last name of this cardholder.
+           * The last name of this cardholder. This field cannot contain any special characters or numbers.
            */
           last_name: string;
 
@@ -2306,12 +2306,12 @@ declare module 'stripe' {
           dob?: Individual.Dob;
 
           /**
-           * The first name of this cardholder.
+           * The first name of this cardholder. This field cannot contain any special characters or numbers.
            */
           first_name: string;
 
           /**
-           * The last name of this cardholder.
+           * The last name of this cardholder. This field cannot contain any special characters or numbers.
            */
           last_name: string;
 

types/2020-08-27/Issuing/Cards.d.ts → types/2022-08-01/Issuing/Cards.d.ts

@@ -123,7 +123,7 @@ declare module 'stripe' {
       }
 
       namespace Card {
-        type CancellationReason = 'lost' | 'stolen';
+        type CancellationReason = 'design_rejected' | 'lost' | 'stolen';
 
         type ReplacementReason = 'damaged' | 'expired' | 'lost' | 'stolen';
 

types/2020-08-27/PaymentMethods.d.ts → types/2022-08-01/PaymentMethods.d.ts

@@ -1591,9 +1591,11 @@ declare module 'stripe' {
        *
        * To attach a new PaymentMethod to a customer for future payments, we recommend you use a [SetupIntent](https://stripe.com/docs/api/setup_intents)
        * or a PaymentIntent with [setup_future_usage](https://stripe.com/docs/api/payment_intents/create#create_payment_intent-setup_future_usage).
-       * These approaches will perform any necessary steps to ensure that the PaymentMethod can be used in a future payment. Using the
-       * /v1/payment_methods/:id/attach endpoint does not ensure that future payments can be made with the attached PaymentMethod.
-       * See [Optimizing cards for future payments](https://stripe.com/docs/payments/payment-intents#future-usage) for more information about setting up future payments.
+       * These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the /v1/payment_methods/:id/attach
+       * endpoint without first using a SetupIntent or PaymentIntent with setup_future_usage does not optimize the PaymentMethod for
+       * future use, which makes later declines and payment friction more likely.
+       * See [Optimizing cards for future payments](https://stripe.com/docs/payments/payment-intents#future-usage) for more information about setting up
+       * future payments.
        *
        * To use this PaymentMethod as the default for invoice or subscription payments,
        * set [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method),

types/2020-08-27/Persons.d.ts → types/2022-08-01/Persons.d.ts

@@ -302,6 +302,7 @@ declare module 'stripe' {
           type Code =
             | 'invalid_address_city_state_postal_code'
             | 'invalid_street_address'
+            | 'invalid_tos_acceptance'
             | 'invalid_value_other'
             | 'verification_document_address_mismatch'
             | 'verification_document_address_missing'
@@ -448,6 +449,7 @@ declare module 'stripe' {
           type Code =
             | 'invalid_address_city_state_postal_code'
             | 'invalid_street_address'
+            | 'invalid_tos_acceptance'
             | 'invalid_value_other'
             | 'verification_document_address_mismatch'
             | 'verification_document_address_missing'

types/2020-08-27/WebhookEndpoints.d.ts → types/2022-08-01/WebhookEndpoints.d.ts

@@ -223,7 +223,8 @@ declare module 'stripe' {
         | '2019-11-05'
         | '2019-12-03'
         | '2020-03-02'
-        | '2020-08-27';
+        | '2020-08-27'
+        | '2022-08-01';
 
       type EnabledEvent =
         | '*'

types/lib.d.ts

@@ -52,7 +52,7 @@ declare module 'stripe' {
       };
       static MAX_BUFFERED_REQUEST_METRICS: number;
     }
-    export type LatestApiVersion = '2020-08-27';
+    export type LatestApiVersion = '2022-08-01';
     export type HttpAgent = Agent;
     export type HttpProtocol = 'http' | 'https';
 

types/test/typescriptTest.ts

@@ -5,11 +5,11 @@
  * and to perform a basic sanity check that types are exported as intended.
  */
 
-///<reference types="../2020-08-27" />
+///<reference types="../2022-08-01" />
 import Stripe from 'stripe';
 
 let stripe = new Stripe('sk_test_123', {
-  apiVersion: '2020-08-27',
+  apiVersion: '2022-08-01',
 });
 
 // @ts-ignore lazily ignore apiVersion requirement.
@@ -27,7 +27,7 @@ stripe = new Stripe('sk_test_123', {
 
 // Check config object.
 stripe = new Stripe('sk_test_123', {
-  apiVersion: '2020-08-27',
+  apiVersion: '2022-08-01',
   typescript: true,
   maxNetworkRetries: 1,
   timeout: 1000,
@@ -49,7 +49,7 @@ stripe.setHost('host', 'port', 'protocol');
     description: 'test',
   };
   const opts: Stripe.RequestOptions = {
-    apiVersion: '2020-08-27',
+    apiVersion: '2022-08-01',
   };
   const customer: Stripe.Customer = await stripe.customers.create(params, opts);