Take a tour Sandbox Signup
Toggle Mobile Navigation
  • Content

API v2 Ruby Client Upgrade Guide

This page is provided as an upgrade guide to all users of the official ruby client.

Two aspects of the upgrade process are covered:

  • Given that version designations for client libraries do not support the same versioning system as the v2 API, we have provided a version mapping table directly below. You can use this table in order to determine which version of the v2 API that a specific client library version is utilizing.
  • Breaking changes to client libraries are normally applied with a bump in the minor version. As an example, suppose you wish to upgrade from 2.11.3 to 2.17.5 while preserving current functionality: apply all changes listed in (2.12.0, 2.13.0, ..., 2.17.0). A guide to breaking changes between all versions of the client library can be found below.

We recommend that you first identify the version of the client library required based on the associated API version denoted in the Client Library Mapping Table (directly below), and then refer to the Guide to Breaking Changes section in order to identify next steps to upgrade.

Version Mapping Table

API Version Client Version (First) Client Version (Last)
2.6 (and below) 2.0.0 2.10.0
2.7 2.10.1 2.10.5
2.8 2.11.0 2.11.4
2.9 2.12.0 2.12.2
2.10 2.13.0 2.15.0
2.11 2.15.1 2.15.3
2.12 2.15.4 2.15.4
2.13 2.16.0 2.16.1
2.14 2.16.2 2.17.0
2.15 2.17.1 2.17.1
2.16 2.17.2 2.17.3
2.17 2.17.4 2.17.5
2.18 2.17.6 2.17.7
2.19 2.17.8 2.17.9
2.20 2.17.10 2.17.10
2.21 2.17.11 2.17.11
2.22 2.18.0 2.18.3
2.24 2.18.4 2.18.6
2.25 2.18.7 2.18.7
2.26 2.18.8 2.18.9
2.27 2.18.10 2.18.11
2.28 2.18.12 2.18.13
2.29 2.18.14  

Guide to Breaking Changes

2.18.0

This release contains one breaking change. It only applies to Vertex users so will not likely affect you. Invoice#tax_types[].type on invoice and preview invoice endpoints is no longer returned.

2.17.0

This release contains one breaking change. Older Recurly.js token signing is no longer supported. You should upgrade to version 4 of Recurly.js. The js module is still around to support storing the public_key.

2.16.0

The only breaking change is the removal of the railtie. The railtie was being included automatically on detecting rails and was automatically setting the accept_language for each request. If this is something you wish to continue doing, you’ll need to set this yourself.

2.15.0

  1. Invoice#refund and Invoice#refund_amount return type

    If you are upgrading from 2.13.X or 2.14.X, a design bug was fixed. Invoice#refund and Invoice#refund_amount once again return an Invoice and not an InvoiceCollection.

  2. Resource#find_each arguments

    Resource#find_each previously only accepted per_page but now accepts an options Hash for pagination params. If you want to preserve functionality:

     # Change This
 Recurly::Invoice.find_each(50) do |invoice|
   puts invoice
 end

 # To This
 Recurly::Invoice.find_each(per_page: 50) do |invoice|
   puts invoice
 end

2.14.0

  1. Invoice#mark_failed now returns InvoiceCollection

    mark_failed no longer reloads the invoice with the response returning true or false, it returns either an InvoiceCollection if failable and request is successful, it returns false if invoice cannot be marked failed. To keep functionality, take the charge_invoice of the returned collection:

     invoice = Recurly::Invoice.find('1001')

 failed_collection = invoice.mark_failed
 if failed_collection
   invoice = failed_collection.charge_invoice
 end

  2. Subscription previews and InvoiceCollection

    Subscription previews and preview changes now return InvoiceCollections rather than Invoice. Utilize the charge_invoice to keep functionality the same:

     subscription.preview

 # Change
 invoice = subscription.invoice
 # To
 invoice = subscription.invoice_collection.charge_invoice

2.13.0

