recurly 3.0.0.beta.3 → 3.0.0.beta.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: c06a13da0a4a02efc0494087590ad6e050b7c21ee0e3539dc85184e7136f2444
-  data.tar.gz: aad797e4c85cfa7e8388755d86fc443b27b187169d65f4db225d73c26a9da6c0
+SHA1:
+  metadata.gz: fa84948d98ac3695fb2639905b05c1ae0ff8ee70
+  data.tar.gz: 36229c9d3cd0e548e1b8845d98453e07b4fc07a8
 SHA512:
-  metadata.gz: ed00a71ff9a370d9ad98fdda0c224bd6c273b69bfd543d1e5f2b40c5aee9d69b79fc1c6a8fe965d4727615d4c06a61291767961659d88567f5ee8e8153c11beb
-  data.tar.gz: 44a44276941e20c12c0998db7b73fb195eaea121be054a6b978a9f3a22cdbef04bf0e9bf5373b1db78cb75f128fec697112907ee0daff2187d7bc5db2b442ee9
+  metadata.gz: 6794cb420246f6407362fa23c1e0c5621df35703fa210f97b4090e0226e56b2e68f8040a654a943909f802c89c7b37246de363bc297bbd8b0af6266de7cf7fe3
+  data.tar.gz: cc7fb401cd2ef58e1444137bb0e881e71afac83135ca18c1012aa8aef0c3f2c2016760382873f3384f1e8f268b61aa3e73313280e7e5248e132b9157ed2936ab

data/.ruby-version

@@ -0,0 +1 @@
+2.4.4

data/.travis.yml

@@ -5,4 +5,6 @@ rvm:
   - 2.4
   - 2.5
   - 2.6
-before_install: gem install bundler -v 1.14.6
+before_install:
+  - gem uninstall -v '>= 2' -i $(rvm gemdir)@global -ax bundler || true
+  - gem install bundler -v '< 2'

data/README.md

@@ -15,7 +15,7 @@ This contains everything in the README as well as code-level documentation. We s
 This gem is a pre-release. In your Gemfile, add `recurly` as a dependency.
 
 ```ruby
-gem 'recurly', '3.0.0.beta.3'
+gem 'recurly', '3.0.0.beta.4'
 ```
 
 It's important that you lock on a specific version as there may be breaking changes between releases.
@@ -48,7 +48,7 @@ Recurly::Client.new(subdomain: 'mysite-prod', api_key: API_KEY) do |client|
 end
 ```
 
-If you only plan on using the client for more than one site, you should initialize a new client for each site.
+If you plan on using the client for more than one site, you should initialize a new client for each site.
 
 ```ruby
 # Give a `site_id`
@@ -112,6 +112,7 @@ The names, types, and descriptions of these arguments are listed in the rubydocs
 
 ```ruby
 options = {
+  limit: 200, # number of items per page
   state: :active, # only active plans
   sort: :updated_at,
   order: :asc,
@@ -125,6 +126,12 @@ plans.each do |plan|
 end
 ```
 
+**A note on `limit`**:
+
+`limit` defaults to 20 items per page and can be set from 1 to 200. Choosing a lower limit means more network requests but smaller payloads.
+We recommend keeping the default for most cases but increasing the limit if you are planning on iterating through many pages of items (e.g. all transactions in your site).
+
+
 ### Creating Resources
 
 Currently, resources are created by passing in a `body` keyword argument in the form of a `Hash`.

data/lib/recurly/client.rb

@@ -65,7 +65,7 @@ module Recurly
 
     def next_page(pager)
       run_request(:get, pager.next, nil, headers).tap do |response|
-        raise_api_error!(response) if response.status != 200
+        raise_api_error!(response) unless (200...300).include?(response.status)
       end
     end
 
@@ -77,7 +77,7 @@ module Recurly
 
     def get(path, **options)
       response = run_request(:get, path, nil, headers)
-      raise_api_error!(response) if response.status != 200
+      raise_api_error!(response) unless (200...300).include?(response.status)
       JSONParser.parse(self, response.body)
     rescue Faraday::ClientError => ex
       raise_network_error!(ex)
@@ -88,18 +88,22 @@ module Recurly
       request.validate!
       logger.info("POST BODY #{JSON.dump(request_data)}")
       response = run_request(:post, path, JSON.dump(request.attributes), headers)
-      raise_api_error!(response) if response.status != 201
+      raise_api_error!(response) unless (200...300).include?(response.status)
       JSONParser.parse(self, response.body)
     rescue Faraday::ClientError => ex
       raise_network_error!(ex)
     end
 
-    def put(path, request_data, request_class, **options)
-      request = request_class.new(request_data)
-      request.validate!
-      logger.info("PUT BODY #{JSON.dump(request_data)}")
-      response = run_request(:put, path, JSON.dump(request_data), headers)
-      raise_api_error!(response) if ![200, 201].include?(response.status)
+    def put(path, request_data=nil, request_class=nil, **options)
+      response = if request_data
+        request = request_class.new(request_data)
+        request.validate!
+        logger.info("PUT BODY #{JSON.dump(request_data)}")
+        run_request(:put, path, JSON.dump(request_data), headers)
+      else
+        run_request(:put, path, nil, headers)
+      end
+      raise_api_error!(response) unless (200...300).include?(response.status)
       JSONParser.parse(self, response.body)
     rescue Faraday::ClientError => ex
       raise_network_error!(ex)
@@ -107,8 +111,10 @@ module Recurly
 
     def delete(path, **options)
       response = run_request(:delete, path, nil, headers)
-      raise_api_error!(response) if ![200, 201].include?(response.status)
-      JSONParser.parse(self, response.body)
+      raise_api_error!(response) unless (200...300).include?(response.status)
+      if response.body && !response.body.empty?
+        JSONParser.parse(self, response.body)
+      end
     rescue Faraday::ClientError => ex
       raise_network_error!(ex)
     end
@@ -152,6 +158,9 @@ module Recurly
       @rate_limit = response.headers['x-ratelimit-limit'].to_i
       @rate_limit_remaining = response.headers['x-ratelimit-remaining'].to_i
       @rate_limit_reset = Time.at(response.headers['x-ratelimit-reset'].to_i).to_datetime
+      if !@_ignore_deprecation_warning && response.headers['Recurly-Deprecated']&.upcase == 'TRUE'
+        puts "[recurly-client-ruby] WARNING: Your current API version \"#{api_version}\" is deprecated and will be sunset on #{response.headers['Recurly-Sunset-Date']}"
+      end
       response
     end
 
@@ -164,6 +173,15 @@ module Recurly
     end
 
     def interpolate_path(path, **options)
+      options.each do |k, v|
+        unless [String, Symbol, Integer, Float].include?(v.class)
+          message = "We cannot build the url with the given argument #{k}=#{v.inspect}."
+          if k =~ /_id$/
+            message << " Since this appears to be an id, perhaps you meant to pass in a String?"
+          end
+          raise ArgumentError, message
+        end
+      end
       path = path.gsub("{", "%{")
       path % options
     end
@@ -179,8 +197,19 @@ module Recurly
     end
 
     def set_faraday_connection(api_key)
-      @conn = Faraday.new(url: BASE_URL) do |faraday|
-        if @log_level == Logger::INFO
+      options = {
+        url: BASE_URL,
+        request: { timeout: 60, open_timeout: 50 },
+        ssl: { verify: true }
+      }
+      # Let's not use the bundled cert in production yet
+      # but we will use these certs for any other staging or dev environment
+      unless BASE_URL.end_with?('.recurly.com')
+        options[:ssl][:ca_file] = File.join(File.dirname(__FILE__), '../data/ca-certificates.crt')
+      end
+
+      @conn = Faraday.new(options) do |faraday|
+        if [Logger::DEBUG, Logger::INFO].include?(@log_level)
           faraday.response :logger
         end
         faraday.basic_auth(api_key, '')

data/lib/recurly/client/adapter.rb

@@ -5,14 +5,14 @@ module Recurly
     module NetHttpPersistentAdapter
       protected
       def configure_net_adapter(faraday)
-        faraday.adapter :net_http_persistent do |http| # yields Net::HTTP
-          # Let's not use the bundled cert in production yet
-          # but we will use these certs for any other staging or dev environment
-          unless BASE_URL.end_with?('.recurly.com')
-            http.ca_file = File.join(File.dirname(__FILE__), '../data/ca-certificates.crt')
+        faraday.adapter :net_http_persistent do |http|
+          # yields Net::HTTP::Persistent
+          # for net-http-persistent 2.X, alternative is for 3.X
+          if http.respond_to? :keep_alive_timeout
+            http.keep_alive_timeout = 60
+          else
+            http.keep_alive = 60
           end
-          http.open_timeout = 50
-          http.read_timeout = 60
         end
       end
     end
@@ -20,17 +20,8 @@ module Recurly
     module NetHttpAdapter
       protected
       def configure_net_adapter(faraday)
