{"_id":"5919d94085b2570f00e41cb8","category":"5919d93885b2570f00e41c3a","next":{"pages":[],"description":""},"order":0,"type":"basic","isReference":false,"link_external":false,"user":"5564a0073a61a72f0067cb22","__v":0,"createdAt":"2015-06-10T22:06:37.745Z","hidden":false,"api":{"results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","auth":"required","params":[],"url":"","apiSetting":null},"link_url":"","project":"555fbba928249c1900618a82","title":"Authentication","slug":"getting-started","sync_unique":"","updates":["5595c7e9f44370190028891c","562aa244ed4bea0d00c11d8b","56bb4e10dabd992100b674f7","56f19a949791b22d0077ba0f"],"version":"5919d93785b2570f00e41c39","body":"[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"API Authentication (HTTP Basic)\"\n}\n[/block]\nRecurly uses HTTP Basic Authentication—your [Private API key](https://app.recurly.com/go/developer/api_access) is securely encrypted by the SSL channel.\n\nIf you are testing the API calls via the command line with cURL, try:\n\n```\ncurl -H 'Accept: application/xml' \\\n -H 'X-Api-Version: 2.6' \\\n -H 'Content-Type: application/xml; charset=utf-8' \\\n -u '[apikey]:' \\\n https://[subdomain].recurly.com/v2/accounts\n```\n\nReplace `[apikey]` and `[subdomain]` with the appropriate values for your site.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Calculating your own authorization header\"\n}\n[/block]\nMost programming languages encode the authorization header automatically. With HTTP Basic Authentication, the `Authorization` header is a string containing a Base-64 encoded username and password. In the case of Recurly’s API, you need only specify the username as your API key. If your library requires a password, set it to an empty string.\n\n```\n\"Authorization\": \"Basic \" + base64_encode(API Key)\n```\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Additional Request Headers\"\n}\n[/block]\n## Accept Header\nRecurly API v2 returns results as XML. Your requests should always include the header requesting the results as XML:\n\n```\nAccept: application/xml\n```\n\n## Content-Type Header\nWhen sending data to Recurly in a POST or PUT request, your request must specify the content type of your request:\n\n```\nContent-Type: application/xml; charset=utf-8\n```\n\n## X-Api-Version Header\nWhen sending data to Recurly, your request should specify the API version you're attempting to interact with:\n```\nX-Api-Version: 2.6\n```\nYou learn more about the different versions in the [API Versioning](doc:versioning) section.\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Acceptable API versions\",\n \"body\": \"Recurly supports the following API versions: **[2.0](https://dev.recurly.com/v2.0/docs)**, **[2.1](https://dev.recurly.com/v2.1/docs)**, **[2.2](https://dev.recurly.com/v2.2/docs)**, **[2.3](https://dev.recurly.com/v2.3/docs)**, **[2.4](https://dev.recurly.com/v2.4/docs)**, **[2.5](https://dev.recurly.com/v2.5/docs)**, **[2.6](https://dev.recurly.com/v2.6/docs)**\"\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Public API Key\"\n}\n[/block]\nRecurly uses two types of API keys: public and private. The Public API key is used by [Recurly.js](doc:recurlyjs) to identify its requests as belonging to your Recurly site. This key can be safely included in Javascript code.\n\nRecurly provides each site with one Public Key. The Public API Key can be regenerated on the [API Credentials](https://app.recurly.com/go/developer/api_access) page.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Private API Keys\"\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"danger\",\n \"title\": \"Treat your Private API Keys like passwords!\",\n \"body\": \"The API key allows access to your site's data. Do not include it in Javascript code exposed to browsers.\"\n}\n[/block]\nRecurly supports the use of multiple Private API keys, which can be used to integrate third party services using unique, controlled credentials.\n\n## Limits & Pricing\nMerchants on the Core or grandfathered Recurly plans or merchants in sandbox mode will be granted 5 private API keys. Merchants on Recurly’s Professional plan will be granted 10 private API keys.\n\n## Default Key\nYour default private API key should be used to integrate Recurly with your backend systems. There will be at least one key active at all times.\n\n## Additional Keys\nAdditional private API keys should be used to connect your Recurly data to additional sources, like analytics software, accounting packages, or email tools. Recurly recommends clearly labeling the name of each key to identify the associated vendor.\n\n## Regenerating Private API Keys\nYour API key can be regenerated by clicking on the Regenerate button on the [API credentials](https://app.recurly.com/go/developer/api_access) page. When you generate a private API key, you have two options:\n\n1. Block the old key immediately. This is primarily recommended when the security of a key has been compromised.\n2. Allow the old key access for 12 hours. This is primarily used when updating systems and a smooth transition between keys is needed.\n\n*If a private API key is changed, an email alert will be sent to your Recurly Site Technical Contact.*\n\n## Read-Only Keys\nWhen creating a private key, you will have the option to set the key to “read-only”. This means the API key may make GET requests but cannot not PUT, POST or DELETE requests.","excerpt":"","githubsync":"","parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Replace [apikey] and [subdomain] with the appropriate values for your site.

Calculating your own authorization header

Most programming languages encode the authorization header automatically. With HTTP Basic Authentication, the Authorization header is a string containing a Base-64 encoded username and password. In the case of Recurly’s API, you need only specify the username as your API key. If your library requires a password, set it to an empty string.

"Authorization": "Basic " + base64_encode(API Key)

Additional Request Headers

Accept Header

Recurly API v2 returns results as XML. Your requests should always include the header requesting the results as XML:

Accept: application/xml

Content-Type Header

When sending data to Recurly in a POST or PUT request, your request must specify the content type of your request:

Content-Type: application/xml; charset=utf-8

X-Api-Version Header

When sending data to Recurly, your request should specify the API version you're attempting to interact with:

X-Api-Version: 2.6

You learn more about the different versions in the API Versioning section.

Acceptable API versions

Public API Key

Recurly uses two types of API keys: public and private. The Public API key is used by Recurly.js to identify its requests as belonging to your Recurly site. This key can be safely included in Javascript code.

Recurly provides each site with one Public Key. The Public API Key can be regenerated on the API Credentials page.

Private API Keys

Treat your Private API Keys like passwords!

The API key allows access to your site's data. Do not include it in Javascript code exposed to browsers.

Recurly supports the use of multiple Private API keys, which can be used to integrate third party services using unique, controlled credentials.

Limits & Pricing

Merchants on the Core or grandfathered Recurly plans or merchants in sandbox mode will be granted 5 private API keys. Merchants on Recurly’s Professional plan will be granted 10 private API keys.

Default Key

Your default private API key should be used to integrate Recurly with your backend systems. There will be at least one key active at all times.

Additional Keys

Additional private API keys should be used to connect your Recurly data to additional sources, like analytics software, accounting packages, or email tools. Recurly recommends clearly labeling the name of each key to identify the associated vendor.

Regenerating Private API Keys

Your API key can be regenerated by clicking on the Regenerate button on the API credentials page. When you generate a private API key, you have two options:

Block the old key immediately. This is primarily recommended when the security of a key has been compromised.

Allow the old key access for 12 hours. This is primarily used when updating systems and a smooth transition between keys is needed.

If a private API key is changed, an email alert will be sent to your Recurly Site Technical Contact.

Read-Only Keys

When creating a private key, you will have the option to set the key to “read-only”. This means the API key may make GET requests but cannot not PUT, POST or DELETE requests.

{"_id":"5919d94085b2570f00e41cb9","user":"559d85d26b21311700fb0b7b","body":"Recurly strives to provide developers with stable APIs to integrate against while still being able to provide new and expanded functionality. To balance these two goals we provide different API versions and only add new features to the latest version of the API. This allows you to choose the best time to update your integration and take advantage of new features.\n\nRecurly offers the following API versions: [2.6](https://dev.recurly.com/v2.6/docs), [2.5](https://dev.recurly.com/v2.5/docs), [2.4](https://dev.recurly.com/v2.4/docs), [2.3](https://dev.recurly.com/v2.3/docs), [2.2](https://dev.recurly.com/v2.2/docs), [2.1](https://dev.recurly.com/v2.1/docs), [2.0](https://dev.recurly.com/v2.0/docs).\n\n## Requesting A Version\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"API Version Deprecation\",\n \"body\": \"As a matter of policy, API versions will remain supported by Recurly for 2 years after they are released. After this time period, the API versions will be deprecated and no longer supported, but will still function.\\n\\nAPI versions 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, and 2.6 will be deprecated on May 1, 2019. Once deprecated, Recurly will no longer support these versions and any associated client libraries, but calls to these versions will function normally. You should expect that updates may include changes to product usability and integrations, so we recommend starting the update process as soon as possible.\\n\\nAPI versions 2.0-2.6 will reach their end of life on November 1, 2019. On and after this date, these API versions will no longer function.\\n\\nWe will be happy to assist you in upgrading to the current API version. Please reach out to us at [email protected] if you have any questions with this documentation.\"\n}\n[/block]\n\nWhen making requests to Recurly, your request should specify the desired API version using the `X-Api-Version` header:\n```\nX-Api-Version: 2.6\n```\nFor backwards compatibility, if no version is specified the default is 2.0.\n\n## Deprecation\n\nTo signal that an API version is deprecated and will be removed in the future, Recurly will respond the following headers:\n```\nRecurly-Deprecated: TRUE\nRecurly-Sunset-Date: 2018-06-01T00:00:00+00:00\n```\nThe sunset date is an ISO 8601 date time when the version will no longer be accessible.\n\nYour integration should check for those headers so you can make updates in a timely fashion.\n\n## Changes in v2.6\n\nRoute changes:\n\nRequest and Response Changes:\n\n- Changed Plan request/response:\n - Added `<trial_requires_billing_info>` element.\n- Changed Subscription response:\n - Added `<no_billing_info_reason>` element.\n- Added `POST /v2/purchases`\n- Added `POST /v2/purchases/preview`\n- Changed Subscription behavior\n - For `POST /v2/subscriptions`\n Sending NULL for `total_billing_cycles` attribute\n will now override plan `total_billing_cycles` setting\n and will make subscription renew forever. Omitting\n the attribute will cause the setting to default to\n the value of plan `total_billing_cycles`\n\nA complete list of changes for all versions is available on the [API Release Notes](https://dev.recurly.com/page/api-release-notes) page.","category":"5919d93885b2570f00e41c3a","hidden":false,"slug":"versioning","type":"basic","api":{"params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","apiSetting":null},"excerpt":"","githubsync":"","link_external":false,"parentDoc":null,"sync_unique":"","title":"API Versioning","next":{"pages":[],"description":""},"order":1,"project":"555fbba928249c1900618a82","__v":0,"createdAt":"2016-07-18T22:26:12.882Z","isReference":false,"link_url":"","updates":[],"version":"5919d93785b2570f00e41c39","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

API Versioning

Recurly strives to provide developers with stable APIs to integrate against while still being able to provide new and expanded functionality. To balance these two goals we provide different API versions and only add new features to the latest version of the API. This allows you to choose the best time to update your integration and take advantage of new features.

Requesting A Version

API Version Deprecation

As a matter of policy, API versions will remain supported by Recurly for 2 years after they are released. After this time period, the API versions will be deprecated and no longer supported, but will still function.

API versions 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, and 2.6 will be deprecated on May 1, 2019. Once deprecated, Recurly will no longer support these versions and any associated client libraries, but calls to these versions will function normally. You should expect that updates may include changes to product usability and integrations, so we recommend starting the update process as soon as possible.

API versions 2.0-2.6 will reach their end of life on November 1, 2019. On and after this date, these API versions will no longer function.

We will be happy to assist you in upgrading to the current API version. Please reach out to us at [email protected] if you have any questions with this documentation.

When making requests to Recurly, your request should specify the desired API version using the X-Api-Version header:

X-Api-Version: 2.6

For backwards compatibility, if no version is specified the default is 2.0.

Deprecation

To signal that an API version is deprecated and will be removed in the future, Recurly will respond the following headers:

{"_id":"5919d94085b2570f00e41cba","version":"5919d93785b2570f00e41c39","__v":0,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","auth":"required","params":[],"url":"","apiSetting":null},"isReference":false,"order":2,"updates":[],"type":"basic","excerpt":"","githubsync":"","next":{"pages":[],"description":""},"parentDoc":null,"project":"555fbba928249c1900618a82","category":"5919d93885b2570f00e41c3a","slug":"pagination","sync_unique":"","title":"Pagination","link_url":"","user":"55648cf93b87582b003ab8b1","body":"[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Number of Records\"\n}\n[/block]\nEndpoints that return a list of resources will include a header indicating the total number of records available. This is specified with the `X-Records` header. E.g., for an endpoint with 14 records:\n\n```\nX-Records: 14\n```\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Next Link\"\n}\n[/block]\nThe amount of records returns within a single API request defaults to 50. It may be changed to a maximum of 200 using a `per_page` query parameter, e.g. to return 200 accounts at a time:\n\n```\nhttps://your-subdomain.recurly.com/v2/accounts?per_page=200\n```\n\nWhen there are more records remaining than fit in the current response, the `Link` header is specified with the URI to the next page of results.\n\n```\nStatus: 200 OK \nX-Records: 204 \nLink: <https://your-subdomain.recurly.com/v2/accounts?cursor=1972702718353176814%3A1465932489>; rel=\"next\" \nETag: \"a4b0568a2278bc591ceb64b31547eb78\" \n```\n\nThe `cursor` parameter is a time-based pointer indicating where to resume the results. By using a cursor instead of page numbers, the API avoids returning duplicate records in the case where additional resources are added between pagination requests.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Sorting and Filtering\"\n}\n[/block]\n Many endpoints support these advanced pagination parameters:\n\n* `sort` : String: The attribute that will be used to order records: `created_at`, `updated_at`. Defaults to `created_at`.\n* `order` : String : The order in which products will be returned: `asc` for ascending order, `desc` for descending order. Defaults to `desc`.\n* `begin_time` : Datetime : Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.\n* `end_time` : Datetime : Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.\n\nReview the parameters on each endpoint for more details.\n[block:callout]\n{\n \"type\": \"info\",\n \"body\": \"An account that was updated on `2016-01-19` and then again on `2016-03-23` would not be returned in a request for `sort=updated_at&end_time=2016-03-01`.\",\n \"title\": \"Updated at really means last updated at\"\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Examples\"\n}\n[/block]\nThis will return accounts that were created on or before 2016-01-01 0:00 UTC in descending order of creation date:\n```\nhttps://your-subdomain.recurly.com/v2/accounts?sort=created_at&order=desc&end_time=2016-01-01\n```\n\nThis will return accounts that were last updated on or after 2016-07-01 10:30:01 Mountain Daylight Time in ascending order of updated date:\n\n```\nhttps://your-subdomain.recurly.com/v2/accounts?sort=updated_at&order=asc&begin_time=2016-07-01T10:30:01-06:00\n```\n[block:callout]\n{\n \"type\": \"warning\",\n \"body\": \"It's important to be aware that when paging through records sorted by their `updated_at` value, the order will change if they are modified:\\n* In ascending order, changes to records in previous pages will cause them to move back the end of the list, meaning you may see them multiple times. This can be avoided by using the time the pagination starts as the `end_time`.\\n* In descending order, changes to records in later pages will cause them to move up to the beginning of the list, meaning you would miss results.\",\n \"title\": \"Beware of changes to records when sorting by updated_at\"\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"<?php\\n// When accessing a sub resource with a many-to-one relation\\n// to the parent model, the attribute returns a Recurly_Stub.\\n// For example, take Account -> Invoices\\n\\n$account = Recurly_Account::get('my_account_code');\\n\\n// Calling ->invoices returns a Stub which allows lazily loading the list\\n$invoices = $account->invoices;\\n\\nprint $invoices;\\n// => <Recurly_Stub[invoices] href=https://api.recurly.com/v2/accounts/my_account_code/invoices>\\n\\n/**\\n * Prior to 2.5.0 calling ->get() would only return the first page\\n * of results. With 2.5.0 and later, all results will be returned.\\n */\\nforeach ($invoices->get() as $inv) {\\n print $inv->invoice_number . \\\"\\\\n\\\";\\n}\\n\\n/**\\n * Creating a List object directly will also allow you to iterate\\n * through all pages\\n */\\n$invoices = Recurly_InvoiceList::getForAccount('my_account_code');\\n\\n// Prints all invoices on the account\\nforeach ($invoices as $inv) {\\n print $inv->invoice_number . \\\"\\\\n\\\";\\n}\\n\",\n \"language\": \"php\",\n \"gist\": \"44632c432dce4f56a0fa\"\n },\n {\n \"code\": \"# When accessing a sub resource with a many-to-one relation \\n# to the parent model, the attribute returns a Recurly::Resource::Pager. \\n# For example, take Account -> Invoices\\n\\naccount = Recurly::Account.find('my_account_code')\\n\\nputs account.invoices.class\\n#=> Recurly::Resource::Pager\\n\\n# Pager#each can be used to iterate through the only the given page\\naccount.invoices.each do |invoice|\\n puts invoice.invoice_number\\nend\\n\\n# The default page size is 50 items, if you wish to page through more\\n# you can use Pager#find_each, find_each continues to fetch pages until\\n# there are none left\\naccount.invoices.find_each do |invoice|\\n puts invoice.invoice_number\\nend\\n\\n# You can also create a Pager directly from a resource\\nputs Recurly::Invoice.paginate.class\\n#=> Recurly::Resource::Pager\\n\\n# paginate takes options\\nRecurly::Invoice.paginate(per_page: 10).each do |invoice|\\n puts invoice.invoice_number\\nend\\n\\n# You can also use #find_each directly on the resource\\nRecurly::Invoice.find_each(per_page: 10).each do |invoice|\\n puts invoice.invoice_number\\nend\\n\",\n \"language\": \"ruby\"\n },\n {\n \"code\": \"# When accessing a sub resource with a many-to-one relation\\n# to the parent model, the attribute returns a `relatiator` function.\\n# When called it returns a recurly.resource.Page.\\n# For example, take Account -> Invoices\\n\\naccount = recurly.Account.get('tester')\\n\\nprint account.invoices\\n# => <function relatitator at 0x1023628c0>\\n\\nprint account.invoices().__class__\\n# => <class 'recurly.resource.Page'>\\n\\n# To page through every invoice on the account\\nfor invoice in account.invoices():\\n print invoice.invoice_number\\n\\n# You can also call the all() method on\\n# a resource to page through every resource\\n# on your site. For instance, to page through\\n# every invoice:\\nfor invoice in recurly.Invoice.all():\\n print invoice.invoice_number\",\n \"language\": \"python\",\n \"name\": null\n },\n {\n \"code\": \"using System.Linq;\\n\\nvar accounts = Accounts.List();\\nwhile (accounts.Any())\\n{\\n foreach (var account in accounts)\\n Console.WriteLine(account);\\n accounts = accounts.Next;\\n}\",\n \"language\": \"csharp\"\n }\n ]\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"body\": \"The PHP `Recurly_Pager` class sets up an iterator across all the relevant records. It does not provide pagination functionality by default.\",\n \"title\": \"PHP Pagination\"\n}\n[/block]","createdAt":"2015-06-15T22:48:39.567Z","hidden":false,"link_external":false,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Pagination

Number of Records

Endpoints that return a list of resources will include a header indicating the total number of records available. This is specified with the X-Records header. E.g., for an endpoint with 14 records:

X-Records: 14

Next Link

The amount of records returns within a single API request defaults to 50. It may be changed to a maximum of 200 using a per_page query parameter, e.g. to return 200 accounts at a time:

https://your-subdomain.recurly.com/v2/accounts?per_page=200

When there are more records remaining than fit in the current response, the Link header is specified with the URI to the next page of results.

The cursor parameter is a time-based pointer indicating where to resume the results. By using a cursor instead of page numbers, the API avoids returning duplicate records in the case where additional resources are added between pagination requests.

Sorting and Filtering

Many endpoints support these advanced pagination parameters:

sort : String: The attribute that will be used to order records: created_at, updated_at. Defaults to created_at.

order : String : The order in which products will be returned: asc for ascending order, desc for descending order. Defaults to desc.

begin_time : Datetime : Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

end_time : Datetime : Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

Review the parameters on each endpoint for more details.

Updated at really means last updated at

An account that was updated on 2016-01-19 and then again on 2016-03-23 would not be returned in a request for sort=updated_at&end_time=2016-03-01.

Examples

This will return accounts that were created on or before 2016-01-01 0:00 UTC in descending order of creation date:

Beware of changes to records when sorting by updated_at

It's important to be aware that when paging through records sorted by their updated_at value, the order will change if they are modified:

In ascending order, changes to records in previous pages will cause them to move back the end of the list, meaning you may see them multiple times. This can be avoided by using the time the pagination starts as the end_time.

In descending order, changes to records in later pages will cause them to move up to the beginning of the list, meaning you would miss results.

<?php// When accessing a sub resource with a many-to-one relation// to the parent model, the attribute returns a Recurly_Stub.// For example, take Account -> Invoices$account=Recurly_Account::get('my_account_code');
// Calling ->invoices returns a Stub which allows lazily loading the list$invoices=$account->invoices;
print$invoices;
// => <Recurly_Stub[invoices] href=https://api.recurly.com/v2/accounts/my_account_code/invoices>/*** Prior to 2.5.0 calling ->get() would only return the first page* of results. With 2.5.0 and later, all results will be returned.*/foreach ($invoices->get() as$inv) {
print$inv->invoice_number . "\n";
}
/*** Creating a List object directly will also allow you to iterate* through all pages*/$invoices=Recurly_InvoiceList::getForAccount('my_account_code');
// Prints all invoices on the accountforeach ($invoicesas$inv) {
print$inv->invoice_number . "\n";
}

# When accessing a sub resource with a many-to-one relation # to the parent model, the attribute returns a Recurly::Resource::Pager. # For example, take Account -> Invoicesaccount=Recurly::Account.find('my_account_code')
putsaccount.invoices.class#=> Recurly::Resource::Pager# Pager#each can be used to iterate through the only the given pageaccount.invoices.eachdo |invoice|
putsinvoice.invoice_numberend# The default page size is 50 items, if you wish to page through more# you can use Pager#find_each, find_each continues to fetch pages until# there are none leftaccount.invoices.find_eachdo |invoice|
putsinvoice.invoice_numberend# You can also create a Pager directly from a resourceputsRecurly::Invoice.paginate.class#=> Recurly::Resource::Pager# paginate takes optionsRecurly::Invoice.paginate(per_page:10).eachdo |invoice|
putsinvoice.invoice_numberend# You can also use #find_each directly on the resourceRecurly::Invoice.find_each(per_page:10).eachdo |invoice|
putsinvoice.invoice_numberend

# When accessing a sub resource with a many-to-one relation# to the parent model, the attribute returns a `relatiator` function.# When called it returns a recurly.resource.Page.# For example, take Account -> Invoicesaccount=recurly.Account.get('tester')
printaccount.invoices# => <function relatitator at 0x1023628c0>printaccount.invoices().__class__# => <class 'recurly.resource.Page'># To page through every invoice on the accountforinvoiceinaccount.invoices():
printinvoice.invoice_number# You can also call the all() method on# a resource to page through every resource# on your site. For instance, to page through# every invoice:forinvoiceinrecurly.Invoice.all():
printinvoice.invoice_number

PHP Pagination

{"_id":"5919d94085b2570f00e41cbb","githubsync":"","isReference":false,"link_url":"","title":"Rate Limits","version":"5919d93785b2570f00e41c39","updates":[],"body":"In order to provide a fast response time to all our customers, we may rate limit excessive requests. By default, new Recurly sites have the following API rate limits:\n\n* Sandbox sites: 400 requests/min. All requests count towards the rate limit.\n* Production sites: 1,000 requests/min. Only GET and HEAD requests count towards the rate limit.\n\nOnce your site moves into production mode, Recurly will only rate limit GET and HEAD requests. New subscriptions, account modifications, and other requests using POST, PUT, or DELETE methods will not count against your rate limit.\n\nThe rate limit is calculated over a sliding 5 minute window. This means a production site could make 4,000 requests within one minute and not hit the rate limit so long as the site made less than 1,000 requests during the prior 4 minutes.\n\nWhen your site reaches its rate limit, your site technical contact will receive an email alerting them of the issue. This email will be sent not more than once every three hours. Our support team will also be notified. Please reach out to Recurly support if you need assistance in resolving this issue.\n\nIf an API request exceeds the rate limit, the API returns a 429 status code indicating `Too Many Requests`. If your business needs a higher limit, please contact support.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"HTTP Headers\"\n}\n[/block]\nEvery authenticated API request returns headers with your current rate limit information. Your requests’ rate limit headers may look like:\n\n```\nX-RateLimit-Limit: 5000\nX-RateLimit-Remaining: 4999\nX-RateLimit-Reset: 1414622019\n```\n\nThe `X-RateLimit-Limit` is your total request limit during the 5 minute window (e.g. requests/min * 5 min). The `X-RateLimit-Remaining` indicates the number of requests remaining until your requests will be denied. Finally, the `X-RateLimit-Reset` header contains a timestamp for when the current window will completely reset assuming no further API requests are made.","category":"5919d93885b2570f00e41c3a","excerpt":"","link_external":false,"order":3,"type":"basic","createdAt":"2015-06-15T22:49:59.038Z","parentDoc":null,"project":"555fbba928249c1900618a82","sync_unique":"","user":"55648cf93b87582b003ab8b1","__v":0,"api":{"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"apiSetting":null},"hidden":false,"next":{"pages":[],"description":""},"slug":"rate-limits","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Rate Limits

In order to provide a fast response time to all our customers, we may rate limit excessive requests. By default, new Recurly sites have the following API rate limits:

Production sites: 1,000 requests/min. Only GET and HEAD requests count towards the rate limit.

Once your site moves into production mode, Recurly will only rate limit GET and HEAD requests. New subscriptions, account modifications, and other requests using POST, PUT, or DELETE methods will not count against your rate limit.

The rate limit is calculated over a sliding 5 minute window. This means a production site could make 4,000 requests within one minute and not hit the rate limit so long as the site made less than 1,000 requests during the prior 4 minutes.

When your site reaches its rate limit, your site technical contact will receive an email alerting them of the issue. This email will be sent not more than once every three hours. Our support team will also be notified. Please reach out to Recurly support if you need assistance in resolving this issue.

If an API request exceeds the rate limit, the API returns a 429 status code indicating Too Many Requests. If your business needs a higher limit, please contact support.

The X-RateLimit-Limit is your total request limit during the 5 minute window (e.g. requests/min * 5 min). The X-RateLimit-Remaining indicates the number of requests remaining until your requests will be denied. Finally, the X-RateLimit-Reset header contains a timestamp for when the current window will completely reset assuming no further API requests are made.

{"_id":"5919d94085b2570f00e41cbc","parentDoc":null,"type":"basic","updates":["56cd46e949abf10b0036a1e6"],"createdAt":"2015-06-10T22:06:26.211Z","hidden":false,"link_external":false,"order":4,"__v":0,"slug":"welcome","sync_unique":"","user":"5564a0073a61a72f0067cb22","link_url":"","project":"555fbba928249c1900618a82","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":"","apiSetting":null},"excerpt":"Every request includes an HTTP status code with the result. The status code should examined before the response. In most error cases, the response body will contain an errors XML document with more details.","githubsync":"","isReference":false,"title":"HTTP Status Codes","version":"5919d93785b2570f00e41c39","body":"## SUCCESSFUL STATUS CODES (2XX)\n`200 OK`\nThe request was successful.\n`201 Created`\nThe resource was successfully created. Confirms a success when creating a new account, credit, subscription, etc.\n`204 No Content`\nThe request was successful and there is no response body.\n\n## CLIENT ERROR STATUS CODES (4XX)\n`400 Bad Request`\nThe request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error. This commonly occurs when your XML is invalid, e.g. ampersands are not correctly encoded in the text of your request. Please inspect the body of the response for more details regarding the error.\n`401 Unauthorized`\nYour API key is missing or invalid.\n`402 Payment Required`\nYour Recurly account is in production mode but is not in good standing. Please pay any outstanding invoices.\n`403 Forbidden`\nThe login is attempting to perform an action it does not have privileges to access. Verify your login credentials are for the appropriate account.\n`404 Not Found`\nThe resource was not found with the given identifier. The response body will explain which resource was not found.\n`405 Method Not Allowed`\nThe requested method is not valid at the given URL.\n`406 Not Acceptable`\nThe request's Accept header is not set to application/xml.\n`412 Precondition Failed`\nThe request was unsuccessful because a condition was not met. For example, this message may be returned if you attempt to cancel a subscription for an account that has no subscription.\n`422 Unprocessable Entity`\nCould not process a POST or PUT request because the request is invalid. See the response body for more details.\n`429 Too many Requests`\nYou have made too many API requests in the last hour. Future API requests will be ignored until the beginning of the next hour.\n\n## SERVER ERROR STATUS CODES (5XX)\n`500 Internal Server Error`\nThe server encountered an error while processing your request and failed.\n`502 Gateway Error`\nThe load balancer or web server has trouble connecting to the Recurly app. Please try the request again.\n`503 Service Unavailable`\nThe service is temporarily unavailable. Please try the request again.\n\n##FUTURE COMPATIBILITY\nFor future compatibility, please interpret the following status code ranges:\n\n**200–299** as success,\n**400–499** as client request errors,\n**500–599** as server errors\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"404 Not Found Responses\"\n}\n[/block]\nWhen a lookup, update, or delete request is requested on an object that does not exist, the server returns `404 Not Found`:\n\n```\nStatus: 404 Not Found\nContent-Type: application/xml; charset=utf-8\n```\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n <symbol>not_found</symbol>\n <description>The record could not be located.</description>\n</error>\n```\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"422 Unprocessable Entity Responses\"\n}\n[/block]\nIf the requested create, update, or delete cannot be performed due to validation errors, the server returns a `422 Unprocessable Entity` response with an array of the validation errors:\n\n```\nStatus: 422 Unprocessable Entity\nContent-Type: application/xml; charset=utf-8\n```\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<errors>\n <error field=\"model_name.field_name\" symbol=\"not_a_number\" lang=\"en-US\">is not a number</error>\n</errors>\n```","category":"5919d93885b2570f00e41c3a","next":{"description":"","pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

HTTP Status Codes

Every request includes an HTTP status code with the result. The status code should examined before the response. In most error cases, the response body will contain an errors XML document with more details.

SUCCESSFUL STATUS CODES (2XX)

200 OKThe request was successful.201 CreatedThe resource was successfully created. Confirms a success when creating a new account, credit, subscription, etc.204 No ContentThe request was successful and there is no response body.

CLIENT ERROR STATUS CODES (4XX)

400 Bad RequestThe request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error. This commonly occurs when your XML is invalid, e.g. ampersands are not correctly encoded in the text of your request. Please inspect the body of the response for more details regarding the error.401 UnauthorizedYour API key is missing or invalid.402 Payment RequiredYour Recurly account is in production mode but is not in good standing. Please pay any outstanding invoices.403 ForbiddenThe login is attempting to perform an action it does not have privileges to access. Verify your login credentials are for the appropriate account.404 Not FoundThe resource was not found with the given identifier. The response body will explain which resource was not found.405 Method Not AllowedThe requested method is not valid at the given URL.406 Not AcceptableThe request's Accept header is not set to application/xml.412 Precondition FailedThe request was unsuccessful because a condition was not met. For example, this message may be returned if you attempt to cancel a subscription for an account that has no subscription.422 Unprocessable EntityCould not process a POST or PUT request because the request is invalid. See the response body for more details.429 Too many RequestsYou have made too many API requests in the last hour. Future API requests will be ignored until the beginning of the next hour.

{"_id":"5919d93b85b2570f00e41c75","createdAt":"2015-06-26T18:21:30.595Z","githubsync":"","isReference":false,"link_url":"","parentDoc":null,"version":"5919d93785b2570f00e41c39","__v":0,"api":{"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"apiSetting":null},"order":0,"title":"Integrations","user":"55648cf93b87582b003ab8b1","category":"5919d93885b2570f00e41c3b","sync_unique":"","type":"basic","body":"Recurly has a variety of integrations you should check out!\n\n[Webhooks API](https://dev.recurly.com/page/webhooks)\n\n[Customer Imports](https://dev.recurly.com/page/customer-imports)","slug":"integrations","link_external":false,"next":{"pages":[],"description":""},"project":"555fbba928249c1900618a82","updates":[],"excerpt":"","hidden":false,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Integrations

{"_id":"5919d94085b2570f00e41cae","isReference":false,"order":0,"updates":["55940e20fd29b92300c262bf","55b2bfc0a74a380d00e290a6","55b2c0466862a10d00887adf","55bbb926a8400c2d00873f2a","565f689e413e06170093df6a","58d2b9a19c99c92f00646f8e"],"version":"5919d93785b2570f00e41c39","type":"basic","user":"55648cf93b87582b003ab8b1","__v":0,"link_url":"","next":{"pages":[],"description":""},"slug":"client-libraries","sync_unique":"","link_external":false,"project":"555fbba928249c1900618a82","title":"Client Libraries","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","auth":"required","params":[],"url":"","apiSetting":null},"body":"Recurly has a variety of official client libraries you should check out!\n\n[PHP](https://dev.recurly.com/page/php)\n[Ruby](https://dev.recurly.com/page/ruby)\n[Python](https://dev.recurly.com/page/python)\n[.Net](https://dev.recurly.com/page/net)\niOS – [Github](https://github.com/recurly/recurly-client-ios) | [Documentation](http://cocoadocs.org/docsets/RecurlySDK/)\n[Android](https://github.com/recurly/recurly-client-android)\n\nThere are also some unofficial libraries created by our users\n\n[Java](https://github.com/killbilling/recurly-java-library)\n[GO](https://github.com/cgerrior/gorecurly)\n[Node.js](https://github.com/cgerrior/node-recurly)","createdAt":"2015-06-26T18:25:56.960Z","excerpt":"","hidden":false,"category":"5919d93885b2570f00e41c3c","githubsync":"","parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Client Libraries

Recurly has a variety of official client libraries you should check out!

{"_id":"5919d93985b2570f00e41c59","githubsync":"","order":1,"parentDoc":null,"type":"basic","updates":["570eb5f23160d10e0041df28"],"version":"5919d93785b2570f00e41c39","api":{"settings":"","auth":"required","params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"apiSetting":null},"category":"5919d93885b2570f00e41c3d","isReference":false,"link_external":false,"sync_unique":"","title":"How it Works","hidden":false,"link_url":"","project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","__v":0,"body":"When a customer submits your payment form, Recurly.js sends customer payment information to be encrypted and stored at Recurly and gives you an authorization key to complete the subscription process using our API.\n\nWith this authorization key (or *token*), you can do anything with our API that requires payment information. Because you never handle any sensitive payment information, your PCI scope is drastically reduced.","createdAt":"2016-03-01T03:19:34.724Z","excerpt":"","next":{"pages":[],"description":""},"slug":"how-it-works","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

How it Works

When a customer submits your payment form, Recurly.js sends customer payment information to be encrypted and stored at Recurly and gives you an authorization key to complete the subscription process using our API.

With this authorization key (or token), you can do anything with our API that requires payment information. Because you never handle any sensitive payment information, your PCI scope is drastically reduced.

Configure

Simply call recurly.configure anywhere on your page, passing your public key. This identifies your site to Recurly servers. You can find your public key in the API Access section of your admin app.

Be sure to replace sc-ABCDEFGHI123456789 with your own public key.

recurly.configure accepts other options not detailed here. You may refer to the source for more detail.

Build a Card form

Build a form however you like. Use the data-recurly attribute to identify input field targets to Recurly.js. To identify where Recurly.js will inject card data fields, we recommend using simple div elements.

To collect card payment information from your customers, you'll create a form similar to this one. Recurly.js uses the data-recurly attributes on the input tags to gather customer information before sending it to our servers.

In order for recurly.js to inject the card payment hosted fields into your form, the target elements must be present in the document at the time you make the recurly.configure call.

Note that card data is not present in the form, but merely given a placeholder element. This is because Recurly.js must inject those fields onto the page within iframes to ensure strict security of customer card data. To further customize your checkout experience, you will be able to pick and use any color for the placeholder text.

This particular form contains the minimum required input fields, and the table below demonstrates all possible input fields.

Since Recurly.js must inject card data fields into iframes, the default browser appearance for those fields will likely not match the appearance of the other fields in your payment form. We provide the following CSS classes to achieve a look and feel similar to your form. Using these classes, you may specify field size, colors, and a full range of appearance customization to make the injected card fields blend into your payment form.

Class Name

Description

recurly-hosted-field

Default styles for the div surrounding each field iframe.

recurly-hosted-field-focus

Applied when the user focuses on a field.

recurly-hosted-field-number

Default styles for the div surrounding the month field iframe.

recurly-hosted-field-month

Default styles for the div surrounding the month field iframe.

recurly-hosted-field-year

Default styles for the div surrounding the year field iframe.

Fonts

You may specify font and placeholder text for card fields through recurly.configure. The example call to the right demonstrates all available style attributes you may send to recurly.configure.

Custom fonts are sourced from Google Web Fonts. Simply use the name of the font as it appears on the Google Web Fonts site.

Responsive styles

All of the built in field classes will support and respond to media queries. You may call recurly.configure again to change style properties -- thus you may change any property if the window size changes.

Working with bank accounts

Just like a card form, use the data-recurly attribute to identify fields to Recurly.js. Since Recurly.js does not need to inject fields for bank accounts, all fields may be displayed as inputs on your payment form.

As you would a card form, you collect bank account payment information from your customers, identifying them with the data-recurly attributes on the input tags. This form demonstrates the minimum required input fields, and the table below highlights all possible input fields.

Getting a Token

$('form').on('submit', function (event) {
varform=this;
event.preventDefault();
recurly.token(form, function (err, token) {
if (err) {
// handle error using err.code and err.fields
} else {
// recurly.js has filled in the 'token' field, so now we can submit the// form to your server; alternatively, you can access token.id and do// any processing you wishform.submit();
}
});
});

Recurly.js works with tokens, which represent secure and temporary storage for your customer's sensitive billing information. They are stored directly on Recurly servers to reduce your PCI exposure.

When your customers submit your billing form, you'll need to interrupt the submit and ask Recurly.js to create a token from the form. You may have noticed an additional hidden field in the form above, token. When you ask Recurly.js for a token during submit, it will automatically populate this field for you. After you get the token, you will submit it to your servers and use it there to talk to any endpoint in our API that accepts a billing_info.

This example demonstrates jQuery as an event-binding and DOM library; however, you may use any library you choose, or interact directly with the DOM (hard mode).

Sends bank account billing information to Recurly to store as a token, sending that token id back to you. Just as with card tokenization, there are two ways to call recurly.bankAccount.token: with a form, and with an object.

The simplest is to pass it a form element containing form fields with their corresponding data-recurly attributes.

Arguments (form)

Param

Type

Description

form

HTMLFormElement

Parent form containing data-recurly fields.

callback

Function

Callback function to accept the returned token.

Alternatively, you can call recurly.bankAccount.token with a plain JavaScript object. This allows a more direct interface to the payment flow, eliminating any need to use the DOM.

Arguments (object)

Param

Type

Description

options

Object

An object with billing information properties matching those [outlined above].

Once Recurly.js has stored your customer's sensitive data and given you a token reference, you will have 20 minutes to use it in our API. Expired tokens are permanently removed from the Recurly servers.

Tokens expire after 20 minutes.

Tokens can be used to populate any account Billing Info data through our API. Simply assign it to the Billing Info's token_id property and we'll do the rest.

These endpoints accept tokens within Billing Info.

{"_id":"5919d93985b2570f00e41c5d","sync_unique":"","type":"basic","excerpt":"","hidden":false,"next":{"pages":[],"description":""},"__v":0,"category":"5919d93885b2570f00e41c3d","project":"555fbba928249c1900618a82","link_external":false,"order":5,"slug":"events","title":"Events","updates":["59095077651f500f001dd3f6"],"createdAt":"2016-03-01T18:53:08.841Z","githubsync":"","isReference":false,"user":"55648cf93b87582b003ab8b1","version":"5919d93785b2570f00e41c39","link_url":"","parentDoc":null,"api":{"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"apiSetting":null},"body":"Listen to events using Emitter methods\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"// Listen to the 'change' event\\nrecurly.on('change', changeHandler);\\n\\n// But we're feeling indecisive today. Let's detach this event\\nrecurly.off('change', changeHandler);\\n\\n// .once will listen for one event then detach itself\\nrecurly.once('field:submit', function () {\\n $('#my-payment-form').submit();\\n});\\n\\nfunction changeHandler (state) {\\n // state.fields\\n}\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\nExample RecurlyState object\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"var recurlyState = {\\n fields: {\\n number: {\\n valid: false,\\n firstSix: '',\\n lastFour: '',\\n brand: 'unknown',\\n empty: true,\\n length: 0,\\n focus: false\\n },\\n month: {\\n valid: false,\\n empty: true,\\n length: 0,\\n focus: false\\n },\\n year: {\\n // same as month\\n },\\n cvv: {\\n // same as month\\n }\\n }\\n}\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\nA `Recurly` instance is an event emitter, and will emit events throughout the lifecycle of your customer's interaction with your payment form. Events can be attached using the `recurly.on` method and removed using `recurly.off`. The example to the right shows the various ways that you can attach and remove events.\n\n### `change`\n\nThis event is emitted whenever a customer changes the state of hosted card fields, those that you may not otherwise observe directly with DOM events. For example, if your customer types '4' into the number field, then the state of the number field will change, and the `change` event will emit.\n\nThe `change` event emits a `RecurlyState` object, whose values are demonstrated to the right. This will give you useful insight into the entire state of the recurly-controlled components of your payment form.\n\n### `field:submit`\n\nThis event is emitted when a user presses the `enter` key while they are focused on a hosted field. Since this action typically submits a form, we recommend performing a payment form submission when this event is emitted.\n\nNote that you can detect the brand of the credit card entered using the \"brand\" field in the state object above.","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

A Recurly instance is an event emitter, and will emit events throughout the lifecycle of your customer's interaction with your payment form. Events can be attached using the recurly.on method and removed using recurly.off. The example to the right shows the various ways that you can attach and remove events.

change

This event is emitted whenever a customer changes the state of hosted card fields, those that you may not otherwise observe directly with DOM events. For example, if your customer types '4' into the number field, then the state of the number field will change, and the change event will emit.

The change event emits a RecurlyState object, whose values are demonstrated to the right. This will give you useful insight into the entire state of the recurly-controlled components of your payment form.

field:submit

This event is emitted when a user presses the enter key while they are focused on a hosted field. Since this action typically submits a form, we recommend performing a payment form submission when this event is emitted.

Note that you can detect the brand of the credit card entered using the "brand" field in the state object above.

{"_id":"5919d93985b2570f00e41c5e","isReference":false,"parentDoc":null,"project":"555fbba928249c1900618a82","slug":"paypal","sync_unique":"","body":"A PayPal transaction is handled entirely within the PayPal checkout flow in a new window. Your customer will authorize a transaction within PayPal. Recurly will then record the authorization and return a Recurly token to you as it does for other payment methods. You will need to use the token within our API before it expires, and expired tokens cannot be retrieved.\n\nFirst, place a button on your page specifically for checking out with PayPal.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"<button>Checkout with PayPal</button>\",\n \"language\": \"html\"\n }\n ]\n}\n[/block]\nNext, create a new `recurly.PayPal` instance.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"var paypal = recurly.PayPal({\\n display: { displayName: ' My product ' }\\n});\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\n**if you're processing PayPal transactions with Braintree**, you'll pass a [client authorization](https://developers.braintreepayments.com/guides/authorization/tokenization-key/javascript/v2#obtaining-a-tokenization-key) during instantiation:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"var paypal = recurly.PayPal({\\n braintree: { clientAuthorization: MY_CLIENT_AUTHORIZATION }\\n});\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\nYour instance must then be set up to handle error scenarios and start the checkout flow.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"paypal.on('error', function (err) {\\n // err.code\\n // err.message\\n // [err.cause] if there is an embedded error\\n});\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\nNext we must bind a listener to a user action on the button and have it trigger the `start` function on your `recurly.PayPal` instance. This will open the PayPal checkout flow.\n[block:callout]\n{\n \"type\": \"info\",\n \"body\": \"As with the rest of Recurly.js, there are no external dependencies. The example uses jQuery to demonstrate binding events, but this can be done any way you wish.\"\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"$('#paypal-button').on('click', function () {\\n paypal.start();\\n});\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"body\": \"the `start` function must be called within a user-initiated event like 'click' or 'touchend'\"\n}\n[/block]\nFinally, add a function to receive the token once your customer completes the checkout flow. At this point you will send the token id to your server to be used in the Recurly API to create a billing info for an account.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"paypal.on('token', function (token) {\\n // token.id\\n});\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"fn\",\n \"title\": \"recurly.PayPal\"\n}\n[/block]\n### Arguments\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Param\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\",\n \"0-0\": \"options\",\n \"0-1\": \"Object\",\n \"0-2\": \"Optional.\",\n \"1-0\": \"options.braintree\",\n \"1-1\": \"Object\",\n \"1-2\": \"Optional. Braintree configuration.\",\n \"2-0\": \"options.braintree.clientAuthorization\",\n \"2-1\": \"String\",\n \"2-2\": \"If using Braintree to proces PayPal transactions, provide your client authorization code here.\"\n },\n \"cols\": 3,\n \"rows\": 3\n}\n[/block]\n### Returns\n\nA new `recurly.PayPal` instance\n[block:api-header]\n{\n \"type\": \"fn\",\n \"title\": \"paypal.start\"\n}\n[/block]\n### Arguments\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"options\",\n \"0-1\": \"Object\",\n \"0-2\": \"Optional\",\n \"1-0\": \"options.description\",\n \"1-1\": \"String\",\n \"1-2\": \"Optional. In legacy PayPal flows, this description will be displayed during the checkout flow.\",\n \"h-0\": \"Param\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 2\n}\n[/block]\n### Returns\n\nNothing.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Events\"\n}\n[/block]\n### `error`\n\nThis event is emitted when any error is encountered, whether during setup of the PayPal flow, or during the checkout process. It will be useful to display errors to your customer if a problem occurs during PayPal checkout.\n\n*Signature* \n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"error\",\n \"0-1\": \"RecurlyError\",\n \"0-2\": \"An error describing the issue that occurred\",\n \"h-0\": \"Param\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 1\n}\n[/block]\n### `cancel`\n\nThis event is emitted when the customer has canceled the PayPal checkout flow before completion. You may wish to reset parts of your checkout experience if this occurs.\n\n*Signature*\n\nNone.\n\n### `token`\n\nThis event is fired when the customer has completed the PayPal checkout flow. Recurly has received the payment details, and generated this token to be used in our API.\n\n### Signature\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"token\",\n \"0-1\": \"Object\",\n \"1-0\": \"token.id\",\n \"1-1\": \"String\",\n \"1-2\": \"Token identifier to be sent to the API\"\n },\n \"cols\": 3,\n \"rows\": 2\n}\n[/block]","createdAt":"2016-03-01T18:54:55.886Z","githubsync":"","link_external":false,"title":"PayPal","excerpt":"Use Recurly to process PayPal transactions using PayPal Business or Braintree.","hidden":false,"order":6,"type":"basic","updates":["59403323f84a32001ba5a47a"],"version":"5919d93785b2570f00e41c39","__v":1,"api":{"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"apiSetting":null},"category":"5919d93885b2570f00e41c3d","link_url":"","next":{"pages":[],"description":""},"user":"55648cf93b87582b003ab8b1","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

PayPal

Use Recurly to process PayPal transactions using PayPal Business or Braintree.

A PayPal transaction is handled entirely within the PayPal checkout flow in a new window. Your customer will authorize a transaction within PayPal. Recurly will then record the authorization and return a Recurly token to you as it does for other payment methods. You will need to use the token within our API before it expires, and expired tokens cannot be retrieved.

First, place a button on your page specifically for checking out with PayPal.

the start function must be called within a user-initiated event like 'click' or 'touchend'

Finally, add a function to receive the token once your customer completes the checkout flow. At this point you will send the token id to your server to be used in the Recurly API to create a billing info for an account.

Returns

fnpaypal.start

Arguments

Param

Type

Description

options

Object

Optional

options.description

String

Optional. In legacy PayPal flows, this description will be displayed during the checkout flow.

Returns

Nothing.

Events

error

This event is emitted when any error is encountered, whether during setup of the PayPal flow, or during the checkout process. It will be useful to display errors to your customer if a problem occurs during PayPal checkout.

Signature

Param

Type

Description

error

RecurlyError

An error describing the issue that occurred

cancel

This event is emitted when the customer has canceled the PayPal checkout flow before completion. You may wish to reset parts of your checkout experience if this occurs.

Signature

None.

token

This event is fired when the customer has completed the PayPal checkout flow. Recurly has received the payment details, and generated this token to be used in our API.

Pricing

Recurly automates complicated subscriptions, with many factors influencing total subscription price. With this in mind, Recurly.js provides a robust pricing module designed to make determining actual subscription costs as simple and flexible as possible.

A Recurly.js pricing module can be attached to the form we created above, or to any other section of your page meant to display subscription pricing. Let's get to the specifics!

This is the simplest way to use the pricing module. Simply pass a container element, and the pricing module with use all elements with a valid data-recurly attribute to determine price. When a value changes, the pricing module will automatically update its values. This allows your customers to manipulate a pricing form at will, and you will be able to react dynamically in any number of ways.

Arguments

Param

Type

Description

container

HTMLElement

Parent element containing all data-recurly elements

Returns

Nothing.

Elements

Elements bound to a pricing module may be for either input or output.

Input elements should be user-manipulable elements like input or select. If you want to input a value but not let a customer manipulate it, use an <input type="hidden">.

Input Elements

Field Name

Example Value

Description

plan

basic

Plan code.

plan_quantity

1

Play quantity. Defaults to 1 if not specified.

coupon

15_off

Coupon code.

addon

1

Addon quantity. To identify the addon being modified, use the data-recurly-addon attribute to set the addon code.

Output elements should be plain text elements like output, span, or div.

Output Elements

Field Name

Example Output

Description

total_now

100.00

Total subscription cost due now.

subtotal_now

90.00

Subtotal of the following pricing components.

addons_now

10.00

Total addon cost.

discount_now

5.00

Amount discounted with coupon use.

setup_fee_now

5.00

Subscription setup fee total.

tax_now

15.00

Total subscription taxation.

currency_code

USD, EUR

ISO-4217 currency code.

currency_symbol

$, €

Symbolic representation of currency_code.

gift_card_now

75.00

The gift card amount that will be applied to the purchase today.

gift_card_next

25.00

The remainder gift card amount that will be applied to the next renewal.

data-recurly values ending in _now like subtotal_now have counterparts ending in _next. As you might expect, these correspond to the next billing cycle cost. These values are especially useful for plans with trial periods.

Pricing instances emit events when various values are set or the price changes.

A Pricing instance itself behaves as an event emitter, where events can be attached using the pricing.on method and removed using pricing.off, similarly to how events are managed on recurly.

Change

This event is emitted whenever a pricing module has updated any of its pricing values. You can use this event to update your pricing display, compute total shopping costs, aggregate to analytics, etc.

Change emits a price object, shown in detail to the right.

set.*

set.* events are emitted when specific pricing objects change on a pricing module. For example, when a customer changes their plan, the pricing module will send set.plan. This is especially useful for updating checkout previews based on what the customer has selected as one example.

The pricing module can be manipulated with a set of direct method calls. This is useful if you would like to set up a complex pricing schema for your customers, or would just like to use a more programmatic method of determining subscription price. Events fire just as they normally would when using pricing.attach.

Note that Recurly.js's DOM binding is one-way. Thus if you use the Pricing API on a pricing instance already attached to a container, the elements within will not update with your Pricing API calls. If you would like two-way DOM binding, we suggest using a framework such as AngularJS and using the Pricing API without attaching it to a container.

The example to the right demonstrates all the ways that a pricing module can be manipulated directly.

PricingPromise

Each Pricing API method will return a PricingPromise. This allows you to chain many asynchronous calls together without having to manage a complex chain of callbacks.

You don't need to worry much about the internals of a PricingPromise, as it is designed to stay out of your way and facilitate asynchronous calls for you.

The catch method, as shown in the example, is used to handle error scenarios, such as when an addon cannot be applied to the selected plan.

At the end of a chain of pricing method calls, be sure to call .done() as this tells the pricing module to begin calculating, and gives you the subscription price.

Validation

Recurly.js bundles a few helpful methods for validating payment information prior to processing. These methods are used when generating tokens, but you can also use them to enhance your form validations and checkout flow.

Lookup data

Bank info data

{"_id":"5919d93985b2570f00e41c61","hidden":false,"parentDoc":null,"sync_unique":"","title":"Errors","updates":[],"api":{"params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","apiSetting":null},"category":"5919d93885b2570f00e41c3d","createdAt":"2016-03-01T19:19:09.515Z","user":"55648cf93b87582b003ab8b1","body":"Example RecurlyError object.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n name: 'validation',\\n code: 'validation',\\n message: 'There was an error validating your request.',\\n fields: [\\n 'number',\\n 'year'\\n ]\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nErrors are encapsulated by a `RecurlyError`, which contains a few standard properties to help you diagnose error cases and inform your customers accordingly.\n\nErrors will be thrown if the exception will prevent proper execution. If an error can be recovered, it will be passed to the proper error handling event listener, callback, or `PricingPromise` handler for you to inspect.\n\n### Best Practices\n\nThe `message` property contains diagnostic information intended to help you diagnose problems with the form, and we do not recommend displaying its contents to your customers.\n\nTo provide the best customer experience, we recommend that you provide your own error text to be displayed, based on the error code you receive.\n\n### Error Codes\n\n## Configuration\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Code\",\n \"h-1\": \"Description\",\n \"0-0\": \"not-configured\",\n \"1-0\": \"missing-public-key\",\n \"2-0\": \"invalid-public-key\",\n \"3-0\": \"already-configured\",\n \"4-0\": \"missing-hosted-field-target\",\n \"5-0\": \"\",\n \"0-1\": \"This error appears when you try to perform an operation without first calling [`recurly.configure`](#configure).\",\n \"2-1\": \"Check the `publicKey` to ensure it matches that of your admin app's [API Access section](https://app.recurly.com/go/developer/api_access).\",\n \"1-1\": \"When you call [`recurly.configure`](#configure), you must do so with a `publicKey` property.\",\n \"3-1\": \"A recurly instance may only be configured once. Doing so more than once is excessive.\",\n \"4-1\": \"This is thrown when the target element for a hosted payment field cannot be found on the page. Check the error message to check the selector being used, then check your page to ensure the element is present when `recurly.configure` is called.\",\n \"5-1\": \"\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]\n## Tokenization\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Code\",\n \"h-1\": \"Description\",\n \"0-0\": \"validation\",\n \"1-0\": \"invalid-parameter\",\n \"2-0\": \"api-error\",\n \"3-0\": \"\",\n \"1-1\": \"Occurs when a tokenization parameter does not pass our internal validations. Check the `fields` property to determine which fields caused the error.\",\n \"2-1\": \"A request to the Recurly API has encountered an issue. This too can indicate many possible issues, and we recommend inspecting the `message` and `fields` properties for more information.\",\n \"3-1\": \"\",\n \"0-1\": \"A request validation error has occurred. This can indicate many possible issues, and you should check the `fields` property to determine which fields caused the error.\"\n },\n \"cols\": 2,\n \"rows\": 3\n}\n[/block]\n## Pricing\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Code\",\n \"h-1\": \"Description\",\n \"0-0\": \"not-found\",\n \"1-0\": \"missing-plan\",\n \"2-0\": \"invalid-addon\",\n \"3-0\": \"invalid-currency\",\n \"5-0\": \"\",\n \"5-1\": \"\",\n \"3-1\": \"Similarly, if a currency is requested which is not valid for the selected plan.\",\n \"2-1\": \"Occurs when an addon is added to a [`Pricing`](#pricing) instance but is not valid for the instance's selected plan.\",\n \"1-1\": \"A [`Pricing`](#pricing) instance will emit this if a plan has not been specified before trying to set a proeprty that depends on a plan, such as a coupon or addon.\",\n \"0-1\": \"This happens when a nonexistent plan is requested.\",\n \"4-0\": \"gift-card-currency-mismatch\",\n \"4-1\": \"Occurs when a gift card is redeemed with a currency that doesn't match the instance's configured currency.\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]\n## PayPal\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"paypal-not-configured\",\n \"0-1\": \"In order to perform a PayPal transaction, your site must be configured to accept PayPal reference\",\n \"1-1\": \"The customer canceled the PayPal agreement flow.\",\n \"2-1\": \"A generic PayPal error has occurred. Inspect `message` to learn more.\",\n \"3-1\": \"The bank routing number is not valid\",\n \"3-0\": \"invalid-routing-number\",\n \"2-0\": \"paypal-error\",\n \"1-0\": \"paypal-canceled\",\n \"h-0\": \"Code\",\n \"h-1\": \"Description\"\n },\n \"cols\": 2,\n \"rows\": 4\n}\n[/block]","isReference":false,"link_url":"","order":9,"githubsync":"","excerpt":"","link_external":false,"next":{"description":"","pages":[]},"project":"555fbba928249c1900618a82","slug":"errors-1","type":"basic","__v":0,"version":"5919d93785b2570f00e41c39","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Errors

Errors are encapsulated by a RecurlyError, which contains a few standard properties to help you diagnose error cases and inform your customers accordingly.

Errors will be thrown if the exception will prevent proper execution. If an error can be recovered, it will be passed to the proper error handling event listener, callback, or PricingPromise handler for you to inspect.

Best Practices

The message property contains diagnostic information intended to help you diagnose problems with the form, and we do not recommend displaying its contents to your customers.

To provide the best customer experience, we recommend that you provide your own error text to be displayed, based on the error code you receive.

Error Codes

Configuration

Code

Description

not-configured

This error appears when you try to perform an operation without first calling recurly.configure.

A recurly instance may only be configured once. Doing so more than once is excessive.

missing-hosted-field-target

This is thrown when the target element for a hosted payment field cannot be found on the page. Check the error message to check the selector being used, then check your page to ensure the element is present when recurly.configure is called.

Tokenization

Code

Description

validation

A request validation error has occurred. This can indicate many possible issues, and you should check the fields property to determine which fields caused the error.

invalid-parameter

Occurs when a tokenization parameter does not pass our internal validations. Check the fields property to determine which fields caused the error.

api-error

A request to the Recurly API has encountered an issue. This too can indicate many possible issues, and we recommend inspecting the message and fields properties for more information.

Pricing

Code

Description

not-found

This happens when a nonexistent plan is requested.

missing-plan

A Pricing instance will emit this if a plan has not been specified before trying to set a proeprty that depends on a plan, such as a coupon or addon.

invalid-addon

Occurs when an addon is added to a Pricing instance but is not valid for the instance's selected plan.

invalid-currency

Similarly, if a currency is requested which is not valid for the selected plan.

gift-card-currency-mismatch

Occurs when a gift card is redeemed with a currency that doesn't match the instance's configured currency.

PayPal

Code

Description

paypal-not-configured

In order to perform a PayPal transaction, your site must be configured to accept PayPal reference

{"_id":"5919d93985b2570f00e41c62","createdAt":"2016-03-01T19:35:36.709Z","link_url":"","parentDoc":null,"sync_unique":"","updates":["582136261142c82700b03347"],"version":"5919d93785b2570f00e41c39","githubsync":"","project":"555fbba928249c1900618a82","slug":"examples","title":"Examples","type":"basic","user":"55648cf93b87582b003ab8b1","excerpt":"","hidden":false,"order":10,"__v":0,"api":{"params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","auth":"required","apiSetting":null},"body":"### Integration examples\n\nWe've prepared a full suite of example integrations for *Ruby*, *Node.js*, *Python*, and *PHP* using popular web frameworks for each language. These examples demonstrate the simplest method of integration, with a no-frills UI.\n\n[Code on GitHub](https://github.com/recurly/recurly-js-examples)","category":"5919d93885b2570f00e41c3d","isReference":false,"link_external":false,"next":{"pages":[],"description":""},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Examples

Integration examples

We've prepared a full suite of example integrations for Ruby, Node.js, Python, and PHP using popular web frameworks for each language. These examples demonstrate the simplest method of integration, with a no-frills UI.

{"_id":"5919d93985b2570f00e41c63","version":"5919d93785b2570f00e41c39","body":"Recurly.js supports Chrome, Firefox, Safari, iOS, and IE 10+.\n\nWe're also here to lend a hand on any Recurly.js integration questions! You can get help from us in a handful of ways:\n\n* Find us and other fellow developers in [#recurly](irc://chat.freenode.net:+6697/recurly) on freenode to chat in real-time.\n* Browse and post questions on [Stackoverflow](http://stackoverflow.com/questions/tagged/recurly). We check these regularly.\n* Take a look at the code on [GitHub](https://github.com/recurly/recurly-js). We welcome bug reports through Issues and contributions through Pull Requests.\n\nFor other Recurly related questions, please contact [[email protected]recurly.com](https://support.recurly.com) for help with your account or other general questions.\n\nFor copies of documentation for previous versions of Recurly.js, please contact support.","next":{"pages":[],"description":""},"order":11,"slug":"support","title":"Support","hidden":false,"parentDoc":null,"link_url":"","project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","api":{"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":"","apiSetting":null},"createdAt":"2016-03-01T19:37:11.437Z","excerpt":"","githubsync":"","link_external":false,"type":"basic","updates":[],"__v":0,"category":"5919d93885b2570f00e41c3d","isReference":false,"sync_unique":"","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Support

Recurly.js supports Chrome, Firefox, Safari, iOS, and IE 10+.

We're also here to lend a hand on any Recurly.js integration questions! You can get help from us in a handful of ways:

Find us and other fellow developers in #recurly on freenode to chat in real-time.

{"_id":"5919d93f85b2570f00e41c9f","link_external":false,"parentDoc":null,"title":"Account Object","type":"get","excerpt":"Accounts are core to managing your customers inside of Recurly. The account object stores the entire Recurly history of your customer and acts as the entry point for working with a customer's billing information, subscription data, transactions, invoices and more.","hidden":false,"order":0,"project":"555fbba928249c1900618a82","updates":["56cec52444c5700b0095c02b"],"user":"55648cf93b87582b003ab8b1","category":"5919d93885b2570f00e41c3e","createdAt":"2015-08-31T20:16:33.273Z","githubsync":"","isReference":true,"link_url":"","body":"","next":{"pages":[],"description":""},"slug":"account-object","sync_unique":"","version":"5919d93785b2570f00e41c39","__v":0,"api":{"examples":{"codes":[{"language":"text","code":""}]},"method":"get","results":{"codes":[{"status":200,"name":"","code":"<account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/1/adjustments\"/>\n <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n <redemptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemptions\"/>\n <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n <account_code>1</account_code>\n <state>active</state>\n <username>verena1234</username>\n <email>[email protected]</email>\n <cc_emails>[email protected],[email protected]</cc_emails>\n <first_name>Verena</first_name>\n <last_name>Example</last_name>\n <company_name>New Company Name</company_name>\n <vat_number nil=\"nil\"/>\n <tax_exempt type=\"boolean\">false</tax_exempt>\n <address>\n <address1>123 Main St.</address1>\n <address2 nil=\"nil\"/>\n <city>San Francisco</city>\n <state>CA</state>\n <zip>94105</zip>\n <country>US</country>\n <phone nil=\"nil\"/>\n </address>\n <accept_language nil=\"nil\"/>\n <has_live_subscription type=\"boolean\">true</has_live_subscription>\n <has_active_subscription type=\"boolean\">true</has_active_subscription>\n <has_future_subscription type=\"boolean\">false</has_future_subscription>\n <has_canceled_subscription type=\"boolean\">false</has_canceled_subscription>\n <has_past_due_invoice type=\"boolean\">false</has_past_due_invoice>\n <hosted_login_token>96e74bd5e14d18e6da463a0d638a2621</hosted_login_token>\n <created_at type=\"datetime\">2016-07-08T20:59:43Z</created_at>\n <updated_at type=\"datetime\">2016-07-11T17:56:24Z</updated_at>\n <closed_at nil=\"nil\"/>\n</account>","language":"xml"}]},"settings":"","auth":"required","params":[{"ref":"","in":"body","required":false,"desc":"The URL of adjustments for the specified account.","default":"","type":"string","name":"adjustments","_id":"557f45d07eafa719001d1c2b"},{"in":"body","required":false,"desc":"The URL of the account balance for the specified account.","default":"","type":"string","name":"account_balance","_id":"57a21cf65220910e002a1764","ref":""},{"required":false,"desc":"The URL of billing info for the specified account.","default":"","type":"string","name":"billing_info","_id":"557f45d07eafa719001d1c2a","ref":"","in":"body"},{"ref":"","in":"body","required":false,"desc":"The URL of invoices for the specified account.","default":"","type":"string","name":"invoices","_id":"557f45d07eafa719001d1c29"},{"default":"","type":"string","name":"redemption","_id":"55e4aa556f190c1900a40881","ref":"","in":"body","required":false,"desc":"The URL of the coupon redemption for the specified account."},{"in":"body","required":false,"desc":"The URL of subscriptions for the specified account.","default":"","type":"string","name":"subscriptions","_id":"55e4aa556f190c1900a40880","ref":""},{"desc":"The URL of transactions for the specified account.","default":"","type":"string","name":"transactions","_id":"55e4aa556f190c1900a4087f","ref":"","in":"body","required":false},{"_id":"55e4aa556f190c1900a4087e","ref":"","in":"body","required":false,"desc":"The unique identifier of the account.","default":"","type":"string","name":"account_code"},{"_id":"55e4aa556f190c1900a4087d","ref":"","in":"body","required":false,"desc":"The state of accounts to return: `active` or `closed`.","default":"","type":"string","name":"state"},{"name":"username","_id":"55e4aa556f190c1900a4087c","ref":"","in":"body","required":false,"desc":"The username of the account.","default":"","type":"string"},{"type":"string","name":"email","_id":"55e4aa556f190c1900a4087b","ref":"","in":"body","required":false,"desc":"The email address of the account.","default":""},{"desc":"Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the `email` field also receives.","default":"","type":"array_string","name":"cc_emails","_id":"560b18973bcbd80d0077d0c0","ref":"","in":"body","required":false},{"_id":"55e4aa556f190c1900a4087a","ref":"","in":"body","required":false,"desc":"The first name of the account.","default":"","type":"string","name":"first_name"},{"_id":"55e4aa556f190c1900a40879","ref":"","in":"body","required":false,"desc":"The last name of the account.","default":"","type":"string","name":"last_name"},{"name":"company_name","_id":"55e4aa556f190c1900a40878","ref":"","in":"body","required":false,"desc":"The company name of the account.","default":"","type":"string"},{"type":"string","name":"vat_number","_id":"55e4aa556f190c1900a40877","ref":"","in":"body","required":false,"desc":"The VAT number of the account (to avoid having the VAT applied).","default":""},{"required":false,"desc":"The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account.","default":"","type":"boolean","name":"tax_exempt","_id":"55e4aa556f190c1900a40876","ref":"","in":"body"},{"type":"object","name":"address","_id":"55e4aa556f190c1900a40875","ref":"","in":"body","required":false,"desc":"The nested address information of the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`.","default":""},{"desc":"The nested shipping address information of the account: `first_name`, `last_name`, `company_name`, `email`, `phone`, `vat_number`, `address1`, `address2`, `city`, `state`, `zip`, `country`, `nickname`. You can pass in up to 20 account shipping addresses along with the request to create a new account. When providing a shipping address, the following are required: first_name, last_name, address1, city, state, zip, and country.","default":"","type":"object","name":"shipping_address","_id":"57fffdd8c7609a0f0063caaf","ref":"","in":"body","required":false},{"name":"accept_language","_id":"55e4aa556f190c1900a40874","ref":"","in":"body","required":false,"desc":"The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.","default":"","type":"string"},{"type":"string","name":"hosted_login_token","_id":"55e4aa556f190c1900a40873","ref":"","in":"body","required":false,"desc":"The unique token for automatically logging the account in to the hosted management pages. You may automatically log the user into their hosted management pages by directing the user to: `https://:subdomain.recurly.com/account/:hosted_login_token`.","default":""},{"required":false,"desc":"The date and time the account was created in Recurly.","default":"","type":"datetime","name":"created_at","_id":"55e4aa556f190c1900a40872","ref":"","in":"body"},{"type":"datetime","name":"updated_at","_id":"5783dc55359cd219005453ec","ref":"","in":"body","required":false,"desc":"The date and time the account or its billing info was last updated.","default":""},{"desc":"For closed accounts, the date and time it was closed.","default":"","type":"datetime","name":"closed_at","_id":"5783dcff359cd219005453ee","ref":"","in":"body","required":false},{"_id":"58c8255f5cb4fe1b00ec5679","ref":"","in":"body","required":false,"desc":"True if the account has at least one live subscription.","default":"","type":"boolean","name":"has_live_subscription"},{"name":"has_active_subscription","_id":"58c8255f5cb4fe1b00ec5678","ref":"","in":"body","required":false,"desc":"True if the account has at least one active subscription.","default":"","type":"boolean"},{"ref":"","in":"body","required":false,"desc":"True if the account has at least one future subscription.","default":"","type":"boolean","name":"has_future_subscription","_id":"58c8255f5cb4fe1b00ec5677"},{"default":"","type":"boolean","name":"has_canceled_subscription","_id":"58c8255f5cb4fe1b00ec5676","ref":"","in":"body","required":false,"desc":"True if the account has at least one canceled subscription."},{"default":"","type":"boolean","name":"has_past_due_invoice","_id":"58c8255f5cb4fe1b00ec5675","ref":"","in":"body","required":false,"desc":"True if the account has at least one past due invoice."}],"url":"/accounts","apiSetting":"59497f16b9248d0024fe3f3f"},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getAccount Object

Accounts are core to managing your customers inside of Recurly. The account object stores the entire Recurly history of your customer and acts as the entry point for working with a customer's billing information, subscription data, transactions, invoices and more.

Body Params

adjustments:

string

The URL of adjustments for the specified account.

account_balance:

string

The URL of the account balance for the specified account.

billing_info:

string

The URL of billing info for the specified account.

invoices:

string

The URL of invoices for the specified account.

redemption:

string

The URL of the coupon redemption for the specified account.

subscriptions:

string

The URL of subscriptions for the specified account.

transactions:

string

The URL of transactions for the specified account.

account_code:

string

The unique identifier of the account.

state:

string

The state of accounts to return: `active` or `closed`.

username:

string

The username of the account.

email:

string

The email address of the account.

cc_emails:

array of strings

Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the `email` field also receives.

first_name:

string

The first name of the account.

last_name:

string

The last name of the account.

company_name:

string

The company name of the account.

vat_number:

string

The VAT number of the account (to avoid having the VAT applied).

tax_exempt:

boolean

The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account.

The nested shipping address information of the account: `first_name`, `last_name`, `company_name`, `email`, `phone`, `vat_number`, `address1`, `address2`, `city`, `state`, `zip`, `country`, `nickname`. You can pass in up to 20 account shipping addresses along with the request to create a new account. When providing a shipping address, the following are required: first_name, last_name, address1, city, state, zip, and country.

accept_language:

string

The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.

hosted_login_token:

string

The unique token for automatically logging the account in to the hosted management pages. You may automatically log the user into their hosted management pages by directing the user to: `https://:subdomain.recurly.com/account/:hosted_login_token`.

{"_id":"5919d93f85b2570f00e41ca0","hidden":false,"next":{"pages":[],"description":""},"order":1,"parentDoc":null,"type":"get","user":"55648cf93b87582b003ab8b1","version":"5919d93785b2570f00e41c39","body":"###Account Query States\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"state\",\n \"h-1\": \"description\",\n \"0-0\": \"`active`\",\n \"1-0\": \"`closed`\",\n \"0-1\": \"Open accounts.\",\n \"1-1\": \"Accounts that are not open.\",\n \"2-0\": \"`subscriber`\",\n \"2-1\": \"Accounts with subscriptions that are valid for the current time. This includes subscriptions in a trial period.\",\n \"3-0\": \"`non_subscriber`\",\n \"3-1\": \"Accounts without subscriptions that are valid for the current time.\",\n \"4-0\": \"`past_due`\",\n \"4-1\": \"Accounts with invoices that have failed initial collection but still have collection attempts remaining.\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"body\": \"Please note: a queried state and the base state of a returned account may differ. For example, querying for `past_due` account will not result in a list of accounts with a `past_due` state (they will either be `active` or `closed`). Only base states (`active`, `closed`) will be present in the returned account records.\"\n}\n[/block]","createdAt":"2015-06-15T21:38:24.720Z","link_url":"","sync_unique":"","title":"List Accounts","api":{"results":{"codes":[{"code":"<accounts type=\"array\">\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/1/adjustments\"/>\n <account_acquisition href=\"https://your-subdomain.recurly.com/v2/accounts/1/acquisition\"/>\n <account_balance href=\"https://your-subdomain.recurly.com/v2/accounts/1/balance\"/>\n <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n <shipping_addresses href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses\"/>\n <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n <account_code>1</account_code>\n <state>active</state>\n <username>verena1234</username>\n <email>[email protected]</email>\n <cc_emails>[email protected],[email protected]</cc_emails>\n <first_name>Verena</first_name>\n <last_name>Example</last_name>\n <company_name>New Company Name</company_name>\n <vat_number nil=\"nil\"/>\n <tax_exempt type=\"boolean\">false</tax_exempt>\n <address>\n <address1>123 Main St.</address1>\n <address2 nil=\"nil\"/>\n <city>San Francisco</city>\n <state>CA</state>\n <zip>94105</zip>\n <country>US</country>\n <phone nil=\"nil\"/>\n </address>\n <accept_language nil=\"nil\"/>\n <hosted_login_token>71c122cb16fc90252ff845eacf5d7814</hosted_login_token>\n <created_at type=\"datetime\">2016-08-03T15:44:05Z</created_at>\n <updated_at type=\"datetime\">2017-03-15T21:22:18Z</updated_at>\n <closed_at nil=\"nil\"/>\n <has_live_subscription type=\"boolean\">false</has_live_subscription>\n <has_active_subscription type=\"boolean\">false</has_active_subscription>\n <has_future_subscription type=\"boolean\">false</has_future_subscription>\n <has_canceled_subscription type=\"boolean\">false</has_canceled_subscription>\n <has_past_due_invoice type=\"boolean\">false</has_past_due_invoice>\n </account>\n</accounts>","language":"xml","status":200,"name":""}]},"settings":"","auth":"required","params":[{"_id":"56465088054d8f0d00bc76aa","ref":"","in":"query","required":false,"desc":"The state of accounts to return: `active`, `closed`, `subscriber`, `non_subscriber`, `past_due`.","default":"","type":"string","name":"state"},{"_id":"578ea5b0c93aac0e00ec8899","ref":"","in":"query","required":false,"desc":"The attribute that will be used to order records: `created_at`, `updated_at`.","default":"created_at","type":"string","name":"sort"},{"_id":"578ea5b0c93aac0e00ec8898","ref":"","in":"query","required":false,"desc":"The order in which products will be returned: `asc` for ascending order, `desc` for descending order.","default":"desc","type":"string","name":"order"},{"_id":"578ea5b0c93aac0e00ec8897","ref":"","in":"query","required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.","default":"","type":"datetime","name":"begin_time"},{"_id":"578ea5b0c93aac0e00ec8896","ref":"","in":"query","required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.","default":"","type":"datetime","name":"end_time"},{"_id":"56d8bace7ce7550b00c81d77","ref":"","in":"query","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page"},{"_id":"56d8bace7ce7550b00c81d78","ref":"","in":"query","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"int","name":"cursor"}],"url":"/accounts","examples":{"codes":[{"name":"","code":"<?php\n\n$accounts = Recurly_AccountList::getActive();\nforeach ($accounts as $account) {\n print \"Account: $account\\n\";\n}\n","language":"php"},{"code":"Recurly::Account.find_each do |account|\n puts \"Account: #{account.inspect}\"\nend","language":"ruby"},{"code":"#client version 2.1.6+\nfor account in Account.all():\n print 'Account: %s' % account\n\n#client version <= 2.1.5\naccounts = Account.all()\nwhile accounts:\n for account in accounts:\n print 'Account: %s' % account\n try:\n accounts = accounts.next_page()\n except PageError:\n accounts = ()","language":"python"},{"language":"csharp","name":null,"code":"using System.Linq;\n\nvar accounts = Accounts.List();\nwhile (accounts.Any())\n{\n\tforeach (var account in accounts)\n\t\tConsole.WriteLine(account);\n\taccounts = accounts.Next;\n}"}]},"method":"get","apiSetting":"59497f16b9248d0024fe3f3f"},"excerpt":"Returns a list of accounts on your site. Results are ordered by the time created, sorted by newest first.","githubsync":"","project":"555fbba928249c1900618a82","updates":["55f1f9abd4d3160d00439b6c"],"__v":1,"category":"5919d93885b2570f00e41c3e","isReference":true,"link_external":false,"slug":"list-accounts","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getList Accounts

Returns a list of accounts on your site. Results are ordered by the time created, sorted by newest first.

Query Params

state:

string

The state of accounts to return: `active`, `closed`, `subscriber`, `non_subscriber`, `past_due`.

sort:

stringcreated_at

The attribute that will be used to order records: `created_at`, `updated_at`.

order:

stringdesc

The order in which products will be returned: `asc` for ascending order, `desc` for descending order.

begin_time:

datetime

Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

end_time:

datetime

Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

per_page:

integer50

Number of records to return per page, up to a maximum of 200.

cursor:

integer

Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.

Account Query States

state

description

active

Open accounts.

closed

Accounts that are not open.

subscriber

Accounts with subscriptions that are valid for the current time. This includes subscriptions in a trial period.

non_subscriber

Accounts without subscriptions that are valid for the current time.

past_due

Accounts with invoices that have failed initial collection but still have collection attempts remaining.

Please note: a queried state and the base state of a returned account may differ. For example, querying for past_due account will not result in a list of accounts with a past_due state (they will either be active or closed). Only base states (active, closed) will be present in the returned account records.

postCreate Account

Creates a new account. You may optionally include billing information.

Body Params

account_code:

required

string

A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z 0-9 @ - _ .] but it may not begin with a dot character. Max of 50 characters.

username:

string

The username for the account, ignore if you do not use usernames. Max of 255 characters.

email:

string

The email address for the account.

first_name:

string

The first name for the account. Max of 255 characters.

last_name:

string

The last name for the account. Max of 255 characters.

company_name:

string

The company name for the account. Max of 50 characters.

vat_number:

string

The VAT number to avoid having the VAT applied (if applicable).

tax_exempt:

boolean

The tax status for the account.

entity_use_code:

string

The Avalara AvaTax value that can be passed to identify the customer type for tax purposes. The range of values can be A - R (more info at Avalara). Value is case-sensitive.

The nested shipping address information of the account: `first_name`, `last_name`, `company_name`, `email`, `phone`, `vat_number`, `address1`, `address2`, `city`, `state`, `zip`, `country`, `nickname`. You can pass in up to 20 account shipping addresses along with the request to create a new account. When providing a shipping address, the following are required: first_name, last_name, address1, city, state, zip, and country.

accept_language:

string

The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.

cc_emails:

array of strings

Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the `email` field also receives.

The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.

cc_emails:

array of strings

Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the `email` field also receives.

Please note

You may optionally include billing information when updating an account. If the billing information is provided, the billing information will be validated. The account will only be updated if the billing information is valid.

deleteClose Account

Marks an account as closed and cancels any active subscriptions.

Path Params

account_code:

required

string

Account's unique code.

Please note

Closing an account permanently deletes its billing information and cancels any active subscriptions (canceled subscriptions will remain active until the end of the current billing cycle before expiring).

putReopen Account

Transitions a closed account back to active.

Path Params

account_code:

required

string

Account's unique code.

Please note

Editing an account, creating an account with the same account_code as the deleted account, or creating a new transaction or subscription will also reopen an account. Reopening an account will restore its history. Reopening an account does not modify any previously canceled or expired subscriptions and billing information will need to be provided by the customer to continue billing.

{"_id":"5919d93f85b2570f00e41ca7","api":{"examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n $notes = Recurly_NoteList::get('b6f5783');\n foreach ($notes as $note) {\n print \"Note: {$note->message}\\n\";\n }\n} catch (Recurly_NotFoundError $e) {\n print \"Invalid account code: $e\";\n}","name":""},{"language":"python","code":"try:\n account = recurly.Account.get('1')\n for note in account.notes():\n print \"Note: %s\" % note.message\nexcept NotFoundError:\n print \"Account not found.\\n\""},{"language":"csharp","code":"using System.Linq;\n\nvar account = Accounts.Get(\"1\");\nvar notes = account.GetNotes();\nwhile (notes.Any())\n{\n\tforeach (var note in notes)\n\t\tConsole.WriteLine(\"Note: \" + note.Message);\n\tnotes = notes.Next;\n}"}]},"method":"get","results":{"codes":[{"status":200,"language":"xml","code":"<notes type=\"array\">\n <note>\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <message>This is my second note</message>\n <created_at type=\"datetime\">2015-06-14T16:08:41Z</created_at>\n </note>\n <note>\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <message>This is my first note</message>\n <created_at type=\"datetime\">2016-06-13T16:06:21Z</created_at>\n </note>\n <!-- Continued... -->\n</notes>","name":""}]},"settings":"","auth":"required","params":[{"desc":"Account's unique code.","default":"","type":"string","name":"account_code","_id":"55944eddccc3052300569882","ref":"","in":"path","required":true},{"_id":"5783c946ce802f0e0087d4bb","ref":"","in":"query","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"name":"sort","_id":"578ea620c93aac0e00ec889d","ref":"","in":"query","required":false,"desc":"The attribute that will be used to order records: `created_at`, `updated_at`.","default":"created_at","type":"string"},{"ref":"","in":"query","required":false,"desc":"The order in which products will be returned: `asc` for ascending order, `desc` for descending order.","default":"desc","type":"string","name":"order","_id":"578ea620c93aac0e00ec889c"},{"in":"query","required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.","default":"","type":"datetime","name":"begin_time","_id":"578ea620c93aac0e00ec889b","ref":""},{"desc":"","default":"","type":"datetime","name":"end_time","_id":"578ea620c93aac0e00ec889a","ref":"","in":"query","required":false},{"name":"per_page","_id":"5783c946ce802f0e0087d4ba","ref":"","in":"query","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int"}],"url":"/accounts/:account_code/notes","apiSetting":"59497f16b9248d0024fe3f3f"},"createdAt":"2015-06-15T22:04:40.352Z","link_url":"","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5919d93785b2570f00e41c39","__v":0,"body":"","category":"5919d93885b2570f00e41c3e","isReference":true,"next":{"description":"","pages":[]},"order":8,"parentDoc":null,"project":"555fbba928249c1900618a82","type":"get","sync_unique":"","title":"List Account Notes","githubsync":"","hidden":false,"link_external":false,"slug":"list-account-notes","excerpt":"Returns a list of the notes on an account sorted in descending order (most recently created first).","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getList Account Notes

Returns a list of the notes on an account sorted in descending order (most recently created first).

Path Params

account_code:

required

string

Account's unique code.

Query Params

cursor:

string

Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.

sort:

stringcreated_at

The attribute that will be used to order records: `created_at`, `updated_at`.

order:

stringdesc

The order in which products will be returned: `asc` for ascending order, `desc` for descending order.

begin_time:

datetime

Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

Result Format

<notestype="array"><note><accounthref="https://your-subdomain.recurly.com/v2/accounts/1"/><message>This is my second note</message><created_attype="datetime">2015-06-14T16:08:41Z</created_at></note><note><accounthref="https://your-subdomain.recurly.com/v2/accounts/1"/><message>This is my first note</message><created_attype="datetime">2016-06-13T16:06:21Z</created_at></note><!-- Continued... --></notes>

{"_id":"5919d93e85b2570f00e41c9a","parentDoc":null,"project":"555fbba928249c1900618a82","user":"55ad15f7f93f0c0d005b88a2","__v":0,"category":"5919d93885b2570f00e41c3f","hidden":false,"sync_unique":"","githubsync":"","link_url":"","next":{"pages":[],"description":""},"version":"5919d93785b2570f00e41c39","api":{"method":"get","results":{"codes":[{"code":"<shipping_addresses type=\"array\">\n <shipping_address href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/1\">\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/1/subscriptions\">\n <id>1</id>\n <nickname>Work</nickname>\n <first_name>Verena</first_name>\n <last_name>Example</last_name>\n <company>Recurly Inc</company>\n <phone>555-222-1212</phone>\n <email>[email protected]</email>\n <address1>123 Main St.</address1>\n <address2>Suite 101</address2>\n <city>San Francisco</city>\n <state>CA</state>\n <zip>94105</zip>\n <country>US</country>\n <created_at type=\"datetime\">2016-06-14T16:08:41Z</created_at>\n <updated_at type=\"datetime\">2016-06-14T16:08:41Z</updated_at>\n </shipping_address>\n <shipping_address href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/2\">\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n <shipping_address_id>2</shipping_address_id>\n <nickname>Home</nickname>\n <first_name>Verena</first_name>\n <last_name>Example</last_name>\n <phone>555-867-5309</phone>\n <email>[email protected]</email>\n <address1>123 Fourth St.</address1>\n <address2>Apt. 101</address2>\n <city>San Francisco</city>\n <state>CA</state>\n <zip>94105</zip>\n <country>US</country>\n <created_at type=\"datetime\">2016-06-14T16:08:42Z</created_at>\n <updated_at type=\"datetime\">2016-06-14T16:08:42Z</updated_at>\n </shipping_address>\n</shipping_addresses>","name":"","status":200,"language":"xml"}]},"settings":"","auth":"required","params":[{"required":true,"desc":"Unique account identifier.","default":"","type":"string","name":"account_code","_id":"578d1aa09a98a41900717d95","ref":"","in":"path"},{"type":"string","name":"cursor","_id":"55821a9e5b7fa60d0068b420","ref":"","in":"query","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":""},{"desc":"The attribute that will be used to order records: `created_at`, `updated_at`.","default":"created_at","type":"string","name":"sort","_id":"578ea7d5426c561700db8694","ref":"","in":"query","required":false},{"name":"order","_id":"578ea7d5426c561700db8693","ref":"","in":"query","required":false,"desc":"The order in which products will be returned: `asc` for ascending order, `desc` for descending order.","default":"desc","type":"string"},{"ref":"","in":"query","required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.","default":"","type":"datetime","name":"begin_time","_id":"578ea7d5426c561700db8692"},{"default":"","type":"datetime","name":"end_time","_id":"578ea7d5426c561700db8691","ref":"","in":"query","required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time."},{"in":"query","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page","_id":"55821a9e5b7fa60d0068b41f","ref":""}],"url":"/accounts/:account_code/shipping_addresses","examples":{"codes":[{"code":"# First get an account\naccount = Recurly::Account.find('1')\n\n# Get all shipping addresses\nshipping_addresses = account.shipping_addresses\n\n# If you want to pass sorting/filtering params:\nshipping_addresses = account.shipping_addresses.all(sort: :updated_at, order: :asc)","language":"ruby"},{"code":"# first we need any account object\naccount = Account.get('1')\n\n# the shipping_addresses method fetches the shipping addresses\n# associated with this account\nshipping_addresses = account.shipping_addresses()","language":"python"}]},"apiSetting":"59497f16b9248d0024fe3f3f"},"isReference":true,"link_external":false,"order":0,"slug":"list-accounts-shipping-address","title":"List Account's Shipping Address","type":"get","body":"","createdAt":"2016-10-14T17:02:21.737Z","excerpt":"Returns a list of shipping addresses for an account.","updates":[],"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getList Account's Shipping Address

Returns a list of shipping addresses for an account.

Path Params

account_code:

required

string

Unique account identifier.

Query Params

cursor:

string

Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.

sort:

stringcreated_at

The attribute that will be used to order records: `created_at`, `updated_at`.

order:

stringdesc

The order in which products will be returned: `asc` for ascending order, `desc` for descending order.

begin_time:

datetime

Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

end_time:

datetime

Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

Definition

Examples

# First get an accountaccount=Recurly::Account.find('1')
# Get all shipping addressesshipping_addresses=account.shipping_addresses# If you want to pass sorting/filtering params:shipping_addresses=account.shipping_addresses.all(sort::updated_at, order::asc)

# first we need any account objectaccount=Account.get('1')
# the shipping_addresses method fetches the shipping addresses# associated with this accountshipping_addresses=account.shipping_addresses()

Path Params

Definition

Examples

{"_id":"5919d94085b2570f00e41ca8","api":{"settings":"","auth":"required","params":[{"ref":"","in":"body","required":false,"desc":"The URL of the account for the specified adjustment.","default":"","type":"string","name":"account","_id":"55f88d0560cc850d008a7bae"},{"in":"body","required":false,"desc":"The URL of the invoice for the specified adjustment.","default":"","type":"string","name":"invoice","_id":"55f88d0560cc850d008a7bad","ref":""},{"required":false,"desc":"The type of adjustment to return: `charge` or `credit`.","default":"","type":"string","name":"type","_id":"55f8905559eace0d0087dc69","ref":"","in":"body"},{"type":"string","name":"uuid","_id":"55f88d0560cc850d008a7bac","ref":"","in":"body","required":false,"desc":"The unique identifier of the adjustment.","default":""},{"desc":"The state of the adjustments to return: `pending` or `invoiced`.","default":"","type":"string","name":"state","_id":"55f88d0560cc850d008a7bab","ref":"","in":"body","required":false},{"_id":"55f88d0560cc850d008a7baa","ref":"","in":"body","required":false,"desc":"Description of the adjustment for the adjustment. Max 255 characters.","default":"","type":"string","name":"description"},{"name":"accounting_code","_id":"55f88d0560cc850d008a7ba9","ref":"","in":"body","required":false,"desc":"Accounting code. Max of 20 characters.","default":"","type":"string"},{"ref":"","in":"body","required":false,"desc":"The origin of the adjustment to return: `plan`, `plan_trial`, `setup_fee`, `add_on`, `add_on_trial`, `one_time`, `debit`, `credit`, `coupon`, or `carryforward`.","default":"","type":"string","name":"origin","_id":"55f88d0560cc850d008a7ba8"},{"in":"body","required":false,"desc":"Positive amount for a charge, negative amount for a credit. Max 10000000.","default":"","type":"int","name":"unit_amount_in_cents","_id":"55f88d0560cc850d008a7ba7","ref":""},{"desc":"Quantity.","default":"1","type":"string","name":"quantity","_id":"55f88d0560cc850d008a7ba6","ref":"","in":"body","required":false},{"_id":"55f88d0560cc850d008a7ba5","ref":"","in":"body","required":false,"desc":"Only shows if adjustment is a credit created from another credit.","default":"","type":"string","name":"original_adjustment_uuid"},{"_id":"55f88d0560cc850d008a7ba4","ref":"","in":"body","required":false,"desc":"The discount on the adjustment, in cents.","default":"","type":"int","name":"discount_in_cents"},{"name":"tax_in_cents","_id":"55f88d0560cc850d008a7ba3","ref":"","in":"body","required":false,"desc":"The tax on the adjustment, in cents.","default":"","type":"int"},{"ref":"","in":"body","required":false,"desc":"The total amount of the adjustment, in cents.","default":"","type":"int","name":"total_in_cents","_id":"55f88d0560cc850d008a7ba2"},{"default":"","type":"string","name":"currency","_id":"55f88d0560cc850d008a7ba1","ref":"","in":"body","required":false,"desc":"Currency, 3-letter ISO code."},{"in":"body","required":false,"desc":"`true` if the current adjustment is taxable, `false` if it is not.","default":"","type":"boolean","name":"taxable","_id":"55f88d0560cc850d008a7ba0","ref":""},{"required":false,"desc":"The tax type of the adjustment.","default":"","type":"string","name":"tax_type","_id":"55f88d0560cc850d008a7b9f","ref":"","in":"body"},{"ref":"","in":"body","required":false,"desc":"The tax region of the adjustment.","default":"","type":"string","name":"tax_region","_id":"55f88d0560cc850d008a7b9e"},{"in":"body","required":false,"desc":"The tax rate of the adjustment.","default":"","type":"string","name":"tax_rate","_id":"55f88d0560cc850d008a7b9d","ref":""},{"required":false,"desc":"`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative adjustments). Credits are always post-tax. Pre-tax discounts should use the Coupons feature.","default":"","type":"boolean","name":"tax_exempt","_id":"55f88d0560cc850d008a7b9c","ref":"","in":"body"},{"type":"array_mixed","name":"tax_details","_id":"55f88d0560cc850d008a7b9b","ref":"","in":"body","required":false,"desc":"The nested address information of the adjustment: `name `, `type`, `tax_rate`, `tax_in_cents`.","default":""},{"desc":"Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.","default":"","type":"string","name":"tax_code","_id":"55f88d2bb089b71700a8363c","ref":"","in":"body","required":false},{"_id":"55f88d0560cc850d008a7b9a","ref":"","in":"body","required":false,"desc":"A timestamp associated with when the adjustment began.","default":"Today","type":"datetime","name":"start_date"},{"name":"end_date","_id":"55f88d0560cc850d008a7b99","ref":"","in":"body","required":false,"desc":"A timestamp associated with when the adjustment ended.","default":"","type":"datetime"},{"ref":"","in":"body","required":false,"desc":"A timestamp associated with when the adjustment was created.","default":"","type":"datetime","name":"created_at","_id":"55f88d0560cc850d008a7b98"},{"in":"body","required":false,"desc":"For plan related line items this will be the plan's code, for add-on related line items it will be the add-on's code.","default":"","type":"string","name":"product_code","_id":"58c821b8580c540f00af78a9","ref":""}],"url":"/adjustments","examples":{"codes":[]},"method":"get","results":{"codes":[{"code":"<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/37bff9dd3ec90471cf62bd4f6f80db3d\" type=\"charge\">\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1006\"/>\n <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/37bfef7a8e44cfc3817b7a43eba8a6e6\"/>\n <uuid>37bff9dd3ec90471cf62bd4f6f80db3d</uuid>\n <state>invoiced</state>\n <description>Refund for Setup fee: Gold plan</description>\n <accounting_code nil=\"nil\"/>\n <product_code>gold</product_code>\n <origin>setup_fee</origin>\n <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n <quantity type=\"integer\">-1</quantity>\n <quantity_remaining type=\"integer\">0</quantity_remaining>\n <original_adjustment_uuid>37bfef7af3cd23ee89d77a435aa1838d</original_adjustment_uuid>\n <discount_in_cents type=\"integer\">0</discount_in_cents>\n <tax_in_cents type=\"integer\">-70</tax_in_cents>\n <total_in_cents type=\"integer\">-870</total_in_cents>\n <currency>EUR</currency>\n <taxable type=\"boolean\">false</taxable>\n <tax_type>usst</tax_type>\n <tax_region>CA</tax_region>\n <tax_rate type=\"float\">0.0875</tax_rate>\n <tax_exempt type=\"boolean\">false</tax_exempt>\n <tax_code nil=\"nil\"/>\n <tax_details type=\"array\">\n <tax_detail>\n <name nil=\"nil\"/>\n <type>state</type>\n <tax_rate type=\"float\">0.065</tax_rate>\n <tax_in_cents type=\"integer\">-52</tax_in_cents>\n </tax_detail>\n <tax_detail>\n <name nil=\"nil\"/>\n <type>county</type>\n <tax_rate type=\"float\">0.01</tax_rate>\n <tax_in_cents type=\"integer\">-8</tax_in_cents>\n </tax_detail>\n <tax_detail>\n <name nil=\"nil\"/>\n <type>city</type>\n <tax_rate type=\"float\">0.0</tax_rate>\n <tax_in_cents type=\"integer\">0</tax_in_cents>\n </tax_detail>\n <tax_detail>\n <name nil=\"nil\"/>\n <type>special</type>\n <tax_rate type=\"float\">0.0125</tax_rate>\n <tax_in_cents type=\"integer\">-10</tax_in_cents>\n </tax_detail>\n </tax_details>\n <start_date type=\"datetime\">2016-08-03T16:02:24Z</start_date>\n <end_date nil=\"nil\"/>\n <created_at type=\"datetime\">2016-08-03T16:13:44Z</created_at>\n <updated_at type=\"datetime\">2016-08-03T16:13:44Z</updated_at>\n <revenue_schedule_type>evenly</revenue_schedule_type>\n</adjustment>","language":"xml","status":200,"name":""}]},"apiSetting":"59497f16b9248d0024fe3f3f"},"body":"","excerpt":"The history of your customer's Recurly account can be tracked through adjustments, made up of credits and charges.","parentDoc":null,"project":"555fbba928249c1900618a82","sync_unique":"","__v":0,"hidden":false,"link_url":"","next":{"pages":[],"description":""},"slug":"adjustment-object","updates":[],"category":"5919d93885b2570f00e41c41","createdAt":"2015-09-15T21:26:29.282Z","githubsync":"","isReference":true,"link_external":false,"order":0,"user":"55648cf93b87582b003ab8b1","version":"5919d93785b2570f00e41c39","title":"Adjustment Object","type":"get","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getAdjustment Object

The history of your customer's Recurly account can be tracked through adjustments, made up of credits and charges.

Positive amount for a charge, negative amount for a credit. Max 10000000.

quantity:

string1

Quantity.

original_adjustment_uuid:

string

Only shows if adjustment is a credit created from another credit.

discount_in_cents:

integer

The discount on the adjustment, in cents.

tax_in_cents:

integer

The tax on the adjustment, in cents.

total_in_cents:

integer

The total amount of the adjustment, in cents.

currency:

string

Currency, 3-letter ISO code.

taxable:

boolean

`true` if the current adjustment is taxable, `false` if it is not.

tax_type:

string

The tax type of the adjustment.

tax_region:

string

The tax region of the adjustment.

tax_rate:

string

The tax rate of the adjustment.

tax_exempt:

boolean

`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative adjustments). Credits are always post-tax. Pre-tax discounts should use the Coupons feature.

Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.

start_date:

datetimeToday

A timestamp associated with when the adjustment began.

end_date:

datetime

A timestamp associated with when the adjustment ended.

created_at:

datetime

A timestamp associated with when the adjustment was created.

product_code:

string

For plan related line items this will be the plan's code, for add-on related line items it will be the add-on's code.

{"_id":"5919d94085b2570f00e41ca9","type":"get","__v":0,"body":"","createdAt":"2015-06-15T22:21:48.674Z","hidden":false,"isReference":true,"link_external":false,"category":"5919d93885b2570f00e41c41","link_url":"","githubsync":"","parentDoc":null,"slug":"list-an-accounts-adjustments","user":"55648cf93b87582b003ab8b1","title":"List Account's Adjustments","updates":[],"api":{"settings":"","auth":"required","params":[{"ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code","_id":"5783c9a7192dcf0e0099828e"},{"default":"created_at","type":"string","name":"sort","_id":"578ea67ec93aac0e00ec88a5","ref":"","in":"query","required":false,"desc":"The attribute that will be used to order records: `created_at`, `updated_at`."},{"in":"query","required":false,"desc":"The order in which products will be returned: `asc` for ascending order, `desc` for descending order.","default":"desc","type":"string","name":"order","_id":"578ea67ec93aac0e00ec88a4","ref":""},{"required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.","default":"","type":"datetime","name":"begin_time","_id":"578ea67ec93aac0e00ec88a3","ref":"","in":"query"},{"ref":"","in":"query","required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.","default":"","type":"datetime","name":"end_time","_id":"578ea67ec93aac0e00ec88a2"},{"default":"50","type":"int","name":"per_page","_id":"5783c9a7192dcf0e0099828c","ref":"","in":"query","required":false,"desc":"Number of records to return per page, up to a maximum of 200."},{"default":"","type":"string","name":"cursor","_id":"5783c9a7192dcf0e0099828d","ref":"","in":"query","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page."}],"url":"/accounts/:account_code/adjustments","examples":{"codes":[{"name":"","language":"php","code":"<?php\n\ntry {\n $adjustments = Recurly_AdjustmentList::get('b6f5783');\n foreach ($adjustments as $adjustment) {\n print \"Adjustment: $adjustment\\n\";\n }\n} catch (Recurly_NotFoundError $e) {\n print \"Invalid account code: $e\";\n}"},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.adjustments.find_each do |adjustment|\n puts \"Adjustment: #{adjustment.inspect}\"\nend"},{"code":"#client version 2.1.6+\naccount = Account.get('1')\nfor adjustment in account.adjustments():\n print 'Adjustment: %s' % adjustment\n\n#client version <= 2.1.5\naccount = Account.get('1')\nadjustments = account.adjustments()\nwhile adjustments:\n for adjustment in adjustments:\n print 'Adjustment: %s' % adjustment\n try:\n adjustments = adjustments.next_page()\n except PageError:\n adjustments = ()","language":"python"},{"language":"csharp","code":"using System.Linq;\n\nvar account = Accounts.Get(\"1\");\nvar adjustments = account.GetAdjustments();\nwhile (adjustments.Any())\n{\n\tforeach (var adjustment in adjustments)\n\t\tConsole.WriteLine(\"Adjustment: \" + adjustment);\n\tadjustments = adjustments.Next;\n}"}]},"method":"get","results":{"codes":[{"status":200,"language":"xml","code":"<adjustments type=\"array\">\n <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/37c0038fe1ffc9405019db4a11a99aa8\" type=\"credit\">\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <uuid>37c0038fe1ffc9405019db4a11a99aa8</uuid>\n <state>pending</state>\n <description>Bonus for being a great customer</description>\n <accounting_code nil=\"nil\"/>\n <product_code nil=\"nil\"/>\n <origin>credit</origin>\n <unit_amount_in_cents type=\"integer\">-2000</unit_amount_in_cents>\n <quantity type=\"integer\">1</quantity>\n <discount_in_cents type=\"integer\">0</discount_in_cents>\n <tax_in_cents type=\"integer\">0</tax_in_cents>\n <total_in_cents type=\"integer\">-2000</total_in_cents>\n <currency>USD</currency>\n <taxable type=\"boolean\">false</taxable>\n <tax_exempt type=\"boolean\">false</tax_exempt>\n <tax_code nil=\"nil\"/>\n <start_date type=\"datetime\">2016-08-03T16:24:20Z</start_date>\n <end_date nil=\"nil\"/>\n <created_at type=\"datetime\">2016-08-03T16:24:20Z</created_at>\n <updated_at type=\"datetime\">2016-08-03T16:24:20Z</updated_at>\n <revenue_schedule_type>at_invoice</revenue_schedule_type>\n </adjustment>\n <!-- Continued... -->\n</adjustments>","name":""}]},"apiSetting":"59497f16b9248d0024fe3f3f"},"excerpt":"Returns a list of adjustments for a given account. Results are ordered by the time created, sorted by newest first.","next":{"pages":[],"description":""},"order":1,"project":"555fbba928249c1900618a82","sync_unique":"","version":"5919d93785b2570f00e41c39","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getList Account's Adjustments

Returns a list of adjustments for a given account. Results are ordered by the time created, sorted by newest first.

Path Params

account_code:

required

string

Account's unique code.

Query Params

sort:

stringcreated_at

The attribute that will be used to order records: `created_at`, `updated_at`.

order:

stringdesc

The order in which products will be returned: `asc` for ascending order, `desc` for descending order.

begin_time:

datetime

Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

end_time:

datetime

Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

per_page:

integer50

Number of records to return per page, up to a maximum of 200.

cursor:

string

Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.

Result Format

<adjustmentstype="array"><adjustmenthref="https://your-subdomain.recurly.com/v2/adjustments/37c0038fe1ffc9405019db4a11a99aa8"type="credit"><accounthref="https://your-subdomain.recurly.com/v2/accounts/1"/><uuid>37c0038fe1ffc9405019db4a11a99aa8</uuid><state>pending</state><description>Bonus for being a great customer</description><accounting_codenil="nil"/><product_codenil="nil"/><origin>credit</origin><unit_amount_in_centstype="integer">-2000</unit_amount_in_cents><quantitytype="integer">1</quantity><discount_in_centstype="integer">0</discount_in_cents><tax_in_centstype="integer">0</tax_in_cents><total_in_centstype="integer">-2000</total_in_cents><currency>USD</currency><taxabletype="boolean">false</taxable><tax_exempttype="boolean">false</tax_exempt><tax_codenil="nil"/><start_datetype="datetime">2016-08-03T16:24:20Z</start_date><end_datenil="nil"/><created_attype="datetime">2016-08-03T16:24:20Z</created_at><updated_attype="datetime">2016-08-03T16:24:20Z</updated_at><revenue_schedule_type>at_invoice</revenue_schedule_type></adjustment><!-- Continued... --></adjustments>

postCreate Charge

Creates a one-time charge on an account. Charges are not invoiced or collected immediately. Non-invoiced charges will automatically be invoices when the account's subscription renews, or you trigger a collection by posting an invoice. Charges may be removed from an account if they have not been invoiced.

Path Params

account_code:

required

string

Your unique account identifier.

Body Params

currency:

required

string

Currency, 3-letter ISO code.

unit_amount_in_cents:

required

string

Positive amount for a charge, negative amount for a credit. Max 10000000.

quantity:

integer1

Quantity.

description:

string

Description of the adjustment for the invoice.

accounting_code:

string

Accounting code. Max of 20 characters.

revenue_schedule_type:

string

Optional field for setting a revenue schedule type. This will determine how revenue for the associated Charge should be recognized. Available schedule types are `never`, `at_range_start`, `at_invoice`, and—if `end_date` is set—`evenly` and `at_range_end`.

tax_exempt:

boolean

`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative adjustments). Credits are always post-tax. Pre-tax discounts should use the Coupons feature.

tax_code:

string

Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.

start_date:

timestampnow

A timestamp associated with when the charge began.

end_date:

timestamp

A timestamp associated with when the charge ended.

product_code:

string

The product code or SKU of the line item. Max of 50 characters. Useful for later reporting on product purchases.

{"_id":"5919d94085b2570f00e41cab","hidden":false,"next":{"pages":[],"description":""},"slug":"create-a-credit","user":"55648cf93b87582b003ab8b1","version":"5919d93785b2570f00e41c39","body":"[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"No Tax on Custom Credits\",\n \"body\": \"Custom credit adjustments will not calculate tax. If the credit you want to create reflects a charge previously billed with tax, we recommend that you refund the invoice instead of making a credit.\"\n}\n[/block]","createdAt":"2015-08-07T19:15:36.088Z","link_url":"","parentDoc":null,"project":"555fbba928249c1900618a82","sync_unique":"","title":"Create Credit","githubsync":"","isReference":true,"link_external":false,"updates":["563ce057913e650d00b65f47"],"__v":0,"api":{"auth":"required","params":[{"_id":"557f5188eb75d80d00af40a6","ref":"","in":"body","required":true,"desc":"Currency, 3-letter ISO code.","default":"","type":"string","name":"currency"},{"_id":"557f5188eb75d80d00af40a7","ref":"","in":"path","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"557f5188eb75d80d00af40a5","ref":"","in":"body","required":true,"desc":"Positive amount for a charge, negative amount for a credit. Max 10000000.","default":"","type":"string","name":"unit_amount_in_cents"},{"name":"quantity","_id":"557f5188eb75d80d00af40a3","ref":"","in":"body","required":false,"desc":"Quantity.","default":"1","type":"int"},{"ref":"","in":"body","required":false,"desc":"Description of the adjustment for the invoice.","default":"","type":"string","name":"description","_id":"557f5188eb75d80d00af40a4"},{"default":"","type":"string","name":"accounting_code","_id":"557f5188eb75d80d00af40a2","ref":"","in":"body","required":false,"desc":"Accounting code. Max of 20 characters."},{"default":"","type":"string","name":"revenue_schedule_type","_id":"578f7836dbb58b0e00bbdf87","ref":"","in":"body","required":false,"desc":"Optional field for setting a revenue schedule type. This will determine how revenue for the associated Credit should be recognized. Available schedule types are `never`, `at_range_start`, `at_invoice`, and—if `end_date` is set—`evenly` and `at_range_end`."},{"default":"now","type":"timestamp","name":"start_date","_id":"55e0dcbda44fae0d0021491f","ref":"","in":"body","required":false,"desc":"A timestamp associated with when the credit began."},{"default":"","type":"timestamp","name":"end_date","_id":"55e0dcbda44fae0d0021491e","ref":"","in":"body","required":false,"desc":"A timestamp associated with when the credit ended."},{"default":"","type":"string","name":"origin","_id":"57b50abbdc26980e00d04c9c","ref":"","in":"body","required":false,"desc":"Only allowed if the Gift Cards feature is enabled on your site and `unit_amount_in_cents` is negative. Can only have a value of `external_gift_card`. Sets the origin of the credit to `external_gift_card` in order to track gift card credits from external gift cards, like InComm, and triggers the logic to not require billing information from gift credit redeemers."},{"default":"","type":"string","name":"product_code","_id":"58a732f1e29fd525004c9b85","ref":"","in":"body","required":false,"desc":"The product code or SKU of the line item. Max of 50 characters. Useful for later reporting on product purchases."}],"url":"/accounts/:account_code/adjustments","examples":{"codes":[{"name":"","code":"<?php\n\n$credit = new Recurly_Adjustment();\n$credit->account_code = '1';\n$credit->description = 'Bonus for being a great customer';\n$credit->unit_amount_in_cents = -2000; // Negative $20.00.\n$credit->currency = 'USD';\n$credit->quantity = 1;\n$credit->create();","language":"php"},{"code":"account = Recurly::Account.find('1')\naccount.adjustments.create(\n :description => 'Bonus for being a great customer',\n :unit_amount_in_cents => -20_00,\n :currency => 'USD',\n :quantity => 1\n)","language":"ruby"},{"code":"account = Account.get('1')\ncredit = Adjustment(\n description='Bonus for being a great customer',\n unit_amount_in_cents=-2000,\n currency='USD',\n quantity=1\n)\naccount.charge(credit)","language":"python"},{"code":"var account = Accounts.Get(\"1\");\nvar adjustment = account.NewAdjustment(\n\t\"USD\", // currency\n\t-2000, // unit_amount_in_cents\n\t\"Bonus for being a great customer\", // description\n\t1); // quantity (default is 1)\nadjustment.Create();","language":"csharp"},{"code":"<adjustment>\n <description>Bonus for being a great customer</description>\n <unit_amount_in_cents>-2000</unit_amount_in_cents>\n <currency>USD</currency>\n <quantity>1</quantity>\n <revenue_schedule_type>at_invoice</revenue_schedule_type>\n</adjustment>","language":"xml"}]},"method":"post","results":{"codes":[{"name":"","code":"<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/37c0038fe1ffc9405019db4a11a99aa8\" type=\"credit\">\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <uuid>37c0038fe1ffc9405019db4a11a99aa8</uuid>\n <state>pending</state>\n <description>Bonus for being a great customer</description>\n <accounting_code nil=\"nil\"/>\n <product_code nil=\"nil\"/>\n <origin>credit</origin>\n <unit_amount_in_cents type=\"integer\">-2000</unit_amount_in_cents>\n <quantity type=\"integer\">1</quantity>\n <discount_in_cents type=\"integer\">0</discount_in_cents>\n <tax_in_cents type=\"integer\">0</tax_in_cents>\n <total_in_cents type=\"integer\">-2000</total_in_cents>\n <currency>USD</currency>\n <taxable type=\"boolean\">false</taxable>\n <tax_exempt type=\"boolean\">false</tax_exempt>\n <tax_code nil=\"nil\"/>\n <start_date type=\"datetime\">2016-08-03T16:24:20Z</start_date>\n <end_date nil=\"nil\"/>\n <created_at type=\"datetime\">2016-08-03T16:24:20Z</created_at>\n <updated_at type=\"datetime\">2016-08-03T16:24:20Z</updated_at>\n <revenue_schedule_type>at_invoice</revenue_schedule_type>\n</adjustment>","language":"xml","status":201}]},"settings":"","apiSetting":"59497f16b9248d0024fe3f3f"},"category":"5919d93885b2570f00e41c41","excerpt":"Creates a one-time charge on an account. Charges are not invoiced or collected immediately. Non-invoiced charges will automatically be invoices when the account's subscription renews, or you trigger a collection by posting an invoice. Charges may be removed from an account if they have not been invoiced.","order":3,"type":"post","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate Credit

Creates a one-time charge on an account. Charges are not invoiced or collected immediately. Non-invoiced charges will automatically be invoices when the account's subscription renews, or you trigger a collection by posting an invoice. Charges may be removed from an account if they have not been invoiced.

Path Params

account_code:

required

string

Your unique account identifier.

Body Params

currency:

required

string

Currency, 3-letter ISO code.

unit_amount_in_cents:

required

string

Positive amount for a charge, negative amount for a credit. Max 10000000.

quantity:

integer1

Quantity.

description:

string

Description of the adjustment for the invoice.

accounting_code:

string

Accounting code. Max of 20 characters.

revenue_schedule_type:

string

Optional field for setting a revenue schedule type. This will determine how revenue for the associated Credit should be recognized. Available schedule types are `never`, `at_range_start`, `at_invoice`, and—if `end_date` is set—`evenly` and `at_range_end`.

start_date:

timestampnow

A timestamp associated with when the credit began.

end_date:

timestamp

A timestamp associated with when the credit ended.

origin:

string

Only allowed if the Gift Cards feature is enabled on your site and `unit_amount_in_cents` is negative. Can only have a value of `external_gift_card`. Sets the origin of the credit to `external_gift_card` in order to track gift card credits from external gift cards, like InComm, and triggers the logic to not require billing information from gift credit redeemers.

product_code:

string

The product code or SKU of the line item. Max of 50 characters. Useful for later reporting on product purchases.

No Tax on Custom Credits

Custom credit adjustments will not calculate tax. If the credit you want to create reflects a charge previously billed with tax, we recommend that you refund the invoice instead of making a credit.

<adjustment><description>Bonus for being a great customer</description><unit_amount_in_cents>-2000</unit_amount_in_cents><currency>USD</currency><quantity>1</quantity><revenue_schedule_type>at_invoice</revenue_schedule_type></adjustment>

Result Format

<adjustmenthref="https://your-subdomain.recurly.com/v2/adjustments/37c0038fe1ffc9405019db4a11a99aa8"type="credit"><accounthref="https://your-subdomain.recurly.com/v2/accounts/1"/><uuid>37c0038fe1ffc9405019db4a11a99aa8</uuid><state>pending</state><description>Bonus for being a great customer</description><accounting_codenil="nil"/><product_codenil="nil"/><origin>credit</origin><unit_amount_in_centstype="integer">-2000</unit_amount_in_cents><quantitytype="integer">1</quantity><discount_in_centstype="integer">0</discount_in_cents><tax_in_centstype="integer">0</tax_in_cents><total_in_centstype="integer">-2000</total_in_cents><currency>USD</currency><taxabletype="boolean">false</taxable><tax_exempttype="boolean">false</tax_exempt><tax_codenil="nil"/><start_datetype="datetime">2016-08-03T16:24:20Z</start_date><end_datenil="nil"/><created_attype="datetime">2016-08-03T16:24:20Z</created_at><updated_attype="datetime">2016-08-03T16:24:20Z</updated_at><revenue_schedule_type>at_invoice</revenue_schedule_type></adjustment>

<errors><transaction_error><error_code>declined</error_code><error_category>soft</error_category><merchant_message>The customer's bank has declined their card. The customer will need to contact their bank to learn the cause.</merchant_message><customer_message>Your transaction was declined. Please use a different card or contact your bank.</customer_message><gateway_error_codenil="nil"/></transaction_error><errorfield="billing_info.base"symbol="declined">Your transaction was declined. Please use a different card or contact your bank.</error><transactionhref="https://your-subdomain.recurly.com/v2/transactions/3c4293ccd7f7bce494f85e4d48beb22e"type="credit_card"><accounthref="https://your-subdomain.recurly.com/v2/accounts/1"/><uuid>3c4293ccd7f7bce494f85e4d48beb22e</uuid><action>verify</action><amount_in_centstype="integer">0</amount_in_cents><tax_in_centstype="integer">0</tax_in_cents><currency>USD</currency><status>declined</status><payment_method>credit_card</payment_method><reference>676848</reference><source>billing_info</source><recurringtype="boolean">false</recurring><testtype="boolean">true</test><voidabletype="boolean">false</voidable><refundabletype="boolean">false</refundable><ip_address>127.0.0.1</ip_address><transaction_error><error_code>declined</error_code><error_category>soft</error_category><merchant_message>The customer's bank has declined their card. The customer will need to contact their bank to learn the cause.</merchant_message><customer_message>Your transaction was declined. Please use a different card or contact your bank.</customer_message><gateway_error_codenil="nil"/></transaction_error><cvv_resultcode=""nil="nil"/><avs_resultcode=""nil="nil"/><avs_result_streetnil="nil"/><avs_result_postalnil="nil"/><created_attype="datetime">2017-03-15T21:03:40Z</created_at><updated_attype="datetime">2017-03-15T21:03:40Z</updated_at><details><account><account_code>1</account_code><first_name>Verena</first_name><last_name>Example</last_name><company>New Company Name</company><email>[email protected]</email><billing_infotype="credit_card"><first_name>Verena</first_name><last_name>Example</last_name><address1>123 Main St.</address1><address2nil="nil"/><city>San Francisco</city><state>CA</state><zip>94105</zip><country>US</country><phonenil="nil"/><vat_numbernil="nil"/><card_type>Visa</card_type><yeartype="integer">2019</year><monthtype="integer">11</month><first_six>400000</first_six><last_four>0002</last_four></billing_info></account></details></transaction></errors>

{"_id":"5919d93885b2570f00e41c50","excerpt":"Creates the account's Billing Information with Bank Account details. You will need to have the ACH feature on your site for this call to work.","link_url":"","order":2,"slug":"create-an-accounts-billing-info-bank-account","__v":0,"api":{"params":[{"in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code","_id":"55944fbb0c33bd0d0005964b","ref":""},{"desc":"The name associated with the account. This may be a person's full name or a business name. This field must be 1 to 50 characters and can include: letters digits space . ' & , -","default":"","type":"string","name":"name_on_account","_id":"5581d1f08625220d00429e6d","ref":"","in":"body","required":true},{"_id":"5581d1f08625220d00429e63","ref":"","in":"body","required":true,"desc":"Must be a real U.S. bank account routing number. All routing numbers are 9 digits.","default":"","type":"int","name":"routing_number"},{"_id":"5581d1f08625220d00429e62","ref":"","in":"body","required":true,"desc":"Bank account number between 4 and 17 digits. We do not validate this number until the first transaction, so we recommend you have the customer confirm their account number.","default":"","type":"int","name":"account_number"},{"_id":"5581d1f08625220d00429e61","ref":"","in":"body","required":true,"desc":"Either 'checking' or 'savings'","default":"","type":"string","name":"account_type"},{"_id":"5581d1f08625220d00429e6c","ref":"","in":"body","required":false,"desc":"Address line 1, recommended for address validation. This field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address1"},{"_id":"5581d1f08625220d00429e6b","ref":"","in":"body","required":false,"desc":"Address line 2, this field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address2"},{"_id":"5581d1f08625220d00429e6a","ref":"","in":"body","required":false,"desc":"City, this field has a 50 character max and can include: letters digits space . , -","default":"","type":"string","name":"city"},{"name":"state","_id":"5581d1f08625220d00429e69","ref":"","in":"body","required":false,"desc":"State, this field has a 2 character max and can be lowercase or uppercase.","default":"","type":"string"},{"ref":"","in":"body","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements). **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country","_id":"5581d1f08625220d00429e68"},{"default":"","type":"string","name":"zip","_id":"5581d1f08625220d00429e67","ref":"","in":"body","required":false,"desc":"Zip or postal code, recommended for address validation. This field can be just 5 digits or can have an optional additional 4 digits separated by a hyphen (e.g. 12345-6789)."},{"default":"","type":"string","name":"phone","_id":"5581d1f08625220d00429e66","ref":"","in":"body","required":false,"desc":"Phone number, this field can be 10 digits."},{"in":"body","required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number","_id":"5581d1f08625220d00429e65","ref":""},{"desc":"Customer's IPv4 address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address","_id":"5581d1f08625220d00429e64","ref":"","in":"body","required":false}],"url":"/accounts/:account_code/billing_info","examples":{"codes":[{"name":"","code":"<?php\n\ntry {\n $billing_info = new Recurly_BillingInfo();\n $billing_info->account_code = 'b6f5783';\n $billing_info->name_on_account = 'Acme Inc.';\n $billing_info->routing_number = '065400137';\n $billing_info->account_number = '4444000000005555';\n $billing_info->account_type = 'checking';\n $billing_info->address1 = '123 Main St.';\n $billing_info->city = 'San Francisco';\n $billing_info->state ='CA';\n $billing_info->country = 'US';\n $billing_info->zip = '94105';\n $billing_info->create();\n\n print \"Billing Info: $billing_info\";\n} catch (Recurly_ValidationError $e) {\n // The data or bank account are invalid\n print \"Invalid data or card: $e\";\n} catch (Recurly_NotFoundError $e) {\n // Could not find account\n print \"Account Not Found: $e\";\n}","language":"php"},{"code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n name_on_account: 'Acme, Inc.',\n routing_number: '065400137',\n account_number: '4444000000005555',\n address1: '123 Main St.',\n city: 'San Francisco',\n state: 'CA',\n country: 'US',\n zip: '94105'\n}\naccount.billing_info.save!","language":"ruby"},{"code":"account = Account.get('1')\nbilling_info = recurly.BillingInfo(\n name_on_account = 'Acme, Inc.',\n routing_number = '065400137',\n account_number = '4444000000005555',\n account_type = 'checking',\n address1 = '123 Main St.',\n city = 'San Francisco',\n state ='CA',\n country = 'US',\n zip = '94105'\n )\naccount.update_billing_info(billing_info)","language":"python"},{"code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.NameOnAccount = \"Acme, Inc.\";\ninfo.RoutingNumber = \"065400137\";\ninfo.AccountNumber = \"4444000000005555\";\ninfo.AccountType = BillingInfo.BankAccountType.Checking;\ninfo.Address1 = \"123 Main St.\";\ninfo.City = \"San Francisco\";\ninfo.State = \"CA\";\ninfo.Country = \"US\";\ninfo.PostalCode = \"94105\";\ninfo.Create();","language":"csharp"},{"code":"<billing_info>\n <name_on_account>Acme, Inc.</name_on_account>\n <address1>123 Main St.</address1>\n <address2 nil=\"nil\"></address2>\n <city>San Francisco</city>\n <state>CA</state>\n <zip>94105</zip>\n <country>US</country>\n <routing_number>065400137</routing_number>\n <account_number>4444000000005555</account_number>\n <account_type>checking</account_type>\n <ip_address>127.0.0.1</ip_address>\n</billing_info>","language":"xml"}]},"method":"post","results":{"codes":[{"language":"xml","status":201,"name":"","code":"<billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\" type=\"bank_account\">\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <name_on_account>Acme, Inc.</name_on_account>\n <first_name nil=\"nil\"></first_name>\n <last_name nil=\"nil\"></last_name>\n <company nil=\"nil\"></company>\n <address1>123 Main St.</address1>\n <address2 nil=\"nil\"></address2>\n <city>San Francisco</city>\n <state>CA</state>\n <zip>94105</zip>\n <country>US</country>\n <phone></phone>\n <vat_number></vat_number>\n <ip_address>127.0.0.1</ip_address>\n <ip_address_country>US</ip_address_country>\n <account_type>checking</account_type>\n <last_four>5555</last_four>\n <routing_number>065400137</routing_number>\n <updated_at type=\"datetime\">2017-02-17T15:38:53Z</updated_at>\n</billing_info>"},{"code":"<errors>\n <error field=\"billing_info.routing_number\" symbol=\"invalid\">is invalid</error>\n</errors>","language":"xml","status":422}]},"settings":"","auth":"required","apiSetting":"59497f16b9248d0024fe3f3f"},"next":{"pages":[],"description":""},"user":"55648cf93b87582b003ab8b1","version":"5919d93785b2570f00e41c39","body":"Instead of using a token generated by Recurly.js, you can instead submit full bank account and address information when creating Billing Information.\n\nWhen Billing Information is submitted, it is only saved if the required fields are provided and they meet the field validation requirements. If the account has a past due invoice, the outstanding balance will be collected when the Billing Information is updated.\n\nIf you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request.\n\nThe required address fields will correspond to the **address requirements** configured for your site.\nIf you need to set a back dated subscription authorziation date for the NACHA three year re-authorization rule, do so on the Create Subscription call using the \"bank_account_authorized_at\" attribute.\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Please note\",\n \"body\": \"Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's bank account details.\"\n}\n[/block]","createdAt":"2015-06-17T20:00:48.689Z","link_external":false,"project":"555fbba928249c1900618a82","sync_unique":"","type":"post","category":"5919d93885b2570f00e41c42","githubsync":"","hidden":false,"isReference":true,"parentDoc":null,"title":"Create Account's Billing Info (Bank Account)","updates":["56ec2580df213e1700f77836"],"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate Account's Billing Info (Bank Account)

Creates the account's Billing Information with Bank Account details. You will need to have the ACH feature on your site for this call to work.

Path Params

account_code:

required

string

Account's unique code.

Body Params

name_on_account:

required

string

The name associated with the account. This may be a person's full name or a business name. This field must be 1 to 50 characters and can include: letters digits space . ' & , -

routing_number:

required

integer

Must be a real U.S. bank account routing number. All routing numbers are 9 digits.

account_number:

required

integer

Bank account number between 4 and 17 digits. We do not validate this number until the first transaction, so we recommend you have the customer confirm their account number.

account_type:

required

string

Either 'checking' or 'savings'

address1:

string

Address line 1, recommended for address validation. This field has a 50 character max and can include: letters digits space . # / , -

address2:

string

Address line 2, this field has a 50 character max and can include: letters digits space . # / , -

city:

string

City, this field has a 50 character max and can include: letters digits space . , -

state:

string

State, this field has a 2 character max and can be lowercase or uppercase.

Instead of using a token generated by Recurly.js, you can instead submit full bank account and address information when creating Billing Information.

When Billing Information is submitted, it is only saved if the required fields are provided and they meet the field validation requirements. If the account has a past due invoice, the outstanding balance will be collected when the Billing Information is updated.

If you want to create an account at the same time, you should use the Account API end-point instead and include Billing Information with your request.

The required address fields will correspond to the address requirements configured for your site.If you need to set a back dated subscription authorziation date for the NACHA three year re-authorization rule, do so on the Create Subscription call using the "bank_account_authorized_at" attribute.