There are many breaking changes due to the Credit Memos PR

  1. InvoiceCollection

    When creating or refunding invoices, we now return an InvoiceCollection object rather than an Invoice. If you wish to upgrade your application without changing functionality, we recommend that you use the charge_invoice on the InvoiceCollection. Example:

     # Change this
 invoice = my_account.invoice!       # Returns an Invoice

 # To this
 collection = my_account.invoice!    # Returns an InvoiceCollection
 invoice = collection.charge_invoice # Returns an Invoice

    These methods, which before returned Invoice now return InvoiceCollection:

    • Purchase.preview!
    • Purchase.invoice!
    • Purchase.authorize!
    • Account#invoice!
    • Account#build_invoice

  2. Invoice subtotal_* changes

    If you want to preserve functionality, change any use of Invoice#subtotal_after_discount_in_cents to Invoice#subtotal_in_cents. If you were previously using Invoice#subtotal_in_cents, this has been changed to Invoice#subtotal_before_discount_in_cents.

  3. Invoice Refund – refund_apply_order changed to refund_method

    If you were using refund_apply_order on any refunds, then you need to change this to use refund_method instead. The keys from this have changed from (credit, transaction) to (credit_first, transaction_first)

     # If you use `credit` with refund_amount or refund
 invoice.refund_amount(1000, 'credit')
 invoice.refund(line_items, 'credit')
 # Change to use `credit_first`
 invoice.refund(line_items, 'credit_first')

 # If you use `transaction` with refund_amount or refund
 invoice.refund_amount(1000, 'transaction')
 invoice.refund(line_items, 'transaction')
 # Change to use `transaction_first`
 invoice.refund(line_items, 'transaction_first')

  4. Invoice States

    If you are checking Invoice#state anywhere, you will want to check that you have the new correct values. collected has changed to paid and open has changed to pending. Example:

     # Change this
 if invoice.state == 'collected'
 # To this
 if invoice.state == 'paid'

 # Change this
 if invoice.state == 'open'
 # To this
 if invoice.state == 'pending'

2.12.0

  1. The ‘subscription’ link on an instance of Adjustment is now only created if adjustment is originating from a subscription plan charge, setup fee, add on, trial or proration credit. It is no longer created for other adjustments.
  2. Instances of Transaction and Invoice no longer have a subscription link and you must now use the subscriptions link. 
    # Change this
sub = invoice.subscription
# To this
sub = invoice.subscriptions.first

2.11.0

There are two breaking changes in this API version you must consider.

Country Codes

All country fields must now contain valid 2 letter ISO 3166 country codes. If your country code fails validation, you will receive a validation error. This affects any endpoint where an address is collected.

Purchase Currency

The purchases endpoint can create and invoice multiple adjustments at once but our invoices can only contain items in one currency. To make this explicit the currency can no longer be provided on an adjustment, it must be set once for the entire purchase:

purchase = Recurly::Purchase.new(
  # The purchase object is the only place you can set the currency:
  currency: 'USD',
  account: {
    account_code: 'someone'
  }
  adjustments: [
    {
       # Remove this currency
       # You can no longer set the currency on adjustment level
       currency: 'USD',
       unit_amount_in_cents: 1000
    }
  ]
)

2.10.0

  1. Since the X-Records header was removed in the pagination endpoint, you can no longer call count on a Pager and expect it to return a cached response.

    From now on, when you call Pager#count, it will send a HEAD request to the server. So make sure you aren’t calling that method in places where you expect the value to be cached for you. For more info see PR #324.

  2. For POST /v2/subscriptions Sending nil for total_billing_cycles attribute will now override plan total_billing_cycles setting and will make subscription renew forever. Omitting the attribute will cause the setting to default to the value of plan total_billing_cycles.

2.9.0

Ruby 1.9 and 2.0 are now deprecated. You may no longer use nokogiri on these rubies. Please see PR #317 for more information. If you wish to use nokogiri and it’s not already required (by rails for instance), you will need to explicitly add it as a dependency and require it.

2.8.0

If you are using as_json on a Resource (previously unsupported) we are now returning the attributes as json rather than the resource as json. This means your returned Hash will not have an attributes key but will rather BE the hash of attributes itself. See PR #295

2.7.0

No breaking changes to address.

2.6.0

No breaking changes to address.

2.5.0

This release has API breaking changes around coupon redemptions. See PR to see if you are affected. If you do not use the Account#redemption method, you can safely pass.

2.4.0

No breaking changes to address.

2.3.0

Adjustment#taxable was removed in favor of Adjustment#tax_exempt. Keep in mind these are both booleans but logically inverse.

2.2.0

This release ensures that exceptions are thrown for all non-200 responses: https://github.com/recurly/recurly-client-ruby/commit/f3c473aa290867ae5eb35eec5b2741b19d1548e5