-        faraday.adapter :net_http do |http| # yields Net::HTTP
-          # Let's not use the bundled cert in production yet
-          # but we will use these certs for any other staging or dev environment
-          unless BASE_URL.end_with?('.recurly.com')
-            http.ca_file = File.join(File.dirname(__FILE__), '../data/ca-certificates.crt')
-          end
-          http.use_ssl = true
-          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          http.open_timeout = 50
-          http.read_timeout = 60
-          http.keep_alive_timeout = 60
+        faraday.adapter :net_http do |http|
+          # yields Net::HTTP
         end
       end
     end

data/lib/recurly/client/operations.rb

@@ -1,13 +1,19 @@
+# This file is automatically created by Recurly's OpenAPI generation process
+# and thus any edits you make by hand will be lost. If you wish to make a
+# change to this file, please create a Github issue explaining the changes you
+# need and we will usher them to the appropriate places.
 module Recurly
   class Client
     def api_version
-      "v2018-06-06"
+      "v2018-08-09"
     end
 
     # List sites
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_sites list_sites api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -24,6 +30,12 @@ module Recurly
     #   prevent some records from being returned.
     #
     # @return [Pager<Resources::Site>] A list of sites.
+    # @example
+    #   sites = @client.list_sites(limit: 200)
+    #   sites.each do |site|
+    #     puts "Site: #{site.subdomain}"
+    #   end
+    #
     def list_sites(**options)
       path = "/sites"
       pager(path, **options)
@@ -31,6 +43,8 @@ module Recurly
 
     # Fetch a site
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_site get_site api documenation}
+    #
     # @return [Resources::Site] A site.
     def get_site()
       path = interpolate_path("/sites/{site_id}", site_id: site_id)
@@ -39,8 +53,10 @@ module Recurly
 
     # List a site's accounts
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_accounts list_accounts api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -67,6 +83,12 @@ module Recurly
     #
     # @param past_due [String] Filter for accounts with an invoice in the +past_due+ state.
     # @return [Pager<Resources::Account>] A list of the site's accounts.
+    # @example
+    #   accounts = @client.list_accounts(limit: 200)
+    #   accounts.each do |account|
+    #     puts "Account: #{account.code}"
+    #   end
+    #
     def list_accounts(**options)
       path = interpolate_path("/sites/{site_id}/accounts", site_id: site_id)
       pager(path, **options)
@@ -74,8 +96,46 @@ module Recurly
 
     # Create an account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_account create_account api documenation}
+    #
     # @param body [Requests::AccountCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::AccountCreate}
     # @return [Resources::Account] An account.
+    # @example
+    #   begin
+    #     account_create = {
+    #       code: account_code,
+    #       first_name: "Benjamin",
+    #       last_name: "Du Monde",
+    #       acquisition: {
+    #         campaign: "podcast-marketing",
+    #         channel: "social_media",
+    #         subchannel: "twitter",
+    #         cost: {
+    #           currency: "USD",
+    #           amount: 0.50
+    #         }
+    #       },
+    #       shipping_addresses: [
+    #         {
+    #           nickname: "Home",
+    #           street1: "1 Tchoupitoulas St",
+    #           city: "New Orleans",
+    #           region: "LA",
+    #           country: "US",
+    #           postal_code: "70115",
+    #           first_name: "Benjamin",
+    #           last_name: "Du Monde"
+    #         }
+    #       ]
+    #     }
+    #     account = @client.create_account(body: account_create)
+    #     puts "Created Account #{account}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def create_account(body:)
       path = interpolate_path("/sites/{site_id}/accounts", site_id: site_id)
       post(path, body, Requests::AccountCreate)
@@ -83,19 +143,18 @@ module Recurly
 
     # Fetch an account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_account get_account api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @return [Resources::Account] An account.
     # @example
     #   begin
-    #     # You can use the `id` field from an Account object
-    #     account = @client.get_account(account_id: "hympfmab60ic")
-    #     # If you only have the account code, you can prefix with `code-`
-    #     account = @client.get_account(account_id: "code-benjamin.dumonde@example.com")
-    #   rescue Recurly::Errors::NotFoundError => e
-    #     puts e
-    #     # => Recurly::NotFoundError: Couldn't find Account with code = benjamin.dumonde@example.com
-    #     puts e.recurly_error
-    #     # => #<Recurly::Error:0x007f8b29918618 @attributes={:type=>"not_found", :message=>"Couldn't find Account with code = benjamin.dumonde@example.com", :params=>[{"param"=>"account_id"}]}>
+    #     account = @client.get_account(account_id: account_id)
+    #     puts "Got Account #{account}"
+    #   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
     #
     def get_account(account_id:)
@@ -105,9 +164,28 @@ module Recurly
 
     # Modify an account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/update_account update_account api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param body [Requests::AccountUpdate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::AccountUpdate}
     # @return [Resources::Account] An account.
+    # @example
+    #   begin
+    #     account_update = {
+    #       first_name: "Aaron",
+    #       last_name: "Du Monde",
+    #     }
+    #     account = @client.update_account(
+    #       account_id: account_id,
+    #       body: account_update
+    #     )
+    #     puts "Updated Account #{account}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def update_account(account_id:, body:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}", site_id: site_id, account_id: account_id)
       put(path, body, Requests::AccountUpdate)
@@ -115,8 +193,20 @@ module Recurly
 
     # Deactivate an account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/deactivate_account deactivate_account api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @return [Resources::Account] An account.
+    # @example
+    #   begin
+    #     account = @client.deactivate_account(account_id: account_id)
+    #     puts "Deactivated Account #{account}"
+    #   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
+    #
     def deactivate_account(account_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}", site_id: site_id, account_id: account_id)
       delete(path)
@@ -124,8 +214,20 @@ module Recurly
 
     # Fetch an account's acquisition data
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_account_acquisition get_account_acquisition api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @return [Resources::AccountAcquisition] An account's acquisition data.
+    # @example
+    #   begin
+    #     @client.get_account_acquisition(account_id: account_id)
+    #     puts "Got AccountAcquisition"
+    #   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
+    #
     def get_account_acquisition(account_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/acquisition", site_id: site_id, account_id: account_id)
       get(path)
@@ -133,6 +235,8 @@ module Recurly
 
     # Update an account's acquisition data
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/update_account_acquisition update_account_acquisition api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param body [Requests::AccountAcquisitionUpdatable] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::AccountAcquisitionUpdatable}
     # @return [Resources::AccountAcquisition] An account's updated acquisition data.
