Repository: stripe/stripe-node
Pull request #952 (2020-07-10 19:08:23)

Add new fields to lastResponse: apiVersion, stripeAccount, idempotencyKey
r? @jlomas-stripe  
cc @stripe/api-libraries @brandur-stripe 

If any of these three fields are set in the headers, copy them over to lastResponse as suggested in #406.
Also add tests for the new fields and refactor an existing test for lastResponse.

polybuildr: Hi @richardm-stripe! I'm glad you brought that up! I started with hardcoding the key but then came across a problem. The test isn't hermetic and actually communicates with the Stripe API, so if I hardcode an idempotency key, running the test twice gives me an error saying: `No such customer: cus_HdkOjCApDMTkzx`.

I'm not sure why it's that error specifically -- I didn't investigate. I can look into it later if you don't already know off the top of your head.
richardm-stripe: Ah thanks @polybuildr, I forgot about that. Can we roll our own random identifier instead of introducing a dependency?
`(Math.random() * Number.MAX_SAFE_INTEGER).toString(16)` or something?

polybuildr: Ah yes, that's a reasonably good solution. I'll update to include a random identifier without using a dependency. :)

Patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d5826d25..ad5274ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,22 @@
 # CHANGELOG
 
+## 8.73.0 - 2020-07-15
+* [#958](https://github.com/stripe/stripe-node/pull/958) Multiple API changes
+  * Add support for `en-GB`, `fr-CA` and `id` as `locale` on Checkout `Session`
+  * Move `purpose` to an enum on `File`
+* [#957](https://github.com/stripe/stripe-node/pull/957) Bump lodash from 4.17.15 to 4.17.19
+
+## 8.72.0 - 2020-07-15
+* [#956](https://github.com/stripe/stripe-node/pull/956) Add support for `amount_total`, `amount_subtotal`, `currency` and `total_details` on Checkout `Session`
+
+## 8.71.0 - 2020-07-14
+* [#955](https://github.com/stripe/stripe-node/pull/955) Change from string to enum value for `billing_address_collection` on Checkout `Session`
+
+## 8.70.0 - 2020-07-13
+* [#953](https://github.com/stripe/stripe-node/pull/953) Multiple API changes
+  * Adds `es-419` as a `locale` to Checkout `Session`
+  * Adds `billing_cycle_anchor` to `default_settings` and `phases` for `SubscriptionSchedule`
+
 ## 8.69.0 - 2020-07-06
 * [#946](https://github.com/stripe/stripe-node/pull/946) Fix `assert_capabilities` type definition
 * [#920](https://github.com/stripe/stripe-node/pull/920) Expose StripeResource on instance
diff --git a/VERSION b/VERSION
index da7724a2..813e0f12 100644
--- a/VERSION
+++ b/VERSION
@@ -1,1 +1,1 @@
-8.69.0
+8.73.0
diff --git a/lib/StripeResource.js b/lib/StripeResource.js
index b2d73fde..efc42a0b 100644
--- a/lib/StripeResource.js
+++ b/lib/StripeResource.js
@@ -124,10 +124,25 @@ StripeResource.prototype = {
         const headers = res.headers || {};
         // NOTE: Stripe responds with lowercase header names/keys.
 
-        // For convenience, make Request-Id easily accessible on
+        // For convenience, make some headers easily accessible on
         // lastResponse.
         res.requestId = headers['request-id'];
 
+        const stripeAccount = headers['stripe-account'];
+        if (stripeAccount) {
+          res.stripeAccount = stripeAccount;
+        }
+
+        const apiVersion = headers['stripe-version'];
+        if (apiVersion) {
+          res.apiVersion = apiVersion;
+        }
+
+        const idempotencyKey = headers['idempotency-key'];
+        if (idempotencyKey) {
+          res.idempotencyKey = idempotencyKey;
+        }
+
         const requestEndTime = Date.now();
         const requestDurationMs = requestEndTime - req._requestStart;
 
diff --git a/package.json b/package.json
index a4ad347d..a1288dac 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "stripe",
-  "version": "8.69.0",
+  "version": "8.73.0",
   "description": "Stripe API wrapper",
   "keywords": [
     "stripe",
diff --git a/types/2020-03-02/Accounts.d.ts b/types/2020-03-02/Accounts.d.ts
index 8f986a11..286aa056 100644
--- a/types/2020-03-02/Accounts.d.ts
+++ b/types/2020-03-02/Accounts.d.ts
@@ -425,7 +425,7 @@ declare module 'stripe' {
         disabled_reason: string | null;
 
         /**
-         * The fields that need to be collected again because validation or verification failed for some reason.
+         * The fields that are `currently_due` and need to be collected again because validation or verification failed for some reason.
          */
         errors: Array<Requirements.Error> | null;
 
diff --git a/types/2020-03-02/Capabilities.d.ts b/types/2020-03-02/Capabilities.d.ts
index 55cc736d..ff2c1b99 100644
--- a/types/2020-03-02/Capabilities.d.ts
+++ b/types/2020-03-02/Capabilities.d.ts
@@ -55,7 +55,7 @@ declare module 'stripe' {
         disabled_reason: string | null;
 
         /**
-         * The fields that need to be collected again because validation or verification failed for some reason.
+         * The fields that are `currently_due` and need to be collected again because validation or verification failed for some reason.
          */
         errors: Array<Requirements.Error>;
 
diff --git a/types/2020-03-02/Cards.d.ts b/types/2020-03-02/Cards.d.ts
index 2234c454..43a839f6 100644
--- a/types/2020-03-02/Cards.d.ts
+++ b/types/2020-03-02/Cards.d.ts
@@ -154,7 +154,7 @@ declare module 'stripe' {
       recipient?: string | Stripe.Recipient | null;
 
       /**
-       * If the card number is tokenized, this is the method that was used. Can be `amex_express_checkout`, `android_pay` (includes Google Pay), `apple_pay`, `masterpass`, `visa_checkout`, or null.
+       * If the card number is tokenized, this is the method that was used. Can be `android_pay` (includes Google Pay), `apple_pay`, `masterpass`, `visa_checkout`, or null.
        */
       tokenization_method: string | null;
     }
diff --git a/types/2020-03-02/Checkout/Sessions.d.ts b/types/2020-03-02/Checkout/Sessions.d.ts
index 9690e231..94c85c2d 100644
--- a/types/2020-03-02/Checkout/Sessions.d.ts
+++ b/types/2020-03-02/Checkout/Sessions.d.ts
@@ -17,10 +17,19 @@ declare module 'stripe' {
         object: 'checkout.session';
 
         /**
-         * The value (`auto` or `required`) for whether Checkout collected the
-         * customer's billing address.
+         * Total of all items before discounts or taxes are applied.
          */
-        billing_address_collection: string | null;
+        amount_subtotal: number | null;
+
+        /**
+         * Total of all items after discounts and taxes are applied.
+         */
+        amount_total: number | null;
+
+        /**
+         * Describes whether Checkout should collect the customer's billing address.
+         */
+        billing_address_collection: Session.BillingAddressCollection | null;
 
         /**
          * The URL the customer will be directed to if they decide to cancel payment and return to your website.
@@ -34,6 +43,11 @@ declare module 'stripe' {
          */
         client_reference_id: string | null;
 
+        /**
+         * Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
+         */
+        currency: string | null;
+
         /**
          * The ID of the customer for this session.
          * For Checkout Sessions in `payment` or `subscription` mode, Checkout
@@ -126,9 +140,16 @@ declare module 'stripe' {
          * subscription creation is successful.
          */
         success_url: string;
+
+        /**
+         * Tax and discount details for the computed total amount.
+         */
+        total_details: Session.TotalDetails | null;
       }
 
       namespace Session {
+        type BillingAddressCollection = 'auto' | 'required';
+
         interface DisplayItem {
           /**
            * Amount for the display item.
@@ -204,11 +225,15 @@ declare module 'stripe' {
           | 'de'
           | 'el'
           | 'en'
+          | 'en-GB'
           | 'es'
+          | 'es-419'
           | 'et'
           | 'fi'
           | 'fr'
+          | 'fr-CA'
           | 'hu'
+          | 'id'
           | 'it'
           | 'ja'
           | 'lt'
@@ -504,6 +529,66 @@ declare module 'stripe' {
         }
 
         type SubmitType = 'auto' | 'book' | 'donate' | 'pay';
+
+        interface TotalDetails {
+          /**
+           * This is the sum of all the line item discounts.
+           */
+          amount_discount: number;
+
+          /**
+           * This is the sum of all the line item tax amounts.
+           */
+          amount_tax: number;
+
+          breakdown?: TotalDetails.Breakdown;
+        }
+
+        namespace TotalDetails {
+          interface Breakdown {
+            /**
+             * The aggregated line item discounts.
+             */
+            discounts: Array<Breakdown.Discount>;
+
+            /**
+             * The aggregated line item tax amounts by rate.
+             */
+            taxes: Array<Breakdown.Tax>;
+          }
+
+          namespace Breakdown {
+            interface Discount {
+              /**
+               * The amount discounted.
+               */
+              amount: number;
+
+              /**
+               * A discount represents the actual application of a coupon to a particular
+               * customer. It contains information about when the discount began and when it
+               * will end.
+               *
+               * Related guide: [Applying Discounts to Subscriptions](https://stripe.com/docs/billing/subscriptions/discounts).
+               */
+              discount: Stripe.Discount;
+            }
+
+            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 SessionCreateParams {
@@ -670,7 +755,7 @@ declare module 'stripe' {
           quantity: number;
 
           /**
-           * The tax rates which apply to this line item. This is only allowed in subscription mode.
+           * The [tax rates](https://stripe.com/docs/api/tax_rates) which apply to this line item. This is only allowed in subscription mode.
            */
           tax_rates?: Array<string>;
         }
@@ -757,11 +842,15 @@ declare module 'stripe' {
           | 'de'
           | 'el'
           | 'en'
+          | 'en-GB'
           | 'es'
+          | 'es-419'
           | 'et'
           | 'fi'
           | 'fr'
+          | 'fr-CA'
           | 'hu'
+          | 'id'
           | 'it'
           | 'ja'
           | 'lt'
@@ -815,7 +904,7 @@ declare module 'stripe' {
           on_behalf_of?: string;
 
           /**
-           * Email address that the receipt for the resulting payment will be sent to.
+           * Email address that the receipt for the resulting payment will be sent to. If `receipt_email` is specified for a payment in live mode, a receipt will be sent regardless of your [email settings](https://dashboard.stripe.com/account/emails).
            */
           receipt_email?: string;
 
diff --git a/types/2020-03-02/Customers.d.ts b/types/2020-03-02/Customers.d.ts
index 443a2bcd..ec6b3e1c 100644
--- a/types/2020-03-02/Customers.d.ts
+++ b/types/2020-03-02/Customers.d.ts
@@ -113,7 +113,7 @@ declare module 'stripe' {
       /**
        * The customer's current subscriptions, if any.
        */
-      subscriptions?: ApiList<Stripe.Subscription>;
+      subscriptions: ApiList<Stripe.Subscription> | null;
 
       /**
        * 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"**.
diff --git a/types/2020-03-02/Files.d.ts b/types/2020-03-02/Files.d.ts
index 2ce3dae6..661051a9 100644
--- a/types/2020-03-02/Files.d.ts
+++ b/types/2020-03-02/Files.d.ts
@@ -30,9 +30,9 @@ declare module 'stripe' {
       links?: ApiList<Stripe.FileLink> | null;
 
       /**
-       * The purpose of the file. Possible values are `additional_verification`, `business_icon`, `business_logo`, `customer_signature`, `dispute_evidence`, `document_provider_identity_document`, `finance_report_run`, `identity_document`, `pci_document`, `sigma_scheduled_query`, or `tax_document_user_upload`.
+       * The [purpose](https://stripe.com/docs/file-upload#uploading-a-file) of the uploaded file.
        */
-      purpose: string;
+      purpose: File.Purpose;
 
       /**
        * The size in bytes of the file object.
@@ -55,6 +55,18 @@ declare module 'stripe' {
       url: string | null;
     }
 
+    namespace File {
+      type Purpose =
+        | 'additional_verification'
+        | 'business_icon'
+        | 'business_logo'
+        | 'customer_signature'
+        | 'dispute_evidence'
+        | 'identity_document'
+        | 'pci_document'
+        | 'tax_document_user_upload';
+    }
+
     interface FileCreateParams {}
 
     interface FileRetrieveParams {
diff --git a/types/2020-03-02/InvoiceLineItems.d.ts b/types/2020-03-02/InvoiceLineItems.d.ts
index e145d4e7..ce9aa3fb 100644
--- a/types/2020-03-02/InvoiceLineItems.d.ts
+++ b/types/2020-03-02/InvoiceLineItems.d.ts
@@ -201,7 +201,7 @@ declare module 'stripe' {
       subscription_default_tax_rates?: Array<string> | null;
 
       /**
-       * List of subscription items, each with an attached plan.
+       * A list of up to 20 subscription items, each with an attached price.
        */
       subscription_items?: Array<
         InvoiceLineItemListUpcomingParams.SubscriptionItem
diff --git a/types/2020-03-02/Invoices.d.ts b/types/2020-03-02/Invoices.d.ts
index 70af923b..da77a7fd 100644
--- a/types/2020-03-02/Invoices.d.ts
+++ b/types/2020-03-02/Invoices.d.ts
@@ -898,7 +898,7 @@ declare module 'stripe' {
       subscription_default_tax_rates?: Array<string> | null;
 
       /**
-       * List of subscription items, each with an attached plan.
+       * A list of up to 20 subscription items, each with an attached price.
        */
       subscription_items?: Array<
         InvoiceRetrieveUpcomingParams.SubscriptionItem
diff --git a/types/2020-03-02/Issuing/Transactions.d.ts b/types/2020-03-02/Issuing/Transactions.d.ts
index 49363c5e..0420e891 100644
--- a/types/2020-03-02/Issuing/Transactions.d.ts
+++ b/types/2020-03-02/Issuing/Transactions.d.ts
@@ -217,7 +217,7 @@ declare module 'stripe' {
             type: string;
 
             /**
-             * The units for `volume`. One of `us_gallon` or `liter`.
+             * The units for `volume_decimal`. One of `us_gallon` or `liter`.
              */
             unit: string;
 
diff --git a/types/2020-03-02/LineItems.d.ts b/types/2020-03-02/LineItems.d.ts
index 77492168..7e2a8b07 100644
--- a/types/2020-03-02/LineItems.d.ts
+++ b/types/2020-03-02/LineItems.d.ts
@@ -63,7 +63,7 @@ declare module 'stripe' {
     namespace LineItem {
       interface Discount {
         /**
-         * Discount amount for this line item.
+         * The amount discounted.
          */
         amount: number;
 
@@ -79,12 +79,12 @@ declare module 'stripe' {
 
       interface Tax {
         /**
-         * Amount of tax for this line item.
+         * Amount of tax applied for this rate.
          */
         amount: number;
 
         /**
-         * Tax rates can be applied to invoices and subscriptions to collect tax.
+         * 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).
          */
diff --git a/types/2020-03-02/PaymentIntents.d.ts b/types/2020-03-02/PaymentIntents.d.ts
index af450f0a..bdef448a 100644
--- a/types/2020-03-02/PaymentIntents.d.ts
+++ b/types/2020-03-02/PaymentIntents.d.ts
@@ -140,7 +140,7 @@ declare module 'stripe' {
       payment_method_types: Array<string>;
 
       /**
-       * Email address that the receipt for the resulting payment will be sent to.
+       * Email address that the receipt for the resulting payment will be sent to. If `receipt_email` is specified for a payment in live mode, a receipt will be sent regardless of your [email settings](https://dashboard.stripe.com/account/emails).
        */
       receipt_email: string | null;
 
@@ -606,7 +606,7 @@ declare module 'stripe' {
       payment_method_types?: Array<string>;
 
       /**
-       * Email address that the receipt for the resulting payment will be sent to.
+       * Email address that the receipt for the resulting payment will be sent to. If `receipt_email` is specified for a payment in live mode, a receipt will be sent regardless of your [email settings](https://dashboard.stripe.com/account/emails).
        */
       receipt_email?: string;
 
@@ -1193,7 +1193,7 @@ declare module 'stripe' {
       payment_method_types?: Array<string>;
 
       /**
-       * Email address that the receipt for the resulting payment will be sent to.
+       * Email address that the receipt for the resulting payment will be sent to. If `receipt_email` is specified for a payment in live mode, a receipt will be sent regardless of your [email settings](https://dashboard.stripe.com/account/emails).
        */
       receipt_email?: string | null;
 
@@ -1752,7 +1752,7 @@ declare module 'stripe' {
       payment_method_options?: PaymentIntentConfirmParams.PaymentMethodOptions;
 
       /**
-       * Email address that the receipt for the resulting payment will be sent to.
+       * Email address that the receipt for the resulting payment will be sent to. If `receipt_email` is specified for a payment in live mode, a receipt will be sent regardless of your [email settings](https://dashboard.stripe.com/account/emails).
        */
       receipt_email?: string | null;
 
@@ -2317,7 +2317,7 @@ declare module 'stripe' {
       list(options?: RequestOptions): ApiListPromise<Stripe.PaymentIntent>;
 
       /**
-       * A PaymentIntent object can be canceled when it is in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_action.
+       * A PaymentIntent object can be canceled when it is in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, or requires_action.
        *
        * Once canceled, no additional charges will be made by the PaymentIntent and any operations on the PaymentIntent will fail with an error. For PaymentIntents with status='requires_capture', the remaining amount_capturable will automatically be refunded.
        */
diff --git a/types/2020-03-02/Persons.d.ts b/types/2020-03-02/Persons.d.ts
index 55b50203..25905258 100644
--- a/types/2020-03-02/Persons.d.ts
+++ b/types/2020-03-02/Persons.d.ts
@@ -246,7 +246,7 @@ declare module 'stripe' {
         currently_due: Array<string>;
 
         /**
-         * The fields that need to be collected again because validation or verification failed for some reason.
+         * The fields that are `currently_due` and need to be collected again because validation or verification failed for some reason.
          */
         errors: Array<Requirements.Error>;
 
diff --git a/types/2020-03-02/SetupIntents.d.ts b/types/2020-03-02/SetupIntents.d.ts
index d55326f6..6d064a6f 100644
--- a/types/2020-03-02/SetupIntents.d.ts
+++ b/types/2020-03-02/SetupIntents.d.ts
@@ -748,7 +748,7 @@ declare module 'stripe' {
       list(options?: RequestOptions): ApiListPromise<Stripe.SetupIntent>;
 
       /**
-       * A SetupIntent object can be canceled when it is in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_action.
+       * A SetupIntent object can be canceled when it is in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.
        *
        * Once canceled, setup is abandoned and any operations on the SetupIntent will fail with an error.
        */
diff --git a/types/2020-03-02/SubscriptionItems.d.ts b/types/2020-03-02/SubscriptionItems.d.ts
index 9cd16bff..f517b635 100644
--- a/types/2020-03-02/SubscriptionItems.d.ts
+++ b/types/2020-03-02/SubscriptionItems.d.ts
@@ -124,7 +124,7 @@ declare module 'stripe' {
        *
        * Use `pending_if_incomplete` to update the subscription using [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates). When you use `pending_if_incomplete` you can only pass the parameters [supported by pending updates](https://stripe.com/docs/billing/pending-updates-reference#supported-attributes).
        *
-       * Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's first invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not create a subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
+       * Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
        */
       payment_behavior?: SubscriptionItemCreateParams.PaymentBehavior;
 
@@ -267,7 +267,7 @@ declare module 'stripe' {
        *
        * Use `pending_if_incomplete` to update the subscription using [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates). When you use `pending_if_incomplete` you can only pass the parameters [supported by pending updates](https://stripe.com/docs/billing/pending-updates-reference#supported-attributes).
        *
-       * Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's first invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not create a subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
+       * Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
        */
       payment_behavior?: SubscriptionItemUpdateParams.PaymentBehavior;
 
@@ -487,7 +487,7 @@ declare module 'stripe' {
       ): Promise<Stripe.UsageRecord>;
 
       /**
-       * For the specified subscription item, returns a list of summary objects. Each object in the list provides usage information that's been summarized from multiple usage records and over a subscription billing period (e.g., 15 usage records in the billing plan's month of September).
+       * For the specified subscription item, returns a list of summary objects. Each object in the list provides usage information that's been summarized from multiple usage records and over a subscription billing period (e.g., 15 usage records in the month of September).
        *
        * The list is sorted in reverse-chronological order (newest first). The first list item represents the most current usage period that hasn't ended yet. Since new usage records can still be added, the returned summary information for the subscription item's ID should be seen as unstable until the subscription billing period ends.
        */
diff --git a/types/2020-03-02/SubscriptionSchedules.d.ts b/types/2020-03-02/SubscriptionSchedules.d.ts
index dea15510..ac66ab2e 100644
--- a/types/2020-03-02/SubscriptionSchedules.d.ts
+++ b/types/2020-03-02/SubscriptionSchedules.d.ts
@@ -42,7 +42,7 @@ declare module 'stripe' {
       default_settings: SubscriptionSchedule.DefaultSettings;
 
       /**
-       * Behavior of the subscription schedule and underlying subscription when it ends.
+       * Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` and `cancel`.
        */
       end_behavior: SubscriptionSchedule.EndBehavior;
 
@@ -96,6 +96,11 @@ declare module 'stripe' {
       }
 
       interface DefaultSettings {
+        /**
+         * Possible values are `phase_start` or `automatic`. If `phase_start` then billing cycle anchor of the subscription is set to the start of the phase when entering the phase. If `automatic` then the billing cycle anchor is automatically modified as needed when entering the phase. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle).
+         */
+        billing_cycle_anchor: DefaultSettings.BillingCycleAnchor;
+
         /**
          * Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period
          */
@@ -123,6 +128,8 @@ declare module 'stripe' {
       }
 
       namespace DefaultSettings {
+        type BillingCycleAnchor = 'automatic' | 'phase_start';
+
         interface BillingThresholds {
           /**
            * Monetary threshold that triggers the subscription to create an invoice
@@ -170,6 +177,11 @@ declare module 'stripe' {
          */
         application_fee_percent: number | null;
 
+        /**
+         * Possible values are `phase_start` or `automatic`. If `phase_start` then billing cycle anchor of the subscription is set to the start of the phase when entering the phase. If `automatic` then the billing cycle anchor is automatically modified as needed when entering the phase. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle).
+         */
+        billing_cycle_anchor: Phase.BillingCycleAnchor | null;
+
         /**
          * Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period
          */
@@ -211,7 +223,7 @@ declare module 'stripe' {
         plans: Array<Phase.Plan>;
 
         /**
-         * Controls whether or not the subscription schedule will prorate when transitioning to this phase. Values are `create_prorations` and `none`.
+         * Controls whether or not the subscription schedule will prorate when transitioning to this phase. Possible values are `create_prorations` and `none`.
          */
         proration_behavior: Phase.ProrationBehavior | null;
 
@@ -249,6 +261,8 @@ declare module 'stripe' {
           quantity: number | null;
         }
 
+        type BillingCycleAnchor = 'automatic' | 'phase_start';
+
         interface BillingThresholds {
           /**
            * Monetary threshold that triggers the subscription to create an invoice
@@ -376,6 +390,11 @@ declare module 'stripe' {
 
     namespace SubscriptionScheduleCreateParams {
       interface DefaultSettings {
+        /**
+         * Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle).
+         */
+        billing_cycle_anchor?: DefaultSettings.BillingCycleAnchor;
+
         /**
          * Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
          */
@@ -403,6 +422,8 @@ declare module 'stripe' {
       }
 
       namespace DefaultSettings {
+        type BillingCycleAnchor = 'automatic' | 'phase_start';
+
         interface BillingThresholds {
           /**
            * Monetary threshold that triggers the subscription to advance to a new billing period
@@ -450,6 +471,11 @@ declare module 'stripe' {
          */
         application_fee_percent?: number;
 
+        /**
+         * Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle).
+         */
+        billing_cycle_anchor?: Phase.BillingCycleAnchor;
+
         /**
          * Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
          */
@@ -496,7 +522,7 @@ declare module 'stripe' {
         plans: Array<Phase.Plan>;
 
         /**
-         * Controls whether or not a subscription schedule will create prorations when transitioning to this phase. Valid values are `create_prorations` or `none`, and the default value is `create_prorations`. See [Prorations](https://stripe.com/docs/billing/subscriptions/prorations).
+         * Controls whether or not a subscription schedule will create prorations when transitioning to this phase. Possible values are `create_prorations` or `none`, and the default value is `create_prorations`. See [Prorations](https://stripe.com/docs/billing/subscriptions/prorations).
          */
         proration_behavior?: Phase.ProrationBehavior;
 
@@ -563,6 +589,8 @@ declare module 'stripe' {
           }
         }
 
+        type BillingCycleAnchor = 'automatic' | 'phase_start';
+
         interface BillingThresholds {
           /**
            * Monetary threshold that triggers the subscription to advance to a new billing period
@@ -728,13 +756,18 @@ declare module 'stripe' {
       prorate?: boolean;
 
       /**
-       * If the update changes the current phase, indicates if the changes should be prorated. Valid values are `create_prorations` or `none`, and the default value is `create_prorations`.
+       * If the update changes the current phase, indicates if the changes should be prorated. Possible values are `create_prorations` or `none`, and the default value is `create_prorations`.
        */
       proration_behavior?: SubscriptionScheduleUpdateParams.ProrationBehavior;
     }
 
     namespace SubscriptionScheduleUpdateParams {
       interface DefaultSettings {
+        /**
+         * Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle).
+         */
+        billing_cycle_anchor?: DefaultSettings.BillingCycleAnchor;
+
         /**
          * Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
          */
@@ -762,6 +795,8 @@ declare module 'stripe' {
       }
 
       namespace DefaultSettings {
+        type BillingCycleAnchor = 'automatic' | 'phase_start';
+
         interface BillingThresholds {
           /**
            * Monetary threshold that triggers the subscription to advance to a new billing period
@@ -809,6 +844,11 @@ declare module 'stripe' {
          */
         application_fee_percent?: number;
 
+        /**
+         * Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle).
+         */
+        billing_cycle_anchor?: Phase.BillingCycleAnchor;
+
         /**
          * Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
          */
@@ -855,7 +895,7 @@ declare module 'stripe' {
         plans: Array<Phase.Plan>;
 
         /**
-         * Controls whether or not a subscription schedule will create prorations when transitioning to this phase. Valid values are `create_prorations` or `none`, and the default value is `create_prorations`. See [Prorations](https://stripe.com/docs/billing/subscriptions/prorations).
+         * Controls whether or not a subscription schedule will create prorations when transitioning to this phase. Possible values are `create_prorations` or `none`, and the default value is `create_prorations`. See [Prorations](https://stripe.com/docs/billing/subscriptions/prorations).
          */
         proration_behavior?: Phase.ProrationBehavior;
 
@@ -927,6 +967,8 @@ declare module 'stripe' {
           }
         }
 
+        type BillingCycleAnchor = 'automatic' | 'phase_start';
+
         interface BillingThresholds {
           /**
            * Monetary threshold that triggers the subscription to advance to a new billing period
diff --git a/types/2020-03-02/Subscriptions.d.ts b/types/2020-03-02/Subscriptions.d.ts
index 861b99b6..56407c2a 100644
--- a/types/2020-03-02/Subscriptions.d.ts
+++ b/types/2020-03-02/Subscriptions.d.ts
@@ -100,7 +100,7 @@ declare module 'stripe' {
       ended_at: number | null;
 
       /**
-       * List of subscription items, each with an attached plan.
+       * List of subscription items, each with an attached price.
        */
       items: ApiList<Stripe.SubscriptionItem>;
 
@@ -371,7 +371,7 @@ declare module 'stripe' {
       expand?: Array<string>;
 
       /**
-       * A list of up to 20 subscription items, each with an attached plan.
+       * A list of up to 20 subscription items, each with an attached price.
        */
       items?: Array<SubscriptionCreateParams.Item>;
 
@@ -694,7 +694,7 @@ declare module 'stripe' {
       expand?: Array<string>;
 
       /**
-       * List of subscription items, each with an attached plan.
+       * A list of up to 20 subscription items, each with an attached price.
        */
       items?: Array<SubscriptionUpdateParams.Item>;
 
@@ -718,7 +718,7 @@ declare module 'stripe' {
        *
        * Use `pending_if_incomplete` to update the subscription using [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates). When you use `pending_if_incomplete` you can only pass the parameters [supported by pending updates](https://stripe.com/docs/billing/pending-updates-reference#supported-attributes).
        *
-       * Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's first invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not create a subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
+       * Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
        */
       payment_behavior?: SubscriptionUpdateParams.PaymentBehavior;
 
diff --git a/types/2020-03-02/TaxRates.d.ts b/types/2020-03-02/TaxRates.d.ts
index a486fff3..b4511d8b 100644
--- a/types/2020-03-02/TaxRates.d.ts
+++ b/types/2020-03-02/TaxRates.d.ts
@@ -15,7 +15,7 @@ declare module 'stripe' {
       object: 'tax_rate';
 
       /**
-       * Defaults to `true`. When set to `false`, this tax rate cannot be applied to objects in the API, but will still be applied to subscriptions and invoices that already have it set.
+       * Defaults to `true`. When set to `false`, this tax rate cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
        */
       active: boolean;
 
@@ -77,7 +77,7 @@ declare module 'stripe' {
       percentage: number;
 
       /**
-       * Flag determining whether the tax rate is active or inactive. Inactive tax rates continue to work where they are currently applied however they cannot be used for new applications.
+       * Flag determining whether the tax rate is active or inactive (archived). Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
        */
       active?: boolean;
 
@@ -111,7 +111,7 @@ declare module 'stripe' {
 
     interface TaxRateUpdateParams {
       /**
-       * Flag determining whether the tax rate is active or inactive. Inactive tax rates continue to work where they are currently applied however they cannot be used for new applications.
+       * Flag determining whether the tax rate is active or inactive (archived). Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
        */
       active?: boolean;
 
@@ -143,12 +143,12 @@ declare module 'stripe' {
 
     interface TaxRateListParams extends PaginationParams {
       /**
-       * Optional flag to filter by tax rates that are either active or not active (archived)
+       * Optional flag to filter by tax rates that are either active or inactive (archived).
        */
       active?: boolean;
 
       /**
-       * Optional range for filtering created date
+       * Optional range for filtering created date.
        */
       created?: RangeQueryParam | number;
 
@@ -158,7 +158,7 @@ declare module 'stripe' {
       expand?: Array<string>;
 
       /**
-       * Optional flag to filter by tax rates that are inclusive (or those that are not inclusive)
+       * Optional flag to filter by tax rates that are inclusive (or those that are not inclusive).
        */
       inclusive?: boolean;
     }
diff --git a/yarn.lock b/yarn.lock
index b3d3eda9..d59d5000 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1398,9 +1398,9 @@ lodash.flattendeep@^4.4.0:
   integrity sha1-+wMJF/hqMTTlvJvsDWngAT3f7bI=
 
 lodash@^4.17.11, lodash@^4.17.13, lodash@^4.17.14, lodash@^4.17.15, lodash@^4.17.5:
-  version "4.17.15"
-  resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.15.tgz#b447f6670a0455bbfeedd11392eff330ea097548"
-  integrity sha512-8xOcRHvCjnocdS5cpwXQXVzmmh5e5+saE2QGoeQmbKmRS6J3VQppPOIt0MnmE+4xlZoumy0GPG0D0MVIQbNA1A==
+  version "4.17.19"
+  resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.19.tgz#e48ddedbe30b3321783c5b4301fbd353bc1e4a4b"
+  integrity sha512-JNvd8XER9GQX0v2qJgsaN/mzFCNA5BRe/j8JN9d+tWyGLSodKQHKFicdwNYzWwI3wjRnaKPsGj1XkBjx/F96DQ==
 
 log-driver@^1.2.7:
   version "1.2.7"


Test patch:
diff --git a/test/stripe.spec.js b/test/stripe.spec.js
index 08e27ffd..2de04746 100644
--- a/test/stripe.spec.js
+++ b/test/stripe.spec.js
@@ -6,6 +6,7 @@ const testUtils = require('../testUtils');
 const utils = require('../lib/utils');
 const Stripe = require('../lib/stripe');
 const stripe = require('../lib/stripe')(testUtils.getUserStripeKey(), 'latest');
+const crypto = require('crypto');
 
 const expect = require('chai').expect;
 
@@ -390,22 +391,58 @@ describe('Stripe Module', function() {
           })
         ).to.eventually.equal('Called!'));
 
-      it('Will expose HTTP response object', () =>
-        expect(
-          new Promise((resolve, reject) => {
-            stripe.customers.create(CUSTOMER_DETAILS, (err, customer) => {
-              cleanup.deleteCustomer(customer.id);
+      describe('lastResponse', () => {
+        it('Will expose HTTP response object', () =>
+          expect(
+            new Promise((resolve, reject) => {
+              stripe.customers.create(CUSTOMER_DETAILS, (err, customer) => {
+                cleanup.deleteCustomer(customer.id);
 
-              const headers = customer.lastResponse.headers;
-              expect(headers).to.contain.keys('request-id');
+                const headers = customer.lastResponse.headers;
+                expect(headers).to.contain.keys('request-id');
 
-              expect(customer.lastResponse.requestId).to.match(/^req_/);
-              expect(customer.lastResponse.statusCode).to.equal(200);
+                resolve('Called!');
+              });
+            })
+          ).to.eventually.equal('Called!'));
 
-              resolve('Called!');
-            });
-          })
-        ).to.eventually.equal('Called!'));
+        it('Will have request id, status code and version', () =>
+          expect(
+            new Promise((resolve, reject) => {
+              stripe.customers.create(CUSTOMER_DETAILS, (_err, customer) => {
+                cleanup.deleteCustomer(customer.id);
+
+                expect(customer.lastResponse.requestId).to.match(/^req_/);
+                expect(customer.lastResponse.statusCode).to.equal(200);
+                expect(customer.lastResponse.apiVersion).to.be.a('string').that
+                  .is.not.empty;
+
+                resolve('Called!');
+              });
+            })
+          ).to.eventually.equal('Called!'));
+
+        it('Will have the idempotency key', () =>
+          expect(
+            new Promise((resolve, reject) => {
+              const key = crypto.randomBytes(16).toString('hex');
+
+              stripe.customers.create(
+                CUSTOMER_DETAILS,
+                {
+                  idempotencyKey: key,
+                },
+                (err, customer) => {
+                  cleanup.deleteCustomer(customer.id);
+
+                  expect(customer.lastResponse.idempotencyKey).to.equal(key);
+
+                  resolve('Called!');
+                }
+              );
+            })
+          ).to.eventually.equal('Called!'));
+      });
 
       it('Given an error the callback will receive it', () =>
         expect(