recurly 3.18.1 → 3.21.0

data/openapi/api.yaml

@@ -24,6 +24,42 @@ info:
     Recurly-Version: recurly.v2019-10-10
     ```
 
+    Recurly's client libraries correspond with API versions as listed below.
+
+    <table>
+      <tr>
+        <th>API Version</th>
+        <th>Client Library Version</th>
+      </tr>
+      <tr>
+        <td>v2021-02-25</td>
+        <td>4.x</td>
+      </tr>
+      <tr>
+        <td>v2019-10-10</td>
+        <td>3.x</td>
+      </tr>
+    </table>
+
+    Client library releases:
+
+    * [Node.js](https://github.com/recurly/recurly-client-node/releases)
+    * [Python](https://github.com/recurly/recurly-client-python/releases)
+    * [.NET](https://github.com/recurly/recurly-client-dotnet/releases)
+    * [Ruby](https://github.com/recurly/recurly-client-ruby/releases)
+    * [Java](https://github.com/recurly/recurly-client-java/releases)
+    * [PHP](https://github.com/recurly/recurly-client-php/releases)
+    * [Go](https://github.com/recurly/recurly-client-go/releases)
+
+    Client libraries follow semantic versioning. For example, [Ruby client library
+    version 3.18.1](https://github.com/recurly/recurly-client-ruby/releases/tag/3.18.1)
+    represents major version `3`, minor version `18` with patch `1`.
+
+    We encourage you to update to the latest version of the API and corresponding client library,
+    as most recent versions are more performant than their predecessors. See the
+    [changelog](https://developers.recurly.com/api/changelog.html) for a comprehensive list of changes
+    introduced in the latest API version.
+
     ### Default Versions
     Specifying a version is required to get a successful response. If you wish to
     receive the latest version and are willing to accept the risk of breaking changes,
@@ -77,6 +113,8 @@ info:
     Please consider changing these messages in target system to be better
     suited to the audience of the system.
 
+    Please see [transaction error codes](https://developers.recurly.com/pages/api-transaction-errors.html) for more details.
+
     ## Pagination
     ### Response Schema
     Every GET listing endpoint returns a response with the same schema:
@@ -153,6 +191,7 @@ x-tagGroups:
   - note
   - account_acquisition
   - billing_info
+  - billing_infos
   - subscription
   - subscription_change
   - shipping_address
@@ -179,6 +218,7 @@ x-tagGroups:
   - site
   - custom_field_definition
   - shipping_method
+  - dunning_campaigns
 tags:
 - name: site
   x-displayName: Site
@@ -191,7 +231,7 @@ tags:
   description: |-
     For merchants who sell the same things to many customers, documenting those offerings in a catalog allows for faster charge creation, easier management of offerings, and analytics about your offerings across all sales channels. Because your offerings can be physical, digital, or service-oriented, Recurly collectively calls these offerings "Items".
 
-    Recurly's item catalog requires the Credit Invoices and Subscription Billing Terms features to be enabled.
+    Recurly's item catalog requires the Credit Invoices feature to be enabled.
 - name: plan
   x-displayName: Plan
   description: A plan tells Recurly how often and how much to charge your customers.
@@ -223,9 +263,15 @@ tags:
     to match this data with revenue and billing data events in Recurly.
 - name: billing_info
   x-displayName: Billing Info
-  description: An account can have one stored payment method at a time. This can be
-    a credit card, PayPal, or bank account. Billing info is usually filled out by
-    the customer upon purchase or when they update their information.
+  description: Without the premium Wallet feature, an account can only have one stored
+    payment method at a time. Examples include credit cards, PayPal, or bank accounts.
+    Billing info is filled out by the customer upon purchase or when they update their
+    information.
+- name: billing_infos
+  x-displayName: Billing Infos
+  description: If the premium Wallet feature is enabled, an account can have multiple
+    payment methods stored. Examples include credit cards, PayPal, or bank accounts.
+    Primary or backup billing infos can be designated from these endpoints.
 - name: subscription
   x-displayName: Subscription
   description: Subscriptions are created when your customers subscribe to one of your
@@ -286,6 +332,9 @@ tags:
 - name: automated_exports
   x-displayName: Automated Exports
   description: Automated exports of customer data.
+- name: dunning_campaigns
+  x-displayName: Dunning Campaigns
+  description: Settings used when attempting to dun customers whose payments are declined.
 paths:
   "/sites":
     get:
@@ -1226,7 +1275,6 @@ paths:
     - "$ref": "#/components/parameters/account_id"
     get:
       tags:
-      - account
       - account_acquisition
       operationId: get_account_acquisition
       summary: Fetch an account's acquisition data
@@ -1335,7 +1383,6 @@ paths:
           Acquisition: %v\", accountAcq.Id)"
     put:
       tags:
-      - account
       - account_acquisition
       operationId: update_account_acquisition
       summary: Update an account's acquisition data
@@ -1503,7 +1550,6 @@ paths:
           Acquisition: %s\", account.Id)"
     delete:
       tags:
-      - account
       - account_acquisition
       operationId: remove_account_acquisition
       summary: Remove an account's acquisition data
@@ -1844,7 +1890,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/billing_info":
     get:
       tags:
-      - account
       - billing_info
       operationId: get_billing_info
       summary: Fetch an account's billing information
@@ -1962,14 +2007,13 @@ paths:
           Info: %v\", billingInfo)"
     put:
       tags:
-      - account
       - billing_info
       operationId: update_billing_info
       summary: Set an account's billing information
       description: |
         If you're using Recurly.js to securely submit data from webforms without sending it through your server,
         you can associate the billing information with an account by passing in the `token_id`. The only other
-        field permitted with `token_id` is `primary_payment_method`.
+        fields permitted with `token_id` are `primary_payment_method` and/or `backup_payment_method`.
 
         For credit card payments you'll need the following required fields:
 
@@ -2137,7 +2181,6 @@ paths:
           Info: %s\", billingInfo)"
     delete:
       tags:
-      - account
       - billing_info
       operationId: remove_billing_info
       summary: Remove an account's billing information
@@ -2244,11 +2287,142 @@ paths:
           {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected
           Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Removed Billing
           Info: %v\", billingInfo)"
+  "/sites/{site_id}/accounts/{account_id}/billing_info/verify":
+    post:
+      tags:
+      - billing_info
+      operationId: verify_billing_info
+      summary: Verify an account's credit card billing information
+      parameters:
+      - "$ref": "#/components/parameters/site_id"
+      - "$ref": "#/components/parameters/account_id"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/BillingInfoVerify"
+        required: false
+      responses:
+        '200':
+          description: Transaction information from verify.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Transaction"
+        '404':
+          description: Account has no billing information, or incorrect site or account
+            ID.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        default:
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '422':
+          description: Invalid billing information, or error running the verification
+            transaction.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorMayHaveTransaction"
+      x-code-samples:
+      - lang: Node.js
+        source: |
+          try {
+            const transaction = await client.verifyBillingInfo(accountId)
+            console.log('Fetched Transaction: ', transaction.id)
+          } catch (err) {
+            if (err instanceof recurly.errors.NotFoundError) {
+              // If the request was not found, you may want to alert the user or
+              // just return null
+              console.log('Resource Not Found')
+            } else {
+              // If we don't know what to do with the err, we should
+              // probably re-raise and let our web framework and logger handle it
+              console.log('Unknown Error: ', err)
+            }
+          }
+      - lang: Python
+        source: |
+          try:
+              transaction = client.verify_billing_info(account_id)
+              print("Got Transaction %s" % transaction)
+          except recurly.errors.NotFoundError:
+              # If the resource was not found, you may want to alert the user or
+              # just return nil
+              print("Resource Not Found")
+      - lang: ".NET"
+        source: |
+          try
+          {
+              Transaction transaction = client.VerifyBillingInfo(accountId);
+              Console.WriteLine($"Fetched transaction {transaction.Id}");
+          }
+          catch (Recurly.Errors.NotFound ex)
+          {
+              // If the resource was not found
+              // we may want to alert the user or just return null
+              Console.WriteLine($"Resource Not Found: {ex.Error.Message}");
+          }
+          catch (Recurly.Errors.ApiError ex)
+          {
+              // Use ApiError to catch a generic error from the API
+              Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}");
+          }
+      - lang: Ruby
+        source: |
+          begin
+            transaction = @client.verify_billing_info(account_id: account_id)
+            puts "Got Transaction #{transaction}"
+          rescue Recurly::Errors::NotFoundError
+            # If the resource was not found, you may want to alert the user or
+            # just return nil
+            puts "Resource Not Found"
+          end
+      - lang: Java
+        source: |
+          try {
+              final Transaction transaction = client.verifyBillingInfo(accountId);
+              System.out.println("Fetched transaction " + transaction.getId());
+          } catch (NotFoundException e) {
+              // If the resource was not found
+              // we may want to alert the user or just return null
+              System.out.println("Resource Not Found: " + e.getError().getMessage());
+          } catch (ApiException e) {
+              // Use ApiException to catch a generic error from the API
+              System.out.println("Unexpected Recurly Error: " + e.getError().getMessage());
+          }
+      - lang: PHP
+        source: |
+          try {
+              $transaction = $client->verifyBillingInfo($account_id);
+
+              echo 'Got Transaction:' . PHP_EOL;
+              var_dump($transaction);
+          } catch (\Recurly\Errors\NotFound $e) {
+              // Could not find the resource, you may want to inform the user
+              // or just return a NULL
+              echo 'Could not find resource.' . PHP_EOL;
+              var_dump($e);
+          } catch (\Recurly\RecurlyError $e) {
+              // Something bad happened... tell the user so that they can fix it?
+              echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL;
+          }
+      - lang: Go
+        source: "verifyBillingInfoParams := &recurly.VerifyBillingInfoParams{}\ntransaction,
+          err := client.VerifyBillingInfo(accountID, verifyBillingInfoParams)\nif
+          e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound
+          {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected
+          Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Fetched Transaction:
+          %v\", transaction)"
   "/sites/{site_id}/accounts/{account_id}/billing_infos":
     get:
       tags:
-      - account
-      - billing_info
+      - billing_infos
       operationId: list_billing_infos
       summary: Get the list of billing information associated with an account
       description: See the [Pagination Guide](/guides/pagination.html) to learn how
@@ -2282,14 +2456,13 @@ paths:
       x-code-samples: []
     post:
       tags:
-      - account
-      - billing_info
+      - billing_infos
       operationId: create_billing_info
-      summary: Set an account's billing information when the wallet feature is enabled
+      summary: Add new billing information on an account
       description: |
         If you're using Recurly.js to securely submit data from webforms without sending it through your server,
         you can associate the billing information with an account by passing in the `token_id`. The only other
-        field permitted with `token_id` is `primary_payment_method`.
+        fields permitted with `token_id` are `primary_payment_method` and/or `backup_payment_method`.
 
         For credit card payments you'll need the following required fields:
 
@@ -2344,8 +2517,7 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/billing_infos/{billing_info_id}":
     get:
       tags:
-      - account
-      - billing_info
+      - billing_infos
       operationId: get_a_billing_info
       summary: Fetch a billing info
       parameters:
@@ -2368,14 +2540,13 @@ paths:
       x-code-samples: []
     put:
       tags:
-      - account
-      - billing_info
+      - billing_infos
       operationId: update_a_billing_info
       summary: Update an account's billing information
       description: |
         If you're using Recurly.js to securely submit data from webforms without sending it through your server,
         you can associate the billing information with an account by passing in the `token_id`. The only other
-        field permitted with `token_id` is `primary_payment_method`.
+        fields permitted with `token_id` are `primary_payment_method` and/or `backup_payment_method`.
 
         For credit card payments you'll need the following required fields:
 
@@ -2430,8 +2601,7 @@ paths:
       x-code-samples: []
     delete:
       tags:
-      - account
-      - billing_info
+      - billing_infos
       operationId: remove_a_billing_info
       summary: Remove an account's billing information
       parameters:
@@ -2462,7 +2632,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/coupon_redemptions":
     get:
       tags:
-      - account
       - coupon_redemption
       operationId: list_account_coupon_redemptions
       summary: Show the coupon redemptions for an account
@@ -2552,7 +2721,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/coupon_redemptions/active":
     get:
       tags:
-      - account
       - coupon_redemption
       operationId: get_active_coupon_redemption
       summary: Show the coupon redemption that is active on an account
@@ -2669,7 +2837,6 @@ paths:
           Coupon Redemption: %v\", couponRedemption.Id)"
     post:
       tags:
-      - account
       - coupon_redemption
       operationId: create_coupon_redemption
       summary: Generate an active coupon redemption on an account or subscription
@@ -2801,7 +2968,6 @@ paths:
           Redemption: %v\", couponRedemption)"
     delete:
       tags:
-      - account
       - coupon_redemption
       operationId: remove_coupon_redemption
       summary: Delete the active coupon redemption from an account
@@ -2917,7 +3083,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/credit_payments":
     get:
       tags:
-      - account
       - credit_payment
       operationId: list_account_credit_payments
       summary: List an account's credit payments
@@ -3014,7 +3179,6 @@ paths:
     get:
       tags:
       - invoice
-      - account
       operationId: list_account_invoices
       summary: List an account's invoices
       description: See the [Pagination Guide](/guides/pagination.html) to learn how
@@ -3110,7 +3274,6 @@ paths:
     post:
       tags:
       - invoice
-      - account
       operationId: create_invoice
       summary: Create an invoice for pending line items
       parameters:
@@ -3282,7 +3445,6 @@ paths:
     post:
       tags:
       - invoice
-      - account
       operationId: preview_invoice
       summary: Preview new invoice for pending line items
       parameters:
@@ -3452,7 +3614,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/line_items":
     get:
       tags:
-      - account
       - line_item
       operationId: list_account_line_items
       summary: List an account's line items
@@ -3551,7 +3712,6 @@ paths:
           Item %3d: %s\\n\",\n\t\t\ti,\n\t\t\tlineItem.Id,\n\t\t)\n\t}\n}"
     post:
       tags:
-      - account
       - line_item
       operationId: create_line_item
       summary: Create a new line item for the account
@@ -3721,7 +3881,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/notes":
     get:
       tags:
-      - account
       - note
       operationId: list_account_notes
       summary: Fetch a list of an account's notes
@@ -3803,7 +3962,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/notes/{account_note_id}":
     get:
       tags:
-      - account
       - note
       operationId: get_account_note
       summary: Fetch an account note
@@ -3931,7 +4089,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/shipping_addresses":
     get:
       tags:
-      - account
       - shipping_address
       operationId: list_shipping_addresses
       summary: Fetch a list of an account's shipping addresses
@@ -4021,7 +4178,6 @@ paths:
           Address %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tshippingAddress.Id,\n\t\t\tshippingAddress.Street1,\n\t\t)\n\t}\n}"
     post:
       tags:
-      - account
       - shipping_address
       operationId: create_shipping_address
       summary: Create a new shipping address for the account
@@ -4212,7 +4368,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/shipping_addresses/{shipping_address_id}":
     get:
       tags:
-      - account
       - shipping_address
       operationId: get_shipping_address
       summary: Fetch an account's shipping address
@@ -4333,7 +4488,6 @@ paths:
           Address: %v\", shippingAddress)"
     put:
       tags:
-      - account
       - shipping_address
       operationId: update_shipping_address
       summary: Update an account's shipping address
@@ -4505,7 +4659,6 @@ paths:
           shippingAddress)"
     delete:
       tags:
-      - account
       - shipping_address
       operationId: remove_shipping_address
       summary: Remove an account's shipping address
@@ -4616,7 +4769,6 @@ paths:
     get:
       tags:
       - subscription
-      - account
       operationId: list_account_subscriptions
       summary: List an account's subscriptions
       description: See the [Pagination Guide](/guides/pagination.html) to learn how
@@ -4712,7 +4864,6 @@ paths:
   "/sites/{site_id}/accounts/{account_id}/transactions":
     get:
       tags:
-      - account
       - transaction
       operationId: list_account_transactions
       summary: List an account's transactions
@@ -5648,7 +5799,6 @@ paths:
   "/sites/{site_id}/coupons/{coupon_id}/generate":
     post:
       tags:
-      - coupon
       - unique_coupon_code
       operationId: generate_unique_coupon_codes
       summary: Generate unique coupon codes
@@ -5842,7 +5992,6 @@ paths:
   "/sites/{site_id}/coupons/{coupon_id}/unique_coupon_codes":
     get:
       tags:
-      - coupon
       - unique_coupon_code
       operationId: list_unique_coupon_codes
       summary: List unique coupon codes associated with a bulk coupon
@@ -8405,7 +8554,6 @@ paths:
   "/sites/{site_id}/invoices/{invoice_id}/line_items":
     get:
       tags:
-      - invoice
       - line_item
       operationId: list_invoice_line_items
       summary: List an invoice's line items
@@ -8496,7 +8644,7 @@ paths:
           $params = ['limit' => 200];
           $invoice_line_items = $client->listInvoiceLineItems($invoice_id, $params);
 
-          foreach($invoice_line_item as $line_item) {
+          foreach($invoice_line_items as $line_item) {
             echo 'Invoice Line Item: ' . $line_item->getId() . PHP_EOL;
           }
       - lang: Go
@@ -8508,7 +8656,6 @@ paths:
   "/sites/{site_id}/invoices/{invoice_id}/coupon_redemptions":
     get:
       tags:
-      - invoice
       - coupon_redemption
       operationId: list_invoice_coupon_redemptions
       summary: Show the coupon redemptions applied to an invoice
@@ -9848,7 +9995,6 @@ paths:
     get:
       tags:
       - add-on
-      - plan
       operationId: list_plan_add_ons
       summary: List a plan's add-ons
       description: See the [Pagination Guide](/guides/pagination.html) to learn how
@@ -9944,7 +10090,6 @@ paths:
     post:
       tags:
       - add-on
-      - plan
       operationId: create_plan_add_on
       summary: Create an add-on
       parameters:
@@ -10142,7 +10287,6 @@ paths:
   "/sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}":
     get:
       tags:
-      - plan
       - add-on
       operationId: get_plan_add_on
       summary: Fetch a plan's add-on
@@ -10262,7 +10406,6 @@ paths:
           Add-On: %v\", planAddOn)"
     put:
       tags:
-      - plan
       - add-on
       operationId: update_plan_add_on
       summary: Update an add-on
@@ -10406,7 +10549,6 @@ paths:
           Add-On: %v\", planAddOn)"
     delete:
       tags:
-      - plan
       - add-on
       operationId: remove_plan_add_on
       summary: Remove an add-on
@@ -11175,8 +11317,7 @@ paths:
             subscription_create = {
               plan_code: plan_code,
               currency: "USD",
-              # This can be an existing account or
-              # a new acocunt
+              # This can be an existing account or a new account
               account: {
                 code: account_code,
               }
@@ -12268,10 +12409,46 @@ paths:
               schema:
                 "$ref": "#/components/schemas/Error"
       x-code-samples: []
-  "/sites/{site_id}/subscriptions/{subscription_id}/change":
+  "/sites/{site_id}/subscriptions/{subscription_id}/preview_renewal":
     get:
       tags:
       - subscription
+      operationId: get_preview_renewal
+      summary: Fetch a preview of a subscription's renewal invoice(s)
+      description: The subscriptions's renewal invoice(s) will be returned if they
+        exist; if they don't (for example, if the subscription is not set to renew),
+        it will return an result with no invoices.
+      parameters:
+      - "$ref": "#/components/parameters/subscription_id"
+      responses:
+        '200':
+          description: A preview of the subscription's renewal invoice(s).
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/InvoiceCollection"
+        '400':
+          description: Invalid or unpermitted parameter.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '404':
+          description: Incorrect site ID or subscription ID.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        default:
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+      x-code-samples: []
+  "/sites/{site_id}/subscriptions/{subscription_id}/change":
+    get:
+      tags:
       - subscription_change
       operationId: get_subscription_change
       summary: Fetch a subscription's pending change
@@ -12403,11 +12580,19 @@ paths:
           change: %s\", subscriptionChange.Id)"
     post:
       tags:
-      - subscription
       - subscription_change
       operationId: create_subscription_change
       summary: Create a new subscription change
-      description: Calling this will overwrite an existing, pending subscription change.
+      description: |
+        Calling this will overwrite an existing, pending subscription change.
+
+        If a subscription has a pending change, and a change is submitted which matches
+        the subscription as it currently exists, the pending change will be deleted,
+        and you will receive a 204 No Content response.
+
+        If a subscription has no pending
+        change, and a change is submitted which matches the subscription as it currently
+        exists, a 422 Unprocessable Entity validation error will be returned.
       parameters:
       - "$ref": "#/components/parameters/site_id"
       - "$ref": "#/components/parameters/subscription_id"
@@ -12424,6 +12609,8 @@ paths:
             application/json:
               schema:
                 "$ref": "#/components/schemas/SubscriptionChange"
+        '204':
+          description: The previous pending change was reverted.
         '404':
           description: Incorrect site ID.
           content:
@@ -12563,7 +12750,6 @@ paths:
           changed: %s\", subscriptionChange.Id)"
     delete:
       tags:
-      - subscription
       - subscription_change
       operationId: remove_subscription_change
       summary: Delete the pending subscription change
@@ -12679,7 +12865,6 @@ paths:
   "/sites/{site_id}/subscriptions/{subscription_id}/change/preview":
     post:
       tags:
-      - subscription
       - subscription_change
       operationId: preview_subscription_change
       summary: Preview a new subscription change
@@ -12725,7 +12910,6 @@ paths:
     get:
       tags:
       - invoice
-      - subscription
       operationId: list_subscription_invoices
       summary: List a subscription's invoices
       description: See the [Pagination Guide](/guides/pagination.html) to learn how
@@ -12822,7 +13006,7 @@ paths:
   "/sites/{site_id}/subscriptions/{subscription_id}/line_items":
     get:
       tags:
-      - subscription
+      - line_item
       operationId: list_subscription_line_items
       summary: List a subscription's line items
       description: See the [Pagination Guide](/guides/pagination.html) to learn how
@@ -12921,7 +13105,6 @@ paths:
   "/sites/{site_id}/subscriptions/{subscription_id}/coupon_redemptions":
     get:
       tags:
-      - subscription
       - coupon_redemption
       operationId: list_subscription_coupon_redemptions
       summary: Show the coupon redemptions for a subscription
@@ -13009,8 +13192,6 @@ paths:
   "/sites/{site_id}/subscriptions/{subscription_id}/add_ons/{add_on_id}/usage":
     get:
       tags:
-      - invoice
-      - subscription
       - usage
       operationId: list_usage
       summary: List a subscription add-on's usage records
@@ -13053,8 +13234,6 @@ paths:
       x-code-samples: []
     post:
       tags:
-      - invoice
-      - subscription
       - usage
       operationId: create_usage
       summary: Log a usage record on this subscription add-on
@@ -13103,8 +13282,6 @@ paths:
   "/sites/{site_id}/usage/{usage_id}":
     get:
       tags:
-      - invoice
-      - subscription
       - usage
       operationId: get_usage
       summary: Get a usage record
@@ -13139,8 +13316,6 @@ paths:
       x-code-samples: []
     put:
       tags:
-      - invoice
-      - subscription
       - usage
       operationId: update_usage
       summary: Update a usage record
@@ -13187,8 +13362,6 @@ paths:
       x-code-samples: []
     delete:
       tags:
-      - invoice
-      - subscription
       - usage
       operationId: remove_usage
       summary: Delete a usage record.
@@ -13990,9 +14163,14 @@ paths:
               var_dump($e);
           }
       - lang: Go
-        source: "collection, err := client.PreviewPurchase(purchaseReq)\nif e, ok
-          := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation
-          {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected
+        source: "purchaseReq := &recurly.PurchaseCreate{\n\tCurrency: recurly.String(\"USD\"),\n\tAccount:
+          &recurly.AccountPurchase{\n\t\tCode: recurly.String(account.Code),\n\t},\n\tSubscriptions:
+          []recurly.SubscriptionPurchase{\n\t\t{\n\t\t\tPlanCode:     recurly.String(plan.Code),\n\t\t\tNextBillDate:
+          recurly.Time(time.Date(2078, time.November, 10, 23, 0, 0, 0, time.UTC)),\n\t\t},\n\t},\n\tShipping:
+          &recurly.ShippingPurchase{\n\t\tAddressId: recurly.String(shippingAddressID),\n\t},\n}\ncollection,
+          err := client.PreviewPurchase(purchaseReq)\nif e, ok := err.(*recurly.Error);
+          ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed
+          validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected
           Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Preview Charge
           Invoice %v\", collection.ChargeInvoice)"
   "/sites/{site_id}/export_dates":
@@ -14220,46 +14398,148 @@ paths:
           err.(*recurly.Error); ok {\n\tfmt.Printf(\"Unexpected Recurly error: %v\",
           e)\n\treturn nil, err\n}\n\nfor _, file := range exportFiles.Files {\n\tfmt.Println(\"Export
           file download URL: \", file.Href)\n}"
-servers:
-- url: https://v3.recurly.com
-components:
-  parameters:
-    site_id:
-      name: site_id
-      in: path
-      description: Site ID or subdomain. For ID no prefix is used e.g. `e28zov4fw0v2`.
-        For subdomain use prefix `subdomain-`, e.g. `subdomain-recurly`.
-      required: true
-      schema:
-        type: string
-    account_id:
-      name: account_id
-      in: path
-      description: Account ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`.
-        For code use prefix `code-`, e.g. `code-bob`.
-      required: true
-      schema:
-        type: string
-    add_on_id:
-      name: add_on_id
-      in: path
-      description: Add-on ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`.
-        For code use prefix `code-`, e.g. `code-gold`.
-      required: true
-      schema:
-        type: string
-    billing_info_id:
-      name: billing_info_id
-      in: path
-      description: Billing Info ID.
-      required: true
-      schema:
-        type: string
-    usage_id:
-      name: usage_id
-      in: path
-      description: Usage Record ID.
-      required: true
+  "/sites/{site_id}/dunning_campaigns":
+    get:
+      tags:
+      - dunning_campaigns
+      operationId: list_dunning_campaigns
+      summary: Show the dunning campaigns for a site
+      description: See the [Pagination Guide](/guides/pagination.html) to learn how
+        to use pagination in the API and Client Libraries.
+      parameters:
+      - "$ref": "#/components/parameters/sort_dates"
+      responses:
+        '200':
+          description: A list of the the dunning_campaigns on an account.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/DunningCampaignList"
+        '404':
+          description: Incorrect site.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        default:
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+      x-code-samples: []
+  "/dunning_campaigns/{dunning_campaign_id}":
+    parameters:
+    - "$ref": "#/components/parameters/dunning_campaign_id"
+    get:
+      tags:
+      - dunning_campaigns
+      operationId: get_dunning_campaign
+      summary: Show the settings for a dunning campaign
+      responses:
+        '200':
+          description: Settings for a dunning campaign.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/DunningCampaign"
+        '400':
+          description: Bad request; perhaps missing or invalid parameters.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '404':
+          description: Incorrect site or campaign ID.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        default:
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+      x-code-samples: []
+  "/dunning_campaigns/{dunning_campaign_id}/bulk_update":
+    put:
+      tags:
+      - dunning_campaigns
+      operationId: put_dunning_campaign_bulk_update
+      summary: Assign a dunning campaign to multiple plans
+      requestBody:
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/DunningCampaignsBulkUpdate"
+      responses:
+        '200':
+          description: A list of updated plans.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/DunningCampaignsBulkUpdateResponse"
+        '400':
+          description: Bad request; perhaps missing or invalid parameters.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '404':
+          description: Incorrect site or campaign ID.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        default:
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+      x-code-samples: []
+servers:
+- url: https://v3.recurly.com
+components:
+  parameters:
+    site_id:
+      name: site_id
+      in: path
+      description: Site ID or subdomain. For ID no prefix is used e.g. `e28zov4fw0v2`.
+        For subdomain use prefix `subdomain-`, e.g. `subdomain-recurly`.
+      required: true
+      schema:
+        type: string
+    account_id:
+      name: account_id
+      in: path
+      description: Account ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`.
+        For code use prefix `code-`, e.g. `code-bob`.
+      required: true
+      schema:
+        type: string
+    add_on_id:
+      name: add_on_id
+      in: path
+      description: Add-on ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`.
+        For code use prefix `code-`, e.g. `code-gold`.
+      required: true
+      schema:
+        type: string
+    billing_info_id:
+      name: billing_info_id
+      in: path
+      description: Billing Info ID. Can ONLY be used for sites utilizing the Wallet
+        feature.
+      required: true
+      schema:
+        type: string
+    usage_id:
+      name: usage_id
+      in: path
+      description: Usage Record ID.
+      required: true
       schema:
         type: string
     coupon_id:
@@ -14363,6 +14643,13 @@ components:
       required: true
       schema:
         type: string
+    dunning_campaign_id:
+      name: dunning_campaign_id
+      in: path
+      description: Dunning Campaign ID, e.g. `e28zov4fw0v2`.
+      required: true
+      schema:
+        type: string
     ids:
       name: ids
       in: query
@@ -15124,20 +15411,28 @@ components:
           - en-AU
           - en-CA
           - en-GB
+          - en-IE
           - en-NZ
           - en-US
           - es-ES
           - es-MX
           - es-US
+          - fi-FI
           - fr-CA
           - fr-FR
           - hi-IN
+          - it-IT
           - ja-JP
+          - ko-KR
           - nl-BE
           - nl-NL
+          - pl-PL
           - pt-BR
           - pt-PT
+          - ro-RO
           - ru-RU
+          - sk-SK
+          - sv-SE
           - tr-TR
           - zh-CN
         cc_emails:
@@ -15204,6 +15499,13 @@ components:
             mail order and telephone transactions.
           enum:
           - moto
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify a dunning campaign. Used to specify if
+            a non-default dunning campaign should be assigned to this account. For
+            sites without multiple dunning campaigns enabled, the default dunning
+            campaign will always be used.
         address:
           "$ref": "#/components/schemas/Address"
         billing_info:
@@ -15241,20 +15543,28 @@ components:
           - en-AU
           - en-CA
           - en-GB
+          - en-IE
           - en-NZ
           - en-US
           - es-ES
           - es-MX
           - es-US
+          - fi-FI
           - fr-CA
           - fr-FR
           - hi-IN
+          - it-IT
           - ja-JP
+          - ko-KR
           - nl-BE
           - nl-NL
+          - pl-PL
           - pt-BR
           - pt-PT
+          - ro-RO
           - ru-RU
+          - sk-SK
+          - sv-SE
           - tr-TR
           - zh-CN
         cc_emails:
@@ -15300,6 +15610,13 @@ components:
           enum:
           - self
           - parent
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify a dunning campaign. Used to specify if
+            a non-default dunning campaign should be assigned to this account. For
+            sites without multiple dunning campaigns enabled, the default dunning
+            campaign will always be used.
         address:
           "$ref": "#/components/schemas/Address"
         billing_info:
@@ -15365,6 +15682,13 @@ components:
         bill_to:
           type: string
           maxLength: 6
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify a dunning campaign. Used to specify if
+            a non-default dunning campaign should be assigned to this account. For
+            sites without multiple dunning campaigns enabled, the default dunning
+            campaign will always be used.
     AccountBalance:
       type: object
       properties:
@@ -15394,6 +15718,12 @@ components:
           format: float
           title: Amount
           description: Total amount the account is past due.
+        processing_prepayment_amount:
+          type: number
+          format: float
+          title: Amount
+          description: Total amount for the prepayment credit invoices in a `processing`
+            state on the account.
     InvoiceAddress:
       allOf:
       - "$ref": "#/components/schemas/Address"
@@ -15437,7 +15767,7 @@ components:
         country:
           type: string
           title: Country
-          description: Country, 2-letter ISO code.
+          description: Country, 2-letter ISO 3166-1 alpha-2 code.
     AddOnMini:
       type: object
       title: Add-on mini details
@@ -15679,7 +16009,6 @@ components:
       required:
       - code
       - name
-      - currencies
     AddOnCreate:
       type: object
       title: Add-on
@@ -15689,16 +16018,16 @@ components:
           type: string
           title: Item Code
           description: Unique code to identify an item. Avaliable when the `Credit