@@ -143,7 +247,19 @@ module Recurly
 
     # Remove an account's acquisition data
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/remove_account_acquisition remove_account_acquisition api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
+    # @example
+    #   begin
+    #     acquisition = @client.remove_account_acquisition(account_id: account_id)
+    #     puts "Removed AccountAcqusition #{acquisition}"
+    #   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
+    #
     def remove_account_acquisition(account_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/acquisition", site_id: site_id, account_id: account_id)
       delete(path)
@@ -151,8 +267,20 @@ module Recurly
 
     # Reactivate an inactive account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/reactivate_account reactivate_account api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @return [Resources::Account] An account.
+    # @example
+    #   begin
+    #     account = @client.reactivate_account(account_id: account_id)
+    #     puts "Reactivated account #{account}"
+    #   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
+    #
     def reactivate_account(account_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/reactivate", site_id: site_id, account_id: account_id)
       put(path)
@@ -160,8 +288,20 @@ module Recurly
 
     # Fetch an account's balance and past due status
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_account_balance get_account_balance api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @return [Resources::AccountBalance] An account's balance.
+    # @example
+    #   begin
+    #     balance = @client.get_account_balance(account_id: account_id)
+    #     puts "Got AccountBalance #{balance}"
+    #   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
+    #
     def get_account_balance(account_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/balance", site_id: site_id, account_id: account_id)
       get(path)
@@ -169,8 +309,20 @@ module Recurly
 
     # Fetch an account's billing information
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_billing_info get_billing_info api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @return [Resources::BillingInfo] An account's billing information.
+    # @example
+    #   begin
+    #     billing = @client.get_billing_info(account_id: account_id)
+    #     puts "Got BillingInfo #{billing}"
+    #   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
+    #
     def get_billing_info(account_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/billing_info", site_id: site_id, account_id: account_id)
       get(path)
@@ -178,9 +330,28 @@ module Recurly
 
     # Set an account's billing information
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/update_billing_info update_billing_info api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param body [Requests::BillingInfoCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::BillingInfoCreate}
     # @return [Resources::BillingInfo] Updated billing information.
+    # @example
+    #   begin
+    #     billing_update = {
+    #       first_name: "Aaron",
+    #       last_name: "Du Monde",
+    #     }
+    #     billing = @client.update_billing_info(
+    #       account_id: account_id,
+    #       body: billing_update
+    #     )
+    #     puts "Updated BillingInfo #{billing}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def update_billing_info(account_id:, body:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/billing_info", site_id: site_id, account_id: account_id)
       put(path, body, Requests::BillingInfoCreate)
@@ -188,7 +359,19 @@ module Recurly
 
     # Remove an account's billing information
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/remove_billing_info remove_billing_info api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
+    # @example
+    #   begin
+    #     @client.remove_billing_info(account_id: account_id)
+    #     puts "Removed BillingInfo #{account_id}"
+    #   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
+    #
     def remove_billing_info(account_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/billing_info", site_id: site_id, account_id: account_id)
       delete(path)
@@ -196,9 +379,11 @@ module Recurly
 
     # Show the coupon redemptions for an account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_account_coupon_redemptions list_account_coupon_redemptions api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -208,7 +393,26 @@ module Recurly
     #   * Records are returned in an arbitrary order. Since results are all
     #     returned at once you can sort the records yourself.
     #
+    # @param sort [String] Sort field. You *really* only want to sort by +updated_at+ in ascending
+    #   order. In descending order updated records will move behind the cursor and could
+    #   prevent some records from being returned.
+    #
+    # @param begin_time [DateTime] Filter by begin_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
+    # @param end_time [DateTime] Filter by end_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
     # @return [Pager<Resources::CouponRedemption>] A list of the the coupon redemptions on an account.
+    # @example
+    #   redemptions = @client.list_account_coupon_redemptions(
+    #     account_id: account_id,
+    #     limit: 200
+    #   )
+    #   redemptions.each do |redemption|
+    #     puts "CouponRedemption: #{redemption.id}"
+    #   end
+    #
     def list_account_coupon_redemptions(account_id:, **options)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/coupon_redemptions", site_id: site_id, account_id: account_id)
       pager(path, **options)
@@ -216,8 +420,20 @@ module Recurly
 
     # Show the coupon redemption that is active on an account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_active_coupon_redemption get_active_coupon_redemption api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @return [Resources::CouponRedemption] An active coupon redemption on an account.
+    # @example
+    #   begin
+    #     redemption = @client.get_active_coupon_redemption(account_id: account_id)
+    #     puts "Got CouponRedemption #{redemption}"
+    #   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
+    #
     def get_active_coupon_redemption(account_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/coupon_redemptions/active", site_id: site_id, account_id: account_id)
       get(path)
@@ -225,9 +441,28 @@ module Recurly
 
     # Generate an active coupon redemption on an account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_coupon_redemption create_coupon_redemption api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param body [Requests::CouponRedemptionCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::CouponRedemptionCreate}
     # @return [Resources::CouponRedemption] Returns the new coupon redemption.
+    # @example
+    #   begin
+    #     redemption_create = {
+    #       currency: 'USD',
+    #       coupon_id: coupon_id
+    #     }
+    #     redemption = @client.create_coupon_redemption(
+    #       account_id: account_id,
+    #       body: redemption_create
+    #     )
+    #     puts "Created CouponRedemption #{redemption}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def create_coupon_redemption(account_id:, body:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/coupon_redemptions/active", site_id: site_id, account_id: account_id)
       post(path, body, Requests::CouponRedemptionCreate)
@@ -235,8 +470,20 @@ module Recurly
 
     # Delete the active coupon redemption from an account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/remove_coupon_redemption remove_coupon_redemption api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @return [Resources::CouponRedemption] Coupon redemption deleted.
+    # @example
+    #   begin
+    #     @client.remove_coupon_redemption(account_id: account_id)
+    #     puts "Removed CouponRedemption #{account_id}"
+    #   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
+    #
     def remove_coupon_redemption(account_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/coupon_redemptions/active", site_id: site_id, account_id: account_id)
       delete(path)
@@ -244,6 +491,8 @@ module Recurly
 
     # List an account's credit payments
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_account_credit_payments list_account_credit_payments api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param limit [Integer] Limit number of records 1-200.
     # @param order [String] Sort order.
@@ -258,6 +507,15 @@ module Recurly
     #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
     #
     # @return [Pager<Resources::CreditPayment>] A list of the account's credit payments.
+    # @example
+    #   payments = @client.list_account_credit_payments(
+    #     account_id: account_id,
+    #     limit: 200
+    #   )
+    #   payments.each do |payment|
+    #     puts "CreditPayment: #{payment.id}"
+    #   end
+    #
     def list_account_credit_payments(account_id:, **options)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/credit_payments", site_id: site_id, account_id: account_id)
       pager(path, **options)
@@ -265,9 +523,11 @@ module Recurly
 
     # List an account's invoices
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_account_invoices list_account_invoices api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -296,6 +556,15 @@ module Recurly
     #   - +type=legacy+, only legacy invoices will be returned.
     #
     # @return [Pager<Resources::Invoice>] A list of the account's invoices.
+    # @example
+    #   invoices = @client.list_account_invoices(
+    #     account_id: account_id,
+    #     limit: 200
+    #   )
+    #   invoices.each do |invoice|
+    #     puts "Invoice: #{invoice.number}"
+    #   end
+    #
     def list_account_invoices(account_id:, **options)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/invoices", site_id: site_id, account_id: account_id)
       pager(path, **options)
@@ -303,9 +572,28 @@ module Recurly
 
     # Create an invoice for pending line items
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_invoice create_invoice api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param body [Requests::InvoiceCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::InvoiceCreate}
     # @return [Resources::InvoiceCollection] Returns the new invoices.
+    # @example
+    #   begin
+    #     invoice_create = {
+    #       currency: 'USD',
+    #       collection_method: 'automatic'
+    #     }
+    #     collection = @client.create_invoice(
+    #       account_id: account_id,
+    #       body: invoice_create
+    #     )
+    #     puts "Created InvoiceCollection #{collection}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def create_invoice(account_id:, body:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/invoices", site_id: site_id, account_id: account_id)
       post(path, body, Requests::InvoiceCreate)
@@ -313,9 +601,28 @@ module Recurly
 
     # Preview new invoice for pending line items
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/preview_invoice preview_invoice api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param body [Requests::InvoiceCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::InvoiceCreate}
     # @return [Resources::InvoiceCollection] Returns the invoice previews.
+    # @example
+    #   begin
+    #     invoice_preview = {
+    #       currency: "USD",
+    #       collection_method: "automatic"
+    #     }
+    #     collection = @client.create_invoice(
+    #       account_id: account_id,
+    #       body: invoice_preview
+    #     )
+    #     puts "Created InvoiceCollection #{collection}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def preview_invoice(account_id:, body:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/invoices/preview", site_id: site_id, account_id: account_id)
       post(path, body, Requests::InvoiceCreate)
@@ -323,9 +630,11 @@ module Recurly
 
     # List an account's line items
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_account_line_items list_account_line_items api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -351,6 +660,15 @@ module Recurly
     # @param state [String] Filter by state field.
     # @param type [String] Filter by type field.
     # @return [Pager<Resources::LineItem>] A list of the account's line items.
+    # @example
+    #   line_items = @client.list_account_line_items(
+    #     account_id: account_id,
+    #     limit: 200
+    #   )
+    #   line_items.each do |line_item|
+    #     puts "LineItem: #{line_item.id}"
+    #   end
+    #
     def list_account_line_items(account_id:, **options)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/line_items", site_id: site_id, account_id: account_id)
       pager(path, **options)
@@ -358,9 +676,29 @@ module Recurly
 
     # Create a new line item for the account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_line_item create_line_item api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param body [Requests::LineItemCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::LineItemCreate}
     # @return [Resources::LineItem] Returns the new line item.
+    # @example
+    #   begin
+    #     line_item_create = {
+    #       currency: 'USD',
+    #       unit_amount: 1_000,
+    #       type: :charge
+    #     }
+    #     line_item = @client.create_line_item(
+    #       account_id: account_id,
+    #       body: line_item_create
+    #     )
+    #     puts "Created LineItem #{line_item}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def create_line_item(account_id:, body:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/line_items", site_id: site_id, account_id: account_id)
       post(path, body, Requests::LineItemCreate)
@@ -368,9 +706,11 @@ module Recurly
 
     # Fetch a list of an account's notes
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_account_notes list_account_notes api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -381,6 +721,12 @@ module Recurly
     #     returned at once you can sort the records yourself.
     #
     # @return [Pager<Resources::AccountNote>] A list of an account's notes.
+    # @example
+    #   account_notes = @client.list_account_notes(account_id: account_id, limit: 200)
+    #   account_notes.each do |note|
+    #     puts "AccountNote: #{note.message}"
+    #   end
+    #
     def list_account_notes(account_id:, **options)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/notes", site_id: site_id, account_id: account_id)
       pager(path, **options)
@@ -388,9 +734,24 @@ module Recurly
 
     # Fetch an account note
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_account_note get_account_note api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param account_note_id [String] Account Note ID.
     # @return [Resources::AccountNote] An account note.
+    # @example
+    #   begin
+    #     note = @client.get_account_note(
+    #       account_id: account_id,
+    #       account_note_id: note_id
+    #     )
+    #     puts "Got AccountNote #{note}"
+    #   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
+    #
     def get_account_note(account_id:, account_note_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/notes/{account_note_id}", site_id: site_id, account_id: account_id, account_note_id: account_note_id)
       get(path)
@@ -398,9 +759,11 @@ module Recurly
 
     # Fetch a list of an account's shipping addresses
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_shipping_addresses list_shipping_addresses api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -423,6 +786,15 @@ module Recurly
     #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
     #
     # @return [Pager<Resources::ShippingAddress>] A list of an account's shipping addresses.
+    # @example
+    #   shipping_addresses = @client.list_shipping_addresses(
+    #     account_id: account_id,
+    #     limit: 200
+    #   )
+    #   shipping_addresses.each do |addr|
+    #     puts "ShippingAddress: #{addr.nickname} - #{addr.street1}"
+    #   end
+    #
     def list_shipping_addresses(account_id:, **options)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/shipping_addresses", site_id: site_id, account_id: account_id)
       pager(path, **options)
@@ -430,6 +802,8 @@ module Recurly
 
     # Create a new shipping address for the account
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_shipping_address create_shipping_address api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param body [Requests::ShippingAddressCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::ShippingAddressCreate}
     # @return [Resources::ShippingAddress] Returns the new shipping address.
@@ -440,9 +814,24 @@ module Recurly
 
     # Fetch an account's shipping address
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_shipping_address get_shipping_address api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param shipping_address_id [String] Shipping Address ID.
     # @return [Resources::ShippingAddress] A shipping address.
+    # @example
+    #   begin
+    #     address = @client.get_shipping_address(
+    #       account_id: account_id,
+    #       shipping_address_id: shipping_address_id
+    #     )
+    #     puts "Got ShippingAddress #{address}"
+    #   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
+    #
     def get_shipping_address(account_id:, shipping_address_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/shipping_addresses/{shipping_address_id}", site_id: site_id, account_id: account_id, shipping_address_id: shipping_address_id)
       get(path)
@@ -450,10 +839,31 @@ module Recurly
 
     # Update an account's shipping address
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/update_shipping_address update_shipping_address api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param shipping_address_id [String] Shipping Address ID.
     # @param body [Requests::ShippingAddressUpdate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::ShippingAddressUpdate}
     # @return [Resources::ShippingAddress] The updated shipping address.
+    # @example
+    #   begin
+    #     address_update = {
+    #       first_name: "Aaron",
+    #       last_name: "Du Monde",
+    #       postal_code: "70130"
+    #     }
+    #     address = @client.update_shipping_address(
+    #       account_id: account_id,
+    #       shipping_address_id: shipping_address_id,
+    #       body: address_update
+    #     )
+    #     puts "Updated ShippingAddress #{address}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def update_shipping_address(account_id:, shipping_address_id:, body:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/shipping_addresses/{shipping_address_id}", site_id: site_id, account_id: account_id, shipping_address_id: shipping_address_id)
       put(path, body, Requests::ShippingAddressUpdate)
@@ -461,8 +871,23 @@ module Recurly
 
     # Remove an account's shipping address
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/remove_shipping_address remove_shipping_address api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
     # @param shipping_address_id [String] Shipping Address ID.
+    # @example
+    #   begin
+    #     @client.remove_shipping_address(
+    #       account_id: account_id,
+    #       shipping_address_id: shipping_address_id
+    #     )
+    #     puts "Removed ShippingAddress #{shipping_address_id}"
+    #   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
+    #
     def remove_shipping_address(account_id:, shipping_address_id:)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/shipping_addresses/{shipping_address_id}", site_id: site_id, account_id: account_id, shipping_address_id: shipping_address_id)
       delete(path)
@@ -470,9 +895,11 @@ module Recurly
 
     # List an account's subscriptions
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_account_subscriptions list_account_subscriptions api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -500,6 +927,15 @@ module Recurly
     #   - When +state=live+, only subscriptions that are in an active, canceled, or future state or are in trial will be returned.
     #
     # @return [Pager<Resources::Subscription>] A list of the account's subscriptions.
+    # @example
+    #   subscriptions = @client.list_account_subscriptions(
+    #     account_id: account_id,
+    #     limit: 200
+    #   )
+    #   subscriptions.each do |subscription|
+    #     puts "Subscription: #{subscription.uuid}"
+    #   end
+    #
     def list_account_subscriptions(account_id:, **options)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/subscriptions", site_id: site_id, account_id: account_id)
       pager(path, **options)
@@ -507,9 +943,11 @@ module Recurly
 
     # List an account's transactions
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_account_transactions list_account_transactions api documenation}
+    #
     # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -531,18 +969,76 @@ module Recurly
     # @param end_time [DateTime] Filter by end_time when +sort=created_at+ or +sort=updated_at+.
     #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
     #
-    # @param type [String] Filter by type field.
+    # @param type [String] Filter by type field. The value +payment+ will return both +purchase+ and +capture+ transactions.
     # @param success [String] Filter by success field.
     # @return [Pager<Resources::Transaction>] A list of the account's transactions.
+    # @example
+    #   transactions = @client.list_account_transactions(
+    #     account_id: account_id,
+    #     limit: 200
+    #   )
+    #   transactions.each do |transaction|
+    #     puts "Transaction: #{transaction.uuid}"
+    #   end
+    #
     def list_account_transactions(account_id:, **options)
       path = interpolate_path("/sites/{site_id}/accounts/{account_id}/transactions", site_id: site_id, account_id: account_id)
       pager(path, **options)
     end
 
+    # List an account's child accounts
+    #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_child_accounts list_child_accounts api documenation}
+    #
+    # @param account_id [String] Account ID or code (use prefix: +code-+, e.g. +code-bob+).
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
+    #
+    #   *Important notes:*
+    #   * The +ids+ parameter cannot be used with any other ordering or filtering
+    #     parameters (+limit+, +order+, +sort+, +begin_time+, +end_time+, etc)
+    #   * Invalid or unknown IDs will be ignored, so you should check that the
+    #     results correspond to your request.
+    #   * Records are returned in an arbitrary order. Since results are all
+    #     returned at once you can sort the records yourself.
+    #
+    # @param limit [Integer] Limit number of records 1-200.
+    # @param order [String] Sort order.
+    # @param sort [String] Sort field. You *really* only want to sort by +updated_at+ in ascending
+    #   order. In descending order updated records will move behind the cursor and could
+    #   prevent some records from being returned.
+    #
+    # @param begin_time [DateTime] Filter by begin_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
+    # @param end_time [DateTime] Filter by end_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
+    # @param subscriber [String] Filter accounts accounts with or without a subscription in the +active+,
+    #   +canceled+, or +future+ state.
+    #
+    # @param past_due [String] Filter for accounts with an invoice in the +past_due+ state.
+    # @return [Pager<Resources::Account>] A list of an account's child accounts.
+    # @example
+    #   # child_accounts = @client.list_child_accounts(
+    #   #   account_id: account_id,
+    #   #   limit: 200
+    #   # )
+    #   # child_accounts.each do |child|
+    #   #   puts "Account: #{child.code}"
+    #   # end
+    #
+    def list_child_accounts(account_id:, **options)
+      path = interpolate_path("/sites/{site_id}/accounts/{account_id}/accounts", site_id: site_id, account_id: account_id)
+      pager(path, **options)
+    end
+
     # List a site's account acquisition data
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_account_acquisition list_account_acquisition api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -564,16 +1060,24 @@ module Recurly
     # @param end_time [DateTime] Filter by end_time when +sort=created_at+ or +sort=updated_at+.
     #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
     #
-    # @return [Resources::AccountAcquisition] A list of the site's account acquisition data.
+    # @return [Pager<Resources::AccountAcquisition>] A list of the site's account acquisition data.
+    # @example
+    #   acquisitions = @client.list_account_acquisition(limit: 200)
+    #   acquisitions.each do |acquisition|
+    #     puts "AccountAcquisition: #{acquisition.cost}"
+    #   end
+    #
     def list_account_acquisition(**options)
       path = interpolate_path("/sites/{site_id}/acquisitions", site_id: site_id)
-      get(path, **options)
+      pager(path, **options)
     end
 
     # List a site's coupons
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_coupons list_coupons api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -596,6 +1100,12 @@ module Recurly
     #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
     #
     # @return [Pager<Resources::Coupon>] A list of the site's coupons.
+    # @example
+    #   coupons = @client.list_coupons(limit: 200)
+    #   coupons.each do |coupon|
+    #     puts "coupon: #{coupon.code}"
+    #   end
+    #
     def list_coupons(**options)
       path = interpolate_path("/sites/{site_id}/coupons", site_id: site_id)
       pager(path, **options)
@@ -603,8 +1113,33 @@ module Recurly
 
     # Create a new coupon
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_coupon create_coupon api documenation}
+    #
     # @param body [Requests::CouponCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::CouponCreate}
     # @return [Resources::Coupon] A new coupon.
+    # @example
+    #   begin
+    #     coupon_create = {
+    #       name: "Promotional Coupon",
+    #       code: coupon_code,
+    #       discount_type: 'fixed',
+    #       currencies: [
+    #         {
+    #           currency: 'USD',
+    #           discount: 10_000
+    #         }
+    #       ]
+    #     }
+    #     coupon = @client.create_coupon(
+    #       body: coupon_create
+    #     )
+    #     puts "Created Coupon #{coupon}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def create_coupon(body:)
       path = interpolate_path("/sites/{site_id}/coupons", site_id: site_id)
       post(path, body, Requests::CouponCreate)
@@ -612,8 +1147,20 @@ module Recurly
 
     # Fetch a coupon
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_coupon get_coupon api documenation}
+    #
     # @param coupon_id [String] Coupon ID or code (use prefix: +code-+, e.g. +code-10off+).
     # @return [Resources::Coupon] A coupon.
+    # @example
+    #   begin
+    #     coupon = @client.get_coupon(coupon_id: coupon_id)
+    #     puts "Got Coupon #{coupon}"
+    #   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
+    #
     def get_coupon(coupon_id:)
       path = interpolate_path("/sites/{site_id}/coupons/{coupon_id}", site_id: site_id, coupon_id: coupon_id)
       get(path)
@@ -621,6 +1168,8 @@ module Recurly
 
     # Update an active coupon
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/update_coupon update_coupon api documenation}
+    #
     # @param coupon_id [String] Coupon ID or code (use prefix: +code-+, e.g. +code-10off+).
     # @param body [Requests::CouponUpdate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::CouponUpdate}
     # @return [Resources::Coupon] The updated coupon.
@@ -631,9 +1180,11 @@ module Recurly
 
     # List unique coupon codes associated with a bulk coupon
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_unique_coupon_codes list_unique_coupon_codes api documenation}
+    #
     # @param coupon_id [String] Coupon ID or code (use prefix: +code-+, e.g. +code-10off+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -663,6 +1214,8 @@ module Recurly
 
     # List a site's credit payments
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_credit_payments list_credit_payments api documenation}
+    #
     # @param limit [Integer] Limit number of records 1-200.
     # @param order [String] Sort order.
     # @param sort [String] Sort field. You *really* only want to sort by +updated_at+ in ascending
@@ -676,6 +1229,12 @@ module Recurly
     #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
     #
     # @return [Pager<Resources::CreditPayment>] A list of the site's credit payments.
+    # @example
+    #   payments = @client.list_credit_payments(limit: 200)
+    #   payments.each do |payment|
+    #     puts "CreditPayment: #{payment.id}"
+    #   end
+    #
     def list_credit_payments(**options)
       path = interpolate_path("/sites/{site_id}/credit_payments", site_id: site_id)
       pager(path, **options)
@@ -683,6 +1242,8 @@ module Recurly
 
     # Fetch a credit payment
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_credit_payment get_credit_payment api documenation}
+    #
     # @param credit_payment_id [String] Credit Payment ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @return [Resources::CreditPayment] A credit payment.
     def get_credit_payment(credit_payment_id:)
@@ -692,8 +1253,10 @@ module Recurly
 
     # List a site's custom field definitions
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_custom_field_definitions list_custom_field_definitions api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -723,6 +1286,8 @@ module Recurly
 
     # Fetch an custom field definition
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_custom_field_definition get_custom_field_definition api documenation}
+    #
     # @param custom_field_definition_id [String] Custom Field Definition ID
     # @return [Resources::CustomFieldDefinition] An custom field definition.
     def get_custom_field_definition(custom_field_definition_id:)
@@ -732,8 +1297,10 @@ module Recurly
 
     # List a site's invoices
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_invoices list_invoices api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -762,6 +1329,12 @@ module Recurly
     #   - +type=legacy+, only legacy invoices will be returned.
     #
     # @return [Pager<Resources::Invoice>] A list of the site's invoices.
+    # @example
+    #   invoices = @client.list_invoices(limit: 200)
+    #   invoices.each do |invoice|
+    #     puts "Invoice: #{invoice.number}"
+    #   end
+    #
     def list_invoices(**options)
       path = interpolate_path("/sites/{site_id}/invoices", site_id: site_id)
       pager(path, **options)
@@ -769,17 +1342,53 @@ module Recurly
 
     # Fetch an invoice
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_invoice get_invoice api documenation}
+    #
     # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
     # @return [Resources::Invoice] An invoice.
