A new version of Recurly’s API has been released! Version 2.5 comes with many improvements such as new endpoints, new request attributes, and new response attributes as well. Let’s dive in and take a look at what’s changed!

First, we have a new endpoint for attempting a collection on an invoice:

PUT `/v2/invoices/:invoice_number/collect`

 This allows you to collect a past-due or pending invoice. This API is rate limited, and only one collection attempt per account is allowed within an hour. You can read more about it in the docs, here.

Next, we have a new GET endpoint, `/v2/invoices/:invoice_number/adjustments`. As you can imagine, this endpoint returns a list of adjustments on a given invoice.

New Response Objects

We’ve also added several objects in our responses across various endpoints. For subscriptions, we’ve added `<started_with_gift>` and `<converted_at>` elements, for determining if a subscription started with a gift and when the subscription was converted.

We’ve added an `<updated_at>` element to our billing information response, so now you know when the account’s billing information was last updated.

We’ve added an `<id>` to each coupon response for easier indexing and reference.

Invoices

On invoices, we’ve added the following elements:

`<subtotal_after_discount_in_cents>`

`<attempt_next_collection_at>`

`<recovery_reason>`

`<all_line_items>`

`<subtotal_after_discount_in_cents>` is helpful for determining the invoice subtotal after all discounts have been accounted for.

`<attempt_next_collection_at>` returns a timestamp of the next time a past due invoice will attempt to collect, while `<recovery_reason>` will return a string sharing the reason the invoice was finally collected.

Finally, for invoices with more than 500 line items, you’ll see a `<all_line_items>` href with a path to follow for displaying all line items on that invoice.

Transactions

Transactions now have lots of new elements to explore, such as `<gateway_type>` which will display the gateway that handled the transaction and an `<origin>` element for displaying the origin of the transaction. `<description>` is for returning a description of the transaction, while `<message>` provides more information about the transaction.

Finally, you can use `<collected_at>` to determine when a transaction was collected and see its approval code with `<approval_code>`.

Accounts

Accounts now return a bevy of booleans, with fairly self-explanatory elements, each of which provides more insights about the current status of a given account:

`<has_live_subscription>`

`<has_active_subscription>`

`<has_future_subscription>`

`<has_canceled_subscription>`

`<has_past_due_invoice>`

New Request Objects

In regards to requests, you can now provide a `<product_code>` when creating an adjustment or transaction, which is helpful for logging the sale of an item in your system. Also, when creating or previewing an invoice, you can now pass an optional `<currency>` element, in case an account had multiple currencies and you’d like to preview or create for just one currency. Note that the invoice request changes are now available on all versions of the API.

For More on Our API

That’s all for v2.5! Lots of wonderful changes to assist in working with a variety of objects across Recurly. While you’re thinking of API health, check out these other blog posts with great API-related information in them:

Using the Right Tools for the Right Job: A Data Extraction Story Staying Up to Date With Recurly's Client Libraries Best Practices for API Integrations in Enterprise Systems

And for more details on the new API, read our release notes.