-            Invoices` and `Subscription Billing Terms` features are enabled. If `item_id`
-            and `item_code` are both present, `item_id` will be used.
+            Invoices` feature is enabled. If `item_id` and `item_code` are both present,
+            `item_id` will be used.
           pattern: "/^[a-z0-9_+-]+$/"
           maxLength: 50
         item_id:
           type: string
           title: Item ID
           description: System-generated unique identifier for an item. Available when
-            the `Credit Invoices` and `Subscription Billing Terms` features are enabled.
-            If `item_id` and `item_code` are both present, `item_id` will be used.
+            the `Credit Invoices` feature is enabled. If `item_id` and `item_code`
+            are both present, `item_id` will be used.
           maxLength: 13
         code:
           type: string
@@ -15839,6 +16168,7 @@ components:
             is not present `currencies` is required.
             * If the add-on's `tier_type` is `tiered`, `volume`, or `stairstep`,
             then `currencies` must be absent.
+            * Must be absent if `add_on_type` is `usage` and `usage_type` is `percentage`.
         tier_type:
           type: string
           title: Tier type
@@ -15866,7 +16196,6 @@ components:
       required:
       - code
       - name
-      - currencies
     AddOnUpdate:
       type: object
       title: Add-on
@@ -15986,7 +16315,8 @@ components:
           minItems: 1
           description: |
             If the add-on's `tier_type` is `tiered`, `volume` or `stairstep`,
