NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist, #1945 most downloaded on Packagist
The PHP client library for the Recurly API
Latest stable
4.82.0
Last release 23 days ago
30 Oct 2026
Ships fairly regularly
a new release about every 3 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
14 years old
222 releases · first in 2013
Drag across the ruler to compare, or tap a release to open it.
This release will upgrade us to API version 2.11. There are no breaking changes.
This release will upgrade us to API version 2.11. There are no breaking changes.
There are several breaking changes to support the new credit memos feature.
This release will upgrade us to API version 2.10.
There are several breaking changes to support the new credit memos feature.
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 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
subtotal_* changesWe have renamed two of the invoice subtotal fields to more clearly reflect their values:
subtotal_in_cents to subtotal_before_discount_in_centssubtotal_after_discount_in_cents to subtotal_in_centsrefund_apply_order changed to refund_methodIf 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_firsttransaction to transaction_firstExamples:
# 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');
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()
Recurly_Invoice->subscription and Recurly_Transaction->subscription removedIf 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();
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Fixed issue with RFC 2616 compliance: headers should be treated as case-insensitive.
There are two breaking changes in this API version you must consider.
This release will upgrade us to API version 2.8.
There are two 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.
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 = new Recurly_Purchase();
# The purchase object is the only place you can set the currency:
$purchase->currency = 'USD';
$purchase->account = new Recurly_Account();
$purchase->account->account_code = 'someone';
$adjustment = new Recurly_Adjustment();
# You can no longer set a currency on an adjustment, so this should be removed:
$adjustment->currency = 'USD';
$adjustment->unit_amount_in_cents = 1000;
$purchase->adjustments[] = $adjustment;
Fixed issue with RFC 2616 compliance: headers should be treated as case-insensitive.
Fixes a bug creating subscriptions for existing accounts (thanks to @g30rg) #326
This bumps us to API v2.7 but does not contain any breaking changes.
If you are upgrading from 2.8.0.rc1, there are no changes. If you are upgrading from <= 2.7.X, there are a few breaking changes this release:
This is the official release of 2.8.0. This will bring us to version 2.6 of the Recurly API.
If you are upgrading from 2.8.0.rc1, there are no changes. If you are upgrading from <= 2.7.X, there are a few breaking changes this release:
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 #314POST /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.Fixed issue with RFC 2616 compliance: headers should be treated as case-insensitive.
Writeable and updatable coupon description #297
getType method to all Resources #299deliver_at goes on the Delivery object #307Added property documentation to several classes (thanks to phpdave) #278
Upgraded to API V2.4: https://dev.recurly.com/v2.4/docs
Recurly_Pager to its items (thanks to cyruscollier) #265account_balance #273Recurly_Adjustment) to specify an origin of external_gift_card #263Recurly_AccountAcquisition #259Recurly_Stub allowing $account->invoices->get(array('state' => 'past_due')) (thanks to developer-devPHP) #270Fixed issue with RFC 2616 compliance: headers should be treated as case-insensitive.
Print warnings when using a deprecated version of the API. #250:
original_transaction to Recurly_Transaction #238Recurly_AccountBalance #239sort accepts created_at or updated_at, defaults to created_at.order accepts desc or asc, defaults to desc.begin_time and end_time accepts an ISO 8601 date or date and time.Recurly_AddonList::get() and Recurly_NoteList::get() to add $params as the second parameter so sort, order and date filtering can be passed in #249revenue_schedule_type to Recurly_Addon, Recurly_Adjustment, Recurly_Plan, Recurly_Subscription and Recurly_SubscriptionAddOn classes #257Fixed issue with RFC 2616 compliance: headers should be treated as case-insensitive.
Added support for setting free_trial_amount and free_trial_unit to Recurly_Coupon #224
free_trial_amount and free_trial_unit to Recurly_Coupon #224Recurly_NoteList #236Recurly_CouponRedemptionList and Recurly_UniqueCouponCodeList #243getRequiredAttributes() #241Added support for parsing fraud attribute on the Transaction class #228
Added support for cc_emails attribute on the Account class #202
Added support for coupon update and restore actions #186
Fixed issue with RFC 2616 compliance: headers should be treated as case-insensitive.
Added setup_fee_accounting_code to Plan #179
setup_fee_accounting_code to Plan #179applies_to_non_plan_charges to Coupon #181redemption_resource to Coupon #181X-Api-Version request header at 2.1 #181uuid to Account #181redemptions to Account #181max_redemptions_per_account to Coupon #181redemptions to Subscription #181coupon_codes to Subscription #181CACertPath to Recurly_Client #176Added duration, temporal_unit, & temporal_amount to Coupon #171
duration, temporal_unit, & temporal_amount to Coupon #171Added gateway_error_code to Recurly_Transaction #163
Fixed bug where fetching an invoice PDF did not use the invoice number prefix #155
Recurly_BillingInfo, these include:
name_on_accountaccount_type (checking or savings)last_fourrouting_numberip_address attribute to Recurly_Transaction#157bank_account_authorized_at to Recurly_Subscription #156Recurly_PushNotification to read data on *_invoice_notification (thanks to rikless) #159Fixes encoding of values with ampersands #150
Added adjustment refund support: refund() and toRefundAttributes() on Recurly_Adjustment #133
Force cURL to validate SSL certificates #122
balance_in_cents_invoiced and balance_in_cents_uninvoiced from Recurly_Account. They were never added to the API.tax_code to Recurly_Plan, Recurly_Addon and Recurly_Adjustment #120Recurly_Invoice::previewPendingCharges($accountCode) #112terms_and_conditions and customer_notes to Recurly_Invoice #115vat_location_valid field to Recurly_Account #127updateNotes() and vat_reverse_charge to Recurly_Subscription. #128vat_reverse_charge_notes to Recurly_Invoice. #128invoice_number_prefix and invoiceNumberWithPrefix() to Recurly_Invoice. This is to be used with the Country Invoice Sequencing feature. #130Fixed issue with RFC 2616 compliance: headers should be treated as case-insensitive.
Added remaining billing cycles to subscriptions: subscription->remaining_billing_cycles 91
subscription->remaining_billing_cycles 91subscription->preview() 94account->entity_use_code 100$subscription->postpone() 105Added tax details to adjustments: $adjustment->tax_details #90
Fixed issue with RFC 2616 compliance: headers should be treated as case-insensitive.
Added support for Recurly_Account field balance_in_cents_invoiced #64
Recurly_Account field balance_in_cents_invoiced #64Recurly_Account field balance_in_cents_uninvoiced #64Recurly_BillingInfo field token_id #83Explictly call Recurly_Resource's constructor #67
Recurly_Resource's constructor #67Recurly_Addon was not found #79 by baxevanisFixed error when trying to redeem expired or maxed out coupons (thanks to @jeffchannell)
Recurly_PushNotification (thanks to @richardkmiller)Recurly_AdjustmentRemove old taxable parameter from Recurly_Adjustment
taxable parameter from Recurly_Adjustmentnull attributes because Recurly_PlanTest needs total_billing_cycles to be set to null for unlimited renewals.Fixed errors thrown due to empty XML strings #62 (Thanks to @beaudesigns)
Fixed invalid XML errors when saving subscriptions with add-ons.
Added support for client subdomains, the default of 'api' should be fine for most users.
Updating client to be compliant with RFC 2616: case-insensitive headers #546
Nothing published for this version
Nothing published for this version
This is a release candidate for 2.8.0. Because of the breaking changes, we have decided to release this slowly. This will bring us to version 2.6 of t…
This is a release candidate for 2.8.0. Because of the breaking changes, we have decided to release this slowly. This will bring us to version 2.6 of the Recurly API.
There are a few breaking changes this release.
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 #314POST /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.One column per quarter.