Merge pull request #366 from recurly/api_version_2_11

API v2.11 changes

lib/recurly.rb

@@ -4,6 +4,7 @@ module Recurly
   require 'recurly/helper'
   require 'recurly/api'
   require 'recurly/resource'
+  require 'recurly/shipping_address'
   require 'recurly/billing_info'
   require 'recurly/account'
   require 'recurly/account_balance'
@@ -23,7 +24,6 @@ module Recurly
   require 'recurly/measured_unit'
   require 'recurly/plan'
   require 'recurly/redemption'
-  require 'recurly/shipping_address'
   require 'recurly/subscription'
   require 'recurly/subscription_add_on'
   require 'recurly/transaction'

lib/recurly/account.rb

@@ -73,6 +73,8 @@ def redemption(coupon_code)
       has_future_subscription
       has_canceled_subscription
       has_past_due_invoice
+      has_paused_subscription
+      preferred_locale
     )
     alias to_param account_code
 

lib/recurly/adjustment.rb

@@ -21,6 +21,9 @@ class Adjustment < Resource
     # @return [Pager<Adjustment>, []]
     has_many :credit_adjustments, class_name: :Adjustment, readonly: true
 
+    # @return [ShippingAddress, nil]
+    has_one :shipping_address, class_name: :ShippingAddress, readonly: false
+
     define_attribute_methods %w(
       uuid
       state
@@ -50,6 +53,7 @@ class Adjustment < Resource
       proration_rate
       credit_reason_code
       original_adjustment_uuid
+      shipping_address_id
     )
     alias to_param uuid
 

lib/recurly/api.rb

@@ -17,7 +17,7 @@ class API
     @@base_uri = "https://api.recurly.com/v2/"
     @@valid_domains = [".recurly.com"]
 
-    RECURLY_API_VERSION = '2.10'
+    RECURLY_API_VERSION = '2.11'
 
     FORMATS = Helper.hash_with_indifferent_read_access(
       'pdf' => 'application/pdf',

lib/recurly/invoice.rb

@@ -32,7 +32,7 @@ class Invoice < Resource
     # @return [Pager<Redemption>, []]
     has_many :redemptions
 
-    # @return [Pager<ShippingAddress>, [ShippingAddress], []]
+    # @return [ShippingAddress, nil]
     has_one :shipping_address, class_name: :ShippingAddress, readonly: true
 
     # @return [Pager<Invoice>, []]

lib/recurly/purchase.rb

@@ -19,18 +19,42 @@ module Recurly
   # in the same way you would when creating a {Subscription} with a new account.
   #
   # You can also pass in adjustments and invoicing data to be passed to the invoice.
+  #
+  # There are multiple ways to set the shipping addresses:
+  # 1. Use {Purchase#shipping_address_id} If you want to apply an existing shipping
+  #    address to all subscriptions and adjustments in this purchase.
+  # 2. Add multiple shipping addresses to {Account#shipping_addresses}. The last
+  #    address in the list will apply to all subscriptions and adjustments
+  #    in this purchase.
+  # 3. Use {Subscription#shipping_address_id} or {Subscription#shipping_address}
+  #    to set a shipping address for only the subscription.
+  # 4. Use {Adjustment#shipping_address_id} or {Adjustment#shipping_address}
+  #    to set a shipping address for only the adjustment.
+  #
   # @example
   #   require 'securerandom'
   #
-  #   purchase = Recurly::Purchase.new({
+  #   purchase = Recurly::Purchase.new(
   #     currency: 'USD',
   #     collection_method: :automatic,
   #     account: {
   #       account_code: SecureRandom.uuid,
+  #       shipping_addresses: [
+  #         {
+  #           first_name: 'Benjamin',
+  #           last_name: 'Du Monde',
+  #           address1: '400 Dolores St.',
+  #           city: 'San Francisco',
+  #           state: 'CA',
+  #           zip: '94110',
+  #           country: 'US',
+  #           nickname: 'Home'
+  #         }
+  #       ],
   #       billing_info: {
   #         first_name: 'Benjamin',
   #         last_name: 'Du Monde',
-  #         address1: '400 Alabama St',
+  #         address1: '400 Alabama St.',
   #         city: 'San Francisco',
   #         state: 'CA',
   #         zip: '94110',
@@ -54,7 +78,7 @@ module Recurly
   #         revenue_schedule_type: :at_invoice
   #       }
   #     ]
-  #   })
+  #   )
   #
   #   begin
   #     preview_invoice = Recurly::Purchase.preview!(purchase)
@@ -98,6 +122,7 @@ class Purchase < Resource
       terms_and_conditions
       customer_notes
       vat_reverse_charge_notes
+      shipping_address_id
     )
 
     class << self

lib/recurly/subscription.rb

@@ -80,6 +80,8 @@ class Subscription < Resource
       no_billing_info_reason
       imported_trial
       credit_customer_notes
+      remaining_pause_cycles
+      paused_at
     )
     alias to_param uuid
 
@@ -220,15 +222,49 @@ def postpone next_renewal_date, bulk=false
 
     # Update the notes sections of the subscription
     #
+    # @param notes [Hash] should be the notes parameters you wish to update
     # @return [true, false] +true+ when successful, +false+ when unable to
-    # @params notes [Hash] should be the notes parameters you wish to update
     def update_notes(notes)
       return false unless link? :notes
       self.attributes = notes
       reload follow_link(:notes, body: to_xml)
       true
     end
 
+    # Pauses a subscription or cancels a scheduled pause.
+    #
+    # * For an active subscription without a pause scheduled already,
+    # this will schedule a pause period to begin at the next renewal
+    # date for the specified number of billing cycles (remaining_pause_cycles).
+    # * When a scheduled pause already exists, this will update the remaining
+    # pause cycles with the new value sent. When zero (0) remaining_pause_cycles
+    # is sent for a subscription with a scheduled pause, the pause will be canceled.
+    # * For a paused subscription, the remaining_pause_cycles will adjust the
+    # length of the current pause period. Sending zero (0) in the remaining_pause_cycles
+    # field will cause the subscription to be resumed at the next renewal date.
+    #
+    # @param remaining_pause_cycles [Integer] The number of billing cycles that the subscription will be paused.
+    # @return true
+    def pause(remaining_pause_cycles)
+      builder = XML.new("<subscription/>")
+      builder.add_element('remaining_pause_cycles', remaining_pause_cycles)
+      reload API.put("#{uri}/pause", builder.to_s)
+      true
+    end
+
+    # Resumes a paused subscription.
+    #
+    # For a paused subscription, this will immediately resume the subscription
+    # from the pause, produce an invoice, and return the newly resumed subscription.
+    # Any at-renewal subscription changes will be immediately applied
+    # when the subscription resumes.
+    #
+    # @return true
+    def resume
+      reload API.put("#{uri}/resume")
+      true
+    end
+
     # Overrides the behavior of `update_attributes` in Resource class so ensure
     # all attributes are marked as dirty if the plan code changes
     def update_attributes attributes = {}

spec/fixtures/accounts/show-200.xml

@@ -40,4 +40,5 @@ Content-Type: application/xml; charset=utf-8
   <has_future_subscription type="boolean">false</has_future_subscription>
   <has_canceled_subscription type="boolean">false</has_canceled_subscription>
   <has_past_due_invoice type="boolean">false</has_past_due_invoice>
+  <preferred_locale>fr-FR</preferred_locale>
 </account>