-            then `currencies` must be absent.
+            then `currencies` must be absent. Must also be absent if `add_on_type` is
+            `usage` and `usage_type` is `percentage`.
         tiers:
           type: array
           title: Tiers
@@ -16058,14 +16388,14 @@ components:
               title: Kount rules
         primary_payment_method:
           type: boolean
-          description: The `primary_payment_method` indicator is used to designate
-            the primary billing info on the account. The first billing info created
-            on an account will always become primary. Adding additional billing infos
-            provides the flexibility to mark another billing info as primary, or adding
-            additional non-primary billing infos. This can be accomplished by passing
-            the `primary_payment_method` indicator. When adding billing infos via
-            the billing_info and /accounts endpoints, this value is not permitted,
-            and will return an error if provided.
+          description: The `primary_payment_method` field is used to indicate the
+            primary billing info on the account. The first billing info created on
+            an account will always become primary. This payment method will be used
+        backup_payment_method:
+          type: boolean
+          description: The `backup_payment_method` field is used to indicate a billing
+            info as a backup on the account that will be tried if the initial billing
+            info used for an invoice is declined.
         created_at:
           type: string
           format: date-time
@@ -16087,7 +16417,8 @@ components:
               maxLength: 20
             country:
               type: string
-              description: Country of IP address, if known by Recurly.
+              description: Country, 2-letter ISO 3166-1 alpha-2 code matching the
+                origin IP address, if known by Recurly.
               maxLength: 2
     BillingInfoCreate:
       type: object
