recurly 4.6.0 → 4.10.0

data/openapi/api.yaml

@@ -219,6 +219,7 @@ x-tagGroups:
   - site
   - custom_field_definition
   - shipping_method
+  - dunning_campaigns
 tags:
 - name: site
   x-displayName: Site
@@ -332,6 +333,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:
@@ -12434,6 +12438,43 @@ paths:
               schema:
                 "$ref": "#/components/schemas/Error"
       x-code-samples: []
+  "/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: []
   "/subscriptions/{subscription_id}/change":
     get:
       tags:
@@ -12570,7 +12611,16 @@ paths:
       - 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/subscription_id"
       requestBody:
@@ -12586,6 +12636,8 @@ paths:
             application/json:
               schema:
                 "$ref": "#/components/schemas/SubscriptionChange"
+        '204':
+          description: The previous pending change was reverted.
         '404':
           description: Incorrect site ID.
           content:
@@ -14395,6 +14447,107 @@ 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}"
+  "/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:
@@ -14538,6 +14691,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
@@ -15287,6 +15447,14 @@ components:
             created by this request. Supports 'moto' value, which is the acronym for
             mail order and telephone transactions.
           "$ref": "#/components/schemas/GatewayTransactionTypeEnum"
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify a dunning campaign. Available when the
+            Dunning Campaigns feature is enabled. 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:
@@ -15357,6 +15525,14 @@ components:
             specifically whether the account is self-paying or will rely on the parent
             account to pay.
           "$ref": "#/components/schemas/BillToEnum"
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify a dunning campaign. Available when the
+            Dunning Campaigns feature is enabled. 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:
@@ -15422,6 +15598,14 @@ components:
         bill_to:
           type: string
           maxLength: 6
+        dunning_campaign_id:
+          type: string
+          title: Dunning Campaign ID
+          description: Unique ID to identify a dunning campaign. Available when the
+            Dunning Campaigns feature is enabled. 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:
@@ -16161,6 +16345,28 @@ components:
             characters comprising a country code; two check digits; and a number that
             includes the domestic bank account number, branch identifier, and potential
             routing information
+        name_on_account:
+          type: string
+          maxLength: 255
+          description: The name associated with the bank account (ACH, SEPA, Bacs
+            only)
+        account_number:
+          type: string
+          maxLength: 255
+          description: The bank account number. (ACH, Bacs only)
+        routing_number:
+          type: string
+          maxLength: 15
+          description: The bank's rounting number. (ACH only)
+        sort_code:
+          type: string
+          maxLength: 15
+          description: Bank identifier code for UK based banks. Required for Bacs
+            based billing infos. (Bacs only)
+        type:
+          "$ref": "#/components/schemas/AchTypeEnum"
+        account_type:
+          "$ref": "#/components/schemas/AchAccountTypeEnum"
         tax_identifier:
           type: string
           description: Tax identifier is required if adding a billing info that is
@@ -17338,6 +17544,13 @@ 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. Available when the Dunning Campaigns feature is enabled.
+            For sites without multiple dunning campaigns enabled, this will always
+            be the default dunning campaign.
     InvoiceCreate:
       type: object
       properties:
@@ -17707,6 +17920,12 @@ components:
           "$ref": "#/components/schemas/LegacyCategoryEnum"
         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
@@ -18250,6 +18469,14 @@ 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. Available when the
+            Dunning Campaigns feature is enabled. 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
@@ -18406,6 +18633,14 @@ 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. Available when the
+            Dunning Campaigns feature is enabled. 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
@@ -18582,6 +18817,14 @@ 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. Available when the
+            Dunning Campaigns feature is enabled. 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.
     AddOnPricing:
       type: object
       properties:
@@ -19239,6 +19482,16 @@ components:
           format: float
           title: Estimated total, before tax.
           minimum: 0