+    # @example
+    #   begin
+    #     invoice = @client.get_invoice(invoice_id: invoice_id)
+    #     puts "Got invoice #{invoice}"
+    #   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
+    #
     def get_invoice(invoice_id:)
       path = interpolate_path("/sites/{site_id}/invoices/{invoice_id}", site_id: site_id, invoice_id: invoice_id)
       get(path)
     end
 
+    # Update an invoice
+    #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/put_invoice put_invoice api documenation}
+    #
+    # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
+    # @param body [Requests::InvoiceUpdatable] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::InvoiceUpdatable}
+    # @return [Resources::Invoice] An invoice.
+    def put_invoice(invoice_id:, body:)
+      path = interpolate_path("/sites/{site_id}/invoices/{invoice_id}", site_id: site_id, invoice_id: invoice_id)
+      put(path, body, Requests::InvoiceUpdatable)
+    end
+
     # Collect a pending or past due, automatic invoice
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/collect_invoice collect_invoice api documenation}
+    #
     # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
     # @return [Resources::Invoice] The updated invoice.
+    # @example
+    #   begin
+    #     invoice = @client.collect_invoice(invoice_id: invoice_id)
+    #     puts "Collected invoice #{invoice}"
+    #   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
+    #
     def collect_invoice(invoice_id:)
       path = interpolate_path("/sites/{site_id}/invoices/{invoice_id}/collect", site_id: site_id, invoice_id: invoice_id)
       put(path)