@@ -16198,8 +16529,9 @@ components:
           type: string
           enum:
           - bacs
+          - becs
           description: The payment method type for a non-credit card based billing
-            info. The value of `bacs` is the only accepted value (Bacs only)
+            info. `bacs` and `becs` are the only accepted values.
         account_type:
           type: string
           enum:
@@ -16220,14 +16552,29 @@ components:
         primary_payment_method:
           type: boolean
           title: Primary Payment Method
-          description: The `primary_payment_method` indicator is used to designate
-            the primary billing info on the account. The first billing info created
-            on an account will always become primary. Adding additional billing infos
+          description: The `primary_payment_method` field is used to designate the
+            primary billing info on the account. The first billing info created on
+            an account will always become primary. Adding additional billing infos
             provides the flexibility to mark another billing info as primary, or adding
             additional non-primary billing infos. This can be accomplished by passing
-            the `primary_payment_method` indicator. When adding billing infos via
-            the billing_info and /accounts endpoints, this value is not permitted,
-            and will return an error if provided.
+            the `primary_payment_method` with a value of `true`. When adding billing
+            infos via the billing_info and /accounts endpoints, this value is not
+            permitted, and will return an error if provided.
+        backup_payment_method:
+          type: boolean
+          description: The `backup_payment_method` field is used to designate a billing
+            info as a backup on the account that will be tried if the initial billing
+            info used for an invoice is declined. All payment methods, including the
+            billing info marked `primary_payment_method` can be set as a backup. An
+            account can have a maximum of 1 backup, if a user sets a different payment
+            method as a backup, the existing backup will no longer be marked as such.
+    BillingInfoVerify:
+      type: object
+      properties:
+        gateway_code:
+          type: string
+          description: An identifier for a specific payment gateway.
+          maxLength: 13
     Coupon:
       type: object
       properties:
