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

2.12.0

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.

2.11.0

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

2.10.0

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

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:
 $invoice->markFailed();

 # To this
 $invoiceCollection = $invoice->markFailed();
 $failedInvoice = $invoiceCollection->charge_invoice;
```
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
```
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

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:

 $invoice->refund($line_items);
 $invoice->refundAmount(1000);

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

credit to credit_first
transaction to transaction_first

Examples:

 # 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');

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
 Recurly_InvoiceList::getCollected()
 # To this
 Recurly_InvoiceList::getPaid()

 # Change this
 Recurly_InvoiceList::getOpen()
 # To this
 Recurly_InvoiceList::getPending()

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();

2.9.0

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.