@@ -787,8 +1396,20 @@ module Recurly
 
     # Mark an open invoice as failed
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/fail_invoice fail_invoice api documenation}
+    #
     # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
     # @return [Resources::Invoice] The updated invoice.
+    # @example
+    #   begin
+    #     invoice = @client.fail_invoice(invoice_id: invoice_id)
+    #     puts "Failed invoice #{invoice}"
+    #   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
+    #
     def fail_invoice(invoice_id:)
       path = interpolate_path("/sites/{site_id}/invoices/{invoice_id}/mark_failed", site_id: site_id, invoice_id: invoice_id)
       put(path)
@@ -796,8 +1417,20 @@ module Recurly
 
     # Mark an open invoice as successful
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/mark_invoice_successful mark_invoice_successful api documenation}
+    #
     # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
     # @return [Resources::Invoice] The updated invoice.
+    # @example
+    #   begin
+    #     invoice = @client.mark_invoice_successful(invoice_id: invoice_id)
+    #     puts "Marked invoice sucessful #{invoice}"
+    #   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
+    #
     def mark_invoice_successful(invoice_id:)
       path = interpolate_path("/sites/{site_id}/invoices/{invoice_id}/mark_successful", site_id: site_id, invoice_id: invoice_id)
       put(path)
@@ -805,8 +1438,20 @@ module Recurly
 
     # Reopen a closed, manual invoice
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/reopen_invoice reopen_invoice api documenation}
+    #
     # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
     # @return [Resources::Invoice] The updated invoice.
+    # @example
+    #   begin
+    #     invoice = @client.reopen_invoice(invoice_id: invoice_id)
+    #     puts "Reopened invoice #{invoice}"
+    #   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
+    #
     def reopen_invoice(invoice_id:)
       path = interpolate_path("/sites/{site_id}/invoices/{invoice_id}/reopen", site_id: site_id, invoice_id: invoice_id)
       put(path)
@@ -814,9 +1459,11 @@ module Recurly
 
     # List a invoice's line items
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_invoice_line_items list_invoice_line_items api documenation}
+    #
     # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -849,9 +1496,11 @@ module Recurly
 
     # Show the coupon redemptions applied to an invoice
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_invoice_coupon_redemptions list_invoice_coupon_redemptions api documenation}
+    #
     # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -861,7 +1510,26 @@ module Recurly
     #   * Records are returned in an arbitrary order. Since results are all
     #     returned at once you can sort the records yourself.
     #
+    # @param sort [String] Sort field. You *really* only want to sort by +updated_at+ in ascending
+    #   order. In descending order updated records will move behind the cursor and could
+    #   prevent some records from being returned.
+    #
+    # @param begin_time [DateTime] Filter by begin_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
+    # @param end_time [DateTime] Filter by end_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
     # @return [Pager<Resources::CouponRedemption>] A list of the the coupon redemptions associated with the invoice.