@@ -16912,7 +17259,7 @@ components:
           title: Field value
           description: Any values that resemble a credit card number or security code
             (CVV/CVC) will be rejected.
-          maxLength: 100
+          maxLength: 255
       required:
       - name
       - value
@@ -17324,6 +17671,12 @@ components:
           - gift_card
           - write_off
           - prepayment
+          - refund
+          - external_refund
+          - carryforward_credit
+          - carryforward_gift_credit
+          - usage_correction
+          - import
         state:
           type: string
           title: Invoice state
@@ -17344,7 +17697,8 @@ components:
           description: The `billing_info_id` is the value that represents a specific
             billing info for an end customer. When `billing_info_id` is used to assign
             billing info to the subscription, all future billing events for the subscription
-            will bill to the specified billing info.
+            will bill to the specified billing info. `billing_info_id` can ONLY be
+            used for sites utilizing the Wallet feature.
         subscription_ids:
           type: array
           title: Subscription IDs
@@ -17414,7 +17768,8 @@ components:
           type: number
           format: float
           title: Subtotal
-          description: The summation of charges, discounts, and credits, before tax.
+          description: The summation of charges and credits, before discounts and
+            taxes.
         tax:
           type: number
           format: float
@@ -17504,6 +17859,12 @@ components:
           format: date-time
           title: Closed at
           description: Date invoice was marked paid or failed.
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify the dunning campaign used when dunning
+            the invoice. For sites without multiple dunning campaigns enabled, this
+            will always be the default dunning campaign.
     InvoiceCreate:
       type: object
       properties:
@@ -17592,7 +17953,8 @@ components:
           description: The `billing_info_id` is the value that represents a specific
             billing info for an end customer. When `billing_info_id` is used to assign
             billing info to the subscription, all future billing events for the subscription
-            will bill to the specified billing info.
+            will bill to the specified billing info. `billing_info_id` can ONLY be
+            used for sites utilizing the Wallet feature.
     InvoiceCollection:
       type: object
       title: Invoice collection
@@ -17883,20 +18245,20 @@ components:
           type: string
           title: Item Code
           description: Unique code to identify an item. Available when the Credit
-            Invoices and Subscription Billing Terms features are enabled.
+            Invoices feature is enabled.
           pattern: "/^[a-z0-9_+-]+$/"
           maxLength: 50
         item_id:
           type: string
           title: Item ID
           description: System-generated unique identifier for an item. Available when
-            the Credit Invoices and Subscription Billing Terms features are enabled.
+            the Credit Invoices feature is enabled.
           maxLength: 13
         external_sku:
           type: string
           title: External SKU
           description: Optional Stock Keeping Unit assigned to an item. Available
