• Content

API v2 PHP Client Upgrade Guide

This page is provided as an upgrade guide to all users of the official php 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 are normally applied with a bump in the minor version. As an example, suppose you wish to upgrade from 2.7.2 to 2.12.1 while preserving current functionality: apply all changes listed in (2.8.0, 2.9.0, ..., 2.11.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.8.0
2.7 2.8.1 2.8.2
2.8 2.9.0 2.11.4
2.9 None None
2.10 2.10.0 2.10.0
2.11 2.10.1 2.10.1
2.12 2.10.2 2.10.2
2.13 2.10.3 2.10.3
2.14 2.10.4 2.10.4
2.15 2.10.5 2.10.5
2.16 2.10.6 2.10.6
2.17 2.11.0 2.11.1
2.18 2.11.2 2.11.2
2.19 2.12.0 2.12.2
2.20 2.12.3 2.12.3
2.21 2.12.4 2.12.4
2.22 2.12.5 2.12.8
2.24 2.12.9 2.12.10
2.25 2.12.11 2.12.12
2.26 2.12.13 2.12.13
2.27 2.12.14 2.12.14
2.28 2.12.15 2.12.15
2.29 2.12.16  

Guide to Breaking Changes


Note: This version contains a bug with the _verifyUri method. Please use 2.12.1 or higher instead.

If you are using the Recurly_ExportFile class, you must now use getDownloadUrl() to get the download url rather than accessing this property directly.

# if you are accessing the download url directly
$url = $export_file->download_url;
# you'll now need to use a getter
$url = $export_file->getDownloadUrl();

If you are using $export_file->download($fp) and not accessing the url directly, you should not be affected.


Older Recurly.js token signing is not longer supported. You should upgrade to version 4 of Recurly.js.


There are several breaking changes to support the new credit memos feature.

  1. InvoiceCollection

    When creating invoices or using markFailed(), we now return an Recurly_InvoiceCollection object rather than an Recurly_Invoice. If you wish to upgrade your application without changing functionality, we recommend that you use the charge_invoice on the Recurly_InvoiceCollection. Example:

     # Change This:
     $invoice = Recurly_Invoice::invoicePendingCharges('my_account_code');
     # To this
     $invoiceCollection = Recurly_Invoice::invoicePendingCharges('my_account_code');
     $invoice = $invoiceCollection->charge_invoice;

    Calls that now return InvoiceCollection instead of Invoice:

    • Recurly_Purchase::invoice()
    • Recurly_Purchase::preview()
    • Recurly_Purchase::authorize()
    • Recurly_Invoice::invoicePendingCharges()
    • Recurly_Invoice::previewPendingCharges()

    Furthermore, Recurly_Invoice->markFailed() no longer updates the invoice but rather returns a new Recurly_InvoiceCollection object:

     # Change This:
     # To this
     $invoiceCollection = $invoice->markFailed();
     $failedInvoice = $invoiceCollection->charge_invoice;
  2. Recurly_Invoice->original_invoice removed

    Recurly_Invoice->original_invoice was removed in favor of Recurly_Invoice->original_invoices. If you want to maintain functionality, change your code grab the first invoice from that endpoint:

     # Change this
     $originalInvoice = $invoice->original_invoice->get();
     # To this
     $originalInvoice = $invoice->original_invoices->get()->current(); # current is first item
  3. Invoice subtotal_* changes

    We have renamed two of the invoice subtotal fields to more clearly reflect their values:

    • Renamed subtotal_in_cents to subtotal_before_discount_in_cents
    • Renamed subtotal_after_discount_in_cents to subtotal_in_cents
  4. Invoice Refund – refund_apply_order changed to refund_method

    If you were using Recurly_Invoice->refund or Recurly_Invoice->refundAmount and explicitly setting the second refund_apply_order parameter, then you may need to change value to fit the new refund_method format. The values for this have changed from (credit, transaction) to (credit_first, transaction_first)

    If you don’t explicitly set the refund_apply_order like in these two calls, no change is needed:


    If you do set the second param, you’ll need to change:

    • credit to credit_first
    • transaction to transaction_first


     # Change `credit`:
     $invoice->refund($line_items, 'credit');
     $invoice->refundAmount(1000, 'credit');
     # To `credit_first`
     $invoice->refund($line_items, 'credit_first');
     $invoice->refundAmount(1000, 'credit_first');
     # Change `transaction`
     $invoice->refund($line_items, 'transaction');
     $invoice->refundAmount(1000, 'transaction');
     # To `transaction_first`
     $invoice->refund($line_items, 'transaction_first');
     $invoice->refundAmount(1000, 'transaction_first');
  5. Invoice States

    If you are checking Recurly_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')

    This also affects the Recurly_InvoiceList::getCollected() and Recurly_InvoiceList::getOpen() functions. Example:

     # Change this
     # To this
     # Change this
     # To this
  6. Deprecated Recurly_Invoice->subscription and Recurly_Transaction->subscription removed

    If you are using Recurly_Invoice->subscription or Recurly_Transaction->subscription anywhere, you will now need to call subscriptions instead and take the first one.

     # Change this
     $subscription = $invoice->subscription->get();
     # To this
     $subscription = $invoice->subscriptions->get()->current();
     # Or this
     $subscription = $transaction->subscription->get();
     # To this
     $subscription = $transaction->subscriptions->get()->current();


There is one breaking changes in this API version you must consider. 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.


  1. PHP 5.3 is no longer officially supported and we no longer run tests against it.
  2. To speed up your listing requests we’re no longer automatically computing the record counts for each request’s X-Records header. For our larger sites this could halve the response time. If you still need a count it will be computed with a separate request. From now on, when you call Recurly_Pager::count(), it will send a HEAD request to the server. Ensure you aren’t calling that method in places where you expect the value to be cached for you. For more information on how this may affect you, see PR #314
  3. For POST /v2/subscriptions Sending null 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.


No breaking changes to address.


No breaking changes to address.


No breaking changes to address.


Removed balance_in_cents_invoiced and balance_in_cents_uninvoiced from Recurly_Account as they were never added to the API.


No breaking changes to address.


No breaking changes to address.