+    # @example
+    #   coupon_redemptions = @client.list_invoice_coupon_redemptions(
+    #     invoice_id: invoice_id,
+    #     limit: 200
+    #   )
+    #   coupon_redemptions.each do |redemption|
+    #     puts "CouponRedemption: #{redemption.id}"
+    #   end
+    #
     def list_invoice_coupon_redemptions(invoice_id:, **options)
       path = interpolate_path("/sites/{site_id}/invoices/{invoice_id}/coupon_redemptions", site_id: site_id, invoice_id: invoice_id)
       pager(path, **options)
@@ -869,6 +1537,8 @@ module Recurly
 
     # List an invoice's related credit or charge invoices
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_related_invoices list_related_invoices api documenation}
+    #
     # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
     # @return [Pager<Resources::Invoice>] A list of the credit or charge invoices associated with the invoice.
     def list_related_invoices(invoice_id:)
@@ -878,9 +1548,28 @@ module Recurly
 
     # Refund an invoice
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/refund_invoice refund_invoice api documenation}
+    #
     # @param invoice_id [String] Invoice ID or number (use prefix: +number-+, e.g. +number-1000+).
     # @param body [Requests::InvoiceRefund] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::InvoiceRefund}
     # @return [Resources::Invoice] Returns the new credit invoice.
+    # @example
+    #   begin
+    #     invoice_refund = {
+    #       type: "amount",
+    #       amount: 100,
+    #     }
+    #     invoice = @client.refund_invoice(
+    #       invoice_id: invoice_id,
+    #       body: invoice_refund
+    #     )
+    #     puts "Refunded invoice #{invoice}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def refund_invoice(invoice_id:, body:)
       path = interpolate_path("/sites/{site_id}/invoices/{invoice_id}/refund", site_id: site_id, invoice_id: invoice_id)
       post(path, body, Requests::InvoiceRefund)
@@ -888,8 +1577,10 @@ module Recurly
 
     # List a site's line items
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_line_items list_line_items api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -922,8 +1613,20 @@ module Recurly
 
     # Fetch a line item
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_line_item get_line_item api documenation}
+    #
     # @param line_item_id [String] Line Item ID.
     # @return [Resources::LineItem] A line item.
+    # @example
+    #   begin
+    #     line_item = @client.get_line_item(line_item_id: line_item_id)
+    #     puts "Got LineItem #{line_item}"
+    #   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
+    #
     def get_line_item(line_item_id:)
       path = interpolate_path("/sites/{site_id}/line_items/{line_item_id}", site_id: site_id, line_item_id: line_item_id)
       get(path)
@@ -931,7 +1634,21 @@ module Recurly
 
     # Delete an uninvoiced line item
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/remove_line_item remove_line_item api documenation}
+    #
     # @param line_item_id [String] Line Item ID.
+    # @example
+    #   begin
+    #     @client.remove_line_item(
+    #       line_item_id: line_item_id
+    #     )
+    #     puts "Removed LineItem #{line_item_id}"
+    #   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
+    #
     def remove_line_item(line_item_id:)
       path = interpolate_path("/sites/{site_id}/line_items/{line_item_id}", site_id: site_id, line_item_id: line_item_id)
       delete(path)
@@ -939,8 +1656,10 @@ module Recurly
 
     # List a site's plans
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_plans list_plans api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -964,6 +1683,12 @@ module Recurly
     #
     # @param state [String] Filter by state.
     # @return [Pager<Resources::Plan>] A list of plans.
+    # @example
+    #   plans = @client.list_plans(limit: 200)
+    #   plans.each do |plan|
+    #     puts "Plan: #{plan.code}"
+    #   end
+    #
     def list_plans(**options)
       path = interpolate_path("/sites/{site_id}/plans", site_id: site_id)
       pager(path, **options)
@@ -971,8 +1696,37 @@ module Recurly
 
     # Create a plan
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_plan create_plan api documenation}
+    #
     # @param body [Requests::PlanCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::PlanCreate}
     # @return [Resources::Plan] A plan.
+    # @example
+    #   begin
+    #     plan_create = {
+    #       code: plan_code,
+    #       name: plan_name,
+    #       currencies: [
+    #         currency: "USD",
+    #         setup_fee: 1_000
+    #       ],
+    #       add_ons: [
+    #         {
+    #           name: 'Extra User',
+    #           code: 'extra_user',
+    #           currencies: [
+    #             { currency: 'USD', unit_amount: 10_000 }
+    #           ]
+    #         }
+    #       ]
+    #     }
+    #     plan = @client.create_plan(body: plan_create)
+    #     puts "Created Plan #{plan}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def create_plan(body:)
       path = interpolate_path("/sites/{site_id}/plans", site_id: site_id)
       post(path, body, Requests::PlanCreate)
@@ -980,8 +1734,20 @@ module Recurly
 
     # Fetch a plan
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_plan get_plan api documenation}
+    #
     # @param plan_id [String] Plan ID or code (use prefix: +code-+, e.g. +code-gold+).
     # @return [Resources::Plan] A plan.
+    # @example
+    #   begin
+    #     plan = @client.get_plan(plan_id: plan_id)
+    #     puts "Got plan #{plan}"
+    #   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
+    #
     def get_plan(plan_id:)
       path = interpolate_path("/sites/{site_id}/plans/{plan_id}", site_id: site_id, plan_id: plan_id)
       get(path)
@@ -989,6 +1755,8 @@ module Recurly
 
     # Update a plan
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/update_plan update_plan api documenation}
+    #
     # @param plan_id [String] Plan ID or code (use prefix: +code-+, e.g. +code-gold+).
     # @param body [Requests::PlanUpdate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::PlanUpdate}
     # @return [Resources::Plan] A plan.
@@ -999,6 +1767,8 @@ module Recurly
 
     # Remove a plan
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/remove_plan remove_plan api documenation}
+    #
     # @param plan_id [String] Plan ID or code (use prefix: +code-+, e.g. +code-gold+).
     # @return [Resources::Plan] Plan deleted
     def remove_plan(plan_id:)
@@ -1008,9 +1778,11 @@ module Recurly
 
     # List a plan's add-ons
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_plan_add_ons list_plan_add_ons api documenation}
+    #
     # @param plan_id [String] Plan ID or code (use prefix: +code-+, e.g. +code-gold+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -1034,6 +1806,15 @@ module Recurly
     #
     # @param state [String] Filter by state.
     # @return [Pager<Resources::AddOn>] A list of add-ons.
+    # @example
+    #   add_ons = @client.list_plan_add_ons(
+    #     plan_id: plan_id,
+    #     limit: 200
+    #   )
+    #   add_ons.each do |add_on|
+    #     puts "AddOn: #{add_on.code}"
+    #   end
+    #
     def list_plan_add_ons(plan_id:, **options)
       path = interpolate_path("/sites/{site_id}/plans/{plan_id}/add_ons", site_id: site_id, plan_id: plan_id)
       pager(path, **options)
@@ -1041,6 +1822,8 @@ module Recurly
 
     # Create an add-on
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_plan_add_on create_plan_add_on api documenation}
+    #
     # @param plan_id [String] Plan ID or code (use prefix: +code-+, e.g. +code-gold+).
     # @param body [Requests::AddOnCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::AddOnCreate}
     # @return [Resources::AddOn] An add-on.
@@ -1051,39 +1834,59 @@ module Recurly
 
     # Fetch a plan's add-on
     #
-    # @param add_on_id [String] Add-on ID or code (use prefix: +code-+, e.g. +code-gold+).
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_plan_add_on get_plan_add_on api documenation}
+    #
     # @param plan_id [String] Plan ID or code (use prefix: +code-+, e.g. +code-gold+).
+    # @param add_on_id [String] Add-on ID or code (use prefix: +code-+, e.g. +code-gold+).
     # @return [Resources::AddOn] An add-on.
-    def get_plan_add_on(add_on_id:, plan_id:)
-      path = interpolate_path("/sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}", site_id: site_id, add_on_id: add_on_id, plan_id: plan_id)
+    # @example
+    #   begin
+    #     add_on = @client.get_plan_add_on(
+    #       plan_id: plan_id, add_on_id: add_on_id
+    #     )
+    #     puts "Got plan add-on #{add_on}"
+    #   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
+    #
+    def get_plan_add_on(plan_id:, add_on_id:)
+      path = interpolate_path("/sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}", site_id: site_id, plan_id: plan_id, add_on_id: add_on_id)
       get(path)
     end
 
     # Update an add-on
     #
-    # @param add_on_id [String] Add-on ID or code (use prefix: +code-+, e.g. +code-gold+).
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/update_plan_add_on update_plan_add_on api documenation}
+    #
     # @param plan_id [String] Plan ID or code (use prefix: +code-+, e.g. +code-gold+).