-            when the Credit Invoices and Subscription Billing Terms features are enabled.
+            when the Credit Invoices feature is enabled.
           maxLength: 50
         revenue_schedule_type:
           type: string
@@ -17932,6 +18294,12 @@ components:
           - carryforward
         account:
           "$ref": "#/components/schemas/AccountMini"
+        bill_for_account_id:
+          type: string
+          title: Bill For Account ID
+          maxLength: 13
+          description: The UUID of the account responsible for originating the line
+            item.
         subscription_id:
           type: string
           title: Subscription ID
@@ -18060,6 +18428,12 @@ components:
           format: float
           title: Unit amount
           description: Positive amount for a charge, negative amount for a credit.
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          description: Determines whether or not tax is included in the unit amount.
+            The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing
+            feature) must be enabled to utilize this flag.
         subtotal:
           type: number
           format: float
@@ -18198,6 +18572,13 @@ components:
             A positive or negative amount with `type=credit` will result in a negative `unit_amount`.
             If `item_code`/`item_id` is present, `unit_amount` can be passed in, to override the `Item`'s
             `unit_amount`. If `item_code`/`item_id` is not present then `unit_amount` is required.
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          default: false
+          description: Determines whether or not tax is included in the unit amount.
+            The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing
+            feature) must be enabled to use this flag.
         quantity:
           type: integer
           title: Quantity
@@ -18214,14 +18595,14 @@ components:
           type: string
           title: Item Code
           description: Unique code to identify an item. Avaliable when the Credit
-            Invoices and Subscription Billing Terms features are enabled.
+            Invoices feature is enabled.
           pattern: "/^[a-z0-9_+-]+$/"
           maxLength: 50
         item_id:
           type: string
           title: Item ID
           description: System-generated unique identifier for an item. Available when
-            the Credit Invoices and Subscription Billing Terms features are enabled.
+            the Credit Invoices feature is enabled.
           maxLength: 13
         revenue_schedule_type:
           type: string
@@ -18447,6 +18828,22 @@ components:
             renew its term at renewal. If `auto_renew` is `false`, then a subscription
             will expire at the end of its term. `auto_renew` can be overridden on
             the subscription record itself.
+        pricing_model:
+          title: Pricing Model
+          type: string
+          enum:
+          - fixed
+          - ramp
+          default: fixed
+          description: |
+            A fixed pricing model has the same price for each billing period.
+            A ramp pricing model defines a set of Ramp Intervals, where a subscription changes price on
+            a specified cadence of billing periods. The price change could be an increase or decrease.
+        ramp_intervals:
+          type: array
+          title: Ramp Intervals
+          items:
+            "$ref": "#/components/schemas/PlanRampInterval"
         accounting_code:
           type: string
           title: Plan accounting code
@@ -18522,6 +18919,13 @@ components:
             Used to determine whether items can be assigned as add-ons to individual subscriptions.
             If `true`, items can be assigned as add-ons to individual subscription add-ons.
             If `false`, only plan add-ons can be used.
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify a dunning campaign. Used to specify if
+            a non-default dunning campaign should be assigned to this plan. For sites
+            without multiple dunning campaigns enabled, the default dunning campaign
+            will always be used.
         created_at:
           type: string
           format: date-time
@@ -18618,6 +19022,22 @@ components:
             renew its term at renewal. If `auto_renew` is `false`, then a subscription
             will expire at the end of its term. `auto_renew` can be overridden on
             the subscription record itself.
+        pricing_model:
+          title: Pricing Model
+          type: string
+          enum:
+          - fixed
+          - ramp
+          default: fixed
+          description: |
+            A fixed pricing model has the same price for each billing period.
+            A ramp pricing model defines a set of Ramp Intervals, where a subscription changes price on
+            a specified cadence of billing periods. The price change could be an increase or decrease.
+        ramp_intervals:
+          type: array
+          title: Ramp Intervals
+          items:
+            "$ref": "#/components/schemas/PlanRampInterval"
         revenue_schedule_type:
           type: string
           title: Revenue schedule type
@@ -18694,6 +19114,13 @@ components:
             Used to determine whether items can be assigned as add-ons to individual subscriptions.
             If `true`, items can be assigned as add-ons to individual subscription add-ons.
             If `false`, only plan add-ons can be used.
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify a dunning campaign. Used to specify if
+            a non-default dunning campaign should be assigned to this plan. For sites
+            without multiple dunning campaigns enabled, the default dunning campaign
+            will always be used.
       required:
       - code
       - name
@@ -18742,8 +19169,15 @@ components:
           type: number
           format: float
           title: Unit price
+          description: This field should not be sent when the pricing model is 'ramp'.
           minimum: 0
           maximum: 1000000
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          default: false
+          description: This field is deprecated. Please do not use it.
+          deprecated: true
     PlanUpdate:
       type: object
       properties:
@@ -18813,6 +19247,11 @@ components:
             renew its term at renewal. If `auto_renew` is `false`, then a subscription
             will expire at the end of its term. `auto_renew` can be overridden on
             the subscription record itself.
+        ramp_intervals:
+          type: array
+          title: Ramp Intervals
+          items:
+            "$ref": "#/components/schemas/PlanRampInterval"
         revenue_schedule_type:
           type: string
           title: Revenue schedule type
@@ -18883,6 +19322,26 @@ components:
             Used to determine whether items can be assigned as add-ons to individual subscriptions.
             If `true`, items can be assigned as add-ons to individual subscription add-ons.
             If `false`, only plan add-ons can be used.
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify a dunning campaign. Used to specify if
+            a non-default dunning campaign should be assigned to this plan. For sites
+            without multiple dunning campaigns enabled, the default dunning campaign
+            will always be used.
+    PlanRampInterval:
+      type: object
+      title: Plan Ramp Interval
+      properties:
+        starting_billing_cycle:
+          type: integer
+          description: Represents the first billing cycle of a ramp.
+          default: 1
+        currencies:
+          type: array
+          description: Represents the price for the ramp interval.
+          items:
+            "$ref": "#/components/schemas/PlanRampPricing"
     AddOnPricing:
       type: object
       properties:
@@ -18897,6 +19356,30 @@ components:
           title: Unit price
           minimum: 0
           maximum: 1000000
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          default: false
+          description: This field is deprecated. Please do not use it.
+          deprecated: true
+      required:
+      - currency
+      - unit_amount
+    PlanRampPricing:
+      type: object
+      properties:
+        currency:
+          type: string
+          title: Currency
+          description: 3-letter ISO 4217 currency code.
+          maxLength: 3
+        unit_amount:
+          type: number
+          format: float
+          title: Unit price
+          description: Represents the price for the Ramp Interval.
+          minimum: 0
+          maximum: 1000000
       required:
       - currency
       - unit_amount
@@ -18914,6 +19397,12 @@ components:
           title: Unit price
           minimum: 0
           maximum: 1000000
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          default: false
+          description: This field is deprecated. Please do not use it.
+          deprecated: true
       required:
       - currency
       - unit_amount
@@ -19018,7 +19507,7 @@ components:
         country:
           type: string
           maxLength: 50
-          description: Country, 2-letter ISO code.
+          description: Country, 2-letter ISO 3166-1 alpha-2 code.
         created_at:
           type: string
           title: Created at
@@ -19073,7 +19562,7 @@ components:
         country:
           type: string
           maxLength: 50
-          description: Country, 2-letter ISO code.
+          description: Country, 2-letter ISO 3166-1 alpha-2 code.
       required:
       - first_name
       - last_name
@@ -19323,7 +19812,7 @@ components:
         country:
           type: string
           maxLength: 50
-          description: Country, 2-letter ISO code.
+          description: Country, 2-letter ISO 3166-1 alpha-2 code.
     Site:
       type: object
       properties:
@@ -19479,6 +19968,13 @@ components:
           default: true
           title: Auto renew
           description: Whether the subscription renews at the end of its term.