+        tax:
+          type: number
+          format: float
+          title: Estimated tax
+        tax_info:
+          "$ref": "#/components/schemas/TaxInfo"
+        total:
+          type: number
+          format: float
+          title: Estimated total
         collection_method:
           title: Collection method
           default: automatic
@@ -19298,6 +19551,12 @@ components:
             set. This timestamp is used for alerting customers to reauthorize in 3
             years in accordance with NACHA rules. If a subscription becomes inactive
             or the billing info is no longer a bank account, this timestamp is cleared.
+        gateway_code:
+          type: string
+          title: Gateway Code
+          description: If present, this subscription's transactions will use the payment
+            gateway with this code.
+          maxLength: 13
         billing_info_id:
           type: string
           title: Billing Info ID
@@ -19730,8 +19989,10 @@ components:
     SubscriptionChangeShippingCreate:
       type: object
       title: Shipping details that will be changed on a subscription
-      description: The shipping address can currently only be changed immediately,
-        using SubscriptionUpdate.
+      description: Shipping addresses are tied to a customer's account. Each account
+        can have up to 20 different shipping addresses, and if you have enabled multiple
+        subscriptions per account, you can associate different shipping addresses
+        to each subscription.
       properties:
         method_id:
           type: string
@@ -19752,6 +20013,13 @@ 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.
+        address_id:
+          type: string
+          titpe: Shipping address ID
+          description: Assign a shipping address from the account's existing shipping
+            addresses. If this and address are both present, address will take precedence.
+        address:
+          "$ref": "#/components/schemas/ShippingAddressCreate"
     SubscriptionCreate:
       type: object
       properties:
@@ -20060,6 +20328,12 @@ components:
             at 31 days exactly.
           minimum: 0
           default: 0
+        gateway_code:
+          type: string
+          title: Gateway Code
+          description: If present, this subscription's transactions will use the payment
+            gateway with this code.
+          maxLength: 13
         shipping:
           "$ref": "#/components/schemas/SubscriptionShippingUpdate"
         billing_info_id:
@@ -20075,7 +20349,8 @@ components:
         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:
@@ -20765,6 +21040,150 @@ 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:
+          "$ref": "#/components/schemas/DunningCycleTypeEnum"
+        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:
@@ -20989,20 +21408,26 @@ 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
       - pt-BR
       - pt-PT
+      - ro-RO
       - ru-RU
+      - sk-SK
       - tr-TR
       - zh-CN
     BillToEnum:
@@ -21142,16 +21567,22 @@ components:
     OriginEnum:
       type: string
       enum:
+      - carryforward_credit
+      - carryforward_gift_credit
       - credit
+      - external_refund
       - gift_card
       - immediate_change
+      - import
       - line_item_refund
       - open_amount_refund
+      - prepayment
       - purchase
+      - refund
       - renewal
       - termination
+      - usage_correction
       - write_off
-      - prepayment
     InvoiceStateEnum:
       type: string
       enum:
@@ -21388,6 +21819,7 @@ components:
       - roku
       - sepadirectdebit
       - wire_transfer
+      - braintree_v_zero
     CardTypeEnum:
       type: string
       enum:
@@ -21404,6 +21836,7 @@ components:
       - Union Pay
       - Unknown
       - Visa
+      - Tarjeta Naranja
     AccountTypeEnum:
       type: string
       enum:
@@ -21462,6 +21895,7 @@ components:
       - ach_transactions_not_supported
       - ach_validation_exception
       - amazon_amount_exceeded
+      - amazon_declined_review
       - amazon_invalid_authorization_status
       - amazon_invalid_close_attempt
       - amazon_invalid_create_order_reference
@@ -21478,13 +21912,17 @@ 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
+      - cancelled
       - cannot_refund_unsettled_transactions
       - card_not_activated
       - card_type_not_accepted
       - cardholder_requested_stop
       - contact_gateway
+      - contract_not_found
       - currency_not_supported
       - customer_canceled_transaction
       - cvv_required