+    # @param add_on_id [String] Add-on ID or code (use prefix: +code-+, e.g. +code-gold+).
     # @param body [Requests::AddOnUpdate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::AddOnUpdate}
     # @return [Resources::AddOn] An add-on.
-    def update_plan_add_on(add_on_id:, plan_id:, body:)
-      path = interpolate_path("/sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}", site_id: site_id, add_on_id: add_on_id, plan_id: plan_id)
+    def update_plan_add_on(plan_id:, add_on_id:, body:)
+      path = interpolate_path("/sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}", site_id: site_id, plan_id: plan_id, add_on_id: add_on_id)
       put(path, body, Requests::AddOnUpdate)
     end
 
     # Remove an add-on
     #
-    # @param add_on_id [String] Add-on ID or code (use prefix: +code-+, e.g. +code-gold+).
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/remove_plan_add_on remove_plan_add_on api documenation}
+    #
     # @param plan_id [String] Plan ID or code (use prefix: +code-+, e.g. +code-gold+).
+    # @param add_on_id [String] Add-on ID or code (use prefix: +code-+, e.g. +code-gold+).
     # @return [Resources::AddOn] Add-on deleted
-    def remove_plan_add_on(add_on_id:, plan_id:)
-      path = interpolate_path("/sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}", site_id: site_id, add_on_id: add_on_id, plan_id: plan_id)
+    def remove_plan_add_on(plan_id:, add_on_id:)
+      path = interpolate_path("/sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}", site_id: site_id, plan_id: plan_id, add_on_id: add_on_id)
       delete(path)
     end
 
     # List a site's add-ons
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_add_ons list_add_ons api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -1114,6 +1917,8 @@ module Recurly
 
     # Fetch an add-on
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_add_on get_add_on api documenation}
+    #
     # @param add_on_id [String] Add-on ID or code (use prefix: +code-+, e.g. +code-gold+).
     # @return [Resources::AddOn] An add-on.
     def get_add_on(add_on_id:)
@@ -1123,8 +1928,10 @@ module Recurly
 
     # List a site's subscriptions
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_subscriptions list_subscriptions api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -1152,6 +1959,12 @@ module Recurly
     #   - When +state=live+, only subscriptions that are in an active, canceled, or future state or are in trial will be returned.
     #
     # @return [Pager<Resources::Subscription>] A list of the site's subscriptions.
+    # @example
+    #   subscriptions = @client.list_subscriptions(limit: 200)
+    #   subscriptions.each do |subscription|
+    #     puts "Subscription: #{subscription.uuid}"
+    #   end
+    #
     def list_subscriptions(**options)
       path = interpolate_path("/sites/{site_id}/subscriptions", site_id: site_id)
       pager(path, **options)
@@ -1159,8 +1972,31 @@ module Recurly
 
     # Create a new subscription
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_subscription create_subscription api documenation}
+    #
     # @param body [Requests::SubscriptionCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::SubscriptionCreate}
     # @return [Resources::Subscription] A subscription.
+    # @example
+    #   begin
+    #     subscription_create = {
+    #       plan_code: plan_code,
+    #       currency: "USD",
+    #       # This can be an existing account or
+    #       # a new acocunt
+    #       account: {
+    #         code: account_code,
+    #       }
+    #     }
+    #     subscription = @client.create_subscription(
+    #       body: subscription_create
+    #     )
+    #     puts "Created Subscription #{subscription}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def create_subscription(body:)
       path = interpolate_path("/sites/{site_id}/subscriptions", site_id: site_id)
       post(path, body, Requests::SubscriptionCreate)
@@ -1168,19 +2004,20 @@ module Recurly
 
     # Fetch a subscription
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_subscription get_subscription api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @return [Resources::Subscription] A subscription.
     # @example
     #   begin
-    #     # You can use the `id` field from a Subscription object
-    #     subscription = @client.get_subscription(subscription_id: "hympfmu77b4d")
-    #     # If you have the uuid, you can prefix with `uuid-`
-    #     subscription = @client.get_subscription(subscription_id: "uuid-419cd2effd49236e502ccc42db928280")
-    #   rescue Recurly::Errors::NotFoundError => e
-    #     puts e
-    #     # => Recurly::NotFoundError: Couldn't Subscription with uuid = 419cd2effd49236e502ccc42db928280
-    #     puts e.recurly_error
-    #     # => #<Recurly::Error:0x007f8b29918618 @attributes={:type=>"not_found", :message=>"Couldn't find Subscription with uuid = 419cd2effd49236e502ccc42db928280", :params=>[{"param"=>"subscription_id"}]}>
+    #     subscription = @client.get_subscription(
+    #       subscription_id: subscription_id
+    #     )
+    #     puts "Got Subscription #{subscription}"
+    #   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
     #
     def get_subscription(subscription_id:)
@@ -1190,9 +2027,28 @@ module Recurly
 
     # Modify a subscription
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/modify_subscription modify_subscription api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @param body [Requests::SubscriptionUpdate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::SubscriptionUpdate}
     # @return [Resources::Subscription] A subscription.
+    # @example
+    #   begin
+    #     subscription_update = {
+    #       customer_notes: "New Notes",
+    #       terms_and_conditions: "New ToC"
+    #     }
+    #     subscription = @client.modify_subscription(
+    #       subscription_id: subscription_id,
+    #       body: subscription_update
+    #     )
+    #     puts "Modified Subscription #{subscription}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def modify_subscription(subscription_id:, body:)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}", site_id: site_id, subscription_id: subscription_id)
       put(path, body, Requests::SubscriptionUpdate)
@@ -1200,6 +2056,8 @@ module Recurly
 
     # Terminate a subscription
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/terminate_subscription terminate_subscription api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @param refund [String] The type of refund to perform:
     #
@@ -1212,6 +2070,18 @@ module Recurly
     #   You may also terminate a subscription with no refund and then manually refund specific invoices.
     #
     # @return [Resources::Subscription] An expired subscription.
+    # @example
+    #   begin
+    #     subscription = @client.terminate_subscription(
+    #       subscription_id: subscription_id,
+    #     )
+    #     puts "Terminated Subscription #{subscription}"
+    #   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
+    #
     def terminate_subscription(subscription_id:, **options)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}", site_id: site_id, subscription_id: subscription_id)
       delete(path, **options)
@@ -1219,8 +2089,22 @@ module Recurly
 
     # Cancel a subscription
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/cancel_subscription cancel_subscription api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @return [Resources::Subscription] A canceled or failed subscription.
+    # @example
+    #   begin
+    #     subscription = @client.cancel_subscription(
+    #       subscription_id: subscription_id
+    #     )
+    #     puts "Canceled Subscription #{subscription}"
+    #   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
+    #
     def cancel_subscription(subscription_id:)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/cancel", site_id: site_id, subscription_id: subscription_id)
       put(path)
@@ -1228,8 +2112,22 @@ module Recurly
 
     # Reactivate a canceled subscription
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/reactivate_subscription reactivate_subscription api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @return [Resources::Subscription] An active subscription.
+    # @example
+    #   begin
+    #     subscription = @client.reactivate_subscription(
+    #       subscription_id: subscription_id
+    #     )
+    #     puts "Reactivated Canceled Subscription #{subscription}"
+    #   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
+    #
     def reactivate_subscription(subscription_id:)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/reactivate", site_id: site_id, subscription_id: subscription_id)
       put(path)
@@ -1237,9 +2135,27 @@ module Recurly
 
     # Pause subscription
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/pause_subscription pause_subscription api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @param body [Requests::SubscriptionPause] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::SubscriptionPause}
     # @return [Resources::Subscription] A subscription.
+    # @example
+    #   begin
+    #     subscription_pause = {
+    #       remaining_pause_cycles: 10
+    #     }
+    #     subscription = @client.pause_subscription(
+    #       subscription_id: subscription_id,
+    #       body: subscription_pause
+    #     )
+    #     puts "Paused Subscription #{subscription}"
+    #   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
+    #
     def pause_subscription(subscription_id:, body:)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/pause", site_id: site_id, subscription_id: subscription_id)
       put(path, body, Requests::SubscriptionPause)
@@ -1247,8 +2163,22 @@ module Recurly
 
     # Resume subscription
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/resume_subscription resume_subscription api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @return [Resources::Subscription] A subscription.
+    # @example
+    #   begin
+    #     subscription = @client.resume_subscription(
+    #       subscription_id: subscription_id
+    #     )
+    #     puts "Resumed Subscription #{subscription}"
+    #   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
+    #
     def resume_subscription(subscription_id:)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/resume", site_id: site_id, subscription_id: subscription_id)
       put(path)