+        ramp_intervals:
+          type: array
+          title: Ramp Intervals
+          description: The ramp intervals representing the pricing schedule for the
+            subscription.
+          items:
+            "$ref": "#/components/schemas/SubscriptionRampIntervalResponse"
         paused_at:
           type: string
           format: date-time
@@ -19507,6 +20003,12 @@ components:
           type: number
           format: float
           title: Subscription unit price
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          description: Determines whether or not tax is included in the unit amount.
+            The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing
+            feature) must be enabled to utilize this flag.
         quantity:
           type: integer
           title: Subscription quantity
@@ -19592,6 +20094,13 @@ components:
           type: string
           title: Billing Info ID
           description: Billing Info ID.
+        active_invoice_id:
+          type: string
+          title: Active invoice ID
+          description: The invoice ID of the latest invoice created for an active
+            subscription.
+          maxLength: 13
+          readOnly: true
     SubscriptionAddOn:
       type: object
       title: Subscription Add-on
@@ -19871,6 +20380,12 @@ components:
           type: number
           format: float
           title: Unit amount
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          default: false
+          description: This field is deprecated. Please do not use it.
+          deprecated: true
         quantity:
           type: integer
           title: Subscription quantity
@@ -19921,6 +20436,28 @@ components:
           format: date-time
           title: Deleted at
           readOnly: true
+        billing_info:
+          "$ref": "#/components/schemas/SubscriptionChangeBillingInfo"
+        ramp_intervals:
+          type: array
+          title: Ramp Intervals
+          description: The ramp intervals representing the pricing schedule for the
+            subscription.
+          items:
+            "$ref": "#/components/schemas/SubscriptionRampIntervalResponse"
+    SubscriptionChangeBillingInfo:
+      type: object
+      description: Accept nested attributes for three_d_secure_action_result_token_id
+      properties:
+        three_d_secure_action_result_token_id:
+          type: string
+          title: 3-D Secure action result token ID
+          description: A token generated by Recurly.js after completing a 3-D Secure
+            device fingerprinting or authentication challenge.
+          maxLength: 22
+    SubscriptionChangeBillingInfoCreate:
+      allOf:
+      - "$ref": "#/components/schemas/SubscriptionChangeBillingInfo"
     SubscriptionChangeCreate:
       type: object
       properties:
@@ -19961,6 +20498,12 @@ components:
             be used.
           minimum: 0
           maximum: 1000000
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          default: false
+          description: This field is deprecated. Please do not use it.
+          deprecated: true
         quantity:
           type: integer
           title: Quantity
@@ -20039,6 +20582,14 @@ components:
             mail order and telephone transactions.
           enum:
           - moto
+        billing_info:
+          "$ref": "#/components/schemas/SubscriptionChangeBillingInfoCreate"
+        ramp_intervals:
+          type: array
+          title: Ramp Intervals
+          description: The new set of ramp intervals for the subscription.
+          items:
+            "$ref": "#/components/schemas/SubscriptionRampInterval"
     SubscriptionChangePreview:
       type: object
       allOf:
@@ -20091,7 +20642,8 @@ components:
           description: The `billing_info_id` is the value that represents a specific
             billing info for an end customer. When `billing_info_id` is used to assign
             billing info to the subscription, all future billing events for the subscription
-            will bill to the specified billing info.
+            will bill to the specified billing info. `billing_info_id` can ONLY be
+            used for sites utilizing the Wallet feature.
         shipping:
           title: Shipping address
           description: Create a shipping address on the account and assign it to the
@@ -20118,6 +20670,13 @@ components:
             the subscription plan for the provided currency.
           minimum: 0
           maximum: 1000000
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          default: false
+          description: Determines whether or not tax is included in the unit amount.
+            The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing
+            feature) must be enabled to use this flag.
         quantity:
           type: integer
           title: Quantity
@@ -20141,8 +20700,11 @@ components:
           type: string
           format: date-time
           title: Trial ends at
-          description: If set, overrides the default trial behavior for the subscription.
-            The date must be in the future.
+          description: IIf set, overrides the default trial behavior for the subscription.
+            When the current date time or a past date time is provided the subscription
+            will begin with no trial phase (overriding any plan default trial). When
+            a future date time is provided the subscription will begin with a trial
+            phase ending at the specified date time.
         starts_at:
           type: string
           format: date-time
@@ -20179,6 +20741,12 @@ components:
           default: true
           title: Auto renew
           description: Whether the subscription renews at the end of its term.
+        ramp_intervals:
+          type: array
+          title: Ramp Intervals
+          description: The new set of ramp intervals for the subscription.
+          items:
+            "$ref": "#/components/schemas/SubscriptionRampInterval"
         revenue_schedule_type:
           type: string
           title: Revenue schedule type
@@ -20248,10 +20816,17 @@ components:
           format: float
           title: Custom subscription pricing
           description: Override the unit amount of the subscription plan by setting
-            this value in cents. If not provided, the subscription will inherit the
-            price from the subscription plan for the provided currency.
+            this value. If not provided, the subscription will inherit the price from
+            the subscription plan for the provided currency.
           minimum: 0
           maximum: 1000000
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          default: false
+          description: Determines whether or not tax is included in the unit amount.
+            The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing
+            feature) must be enabled to use this flag.
         quantity:
           type: integer
           title: Quantity
@@ -20275,7 +20850,10 @@ components:
           format: date-time
           title: Trial ends at
           description: If set, overrides the default trial behavior for the subscription.
-            The date must be in the future.
+            When the current date time or a past date time is provided the subscription
+            will begin with no trial phase (overriding any plan default trial). When
+            a future date time is provided the subscription will begin with a trial
+            phase ending at the specified date time.
         starts_at:
           type: string
           format: date-time
@@ -20320,6 +20898,12 @@ components:
           - evenly
           - at_range_end
           - at_range_start
+        ramp_intervals:
+          type: array
+          title: Ramp Intervals
+          description: The new set of ramp intervals for the subscription.
+          items:
+            "$ref": "#/components/schemas/SubscriptionRampInterval"
       required:
       - plan_code
     SubscriptionUpdate:
@@ -20392,6 +20976,12 @@ components:
             at 31 days exactly.
           minimum: 0
           default: 0
+        tax_inclusive:
+          type: boolean
+          title: Tax Inclusive?
+          default: false
+          description: This field is deprecated. Please do not use it.
+          deprecated: true
         shipping:
           "$ref": "#/components/schemas/SubscriptionShippingUpdate"
         billing_info_id:
@@ -20400,14 +20990,16 @@ components:
           description: The `billing_info_id` is the value that represents a specific
             billing info for an end customer. When `billing_info_id` is used to assign
             billing info to the subscription, all future billing events for the subscription
-            will bill to the specified billing info.
+            will bill to the specified billing info. `billing_info_id` can ONLY be
+            used for sites utilizing the Wallet feature.
     SubscriptionPause:
       type: object
       properties:
         remaining_pause_cycles:
           type: integer
           title: Remaining pause cycles
-          description: Number of billing cycles to pause the subscriptions.
+          description: Number of billing cycles to pause the subscriptions. A value
+            of 0 will cancel any pending pauses on the subscription.
       required:
       - remaining_pause_cycles
     SubscriptionShipping:
@@ -20495,6 +21087,30 @@ components:
           format: float
           title: Assigns the subscription's shipping cost. If this is greater than
             zero then a `method_id` or `method_code` is required.
+    SubscriptionRampInterval:
+      type: object
+      title: Subscription Ramp Interval
+      properties:
+        starting_billing_cycle:
+          type: integer
+          description: Represents how many billing cycles are included in a ramp interval.
+          default: 1
+        unit_amount:
+          type: integer
+          description: Represents the price for the ramp interval.
+    SubscriptionRampIntervalResponse:
+      type: object
+      title: Subscription Ramp Interval
+      properties:
+        starting_billing_cycle:
+          type: integer
+          description: Represents how many billing cycles are included in a ramp interval.
+        remaining_billing_cycles:
+          type: integer
+          description: Represents how many billing cycles are left in a ramp interval.
+        unit_amount:
+          type: integer
+          description: Represents the price for the ramp interval.
     TaxInfo:
       type: object
       title: Tax info