@@ -21496,9 +21934,12 @@ components:
       - declined_saveable
       - declined_security_code
       - deposit_referenced_chargeback
+      - direct_debit_type_not_accepted
       - duplicate_transaction
       - exceeds_daily_limit
+      - exceeds_max_amount
       - expired_card
+      - finbot_disconnect
       - finbot_unavailable
       - fraud_address
       - fraud_address_recurly
@@ -21506,36 +21947,45 @@ components:
       - fraud_gateway
       - fraud_generic
       - fraud_ip_address
+      - fraud_manual_decision
       - fraud_risk_check
       - fraud_security_code
       - fraud_stolen_card
       - fraud_too_many_attempts
       - fraud_velocity
+      - gateway_account_setup_incomplete
       - gateway_error
       - gateway_rate_limited
       - gateway_timeout
       - gateway_token_not_found
       - gateway_unavailable
+      - gateway_validation_exception
       - insufficient_funds
       - invalid_account_number
       - invalid_amount
+      - invalid_billing_agreement_status
       - invalid_card_number
       - invalid_data
       - invalid_email
-      - invalid_gateway_configuration
       - invalid_gateway_access_token
+      - invalid_gateway_configuration
       - invalid_issuer
       - invalid_login
       - invalid_merchant_type
+      - invalid_name
+      - invalid_payment_method
+      - invalid_payment_method_hard
       - invalid_transaction
       - issuer_unavailable
       - merch_max_transaction_limit_exceeded
+      - moneybot_disconnect
       - moneybot_unavailable
       - no_billing_information
       - no_gateway
       - no_gateway_found_for_transaction_amount
       - partial_approval
       - partial_credits_not_supported
+      - payer_authentication_rejected
       - payment_cannot_void_authorization
       - payment_not_accepted
       - paypal_account_issue
@@ -21545,7 +21995,9 @@ components:
       - paypal_hard_decline
       - paypal_invalid_billing_agreement
       - paypal_primary_declined
+      - processor_not_available
       - processor_unavailable
+      - recurly_credentials_not_found
       - recurly_error
       - recurly_failed_to_get_token
       - recurly_token_mismatch
@@ -21553,10 +22005,18 @@ components:
       - reference_transactions_not_enabled
       - restricted_card
       - restricted_card_chargeback
+      - rjs_token_expired
+      - roku_invalid_card_number
+      - roku_invalid_cib
+      - roku_invalid_payment_method
+      - roku_zip_code_mismatch
       - simultaneous
       - ssl_error
       - temporary_hold
+      - three_d_secure_action_required
+      - three_d_secure_action_result_token_mismatch
       - three_d_secure_authentication
+      - three_d_secure_connection_error
       - three_d_secure_not_supported
       - too_many_attempts
       - total_credit_exceeds_capture
@@ -21568,10 +22028,13 @@ components:
       - transaction_cannot_be_voided
       - transaction_failed_to_settle
       - transaction_not_found
+      - transaction_service_v2_disconnect
+      - transaction_service_v2_unavailable
       - transaction_settled
       - transaction_stale_at_gateway
       - try_again
       - unknown
+      - unmapped_partner_error
       - vaultly_service_unavailable
       - zero_dollar_auth_not_supported
     ExportDates:
@@ -21617,3 +22080,22 @@ components:
       enum:
       - cpf
       - cuit
+    DunningCycleTypeEnum:
+      type: string
+      description: The type of invoice this cycle applies to.
+      enum:
+      - automatic
+      - manual
+      - trial
+    AchTypeEnum:
+      type: string
+      description: The payment method type for a non-credit card based billing info.
+        The value of `bacs` is the only accepted value (Bacs only)
+      enum:
+      - bacs
+    AchAccountTypeEnum:
+      type: string
+      description: The bank account type. (ACH only)
+      enum:
+      - checking
+      - savings