@@ -1256,8 +2186,22 @@ module Recurly
 
     # Fetch a subscription's pending change
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_subscription_change get_subscription_change api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @return [Resources::SubscriptionChange] A subscription's pending change.
+    # @example
+    #   begin
+    #     change = @client.get_subscription_change(
+    #       subscription_id: subscription_id
+    #     )
+    #     puts "Got SubscriptionChange #{change}"
+    #   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
+    #
     def get_subscription_change(subscription_id:)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/change", site_id: site_id, subscription_id: subscription_id)
       get(path)
@@ -1265,9 +2209,28 @@ module Recurly
 
     # Create a new subscription change
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/create_subscription_change create_subscription_change api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @param body [Requests::SubscriptionChangeCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::SubscriptionChangeCreate}
     # @return [Resources::SubscriptionChange] A subscription change.
+    # @example
+    #   begin
+    #     change_create = {
+    #       timeframe: "now",
+    #       plan_code: new_plan_code
+    #     }
+    #     change = @client.create_subscription_change(
+    #       subscription_id: subscription_id,
+    #       body: change_create
+    #     )
+    #     puts "Created SubscriptionChange #{change}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def create_subscription_change(subscription_id:, body:)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/change", site_id: site_id, subscription_id: subscription_id)
       post(path, body, Requests::SubscriptionChangeCreate)
@@ -1275,7 +2238,21 @@ module Recurly
 
     # Delete the pending subscription change
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/remove_subscription_change remove_subscription_change api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
+    # @example
+    #   begin
+    #     @client.remove_subscription_change(
+    #       subscription_id: subscription_id
+    #     )
+    #     puts "Removed SubscriptionChange #{subscription_id}"
+    #   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
+    #
     def remove_subscription_change(subscription_id:)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/change", site_id: site_id, subscription_id: subscription_id)
       delete(path)
@@ -1283,9 +2260,11 @@ module Recurly
 
     # List a subscription's invoices
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_subscription_invoices list_subscription_invoices api documenation}
+    #
     # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -1314,15 +2293,27 @@ module Recurly
     #   - +type=legacy+, only legacy invoices will be returned.
     #
     # @return [Pager<Resources::Invoice>] A list of the subscription's invoices.
+    # @example
+    #   invoices = @client.list_subscription_invoices(
+    #     subscription_id: subscription_id,
+    #     limit: 200
+    #   )
+    #   invoices.each do |invoice|
+    #     puts "Invoice: #{invoice.number}"
+    #   end
+    #
     def list_subscription_invoices(subscription_id:, **options)
       path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/invoices", site_id: site_id, subscription_id: subscription_id)
       pager(path, **options)
     end
 
-    # List a site's transactions
+    # List a subscription's line items
     #
-    # @param ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1+.
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_subscription_line_items list_subscription_line_items api documenation}
+    #
+    # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
     #
     #   *Important notes:*
     #   * The +ids+ parameter cannot be used with any other ordering or filtering
@@ -1344,9 +2335,101 @@ module Recurly
     # @param end_time [DateTime] Filter by end_time when +sort=created_at+ or +sort=updated_at+.
     #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
     #
+    # @param original [String] Filter by original field.
+    # @param state [String] Filter by state field.
     # @param type [String] Filter by type field.
+    # @return [Pager<Resources::LineItem>] A list of the subscription's line items.
+    # @example
+    #   line_items = @client.list_subscription_line_items(
+    #     subscription_id: subscription_id,
+    #     limit: 200
+    #   )
+    #   line_items.each do |line_item|
+    #     puts "LineItem: #{line_item.id}"
+    #   end
+    #
+    def list_subscription_line_items(subscription_id:, **options)
+      path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/line_items", site_id: site_id, subscription_id: subscription_id)
+      pager(path, **options)
+    end
+
+    # Show the coupon redemptions for a subscription
+    #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_subscription_coupon_redemptions list_subscription_coupon_redemptions api documenation}
+    #
+    # @param subscription_id [String] Subscription ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
+    #
+    #   *Important notes:*
+    #   * The +ids+ parameter cannot be used with any other ordering or filtering
+    #     parameters (+limit+, +order+, +sort+, +begin_time+, +end_time+, etc)
+    #   * Invalid or unknown IDs will be ignored, so you should check that the
+    #     results correspond to your request.
+    #   * Records are returned in an arbitrary order. Since results are all
+    #     returned at once you can sort the records yourself.
+    #
+    # @param sort [String] Sort field. You *really* only want to sort by +updated_at+ in ascending
+    #   order. In descending order updated records will move behind the cursor and could
+    #   prevent some records from being returned.
+    #
+    # @param begin_time [DateTime] Filter by begin_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
+    # @param end_time [DateTime] Filter by end_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
+    # @return [Pager<Resources::CouponRedemption>] A list of the the coupon redemptions on a subscription.
+    # @example
+    #   coupon_redemptions = @client.list_subscription_coupon_redemptions(
+    #     subscription_id: subscription_id,
+    #     limit: 200
+    #   )
+    #   coupon_redemptions.each do |redemption|
+    #     puts "CouponRedemption: #{redemption.id}"
+    #   end
+    #
+    def list_subscription_coupon_redemptions(subscription_id:, **options)
+      path = interpolate_path("/sites/{site_id}/subscriptions/{subscription_id}/coupon_redemptions", site_id: site_id, subscription_id: subscription_id)
+      pager(path, **options)
+    end
+
+    # List a site's transactions
+    #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/list_transactions list_transactions api documenation}
+    #
+    # @param ids [string] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #   commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
+    #
+    #   *Important notes:*
+    #   * The +ids+ parameter cannot be used with any other ordering or filtering
+    #     parameters (+limit+, +order+, +sort+, +begin_time+, +end_time+, etc)
+    #   * Invalid or unknown IDs will be ignored, so you should check that the
+    #     results correspond to your request.
+    #   * Records are returned in an arbitrary order. Since results are all
+    #     returned at once you can sort the records yourself.
+    #
+    # @param limit [Integer] Limit number of records 1-200.
+    # @param order [String] Sort order.
+    # @param sort [String] Sort field. You *really* only want to sort by +updated_at+ in ascending
+    #   order. In descending order updated records will move behind the cursor and could
+    #   prevent some records from being returned.
+    #
+    # @param begin_time [DateTime] Filter by begin_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
+    # @param end_time [DateTime] Filter by end_time when +sort=created_at+ or +sort=updated_at+.
+    #   *Note:* this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
+    #
+    # @param type [String] Filter by type field. The value +payment+ will return both +purchase+ and +capture+ transactions.
     # @param success [String] Filter by success field.
     # @return [Pager<Resources::Transaction>] A list of the site's transactions.
+    # @example
+    #   transactions = @client.list_transactions(limit: 200)
+    #   transactions.each do |transaction|
+    #     puts "Transaction: #{transaction.uuid}"
+    #   end
+    #
     def list_transactions(**options)
       path = interpolate_path("/sites/{site_id}/transactions", site_id: site_id)
       pager(path, **options)
@@ -1354,8 +2437,20 @@ module Recurly
 
     # Fetch a transaction
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_transaction get_transaction api documenation}
+    #
     # @param transaction_id [String] Transaction ID or UUID (use prefix: +uuid-+, e.g. +uuid-123457890+).
     # @return [Resources::Transaction] A transaction.
+    # @example
+    #   begin
+    #     transaction = @client.get_transaction(transaction_id: transaction_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
+    #
     def get_transaction(transaction_id:)
       path = interpolate_path("/sites/{site_id}/transactions/{transaction_id}", site_id: site_id, transaction_id: transaction_id)
       get(path)
@@ -1363,6 +2458,8 @@ module Recurly
 
     # Fetch a unique coupon code
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/get_unique_coupon_code get_unique_coupon_code api documenation}
+    #
     # @param unique_coupon_code_id [String] Unique Coupon Code ID or code (use prefix: +code-+, e.g. +code-abc-8dh2-def+).
     # @return [Resources::UniqueCouponCode] A unique coupon code.
     def get_unique_coupon_code(unique_coupon_code_id:)
@@ -1372,6 +2469,8 @@ module Recurly
 
     # Deactivate a unique coupon code
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/deactivate_unique_coupon_code deactivate_unique_coupon_code api documenation}
+    #
     # @param unique_coupon_code_id [String] Unique Coupon Code ID or code (use prefix: +code-+, e.g. +code-abc-8dh2-def+).
     # @return [Resources::UniqueCouponCode] A unique coupon code.
     def deactivate_unique_coupon_code(unique_coupon_code_id:)
@@ -1381,6 +2480,8 @@ module Recurly
 
     # Restore a unique coupon code
     #
+    # {https://partner-docs.recurly.com/v2018-08-09#operation/reactivate_unique_coupon_code reactivate_unique_coupon_code api documenation}
+    #
     # @param unique_coupon_code_id [String] Unique Coupon Code ID or code (use prefix: +code-+, e.g. +code-abc-8dh2-def+).
     # @return [Resources::UniqueCouponCode] A unique coupon code.
     def reactivate_unique_coupon_code(unique_coupon_code_id:)