@@ -20516,6 +21132,38 @@ components:
           type: number
           format: float
           title: Rate
+        tax_details:
+          type: array
+          description: Provides additional tax details for Canadian Sales Tax when
+            there is tax applied at both the country and province levels. This will
+            only be populated for the Invoice response when fetching a single invoice
+            and not for the InvoiceList or LineItem.
+          items:
+            "$ref": "#/components/schemas/TaxDetail"
+    TaxDetail:
+      type: object
+      title: Tax detail
+      properties:
+        type:
+          type: string
+          title: Type
+          description: Provides the tax type for the region. For Canadian Sales Tax,
+            this will be GST, HST, QST or PST.
+        region:
+          type: string
+          title: Region
+          description: Provides the tax region applied on an invoice. For Canadian
+            Sales Tax, this will be either the 2 letter province code or country code.
+        rate:
+          type: number
+          format: float
+          title: Rate
+          description: Provides the tax rate for the region.
+        tax:
+          type: number
+          format: float
+          title: Tax
+          description: The total tax applied for this tax type.
     Transaction:
       type: object
       properties:
@@ -20612,6 +21260,10 @@ components:
           type: boolean
           title: Success?
           description: Did this transaction complete successfully?
+        backup_payment_method_used:
+          type: boolean
+          title: Backup Payment Method Used?
+          description: Indicates if the transaction was completed using a backup payment
         refunded:
           type: boolean
           title: Refunded?
@@ -20637,7 +21289,8 @@ components:
             - When the merchant enters billing information using the UI, no IP address is recorded.
         ip_address_country:
           type: string
-          title: IP address's country
+          title: Origin IP address country, 2-letter ISO 3166-1 alpha-2 code, if known
+            by Recurly.
         status_code:
           type: string
           title: Status code
@@ -21031,7 +21684,8 @@ components:
           description: The `billing_info_id` is the value that represents a specific
             billing info for an end customer. When `billing_info_id` is used to assign
             billing info to the subscription, all future billing events for the subscription
-            will bill to the specified billing info.
+            will bill to the specified billing info. `billing_info_id` can ONLY be
+            used for sites utilizing the Wallet feature.
         collection_method:
           type: string
           title: Collection method
@@ -21136,6 +21790,155 @@ components:
       required:
       - currency
       - account
+    DunningCampaign:
+      type: object
+      description: Settings for a dunning campaign.
+      properties:
+        id:
+          type: string
+        object:
+          type: string
+          title: Object type
+        code:
+          type: string
+          description: Campaign code.
+        name:
+          type: string
+          description: Campaign name.
+        description:
+          type: string
+          description: Campaign description.
+        default_campaign:
+          type: boolean
+          description: Whether or not this is the default campaign for accounts or
+            plans without an assigned dunning campaign.
+        dunning_cycles:
+          type: array
+          description: Dunning Cycle settings.
+          items:
+            "$ref": "#/components/schemas/DunningCycle"
+        created_at:
+          type: string
+          format: date-time
+          description: When the current campaign was created in Recurly.
+        updated_at:
+          type: string
+          format: date-time
+          description: When the current campaign was updated in Recurly.
+        deleted_at:
+          type: string
+          format: date-time
+          description: When the current campaign was deleted in Recurly.
+    DunningCampaignList:
+      type: object
+      properties:
+        object:
+          type: string
+          title: Object type
+          description: Will always be List.
+        has_more:
+          type: boolean
+          description: Indicates there are more results on subsequent pages.
+        next:
+          type: string
+          description: Path to subsequent page of results.
+        data:
+          type: array
+          items:
+            "$ref": "#/components/schemas/DunningCampaign"
+    DunningCycle:
+      type: object
+      properties:
+        type:
+          type: string
+          description: The type of invoice this cycle applies to.
+          enum:
+          - automatic
+          - manual
+          - trial
+        applies_to_manual_trial:
+          type: boolean
+          description: Whether the dunning settings will be applied to manual trials.
+            Only applies to trial cycles.
+        first_communication_interval:
+          type: integer
+          description: The number of days after a transaction failure before the first
+            dunning email is sent.
+        send_immediately_on_hard_decline:
+          type: boolean
+          description: Whether or not to send an extra email immediately to customers
+            whose initial payment attempt fails with either a hard decline or invalid
+            billing info.
+        intervals:
+          type: array
+          description: Dunning intervals.
+          items:
+            "$ref": "#/components/schemas/DunningInterval"
+        expire_subscription:
+          type: boolean
+          description: Whether the subscription(s) should be cancelled at the end
+            of the dunning cycle.
+        fail_invoice:
+          type: boolean
+          description: Whether the invoice should be failed at the end of the dunning
+            cycle.
+        total_dunning_days:
+          type: integer
+          description: The number of days between the first dunning email being sent
+            and the end of the dunning cycle.
+        total_recycling_days:
+          type: integer
+          description: The number of days between a transaction failure and the end
+            of the dunning cycle.
+        version:
+          type: integer
+          description: Current campaign version.
+        created_at:
+          type: string
+          format: date-time
+          description: When the current settings were created in Recurly.
+        updated_at:
+          type: string
+          format: date-time
+          description: When the current settings were updated in Recurly.
+    DunningInterval:
+      properties:
+        days:
+          type: integer
+          description: Number of days before sending the next email.
+        email_template:
+          type: string
+          description: Email template being used.
+    DunningCampaignsBulkUpdate:
+      properties:
+        plan_codes:
+          type: array
+          maxItems: 200
+          description: List of `plan_codes` associated with the Plans for which the
+            dunning campaign should be updated. Required unless `plan_ids` is present.
+          items:
+            type: string
+        plan_ids:
+          type: array
+          maxItems: 200
+          description: List of `plan_ids` associated with the Plans for which the
+            dunning campaign should be updated. Required unless `plan_codes` is present.
+          items:
+            type: string
+    DunningCampaignsBulkUpdateResponse:
+      properties:
+        object:
+          type: string
+          title: Object type
+          readOnly: true
+        plans:
+          type: array
+          title: Plans
+          description: An array containing all of the `Plan` resources that have been
+            updated.
+          maxItems: 200
+          items:
+            "$ref": "#/components/schemas/Plan"
     PaymentMethod:
       properties:
         object:
@@ -21157,6 +21960,7 @@ components:
           - gateway_token
           - iban_bank_account
           - other
+          - braintree_v_zero
         card_type:
           type: string
           description: Visa, MasterCard, American Express, Discover, JCB, etc.
@@ -21174,6 +21978,7 @@ components:
           - Union Pay
           - Unknown
           - Visa
+          - Tarjeta Naranja
         first_six:
           type: string
           description: Credit card number's first six digits.
@@ -21200,6 +22005,11 @@ components:
           description: A token used in place of a credit card in order to perform
             transactions.
           maxLength: 50
+        cc_bin_country:
+          type: string
+          description: The 2-letter ISO 3166-1 alpha-2 country code associated with
+            the credit card BIN, if known by Recurly. Available on the BillingInfo
+            object only. Available when the BIN country lookup feature is enabled.
         gateway_code:
           type: string
           description: An identifier for a specific payment gateway.
@@ -21249,6 +22059,7 @@ components:
           - validation
           - missing_feature
           - rate_limited
+          - tax_service_error
         message:
           type: string
           title: Message
@@ -21328,6 +22139,8 @@ components:
                 - batch_processing_error
                 - billing_agreement_already_accepted
                 - billing_agreement_not_accepted
+                - billing_agreement_not_found
+                - billing_agreement_replaced
                 - call_issuer
                 - call_issuer_update_cardholder_data
                 - cannot_refund_unsettled_transactions
@@ -21373,6 +22186,7 @@ components:
                 - invalid_data
                 - invalid_email
                 - invalid_gateway_configuration
+                - invalid_gateway_access_token
                 - invalid_issuer
                 - invalid_login
                 - invalid_merchant_type