{"_id":"57803084827bd50e006b0468","title":"Authentication","type":"basic","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.2' \\\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.2\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)**\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Public API Key\"\n}\n[/block]\nRecurly uses to 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.","hidden":false,"link_url":"","next":{"description":"","pages":[]},"parentDoc":null,"project":"555fbba928249c1900618a82","updates":["5595c7e9f44370190028891c","562aa244ed4bea0d00c11d8b","56bb4e10dabd992100b674f7","56f19a949791b22d0077ba0f"],"__v":14,"api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"","apiSetting":null},"githubsync":"","link_external":false,"user":"5564a0073a61a72f0067cb22","category":"57803084827bd50e006b0458","excerpt":"","slug":"getting-started","version":"57803084827bd50e006b0457","createdAt":"2015-06-10T22:06:37.745Z","isReference":false,"order":0,"sync_unique":"","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Authentication


API Authentication (HTTP Basic)

Recurly uses HTTP Basic Authentication—your Private API key is securely encrypted by the SSL channel.

If you are testing the API calls via the command line with cURL, try:

curl -H 'Accept: application/xml' \
     -H 'X-Api-Version: 2.2' \
     -H 'Content-Type: application/xml; charset=utf-8' \
     -u '[apikey]:' \
    https://[subdomain].recurly.com/v2/accounts

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.2

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

Acceptable API versions

Recurly supports the following API versions: 2.0, 2.1, 2.2, 2.3, 2.4, 2.5

Public API Key

Recurly uses to 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:

  1. Block the old key immediately. This is primarily recommended when the security of a key has been compromised.
  2. 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.

View all 89 endpoints
{"_id":"578d57849a98a41900717e68","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.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.2\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.2\nThis release focused on supporting our new [Usage-Based Billing](https://docs.recurly.com/docs/usage-based-billing) feature.\n\nAdded endpoints for managing Measured Units:\n- [List Measured Units](doc:list-measured-units)\n- [Create Measured Unit](doc:create-measured-unit)\n- [Lookup Measured Unit](doc:lookup-measured-unit)\n- [Update Measured Unit](doc:update-measured-unit)\n- [Delete Measured Unit](doc:delete-measured-unit)\n\nAdded endpoints for managing Usage-Based Billing:\n- [List a Subscription Add-On's Usage](doc:list-add-ons-usage)\n- [Log Usage](doc:log-usage)\n- [Lookup Usage Record](doc:lookup-usage-record)\n- [Update Usage Record](doc:update-usage)\n- [Delete Usage Record](doc:delete-a-usage-record)\n\nDetailed listing of changes to requests and responses:\n- Changed Account response:\n  - Added `<updated_at>` element.\n- Changed Add-On response:\n  - Added `<measured_unit>` link element.\n  - Added `<add_on_type>` element.\n  - Added `<usage_type>` element.\n  - Added `<usage_percentage>` element.\n  - Added `<updated_at>` element.\n- Changed Adjustment response:\n  - Added `<updated_at>` element.\n- Changed Coupon response:\n  - Added `<updated_at>` element.\n- Changed Invoice response:\n  - Added `<updated_at>` element.\n- Changed Plan response:\n  - Added `<updated_at>` element.\n- Changed Redemption response:\n  - Added `<updated_at>` element.\n- Changed Subscription response:\n  - Added the following to `<subscription_add_on>`:\n    - `<add_on_type>` element.\n    - `<measured_unit>` link element.\n    - `<usage>` link element.\n    - `<unit_amount_in_cents>` element.\n  - Added `<updated_at>` element.\n- Changed Transaction response:\n  - Added `<updated_at>` element.\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":"57803084827bd50e006b0458","link_external":false,"link_url":"","next":{"description":"","pages":[]},"title":"API Versioning","__v":17,"isReference":false,"order":1,"type":"basic","user":"559d85d26b21311700fb0b7b","api":{"params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","url":"","auth":"required","apiSetting":null},"createdAt":"2016-07-18T22:26:12.882Z","excerpt":"","githubsync":"","sync_unique":"","updates":[],"hidden":false,"parentDoc":null,"project":"555fbba928249c1900618a82","slug":"versioning","version":"57803084827bd50e006b0457","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.

Recurly offers the following API versions: 2.5, 2.4, 2.3, 2.2, 2.1, 2.0.

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.2

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:

Recurly-Deprecated: TRUE
Recurly-Sunset-Date: 2018-06-01T00:00:00+00:00

The sunset date is an ISO 8601 date time when the version will no longer be accessible.

Your integration should check for those headers so you can make updates in a timely fashion.

Changes in v2.2

This release focused on supporting our new Usage-Based Billing feature.

Added endpoints for managing Measured Units:

Added endpoints for managing Usage-Based Billing:

Detailed listing of changes to requests and responses:

  • Changed Account response:
    • Added <updated_at> element.
  • Changed Add-On response:
    • Added <measured_unit> link element.
    • Added <add_on_type> element.
    • Added <usage_type> element.
    • Added <usage_percentage> element.
    • Added <updated_at> element.
  • Changed Adjustment response:
    • Added <updated_at> element.
  • Changed Coupon response:
    • Added <updated_at> element.
  • Changed Invoice response:
    • Added <updated_at> element.
  • Changed Plan response:
    • Added <updated_at> element.
  • Changed Redemption response:
    • Added <updated_at> element.
  • Changed Subscription response:
    • Added the following to <subscription_add_on>:
      • <add_on_type> element.
      • <measured_unit> link element.
      • <usage> link element.
      • <unit_amount_in_cents> element.
    • Added <updated_at> element.
  • Changed Transaction response:
    • Added <updated_at> element.

A complete list of changes for all versions is available on the API Release Notes page.

{"_id":"57803084827bd50e006b046a","type":"basic","updates":["57a0bb3d1435850e00dfbc67"],"category":"57803084827bd50e006b0458","githubsync":"","link_url":"","sync_unique":"","title":"Pagination","user":"55648cf93b87582b003ab8b1","createdAt":"2015-06-15T22:48:39.567Z","isReference":false,"slug":"pagination","version":"57803084827bd50e006b0457","__v":2,"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\"\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=1304958672>; rel=\"next\"\nETag: \"a4b0568a2278bc591ceb64b31547eb78\"\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Cursors\"\n}\n[/block]\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\": \"Previous Pages\"\n}\n[/block]\nAfter paginating beyond the first page of results, the Link header will include a link to return to the first page of results (`rel=\"start\"`) and the previous page (`rel=\"prev\"`):\n\n```\nStatus: 200 OK\nX-Records: 204\nLink: <https://your-subdomain.recurly.com/v2/transactions>; rel=\"start\",\n  <https://your-subdomain.recurly.com/v2/transactions?cursor=-1318344434>; rel=\"prev\",\n  <https://your-subdomain.recurly.com/v2/transactions?cursor=1318388868>; rel=\"next\"\nETag: \"c7431fcfc386fd59ee6c3c2e9ac2a30c\"\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}\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]","project":"555fbba928249c1900618a82","link_external":false,"order":2,"parentDoc":null,"api":{"auth":"required","params":[],"results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","url":"","apiSetting":null},"excerpt":"","hidden":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

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.

Status: 200 OK
X-Records: 204
Link: <https://your-subdomain.recurly.com/v2/accounts?cursor=1304958672>; rel="next"
ETag: "a4b0568a2278bc591ceb64b31547eb78"

Cursors

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.

Previous Pages

After paginating beyond the first page of results, the Link header will include a link to return to the first page of results (rel="start") and the previous page (rel="prev"):

Status: 200 OK
X-Records: 204
Link: <https://your-subdomain.recurly.com/v2/transactions>; rel="start",
  <https://your-subdomain.recurly.com/v2/transactions?cursor=-1318344434>; rel="prev",
  <https://your-subdomain.recurly.com/v2/transactions?cursor=1318388868>; rel="next"
ETag: "c7431fcfc386fd59ee6c3c2e9ac2a30c"
<?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 account
foreach ($invoices as $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 -> Invoices

account = Recurly::Account.find('my_account_code')

puts account.invoices.class
#=> Recurly::Resource::Pager

# Pager#each can be used to iterate through the only the given page
account.invoices.each do |invoice|
  puts invoice.invoice_number
end

# 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 left
account.invoices.find_each do |invoice|
  puts invoice.invoice_number
end

# You can also create a Pager directly from a resource
puts Recurly::Invoice.paginate.class
#=> Recurly::Resource::Pager

# paginate takes options
Recurly::Invoice.paginate(per_page: 10).each do |invoice|
  puts invoice.invoice_number
end

# You can also use #find_each directly on the resource
Recurly::Invoice.find_each(per_page: 10).each do |invoice|
  puts invoice.invoice_number
end
# 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 -> Invoices

account = recurly.Account.get('tester')

print account.invoices
# => <function relatitator at 0x1023628c0>

print account.invoices().__class__
# => <class 'recurly.resource.Page'>

# To page through every invoice on the account
for invoice in account.invoices():
    print invoice.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:
for invoice in recurly.Invoice.all():
    print invoice.invoice_number

PHP Pagination

The PHP Recurly_Pager class sets up an iterator across all the relevant records. It does not provide pagination functionality by default.

{"_id":"57803084827bd50e006b046b","githubsync":"","hidden":false,"title":"Rate Limits","type":"basic","user":"55648cf93b87582b003ab8b1","api":{"auth":"required","params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","apiSetting":null},"createdAt":"2015-06-15T22:49:59.038Z","order":3,"project":"555fbba928249c1900618a82","sync_unique":"","updates":[],"version":"57803084827bd50e006b0457","excerpt":"","isReference":false,"link_external":false,"next":{"description":"","pages":[]},"slug":"rate-limits","__v":1,"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\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":"57803084827bd50e006b0458","link_url":"","parentDoc":null,"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:

  • Sandbox sites: 400 requests/min. All requests count towards the rate limit.
  • 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.

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.

HTTP Headers

Every authenticated API request returns headers with your current rate limit information. Your requests’ rate limit headers may look like:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1414622019

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":"57803084827bd50e006b0469","hidden":false,"link_url":"","project":"555fbba928249c1900618a82","updates":["56cd46e949abf10b0036a1e6","579a0c78ebcc7419003c0db7"],"parentDoc":null,"type":"basic","version":"57803084827bd50e006b0457","api":{"params":[],"results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"","auth":"required","apiSetting":null},"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```","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.","link_external":false,"slug":"welcome","sync_unique":"","user":"5564a0073a61a72f0067cb22","__v":3,"githubsync":"","isReference":false,"category":"57803084827bd50e006b0458","createdAt":"2015-06-10T22:06:26.211Z","order":4,"title":"HTTP Status Codes","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 OK
The request was successful.
201 Created
The resource was successfully created. Confirms a success when creating a new account, credit, subscription, etc.
204 No Content
The request was successful and there is no response body.

CLIENT ERROR STATUS CODES (4XX)

400 Bad Request
The 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 Unauthorized
Your API key is missing or invalid.
402 Payment Required
Your Recurly account is in production mode but is not in good standing. Please pay any outstanding invoices.
403 Forbidden
The 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 Found
The resource was not found with the given identifier. The response body will explain which resource was not found.
405 Method Not Allowed
The requested method is not valid at the given URL.
406 Not Acceptable
The request's Accept header is not set to application/xml.
412 Precondition Failed
The 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 Entity
Could not process a POST or PUT request because the request is invalid. See the response body for more details.
429 Too many Requests
You have made too many API requests in the last hour. Future API requests will be ignored until the beginning of the next hour.

SERVER ERROR STATUS CODES (5XX)

500 Internal Server Error
The server encountered an error while processing your request and failed.
502 Gateway Error
The load balancer or web server has trouble connecting to the Recurly app. Please try the request again.
503 Service Unavailable
The service is temporarily unavailable. Please try the request again.

FUTURE COMPATIBILITY

For future compatibility, please interpret the following status code ranges:

200–299 as success,
400–499 as client request errors,
500–599 as server errors

404 Not Found Responses

When a lookup, update, or delete request is requested on an object that does not exist, the server returns 404 Not Found:

Status: 404 Not Found
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <symbol>not_found</symbol>
  <description>The record could not be located.</description>
</error>

422 Unprocessable Entity Responses

If 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:

Status: 422 Unprocessable Entity
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error field="model_name.field_name" symbol="not_a_number" lang="en-US">is not a number</error>
</errors>
{"_id":"57803084827bd50e006b047a","link_url":"","sync_unique":"","title":"Client Libraries","user":"55648cf93b87582b003ab8b1","createdAt":"2015-06-26T18:25:56.960Z","githubsync":"","link_external":false,"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)","slug":"client-libraries","type":"basic","__v":0,"api":{"params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","auth":"required","apiSetting":null},"updates":["55940e20fd29b92300c262bf","55b2bfc0a74a380d00e290a6","55b2c0466862a10d00887adf","55bbb926a8400c2d00873f2a","565f689e413e06170093df6a"],"version":"57803084827bd50e006b0457","excerpt":"","isReference":false,"project":"555fbba928249c1900618a82","parentDoc":null,"category":"57803084827bd50e006b045a","hidden":false,"order":0,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Client Libraries


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

PHP
Ruby
Python
.Net
iOS – Github | Documentation
Android

There are also some unofficial libraries created by our users

Java
GO
Node.js

{"_id":"57803084827bd50e006b049e","category":"57803084827bd50e006b045c","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.","githubsync":"","isReference":true,"parentDoc":null,"sync_unique":"","api":{"auth":"required","examples":{"codes":[{"language":"text","code":""}]},"method":"get","params":[{"default":"","type":"string","name":"username","_id":"55e4aa556f190c1900a4087c","ref":"","in":"query","required":false,"desc":"The username of the account."},{"default":"","type":"string","name":"first_name","_id":"55e4aa556f190c1900a4087a","ref":"","in":"query","required":false,"desc":"The first name of the account."},{"in":"query","required":false,"desc":"The state of accounts to return: `active` or `closed`.","default":"","type":"string","name":"state","_id":"55e4aa556f190c1900a4087d","ref":""},{"desc":"The last name of the account.","default":"","type":"string","name":"last_name","_id":"55e4aa556f190c1900a40879","ref":"","in":"query","required":false},{"name":"adjustments","_id":"557f45d07eafa719001d1c2b","ref":"","in":"query","required":false,"desc":"The URL of adjustments for the specified account.","default":"","type":"string"},{"type":"string","name":"account_code","_id":"55e4aa556f190c1900a4087e","ref":"","in":"query","required":false,"desc":"The unique identifier of the account.","default":""},{"required":false,"desc":"The company name of the account.","default":"","type":"string","name":"company_name","_id":"55e4aa556f190c1900a40878","ref":"","in":"query"},{"type":"string","name":"invoices","_id":"557f45d07eafa719001d1c29","ref":"","in":"query","required":false,"desc":"The URL of invoices for the specified account.","default":""},{"required":false,"desc":"The URL of billing info for the specified account.","default":"","type":"string","name":"billing_info","_id":"557f45d07eafa719001d1c2a","ref":"","in":"query"},{"type":"string","name":"vat_number","_id":"55e4aa556f190c1900a40877","ref":"","in":"query","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":"query"},{"type":"string","name":"subscriptions","_id":"55e4aa556f190c1900a40880","ref":"","in":"query","required":false,"desc":"The URL of subscriptions for the specified account.","default":""},{"desc":"The URL of the coupon redemption for the specified account.","default":"","type":"string","name":"redemption","_id":"55e4aa556f190c1900a40881","ref":"","in":"query","required":false},{"_id":"55e4aa556f190c1900a4087f","ref":"","in":"query","required":false,"desc":"The URL of transactions for the specified account.","default":"","type":"string","name":"transactions"},{"name":"email","_id":"55e4aa556f190c1900a4087b","ref":"","in":"query","required":false,"desc":"The email address of the account.","default":"","type":"string"},{"type":"array_string","name":"cc_emails","_id":"560b18973bcbd80d0077d0c0","ref":"","in":"query","required":false,"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":""},{"required":false,"desc":"The nested address information of the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`.","default":"","type":"object","name":"address","_id":"55e4aa556f190c1900a40875","ref":"","in":"query"},{"ref":"","in":"query","required":false,"desc":"The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.","default":"","type":"string","name":"accept_language","_id":"55e4aa556f190c1900a40874"},{"in":"query","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":"","type":"string","name":"hosted_login_token","_id":"55e4aa556f190c1900a40873","ref":""},{"required":false,"desc":"The date and time the account was created in Recurly.","default":"","type":"datetime","name":"created_at","_id":"55e4aa556f190c1900a40872","ref":"","in":"query"},{"type":"datetime","name":"updated_at","_id":"5783dc55359cd219005453ec","ref":"","in":"query","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":"query","required":false}],"results":{"codes":[{"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  <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","status":200,"name":""}]},"settings":"","url":"/accounts","apiSetting":"59497f16b9248d0024fe3f31"},"editedParams":true,"project":"555fbba928249c1900618a82","type":"get","user":"55648cf93b87582b003ab8b1","link_external":false,"body":"","createdAt":"2015-08-31T20:16:33.273Z","editedParams2":true,"hidden":false,"link_url":"","order":0,"slug":"account-object","title":"Account Object","__v":5,"version":"57803084827bd50e006b0457","updates":["56cec52444c5700b0095c02b"],"next":{"pages":[]},"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.

Query Params

username:
string
The username of the account.
first_name:
string
The first name of the account.
state:
string
The state of accounts to return: `active` or `closed`.
last_name:
string
The last name of the account.
adjustments:
string
The URL of adjustments for the specified account.
account_code:
string
The unique identifier of the account.
company_name:
string
The company name of the account.
invoices:
string
The URL of invoices for the specified account.
billing_info:
string
The URL of billing info for the specified 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.
subscriptions:
string
The URL of subscriptions for the specified account.
redemption:
string
The URL of the coupon redemption for the specified account.
transactions:
string
The URL of transactions for the specified 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.
address:
object
The nested address information of the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`.
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`.
created_at:
datetime
The date and time the account was created in Recurly.
updated_at:
datetime
The date and time the account or its billing info was last updated.
closed_at:
datetime
For closed accounts, the date and time it was closed.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
  <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
  <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
  <redemptions href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions"/>
  <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>[email protected]</email>
  <cc_emails>[email protected],[email protected]</cc_emails>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company_name>New Company Name</company_name>
  <vat_number nil="nil"/>
  <tax_exempt type="boolean">false</tax_exempt>
  <address>
    <address1>123 Main St.</address1>
    <address2 nil="nil"/>
    <city>San Francisco</city>
    <state>CA</state>
    <zip>94105</zip>
    <country>US</country>
    <phone nil="nil"/>
  </address>
  <accept_language nil="nil"/>
  <hosted_login_token>96e74bd5e14d18e6da463a0d638a2621</hosted_login_token>
  <created_at type="datetime">2016-07-08T20:59:43Z</created_at>
  <updated_at type="datetime">2016-07-11T17:56:24Z</updated_at>
  <closed_at nil="nil"/>
</account>


{"_id":"57803084827bd50e006b049f","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]","link_external":false,"parentDoc":null,"sync_unique":"","githubsync":"","type":"get","updates":["55f1f9abd4d3160d00439b6c"],"version":"57803084827bd50e006b0457","__v":1,"createdAt":"2015-06-15T21:38:24.720Z","hidden":false,"isReference":true,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"list-accounts","user":"55648cf93b87582b003ab8b1","api":{"params":[{"default":"","desc":"The state of accounts to return: `active`, `closed`, `subscriber`, `non_subscriber`, `past_due`.","in":"query","name":"state","ref":"","required":false,"type":"string","_id":"56465088054d8f0d00bc76aa"},{"type":"int","name":"cursor","in":"query","_id":"56d8bace7ce7550b00c81d78","ref":"","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":""},{"required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page","in":"query","_id":"56d8bace7ce7550b00c81d77","ref":""}],"results":{"codes":[{"name":"","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    <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    <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>\n  <!-- Continued... -->\n</accounts>","language":"xml","status":200}]},"settings":"","url":"/accounts","auth":"required","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"},{"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}","language":"csharp","name":null}]},"method":"get","apiSetting":"59497f16b9248d0024fe3f31"},"category":"57803084827bd50e006b045c","editedParams":true,"editedParams2":true,"excerpt":"Returns a list of accounts on your site. Results are ordered by the time created, sorted by newest first.","title":"List Accounts","next":{"pages":[]},"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`.
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.
per_page:
integer50
Number of records to return per page, up to a maximum of 200.

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.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

$accounts = Recurly_AccountList::getActive();
foreach ($accounts as $account) {
  print "Account: $account\n";
}
Recurly::Account.find_each do |account|
  puts "Account: #{account.inspect}"
end
#client version 2.1.6+
for account in Account.all():
    print 'Account: %s' % account

#client version <= 2.1.5
accounts = Account.all()
while accounts:
    for account in accounts:
        print 'Account: %s' % account
    try:
        accounts = accounts.next_page()
    except PageError:
        accounts = ()
using System.Linq;

var accounts = Accounts.List();
while (accounts.Any())
{
	foreach (var account in accounts)
		Console.WriteLine(account);
	accounts = accounts.Next;
}

Result Format

<accounts type="array">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1">
    <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
    <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
    <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
    <redemptions href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions"/>
    <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
    <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
    <account_code>1</account_code>
    <state>active</state>
    <username>verena1234</username>
    <email>[email protected]</email>
    <cc_emails>[email protected],[email protected]</cc_emails>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name>New Company Name</company_name>
    <vat_number nil="nil"/>
    <tax_exempt type="boolean">false</tax_exempt>
    <address>
      <address1>123 Main St.</address1>
      <address2 nil="nil"/>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94105</zip>
      <country>US</country>
      <phone nil="nil"/>
    </address>
    <accept_language nil="nil"/>
    <hosted_login_token>96e74bd5e14d18e6da463a0d638a2621</hosted_login_token>
    <created_at type="datetime">2016-07-08T20:59:43Z</created_at>
    <updated_at type="datetime">2016-07-11T17:56:24Z</updated_at>
    <closed_at nil="nil"/>
  </account>
  <!-- Continued... -->
</accounts>


{"_id":"57803084827bd50e006b04a1","user":"55648cf93b87582b003ab8b1","version":"57803084827bd50e006b0457","api":{"results":{"codes":[{"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  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\"/>\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>Recurly Inc</company_name>\n  <vat_number nil=\"nil\"/>\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>3ed66441313a90bd7e8039b31985dee8</hosted_login_token>\n  <created_at type=\"datetime\">2016-06-14T16:08:41Z</created_at>\n  <closed_at nil=\"nil\"/>\n</account>","language":"xml","status":201}]},"settings":"","url":"/accounts","auth":"required","examples":{"codes":[{"code":"<?php\n  \ntry {\n  $account = new Recurly_Account('b6f5783');\n  $account->email = '[email protected]';\n  $account->first_name = 'Verena';\n  $account->last_name = 'Example';\n  $account->create();\n\n  print \"Account: $account\\n\";\n\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Account: $e\";\n}","language":"php","name":""},{"code":"account = Recurly::Account.create(\n  :account_code => '1',\n  :email        => '[email protected]',\n  :first_name   => 'Verena',\n  :last_name    => 'Example'\n)","language":"ruby"},{"code":"account = Account(account_code='1')\naccount.email = '[email protected]'\naccount.first_name = 'Verena'\naccount.last_name = 'Example'\naccount.save()","language":"python"},{"code":"var account = new Account(\"1\")\n{\n  Email = \"[email protected]\",\n  FirstName = \"Verena\",\n  LastName = \"Example\"\n};\naccount.Create();","language":"csharp"},{"language":"xml","code":"<account>\n  <account_code>1</account_code>\n  <email>[email protected]</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <username>verena1234</username>\n  <cc_emails>[email protected],[email protected]</cc_emails>\n  <company_name>Recurly Inc</company_name>\n  <address>\n    <address1>123 Main St.</address1>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n  </address>\n</account>"}]},"method":"post","params":[{"desc":"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.","in":"body","name":"account_code","ref":"","required":true,"type":"string","_id":"557f3209e211d20d00601425","default":""},{"in":"body","name":"username","ref":"","required":false,"type":"string","_id":"557f3209e211d20d00601424","default":"","desc":"The username for the account, ignore if you do not use usernames. Max of 255 characters."},{"required":false,"type":"string","_id":"557f3209e211d20d00601423","default":"","desc":"The email address for the account.","in":"body","name":"email","ref":""},{"name":"first_name","ref":"","required":false,"type":"string","_id":"557f32d1e211d20d00601430","default":"","desc":"The first name for the account. Max of 255 characters.","in":"body"},{"type":"string","_id":"557f32d1e211d20d0060142f","default":"","desc":"The last name for the account.  Max of 255 characters.","in":"body","name":"last_name","ref":"","required":false},{"default":"","desc":"The company name for the account. Max of 50 characters.","in":"body","name":"company_name","ref":"","required":false,"type":"string","_id":"557f32d1e211d20d0060142e"},{"ref":"","required":false,"type":"string","_id":"557f32d1e211d20d0060142d","default":"","desc":"The VAT number to avoid having the VAT applied (if applicable).","in":"body","name":"vat_number"},{"ref":"","required":false,"type":"boolean","_id":"557f32d1e211d20d0060142c","default":"","desc":"The tax status for the account.","in":"body","name":"tax_exempt"},{"desc":"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.","in":"body","name":"entity_use_code","ref":"","required":false,"type":"string","_id":"557f32d1e211d20d0060142b","default":""},{"name":"billing_info","ref":"","required":false,"type":"object","_id":"557f32d1e211d20d0060142a","default":"","desc":"The nested billing information. If present, the account will only be created after the billing information is validated.","in":"body"},{"_id":"557f32d1e211d20d00601429","default":"","desc":"The nested address information for the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`.","in":"body","name":"address","ref":"","required":false,"type":"object"},{"type":"string","_id":"557f32d1e211d20d00601428","default":"","desc":"The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.","in":"body","name":"accept_language","ref":"","required":false},{"ref":"","required":false,"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","in":"body","_id":"561c362cd308ee0d00749370"}],"apiSetting":"59497f16b9248d0024fe3f31"},"editedParams2":true,"hidden":false,"isReference":true,"parentDoc":null,"createdAt":"2015-06-15T20:12:03.880Z","excerpt":"Creates a new account. You may optionally include billing information.","order":2,"__v":1,"category":"57803084827bd50e006b045c","editedParams":true,"type":"post","sync_unique":"","title":"Create an Account","body":"","githubsync":"","link_external":false,"link_url":"","project":"555fbba928249c1900618a82","slug":"create-an-account","updates":["562908002c0fd9190067da26"],"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate an 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.
billing_info:
object
The nested billing information. If present, the account will only be created after the billing information is validated.
address:
object
The nested address information for the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`.
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.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php
  
try {
  $account = new Recurly_Account('b6f5783');
  $account->email = '[email protected]';
  $account->first_name = 'Verena';
  $account->last_name = 'Example';
  $account->create();

  print "Account: $account\n";

} catch (Recurly_ValidationError $e) {
  print "Invalid Account: $e";
}
account = Recurly::Account.create(
  :account_code => '1',
  :email        => '[email protected]',
  :first_name   => 'Verena',
  :last_name    => 'Example'
)
account = Account(account_code='1')
account.email = '[email protected]'
account.first_name = 'Verena'
account.last_name = 'Example'
account.save()
var account = new Account("1")
{
  Email = "[email protected]",
  FirstName = "Verena",
  LastName = "Example"
};
account.Create();
<account>
  <account_code>1</account_code>
  <email>[email protected]</email>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <username>verena1234</username>
  <cc_emails>[email protected],[email protected]</cc_emails>
  <company_name>Recurly Inc</company_name>
  <address>
    <address1>123 Main St.</address1>
    <city>San Francisco</city>
    <state>CA</state>
    <zip>94105</zip>
    <country>US</country>
  </address>
</account>

Result Format

<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
  <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
  <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
  <redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemption"/>
  <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>[email protected]</email>
  <cc_emails>[email protected],[email protected]</cc_emails>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company_name>Recurly Inc</company_name>
  <vat_number nil="nil"/>
  <address>
    <address1>123 Main St.</address1>
    <address2 nil="nil"/>
    <city>San Francisco</city>
    <state>CA</state>
    <zip>94105</zip>
    <country>US</country>
    <phone nil="nil"/>
  </address>
  <accept_language nil="nil"/>
  <hosted_login_token>3ed66441313a90bd7e8039b31985dee8</hosted_login_token>
  <created_at type="datetime">2016-06-14T16:08:41Z</created_at>
  <closed_at nil="nil"/>
</account>


{"_id":"57803084827bd50e006b04a0","__v":1,"body":"","type":"get","createdAt":"2015-06-15T21:45:49.420Z","isReference":true,"project":"555fbba928249c1900618a82","version":"57803084827bd50e006b0457","link_external":false,"link_url":"","parentDoc":null,"title":"Get Account","category":"57803084827bd50e006b045c","editedParams":true,"excerpt":"Returns information about a single account.","hidden":false,"slug":"get-account","sync_unique":"","updates":["55bbdd4e1067fc1700510eed"],"user":"55648cf93b87582b003ab8b1","api":{"examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $account = Recurly_Account::get('1');\n  print \"Account: $account\\n\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Account not found.\\n\";\n}","name":""},{"language":"ruby","code":"begin\n  account = Recurly::Account.find '1'\n  puts \"Account: #{account.inspect}\"\nrescue Recurly::Resource::NotFound => e\n  puts e.message\nend"},{"language":"python","code":"try:\n  account = Account.get('1')\n  print \"Account: %s\" % account\nexcept NotFoundError:\n  print \"Account not found.\\n\""},{"language":"csharp","code":"try\n{\n\tvar account = Accounts.Get(\"1\");\n\tConsole.WriteLine(\"Account \" + account);\n}\ncatch (NotFoundException e)\n{\n\tConsole.WriteLine(\"Account not found.\");\n}"}]},"method":"get","params":[{"type":"string","_id":"557f478deb75d80d00af4086","default":"","desc":"Account's unique code.","in":"path","name":"account_code","ref":"","required":true}],"results":{"codes":[{"status":200,"language":"xml","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  <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>","name":""}]},"settings":"","url":"/accounts/:account_code","auth":"required","apiSetting":"59497f16b9248d0024fe3f31"},"editedParams2":true,"githubsync":"","order":3,"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getGet Account

Returns information about a single account.

Path Params

account_code:
required
string
Account's unique code.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $account = Recurly_Account::get('1');
  print "Account: $account\n";
} catch (Recurly_NotFoundError $e) {
  print "Account not found.\n";
}
begin
  account = Recurly::Account.find '1'
  puts "Account: #{account.inspect}"
rescue Recurly::Resource::NotFound => e
  puts e.message
end
try:
  account = Account.get('1')
  print "Account: %s" % account
except NotFoundError:
  print "Account not found.\n"
try
{
	var account = Accounts.Get("1");
	Console.WriteLine("Account " + account);
}
catch (NotFoundException e)
{
	Console.WriteLine("Account not found.");
}

Result Format

<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
  <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
  <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
  <redemptions href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions"/>
  <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>[email protected]</email>
  <cc_emails>[email protected],[email protected]</cc_emails>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company_name>New Company Name</company_name>
  <vat_number nil="nil"/>
  <tax_exempt type="boolean">false</tax_exempt>
  <address>
    <address1>123 Main St.</address1>
    <address2 nil="nil"/>
    <city>San Francisco</city>
    <state>CA</state>
    <zip>94105</zip>
    <country>US</country>
    <phone nil="nil"/>
  </address>
  <accept_language nil="nil"/>
  <hosted_login_token>96e74bd5e14d18e6da463a0d638a2621</hosted_login_token>
  <created_at type="datetime">2016-07-08T20:59:43Z</created_at>
  <updated_at type="datetime">2016-07-11T17:56:24Z</updated_at>
  <closed_at nil="nil"/>
</account>


{"_id":"57803084827bd50e006b04a2","__v":6,"editedParams2":true,"link_external":false,"link_url":"","order":4,"slug":"update-account","sync_unique":"","excerpt":"Updates an existing account.","githubsync":"","hidden":false,"isReference":true,"project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","api":{"params":[{"type":"string","name":"vat_number","_id":"557f4a527eafa719001d1c3d","ref":"","in":"body","required":false,"desc":"The VAT number to avoid having the VAT applied (if applicable).","default":""},{"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":"557f4a527eafa719001d1c3c","ref":"","in":"body","required":false},{"name":"account_code","_id":"557f4a527eafa719001d1c43","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string"},{"type":"string","name":"email","_id":"557f4a527eafa719001d1c41","ref":"","in":"body","required":false,"desc":"The email address for the account.","default":""},{"required":false,"desc":"The username for the account, ignore if you do not use usernames. Max of 255 characters.","default":"","type":"string","name":"username","_id":"557f4a527eafa719001d1c42","ref":"","in":"body"},{"ref":"","in":"body","required":false,"desc":"The last name for the account. Max of 255 characters.","default":"","type":"string","name":"last_name","_id":"557f4a527eafa719001d1c3f"},{"in":"body","required":false,"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":"561c3606d468a60d00f51ebe","ref":""},{"desc":"The first name for the account. Max of 255 characters.","default":"","type":"string","name":"first_name","_id":"557f4a527eafa719001d1c40","ref":"","in":"body","required":false},{"_id":"557f4a527eafa719001d1c3e","ref":"","in":"body","required":false,"desc":"The company name for the account. Max of 255 characters.","default":"","type":"string","name":"company_name"},{"_id":"557f4a527eafa719001d1c3b","ref":"","in":"body","required":false,"desc":"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.","default":"","type":"string","name":"entity_use_code"},{"name":"billing_info","_id":"557f4a527eafa719001d1c3a","ref":"","in":"body","required":false,"desc":"The nested billing information. If present, the account will only be created after the billing information is validated.","default":"","type":"object"},{"ref":"","in":"body","required":false,"desc":"The nested address information for the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`.","default":"","type":"object","name":"address","_id":"557f4a527eafa719001d1c39"},{"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","name":"accept_language","_id":"557f4a527eafa719001d1c38","ref":""}],"results":{"codes":[{"status":200,"language":"xml","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  <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-11T19:04:26Z</updated_at>\n  <closed_at nil=\"nil\"/>\n</account>","name":""}]},"settings":"","url":"/accounts/:account_code","auth":"required","examples":{"codes":[{"name":"","code":"<?php\n\ntry {\n  $account = Recurly_Account::get('b6f5783');\n  $account->company_name = 'New Company Name';\n  $account->update();\n\n  print \"Account: $account\\n\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid account code: $e\";\n}","language":"php"},{"code":"account = Recurly::Account.find('account_1')\naccount.company_name = 'New Company Name'\naccount.save","language":"ruby"},{"language":"python","code":"account = Account.get('account_1')\naccount.company_name = 'New Company Name'\naccount.save()"},{"code":"var account = Account.Get(\"account_1\");\naccount.CompanyName = 'New Company Name'\naccount.Update();","language":"csharp"},{"code":"<account>\n  <company_name>New Company Name</company_name>\n</account>","language":"xml"}]},"method":"put","apiSetting":"59497f16b9248d0024fe3f31"},"createdAt":"2015-06-15T21:57:38.556Z","editedParams":true,"parentDoc":null,"type":"put","updates":["568ffb69769f210d00132584"],"body":"[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Please note\",\n  \"body\": \"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.\"\n}\n[/block]","category":"57803084827bd50e006b045c","title":"Update Account","version":"57803084827bd50e006b0457","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

putUpdate Account

Updates an existing account.

Path Params

account_code:
required
string
Account's unique code.

Body Params

vat_number:
string
The VAT number to avoid having the VAT applied (if applicable).
tax_exempt:
boolean
The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account.
email:
string
The email address for the account.
username:
string
The username for the account, ignore if you do not use usernames. Max of 255 characters.
last_name:
string
The last name for the account. Max of 255 characters.
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 for the account. Max of 255 characters.
company_name:
string
The company name for the account. Max of 255 characters.
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.
billing_info:
object
The nested billing information. If present, the account will only be created after the billing information is validated.
address:
object
The nested address information for the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`.
accept_language:
string
The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.

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.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $account = Recurly_Account::get('b6f5783');
  $account->company_name = 'New Company Name';
  $account->update();

  print "Account: $account\n";
} catch (Recurly_NotFoundError $e) {
  print "Invalid account code: $e";
}
account = Recurly::Account.find('account_1')
account.company_name = 'New Company Name'
account.save
account = Account.get('account_1')
account.company_name = 'New Company Name'
account.save()
var account = Account.Get("account_1");
account.CompanyName = 'New Company Name'
account.Update();
<account>
  <company_name>New Company Name</company_name>
</account>

Result Format

<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
  <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
  <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
  <redemptions href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions"/>
  <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>[email protected]</email>
  <cc_emails>[email protected],[email protected]</cc_emails>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company_name>New Company Name</company_name>
  <vat_number nil="nil"/>
  <tax_exempt type="boolean">false</tax_exempt>
  <address>
    <address1>123 Main St.</address1>
    <address2 nil="nil"/>
    <city>San Francisco</city>
    <state>CA</state>
    <zip>94105</zip>
    <country>US</country>
    <phone nil="nil"/>
  </address>
  <accept_language nil="nil"/>
  <hosted_login_token>96e74bd5e14d18e6da463a0d638a2621</hosted_login_token>
  <created_at type="datetime">2016-07-08T20:59:43Z</created_at>
  <updated_at type="datetime">2016-07-11T19:04:26Z</updated_at>
  <closed_at nil="nil"/>
</account>


{"_id":"57803084827bd50e006b04a3","user":"55648cf93b87582b003ab8b1","version":"57803084827bd50e006b0457","hidden":false,"order":5,"updates":[],"link_url":"","parentDoc":null,"githubsync":"","link_external":false,"project":"555fbba928249c1900618a82","slug":"close-account","__v":1,"body":"[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Please note\",\n  \"body\": \"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).\"\n}\n[/block]","category":"57803084827bd50e006b045c","createdAt":"2015-06-15T22:00:42.004Z","editedParams":true,"editedParams2":true,"excerpt":"Marks an account as closed and cancels any active subscriptions.","isReference":true,"api":{"params":[{"default":"","desc":"Account's unique code.","in":"path","name":"account_code","ref":"","required":true,"type":"string","_id":"55944ebb5c9eaa2300a86337"}],"results":{"codes":[{"code":"","name":"","status":200,"language":"xml"}]},"settings":"","url":"/accounts/:account_code","auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $account = Recurly_Account::get('b6f5783');\n  $account->close();\n\n  print \"Account: $account\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid account code: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.destroy"},{"language":"python","code":"account = Account.get('1')\naccount.delete()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\naccount.Close();"}]},"method":"delete","apiSetting":"59497f16b9248d0024fe3f31"},"type":"delete","sync_unique":"","title":"Close Account","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

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).

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $account = Recurly_Account::get('b6f5783');
  $account->close();

  print "Account: $account";
} catch (Recurly_NotFoundError $e) {
  print "Invalid account code: $e";
}
account = Recurly::Account.find('1')
account.destroy
account = Account.get('1')
account.delete()
var account = Accounts.Get("1");
account.Close();


{"_id":"57803084827bd50e006b04a4","order":6,"__v":1,"category":"57803084827bd50e006b045c","isReference":true,"link_url":"","parentDoc":null,"slug":"reopen-account","title":"Reopen Account","type":"put","api":{"results":{"codes":[{"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  <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  <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-11T19:04:43Z</updated_at>\n  <closed_at nil=\"nil\"/>\n</account>","language":"xml","status":200}]},"settings":"","url":"/accounts/:account_code/reopen","auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $account = Recurly_Account::get('b6f5783');\n  $account->reopen();\n\n  // Or to fetch and reopen in one call\n  // $account = Recurly_Account::reopenAccount('b6f5783');\n\n  print \"Account: $account\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid account code: $e\";\n} catch (Recurly_ValidationError $e) {\n  print \"Account already open: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find '1'\naccount.reopen"},{"language":"python","code":"account = Account.get('1')\naccount.reopen() "},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\naccount.Reopen();"}]},"method":"put","params":[{"in":"path","name":"account_code","ref":"","required":true,"type":"string","_id":"55944ed45c9eaa2300a86339","default":"","desc":"Account's unique code."}],"apiSetting":"59497f16b9248d0024fe3f31"},"editedParams2":true,"hidden":false,"user":"55648cf93b87582b003ab8b1","project":"555fbba928249c1900618a82","updates":[],"version":"57803084827bd50e006b0457","body":"[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Please note\",\n  \"body\": \"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.\"\n}\n[/block]","githubsync":"","link_external":false,"sync_unique":"","createdAt":"2015-06-15T22:03:14.174Z","editedParams":true,"excerpt":"Transitions a closed account back to active.","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

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.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $account = Recurly_Account::get('b6f5783');
  $account->reopen();

  // Or to fetch and reopen in one call
  // $account = Recurly_Account::reopenAccount('b6f5783');

  print "Account: $account";
} catch (Recurly_NotFoundError $e) {
  print "Invalid account code: $e";
} catch (Recurly_ValidationError $e) {
  print "Account already open: $e";
}
account = Recurly::Account.find '1'
account.reopen
account = Account.get('1')
account.reopen() 
var account = Accounts.Get("1");
account.Reopen();

Result Format

<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
  <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
  <redemptions href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions"/>
  <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>[email protected]</email>
  <cc_emails>[email protected],[email protected]</cc_emails>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company_name>New Company Name</company_name>
  <vat_number nil="nil"/>
  <tax_exempt type="boolean">false</tax_exempt>
  <address>
    <address1>123 Main St.</address1>
    <address2 nil="nil"/>
    <city>San Francisco</city>
    <state>CA</state>
    <zip>94105</zip>
    <country>US</country>
    <phone nil="nil"/>
  </address>
  <accept_language nil="nil"/>
  <hosted_login_token>96e74bd5e14d18e6da463a0d638a2621</hosted_login_token>
  <created_at type="datetime">2016-07-08T20:59:43Z</created_at>
  <updated_at type="datetime">2016-07-11T19:04:43Z</updated_at>
  <closed_at nil="nil"/>
</account>


{"_id":"57803084827bd50e006b04a5","editedParams":true,"editedParams2":true,"order":7,"slug":"list-account-notes","type":"get","api":{"method":"get","params":[{"in":"path","name":"account_code","ref":"","required":true,"type":"string","_id":"55944eddccc3052300569882","default":"","desc":"Account's unique code."},{"ref":"","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","in":"query","_id":"5783c946ce802f0e0087d4bb"},{"required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page","in":"query","_id":"5783c946ce802f0e0087d4ba","ref":""}],"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":"","url":"/accounts/:account_code/notes","auth":"required","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":""},{"code":"try:\n  account = Account.get('1')\n  for note in account.notes():\n   print \"Note: %s\" % note.message\nexcept NotFoundError:\n  print \"Account not found.\\n\"","language":"python"},{"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}"}]},"apiSetting":"59497f16b9248d0024fe3f31"},"project":"555fbba928249c1900618a82","sync_unique":"","updates":[],"user":"55648cf93b87582b003ab8b1","version":"57803084827bd50e006b0457","category":"57803084827bd50e006b045c","parentDoc":null,"body":"","createdAt":"2015-06-15T22:04:40.352Z","githubsync":"","hidden":false,"isReference":true,"link_external":false,"link_url":"","title":"List Account Notes","__v":2,"excerpt":"Returns a list of the notes on an account sorted in descending order (most recently created first).","next":{"pages":[]},"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.
per_page:
integer50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $notes = Recurly_NoteList::get('b6f5783');
  foreach ($notes as $note) {
    print "Note: {$note->message}\n";
  }
} catch (Recurly_NotFoundError $e) {
  print "Invalid account code: $e";
}
try:
  account = Account.get('1')
  for note in account.notes():
   print "Note: %s" % note.message
except NotFoundError:
  print "Account not found.\n"
using System.Linq;

var account = Accounts.Get("1");
var notes = account.GetNotes();
while (notes.Any())
{
	foreach (var note in notes)
		Console.WriteLine("Note: " + note.Message);
	notes = notes.Next;
}

Result Format

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


{"_id":"57803084827bd50e006b0474","githubsync":"","slug":"adjustment-object","updates":[],"hidden":false,"link_url":"","parentDoc":null,"title":"Adjustment Object","version":"57803084827bd50e006b0457","editedParams":true,"editedParams2":true,"link_external":false,"project":"555fbba928249c1900618a82","__v":3,"createdAt":"2015-09-15T21:26:29.282Z","excerpt":"The history of your customer's Recurly account can be tracked through adjustments, made up of credits and charges.","isReference":true,"order":0,"sync_unique":"","type":"get","user":"55648cf93b87582b003ab8b1","api":{"method":"get","params":[{"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":"","in":"query"},{"type":"int","name":"tax_in_cents","_id":"55f88d0560cc850d008a7ba3","ref":"","in":"query","required":false,"desc":"The tax on the adjustment, in cents.","default":""},{"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","ref":"","in":"query","required":false},{"_id":"55f88d0560cc850d008a7ba2","ref":"","in":"query","required":false,"desc":"The total amount of the adjustment, in cents.","default":"","type":"int","name":"total_in_cents"},{"name":"type","_id":"55f8905559eace0d0087dc69","ref":"","in":"query","required":false,"desc":"The type of adjustment to return: `charge` or `credit`.","default":"","type":"string"},{"type":"string","name":"currency","_id":"55f88d0560cc850d008a7ba1","ref":"","in":"query","required":false,"desc":"Currency, 3-letter ISO code.","default":""},{"required":false,"desc":"`true` if the current adjustment is taxable, `false` if it is not.","default":"","type":"boolean","name":"taxable","_id":"55f88d0560cc850d008a7ba0","ref":"","in":"query"},{"ref":"","in":"query","required":false,"desc":"The URL of the invoice for the specified adjustment.","default":"","type":"string","name":"invoice","_id":"55f88d0560cc850d008a7bad"},{"default":"","type":"string","name":"account","_id":"55f88d0560cc850d008a7bae","ref":"","in":"query","required":false,"desc":"The URL of the account for the specified adjustment."},{"in":"query","required":false,"desc":"Only shows if adjustment is a credit created from another credit.","default":"","type":"string","name":"original_adjustment_uuid","_id":"55f88d0560cc850d008a7ba5","ref":""},{"desc":"The tax region of the adjustment.","default":"","type":"string","name":"tax_region","_id":"55f88d0560cc850d008a7b9e","ref":"","in":"query","required":false},{"_id":"55f88d0560cc850d008a7baa","ref":"","in":"query","required":false,"desc":"Description of the adjustment for the adjustment. Max 255 characters.","default":"","type":"string","name":"description"},{"name":"state","_id":"55f88d0560cc850d008a7bab","ref":"","in":"query","required":false,"desc":"The state of the adjustments to return: `pending` or `invoiced`.","default":"","type":"string"},{"ref":"","in":"query","required":false,"desc":"The unique identifier of the adjustment.","default":"","type":"string","name":"uuid","_id":"55f88d0560cc850d008a7bac"},{"in":"query","required":false,"desc":"The tax rate of the adjustment.","default":"","type":"string","name":"tax_rate","_id":"55f88d0560cc850d008a7b9d","ref":""},{"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":"query","required":false},{"name":"accounting_code","_id":"55f88d0560cc850d008a7ba9","ref":"","in":"query","required":false,"desc":"Accounting code. Max of 20 characters.","default":"","type":"string"},{"type":"string","name":"quantity","_id":"55f88d0560cc850d008a7ba6","ref":"","in":"query","required":false,"desc":"Quantity.","default":"1"},{"desc":"The discount on the adjustment, in cents.","default":"","type":"int","name":"discount_in_cents","_id":"55f88d0560cc850d008a7ba4","ref":"","in":"query","required":false},{"name":"tax_type","_id":"55f88d0560cc850d008a7b9f","ref":"","in":"query","required":false,"desc":"The tax type of the adjustment.","default":"","type":"string"},{"ref":"","in":"query","required":false,"desc":"The nested address information of the adjustment: `name `, `type`, `tax_rate`, `tax_in_cents`.","default":"","type":"array_mixed","name":"tax_details","_id":"55f88d0560cc850d008a7b9b"},{"in":"query","required":false,"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":""},{"desc":"A timestamp associated with when the adjustment began.","default":"Today","type":"datetime","name":"start_date","_id":"55f88d0560cc850d008a7b9a","ref":"","in":"query","required":false},{"name":"end_date","_id":"55f88d0560cc850d008a7b99","ref":"","in":"query","required":false,"desc":"A timestamp associated with when the adjustment ended.","default":"","type":"datetime"},{"type":"datetime","name":"created_at","_id":"55f88d0560cc850d008a7b98","ref":"","in":"query","required":false,"desc":"A timestamp associated with when the adjustment was created.","default":""}],"results":{"codes":[{"name":"","code":"<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60\" type=\"charge\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/100\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <uuid>626db120a84102b1809909071c701c60</uuid>\n  <state>invoiced</state>\n  <description>Description of the adjustment</description>\n  <accounting_code>adjustment_ac</accounting_code>\n  <product_code>basic</product_code>\n  <origin>debit</origin>\n  <unit_amount_in_cents type=\"integer\">2000</unit_amount_in_cents>\n  <quantity type=\"integer\">1</quantity>\n  <original_adjustment_uuid>2cc95aa62517e56d5bec3a48afa1b3b9</original_adjustment_uuid>\n  <discount_in_cents type=\"integer\">0</discount_in_cents>\n  <tax_in_cents type=\"integer\">175</tax_in_cents>\n  <total_in_cents type=\"integer\">2175</total_in_cents>\n  <currency>USD</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_details type=\"array\">\n    <tax_detail>\n      <name>california</name>\n      <type>state</type>\n      <tax_rate type=\"float\">0.065</tax_rate>\n      <tax_in_cents type=\"integer\">130</tax_in_cents>\n    </tax_detail>\n  </tax_details>\n  <start_date type=\"datetime\">2015-02-04T23:13:07Z</start_date>\n  <end_date nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-02-04T23:13:07Z</created_at>\n</adjustment>","language":"xml","status":200}]},"settings":"","url":"/adjustments","auth":"required","examples":{"codes":[]},"apiSetting":"59497f16b9248d0024fe3f31"},"body":"","category":"57803084827bd50e006b045d","next":{"pages":[]},"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.

Query Params

unit_amount_in_cents:
integer
Positive amount for a charge, negative amount for a credit. Max 10000000.
tax_in_cents:
integer
The tax on the adjustment, in cents.
origin:
string
The origin of the adjustment to return: `plan`, `plan_trial`, `setup_fee`, `add_on`, `add_on_trial`, `one_time`, `debit`, `credit`, `coupon`, or `carryforward`.
total_in_cents:
integer
The total amount of the adjustment, in cents.
type:
string
The type of adjustment to return: `charge` or `credit`.
currency:
string
Currency, 3-letter ISO code.
taxable:
boolean
`true` if the current adjustment is taxable, `false` if it is not.
invoice:
string
The URL of the invoice for the specified adjustment.
account:
string
The URL of the account for the specified adjustment.
original_adjustment_uuid:
string
Only shows if adjustment is a credit created from another credit.
tax_region:
string
The tax region of the adjustment.
description:
string
Description of the adjustment for the adjustment. Max 255 characters.
state:
string
The state of the adjustments to return: `pending` or `invoiced`.
uuid:
string
The unique identifier 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.
accounting_code:
string
Accounting code. Max of 20 characters.
quantity:
string1
Quantity.
discount_in_cents:
integer
The discount on the adjustment, in cents.
tax_type:
string
The tax type of the adjustment.
tax_details:
array of mixed
The nested address information of the adjustment: `name `, `type`, `tax_rate`, `tax_in_cents`.
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:
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.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

<adjustment href="https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60" type="charge">
  <account href="https://your-subdomain.recurly.com/v2/accounts/100"/>
  <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
  <uuid>626db120a84102b1809909071c701c60</uuid>
  <state>invoiced</state>
  <description>Description of the adjustment</description>
  <accounting_code>adjustment_ac</accounting_code>
  <product_code>basic</product_code>
  <origin>debit</origin>
  <unit_amount_in_cents type="integer">2000</unit_amount_in_cents>
  <quantity type="integer">1</quantity>
  <original_adjustment_uuid>2cc95aa62517e56d5bec3a48afa1b3b9</original_adjustment_uuid>
  <discount_in_cents type="integer">0</discount_in_cents>
  <tax_in_cents type="integer">175</tax_in_cents>
  <total_in_cents type="integer">2175</total_in_cents>
  <currency>USD</currency>
  <taxable type="boolean">false</taxable>
  <tax_type>usst</tax_type>
  <tax_region>CA</tax_region>
  <tax_rate type="float">0.0875</tax_rate>
  <tax_exempt type="boolean">false</tax_exempt>
  <tax_details type="array">
    <tax_detail>
      <name>california</name>
      <type>state</type>
      <tax_rate type="float">0.065</tax_rate>
      <tax_in_cents type="integer">130</tax_in_cents>
    </tax_detail>
  </tax_details>
  <start_date type="datetime">2015-02-04T23:13:07Z</start_date>
  <end_date nil="nil"/>
  <created_at type="datetime">2015-02-04T23:13:07Z</created_at>
</adjustment>


{"_id":"57803084827bd50e006b0475","createdAt":"2015-06-15T22:21:48.674Z","editedParams":true,"githubsync":"","link_external":false,"type":"get","user":"55648cf93b87582b003ab8b1","api":{"params":[{"required":true,"type":"string","_id":"5783c9a7192dcf0e0099828e","default":"","desc":"Account's unique code.","in":"path","name":"account_code","ref":""},{"default":"","type":"string","name":"cursor","in":"query","_id":"5783c9a7192dcf0e0099828d","ref":"","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."},{"in":"query","_id":"5783c9a7192dcf0e0099828c","ref":"","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page"}],"results":{"codes":[{"status":200,"language":"xml","code":"<adjustments type=\"array\">\n  <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/374ae5e89793ab0158f836428ea3af38\" 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/374ae5e848adcfd332fdd3469d89c888\"/>\n    <uuid>374ae5e89793ab0158f836428ea3af38</uuid>\n    <state>invoiced</state>\n    <description>Gold plan</description>\n    <accounting_code nil=\"nil\"/>\n    <product_code>gold</product_code>\n    <origin>plan</origin>\n    <unit_amount_in_cents type=\"integer\">4500</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\">394</tax_in_cents>\n    <total_in_cents type=\"integer\">4894</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    <start_date type=\"datetime\">2016-07-11T22:36:22Z</start_date>\n    <end_date type=\"datetime\">2016-08-11T22:36:22Z</end_date>\n    <created_at type=\"datetime\">2016-07-11T22:36:22Z</created_at>\n    <updated_at type=\"datetime\">2016-07-11T22:36:22Z</updated_at>\n  </adjustment>\n  <!-- Continued... -->\n</adjustments>","name":""}]},"settings":"","url":"/accounts/:account_code/adjustments","auth":"required","examples":{"codes":[{"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}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.adjustments.find_each do |adjustment|\n  puts \"Adjustment: #{adjustment.inspect}\"\nend"},{"language":"python","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":"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","apiSetting":"59497f16b9248d0024fe3f31"},"isReference":true,"link_url":"","sync_unique":"","hidden":false,"category":"57803084827bd50e006b045d","excerpt":"Returns a list of adjustments for a given account. Results are ordered by the time created, sorted by newest first.","order":1,"project":"555fbba928249c1900618a82","updates":[],"__v":2,"body":"","editedParams2":true,"parentDoc":null,"slug":"list-an-accounts-adjustments","title":"List an Account's Adjustments","version":"57803084827bd50e006b0457","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getList an 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

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.
per_page:
integer50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $adjustments = Recurly_AdjustmentList::get('b6f5783');
  foreach ($adjustments as $adjustment) {
    print "Adjustment: $adjustment\n";
  }
} catch (Recurly_NotFoundError $e) {
  print "Invalid account code: $e";
}
account = Recurly::Account.find('1')
account.adjustments.find_each do |adjustment|
  puts "Adjustment: #{adjustment.inspect}"
end
#client version 2.1.6+
account = Account.get('1')
for adjustment in account.adjustments():
    print 'Adjustment: %s' % adjustment

#client version <= 2.1.5
account = Account.get('1')
adjustments = account.adjustments()
while adjustments:
    for adjustment in adjustments:
        print 'Adjustment: %s' % adjustment
    try:
        adjustments = adjustments.next_page()
    except PageError:
        adjustments = ()
using System.Linq;

var account = Accounts.Get("1");
var adjustments = account.GetAdjustments();
while (adjustments.Any())
{
	foreach (var adjustment in adjustments)
		Console.WriteLine("Adjustment: " + adjustment);
	adjustments = adjustments.Next;
}

Result Format

<adjustments type="array">
  <adjustment href="https://your-subdomain.recurly.com/v2/adjustments/374ae5e89793ab0158f836428ea3af38" type="charge">
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <invoice href="https://your-subdomain.recurly.com/v2/invoices/1006"/>
    <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/374ae5e848adcfd332fdd3469d89c888"/>
    <uuid>374ae5e89793ab0158f836428ea3af38</uuid>
    <state>invoiced</state>
    <description>Gold plan</description>
    <accounting_code nil="nil"/>
    <product_code>gold</product_code>
    <origin>plan</origin>
    <unit_amount_in_cents type="integer">4500</unit_amount_in_cents>
    <quantity type="integer">1</quantity>
    <discount_in_cents type="integer">0</discount_in_cents>
    <tax_in_cents type="integer">394</tax_in_cents>
    <total_in_cents type="integer">4894</total_in_cents>
    <currency>EUR</currency>
    <taxable type="boolean">false</taxable>
    <tax_type>usst</tax_type>
    <tax_region>CA</tax_region>
    <tax_rate type="float">0.0875</tax_rate>
    <tax_exempt type="boolean">false</tax_exempt>
    <tax_code nil="nil"/>
    <start_date type="datetime">2016-07-11T22:36:22Z</start_date>
    <end_date type="datetime">2016-08-11T22:36:22Z</end_date>
    <created_at type="datetime">2016-07-11T22:36:22Z</created_at>
    <updated_at type="datetime">2016-07-11T22:36:22Z</updated_at>
  </adjustment>
  <!-- Continued... -->
</adjustments>


{"_id":"57803084827bd50e006b0477","category":"57803084827bd50e006b045d","editedParams":true,"githubsync":"","isReference":true,"link_url":"","project":"555fbba928249c1900618a82","title":"Create a Charge","type":"post","user":"55648cf93b87582b003ab8b1","__v":1,"editedParams2":true,"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.","link_external":false,"order":2,"parentDoc":null,"version":"57803084827bd50e006b0457","api":{"url":"/accounts/:account_code/adjustments","auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $charge = new Recurly_Adjustment();\n  $charge->account_code = 'b6f5783';\n  $charge->description = 'Charge for extra bandwidth';\n  $charge->unit_amount_in_cents = 5000; // $50.00\n  $charge->currency = 'USD';\n  $charge->quantity = 1;\n  $charge->accounting_code = 'bandwidth';\n  $charge->tax_exempt = false;\n  $charge->create();\n\n  print \"Charge: $charge\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Account not found: $e\";\n}","name":""},{"code":"account = Recurly::Account.find('1')\naccount.adjustments.create(\n  :description          => 'Charge for extra bandwidth',\n  :unit_amount_in_cents => 50_00,\n  :currency             => 'USD',\n  :quantity             => 1,\n  :accounting_code      => 'bandwidth',\n  :tax_exempt           => false\n)","language":"ruby"},{"language":"python","code":"account = Account.get('1')\ncharge = Adjustment(\n  description='Charge for extra bandwidth',\n  unit_amount_in_cents=5000,\n  currency='USD',\n  quantity=1,\n  accounting_code='bandwidth',\n  tax_exempt=False\n)\naccount.charge(charge)"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar adjustment = account.NewAdjustment(\n\t\"USD\",                        // currency\n\t5000,                         // unit_amount_in_cents\n\t\"Charge for extra bandwidth\", // description\n\t1,                            // quantity\n\t\"bandwidth\",                  // accounting_code\n\tfalse);                       // tax_exempt\nadjustment.Create();"},{"language":"xml","code":"<adjustment>\n  <description>Charge for extra bandwidth</description>\n  <unit_amount_in_cents>5000</unit_amount_in_cents>\n  <currency>USD</currency>\n  <quantity>1</quantity>\n  <accounting_code>bandwidth</accounting_code>\n  <tax_exempt>false</tax_exempt>\n</adjustment>"}]},"method":"post","params":[{"in":"path","_id":"557f5188eb75d80d00af40a7","ref":"","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"default":"","desc":"Currency, 3-letter ISO code.","in":"body","name":"currency","ref":"","required":true,"type":"string","_id":"557f5188eb75d80d00af40a6"},{"type":"string","name":"unit_amount_in_cents","in":"body","_id":"557f5188eb75d80d00af40a5","ref":"","required":true,"desc":"Positive amount for a charge, negative amount for a credit. Max 10000000.","default":""},{"required":false,"desc":"Description of the adjustment for the invoice.","default":"","type":"string","name":"description","in":"body","_id":"557f5188eb75d80d00af40a4","ref":""},{"in":"body","name":"quantity","ref":"","required":false,"type":"int","_id":"557f5188eb75d80d00af40a3","default":"1","desc":"Quantity."},{"name":"accounting_code","in":"body","_id":"557f5188eb75d80d00af40a2","ref":"","required":false,"desc":"Accounting code. Max of 20 characters.","default":"","type":"string"},{"default":"","type":"boolean","name":"tax_exempt","in":"body","_id":"557f5188eb75d80d00af40a1","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."},{"_id":"557f5188eb75d80d00af40a0","ref":"","required":false,"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","in":"body"},{"_id":"55e09fbfa44fae0d0021473e","default":"now","desc":"A timestamp associated with when the charge began.","in":"body","name":"start_date","ref":"","required":false,"type":"timestamp"},{"type":"timestamp","_id":"55e09fbfa44fae0d0021473d","default":"","desc":"A timestamp associated with when the charge ended.","in":"body","name":"end_date","ref":"","required":false}],"results":{"codes":[{"name":"","status":201,"language":"xml","code":"<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/374a2729397882fafbc82041a0a4dd0d\" type=\"charge\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <uuid>374a2729397882fafbc82041a0a4dd0d</uuid>\n  <state>pending</state>\n  <description>Charge for extra bandwidth</description>\n  <accounting_code>bandwidth</accounting_code>\n  <product_code nil=\"nil\"/>\n  <origin>debit</origin>\n  <unit_amount_in_cents type=\"integer\">5000</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\">5000</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-07-11T19:08:01Z</start_date>\n  <end_date nil=\"nil\"/>\n  <created_at type=\"datetime\">2016-07-11T19:08:01Z</created_at>\n  <updated_at type=\"datetime\">2016-07-11T19:08:01Z</updated_at>\n</adjustment>"}]},"settings":"","apiSetting":"59497f16b9248d0024fe3f31"},"createdAt":"2015-06-15T22:28:24.162Z","hidden":false,"sync_unique":"","updates":["55b2f1b5a96deb1900990c6f","565dc7d277f0090d0058196c"],"body":"","slug":"create-a-charge-or-credit","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate a 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.
description:
string
Description of the adjustment for the invoice.
quantity:
integer1
Quantity.
accounting_code:
string
Accounting code. Max of 20 characters.
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.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $charge = new Recurly_Adjustment();
  $charge->account_code = 'b6f5783';
  $charge->description = 'Charge for extra bandwidth';
  $charge->unit_amount_in_cents = 5000; // $50.00
  $charge->currency = 'USD';
  $charge->quantity = 1;
  $charge->accounting_code = 'bandwidth';
  $charge->tax_exempt = false;
  $charge->create();

  print "Charge: $charge";
} catch (Recurly_NotFoundError $e) {
  print "Account not found: $e";
}
account = Recurly::Account.find('1')
account.adjustments.create(
  :description          => 'Charge for extra bandwidth',
  :unit_amount_in_cents => 50_00,
  :currency             => 'USD',
  :quantity             => 1,
  :accounting_code      => 'bandwidth',
  :tax_exempt           => false
)
account = Account.get('1')
charge = Adjustment(
  description='Charge for extra bandwidth',
  unit_amount_in_cents=5000,
  currency='USD',
  quantity=1,
  accounting_code='bandwidth',
  tax_exempt=False
)
account.charge(charge)
var account = Accounts.Get("1");
var adjustment = account.NewAdjustment(
	"USD",                        // currency
	5000,                         // unit_amount_in_cents
	"Charge for extra bandwidth", // description
	1,                            // quantity
	"bandwidth",                  // accounting_code
	false);                       // tax_exempt
adjustment.Create();
<adjustment>
  <description>Charge for extra bandwidth</description>
  <unit_amount_in_cents>5000</unit_amount_in_cents>
  <currency>USD</currency>
  <quantity>1</quantity>
  <accounting_code>bandwidth</accounting_code>
  <tax_exempt>false</tax_exempt>
</adjustment>

Result Format

<adjustment href="https://your-subdomain.recurly.com/v2/adjustments/374a2729397882fafbc82041a0a4dd0d" type="charge">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <uuid>374a2729397882fafbc82041a0a4dd0d</uuid>
  <state>pending</state>
  <description>Charge for extra bandwidth</description>
  <accounting_code>bandwidth</accounting_code>
  <product_code nil="nil"/>
  <origin>debit</origin>
  <unit_amount_in_cents type="integer">5000</unit_amount_in_cents>
  <quantity type="integer">1</quantity>
  <discount_in_cents type="integer">0</discount_in_cents>
  <tax_in_cents type="integer">0</tax_in_cents>
  <total_in_cents type="integer">5000</total_in_cents>
  <currency>USD</currency>
  <taxable type="boolean">false</taxable>
  <tax_exempt type="boolean">false</tax_exempt>
  <tax_code nil="nil"/>
  <start_date type="datetime">2016-07-11T19:08:01Z</start_date>
  <end_date nil="nil"/>
  <created_at type="datetime">2016-07-11T19:08:01Z</created_at>
  <updated_at type="datetime">2016-07-11T19:08:01Z</updated_at>
</adjustment>


{"_id":"57803084827bd50e006b0478","category":"57803084827bd50e006b045d","createdAt":"2015-08-07T19:15:36.088Z","hidden":false,"isReference":true,"updates":["563ce057913e650d00b65f47"],"user":"55648cf93b87582b003ab8b1","body":"","editedParams2":true,"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.","link_external":false,"link_url":"","parentDoc":null,"title":"Create a Credit","__v":2,"version":"57803084827bd50e006b0457","type":"post","githubsync":"","project":"555fbba928249c1900618a82","slug":"create-a-credit","api":{"params":[{"ref":"","in":"path","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code","_id":"557f5188eb75d80d00af40a7"},{"in":"body","required":true,"desc":"Currency, 3-letter ISO code.","default":"","type":"string","name":"currency","_id":"557f5188eb75d80d00af40a6","ref":""},{"required":true,"desc":"Positive amount for a charge, negative amount for a credit. Max 10000000.","default":"","type":"string","name":"unit_amount_in_cents","_id":"557f5188eb75d80d00af40a5","ref":"","in":"body"},{"ref":"","in":"body","required":false,"desc":"Quantity.","default":"1","type":"int","name":"quantity","_id":"557f5188eb75d80d00af40a3"},{"default":"","type":"string","name":"description","_id":"557f5188eb75d80d00af40a4","ref":"","in":"body","required":false,"desc":"Description of the adjustment for the invoice."},{"in":"body","required":false,"desc":"Accounting code. Max of 20 characters.","default":"","type":"string","name":"accounting_code","_id":"557f5188eb75d80d00af40a2","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":"557f5188eb75d80d00af40a1","ref":"","in":"body"},{"ref":"","in":"body","required":false,"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":"557f5188eb75d80d00af40a0"},{"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."}],"results":{"codes":[{"status":201,"language":"xml","code":"<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/374a278d22d88f356aecfb400faa768f\" type=\"credit\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <uuid>374a278d22d88f356aecfb400faa768f</uuid>\n  <state>pending</state>\n  <description>Refund 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-07-11T19:08:27Z</start_date>\n  <end_date nil=\"nil\"/>\n  <created_at type=\"datetime\">2016-07-11T19:08:27Z</created_at>\n  <updated_at type=\"datetime\">2016-07-11T19:08:27Z</updated_at>\n</adjustment>","name":""}]},"settings":"","url":"/accounts/:account_code/adjustments","auth":"required","examples":{"codes":[{"name":"","code":"<?php\n\n$credit = new Recurly_Adjustment();\n$credit->account_code = '1';\n$credit->description = 'Refund 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          => 'Refund 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='Refund 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\"Refund for being a great customer\", // description\n\t1);                                  // quantity (default is 1)\nadjustment.Create();","language":"csharp"},{"language":"xml","code":"<adjustment>\n  <description>Refund 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</adjustment>"}]},"method":"post","apiSetting":"59497f16b9248d0024fe3f31"},"order":3,"sync_unique":"","editedParams":true,"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate a 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.
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 credit began.
end_date:
timestamp
A timestamp associated with when the credit ended.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

$credit = new Recurly_Adjustment();
$credit->account_code = '1';
$credit->description = 'Refund for being a great customer';
$credit->unit_amount_in_cents = -2000; // Negative $20.00.
$credit->currency = 'USD';
$credit->quantity = 1;
$credit->create();
account = Recurly::Account.find('1')
account.adjustments.create(
  :description          => 'Refund for being a great customer',
  :unit_amount_in_cents => -20_00,
  :currency             => 'USD',
  :quantity             => 1
)
account = Account.get('1')
credit = Adjustment(
  description='Refund for being a great customer',
  unit_amount_in_cents=-2000,
  currency='USD',
  quantity=1
)
account.charge(credit)
var account = Accounts.Get("1");
var adjustment = account.NewAdjustment(
	"USD",                               // currency
	-2000,                               // unit_amount_in_cents
	"Refund for being a great customer", // description
	1);                                  // quantity (default is 1)
adjustment.Create();
<adjustment>
  <description>Refund for being a great customer</description>
  <unit_amount_in_cents>-2000</unit_amount_in_cents>
  <currency>USD</currency>
  <quantity>1</quantity>
</adjustment>

Result Format

<adjustment href="https://your-subdomain.recurly.com/v2/adjustments/374a278d22d88f356aecfb400faa768f" type="credit">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <uuid>374a278d22d88f356aecfb400faa768f</uuid>
  <state>pending</state>
  <description>Refund for being a great customer</description>
  <accounting_code nil="nil"/>
  <product_code nil="nil"/>
  <origin>credit</origin>
  <unit_amount_in_cents type="integer">-2000</unit_amount_in_cents>
  <quantity type="integer">1</quantity>
  <discount_in_cents type="integer">0</discount_in_cents>
  <tax_in_cents type="integer">0</tax_in_cents>
  <total_in_cents type="integer">-2000</total_in_cents>
  <currency>USD</currency>
  <taxable type="boolean">false</taxable>
  <tax_exempt type="boolean">false</tax_exempt>
  <tax_code nil="nil"/>
  <start_date type="datetime">2016-07-11T19:08:27Z</start_date>
  <end_date nil="nil"/>
  <created_at type="datetime">2016-07-11T19:08:27Z</created_at>
  <updated_at type="datetime">2016-07-11T19:08:27Z</updated_at>
</adjustment>


{"_id":"57803084827bd50e006b0476","link_url":"","parentDoc":null,"project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","api":{"auth":"required","examples":{"codes":[{"name":"","language":"php","code":"<?php\n\ntry {\n  $adjustment = Recurly_Adjustment::get('2fded6a3e36e8b56b37007432f8c1b0d');\n  print \"Adjustment: $adjustment\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid adjustment uuid: $e\";\n}"},{"language":"ruby","code":"adjustment = Recurly::Adjustment.find('30498bb2d52bb9037b4d62480eb98b8f')\n"},{"code":"adjustment = Adjustment.get('30498bb2d52bb9037b4d62480eb98b8f')\n","language":"python"},{"language":"csharp","code":"var adjustment = Adjustments.Get(\"30498bb2d52bb9037b4d62480eb98b8f\");\nConsole.WriteLine(\"Adjustment: \" + adjustment);"}]},"method":"get","params":[{"required":true,"desc":"The unique identifier for the adjustment","default":"","type":"string","name":"uuid","in":"path","_id":"55944f4fccc3052300569883","ref":""}],"results":{"codes":[{"status":200,"language":"xml","code":"<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/374ae5e89793ab0158f836428ea3af38\" 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/374ae5e848adcfd332fdd3469d89c888\"/>\n  <uuid>374ae5e89793ab0158f836428ea3af38</uuid>\n  <state>invoiced</state>\n  <description>Gold plan</description>\n  <accounting_code nil=\"nil\"/>\n  <product_code>gold</product_code>\n  <origin>plan</origin>\n  <unit_amount_in_cents type=\"integer\">4500</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\">394</tax_in_cents>\n  <total_in_cents type=\"integer\">4894</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\">293</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\">45</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\">56</tax_in_cents>\n    </tax_detail>\n  </tax_details>\n  <start_date type=\"datetime\">2016-07-11T22:36:22Z</start_date>\n  <end_date type=\"datetime\">2016-08-11T22:36:22Z</end_date>\n  <created_at type=\"datetime\">2016-07-11T22:36:22Z</created_at>\n  <updated_at type=\"datetime\">2016-07-11T22:36:22Z</updated_at>\n</adjustment>","name":""}]},"settings":"","url":"/adjustments/:uuid","apiSetting":"59497f16b9248d0024fe3f31"},"editedParams2":true,"category":"57803084827bd50e006b045d","createdAt":"2015-06-15T22:24:48.657Z","excerpt":"Returns information about a single adjustment.","hidden":false,"isReference":true,"sync_unique":"","__v":1,"body":"","title":"Get an Adjustment","type":"get","editedParams":true,"slug":"get-an-adjustment","link_external":false,"order":4,"updates":["55b79c68aea7c8190058b98e"],"version":"57803084827bd50e006b0457","githubsync":"","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getGet an Adjustment

Returns information about a single adjustment.

Path Params

uuid:
required
string
The unique identifier for the adjustment

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $adjustment = Recurly_Adjustment::get('2fded6a3e36e8b56b37007432f8c1b0d');
  print "Adjustment: $adjustment";
} catch (Recurly_NotFoundError $e) {
  print "Invalid adjustment uuid: $e";
}
adjustment = Recurly::Adjustment.find('30498bb2d52bb9037b4d62480eb98b8f')
adjustment = Adjustment.get('30498bb2d52bb9037b4d62480eb98b8f')
var adjustment = Adjustments.Get("30498bb2d52bb9037b4d62480eb98b8f");
Console.WriteLine("Adjustment: " + adjustment);

Result Format

<adjustment href="https://your-subdomain.recurly.com/v2/adjustments/374ae5e89793ab0158f836428ea3af38" type="charge">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <invoice href="https://your-subdomain.recurly.com/v2/invoices/1006"/>
  <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/374ae5e848adcfd332fdd3469d89c888"/>
  <uuid>374ae5e89793ab0158f836428ea3af38</uuid>
  <state>invoiced</state>
  <description>Gold plan</description>
  <accounting_code nil="nil"/>
  <product_code>gold</product_code>
  <origin>plan</origin>
  <unit_amount_in_cents type="integer">4500</unit_amount_in_cents>
  <quantity type="integer">1</quantity>
  <discount_in_cents type="integer">0</discount_in_cents>
  <tax_in_cents type="integer">394</tax_in_cents>
  <total_in_cents type="integer">4894</total_in_cents>
  <currency>EUR</currency>
  <taxable type="boolean">false</taxable>
  <tax_type>usst</tax_type>
  <tax_region>CA</tax_region>
  <tax_rate type="float">0.0875</tax_rate>
  <tax_exempt type="boolean">false</tax_exempt>
  <tax_code nil="nil"/>
  <tax_details type="array">
    <tax_detail>
      <name nil="nil"/>
      <type>state</type>
      <tax_rate type="float">0.065</tax_rate>
      <tax_in_cents type="integer">293</tax_in_cents>
    </tax_detail>
    <tax_detail>
      <name nil="nil"/>
      <type>county</type>
      <tax_rate type="float">0.01</tax_rate>
      <tax_in_cents type="integer">45</tax_in_cents>
    </tax_detail>
    <tax_detail>
      <name nil="nil"/>
      <type>city</type>
      <tax_rate type="float">0.0</tax_rate>
      <tax_in_cents type="integer">0</tax_in_cents>
    </tax_detail>
    <tax_detail>
      <name nil="nil"/>
      <type>special</type>
      <tax_rate type="float">0.0125</tax_rate>
      <tax_in_cents type="integer">56</tax_in_cents>
    </tax_detail>
  </tax_details>
  <start_date type="datetime">2016-07-11T22:36:22Z</start_date>
  <end_date type="datetime">2016-08-11T22:36:22Z</end_date>
  <created_at type="datetime">2016-07-11T22:36:22Z</created_at>
  <updated_at type="datetime">2016-07-11T22:36:22Z</updated_at>
</adjustment>


{"_id":"57803084827bd50e006b0479","__v":1,"excerpt":"Delete an adjustment from an account. Only non-invoiced adjustments can be deleted.","hidden":false,"order":5,"project":"555fbba928249c1900618a82","editedParams":true,"parentDoc":null,"slug":"delete-an-adjustment","sync_unique":"","type":"delete","version":"57803084827bd50e006b0457","category":"57803084827bd50e006b045d","isReference":true,"link_external":false,"link_url":"","user":"55648cf93b87582b003ab8b1","api":{"method":"delete","params":[{"default":"","type":"string","name":"uuid","in":"path","_id":"55944f6a0c33bd0d0005964a","ref":"","required":true,"desc":"The unique identifier for the adjustment"}],"results":{"codes":[{"language":"xml","code":"Status: 204 No Content","status":204}]},"settings":"","url":"/adjustments/:uuid","auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $adjustment = Recurly_Adjustment::get('626db120a84102b1809909071c701c60');\n  $adjustment->delete();\n\n  print \"Adjustment: $adjustment\";\n} catch (Recurly_NotFoundError $e) {\n  // NotFoundError if invalid uuid or already deleted\n  print \"Invalid adjustment uuid: $e\";\n}\n","name":""},{"language":"ruby","code":"adjustment = Recurly::Adjustment.find('945a4cb9afd64300b97b138407a51aef')\nadjustment.destroy"},{"language":"python","code":"adjustment = Adjustment.get('945a4cb9afd64300b97b138407a51aef')\nadjustment.delete()"},{"language":"csharp","code":"var adjustment = Adjustments.Get(\"945a4cb9afd64300b97b138407a51aef\");\nadjustment.Delete("}]},"apiSetting":"59497f16b9248d0024fe3f31"},"body":"[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Please note\",\n  \"body\": \"An adjustment may only be deleted if it has not been invoiced.\"\n}\n[/block]","createdAt":"2015-06-15T23:21:38.993Z","editedParams2":true,"githubsync":"","title":"Delete an Adjustment","updates":[],"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

deleteDelete an Adjustment

Delete an adjustment from an account. Only non-invoiced adjustments can be deleted.

Path Params

uuid:
required
string
The unique identifier for the adjustment

Please note

An adjustment may only be deleted if it has not been invoiced.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $adjustment = Recurly_Adjustment::get('626db120a84102b1809909071c701c60');
  $adjustment->delete();

  print "Adjustment: $adjustment";
} catch (Recurly_NotFoundError $e) {
  // NotFoundError if invalid uuid or already deleted
  print "Invalid adjustment uuid: $e";
}
adjustment = Recurly::Adjustment.find('945a4cb9afd64300b97b138407a51aef')
adjustment.destroy
adjustment = Adjustment.get('945a4cb9afd64300b97b138407a51aef')
adjustment.delete()
var adjustment = Adjustments.Get("945a4cb9afd64300b97b138407a51aef");
adjustment.Delete(

Result Format

Status: 204 No Content


{"_id":"57803084827bd50e006b0494","githubsync":"","updates":[],"user":"55648cf93b87582b003ab8b1","version":"57803084827bd50e006b0457","type":"get","api":{"results":{"codes":[{"status":200,"language":"xml","code":"<billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company nil=\"nil\"/>\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  <vat_number nil=\"nil\"/>\n  <ip_address>127.0.0.1</ip_address>\n  <ip_address_country nil=\"nil\"/>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2019</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info","auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $billing_info = Recurly_BillingInfo::get('b6f5783');\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account or account\n  // doesn't have billing info\n  print \"Not found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\nbilling_info = account.billing_info"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = account.BillingInfo;"}]},"method":"get","params":[{"ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code","_id":"55944f815c9eaa2300a8633a"},{"default":"","type":"string","name":"ip_address","_id":"5581ce0ea5474a0d00d94698","ref":"","in":"query","required":false,"desc":"Customer's IP address when updating their billing information"},{"in":"query","required":false,"desc":"Zip or postal code","default":"","type":"string","name":"zip","_id":"5581ce0ea5474a0d00d9469a","ref":""},{"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements)","default":"","type":"string","name":"country","_id":"5581ce0ea5474a0d00d9469b","ref":"","in":"query","required":false},{"_id":"5581ce0ea5474a0d00d9469c","ref":"","in":"query","required":false,"desc":"State","default":"","type":"string","name":"state"},{"_id":"5581ce0ea5474a0d00d94694","ref":"","in":"query","required":false,"desc":"Visa, MasterCard, American Express, Discover, JCB, etc","default":"","type":"string","name":"card_type"},{"_id":"5646783bc7687d0d00739f3f","ref":"","in":"query","required":false,"desc":"Company name","default":"","type":"string","name":"company"},{"_id":"5581ce0ea5474a0d00d94691","ref":"","in":"query","required":false,"desc":"PayPal Billing Agreement ID","default":"","type":"string","name":"paypal_billing_agreement_id"},{"name":"address2","_id":"5581ce0ea5474a0d00d9469e","ref":"","in":"query","required":false,"desc":"Address line 2","default":"","type":"string"},{"ref":"","in":"query","required":false,"desc":"City","default":"","type":"string","name":"city","_id":"5581ce0ea5474a0d00d9469d"},{"in":"query","required":false,"desc":"Last name","default":"","type":"string","name":"last_name","_id":"5581ce0ea5474a0d00d946a0","ref":""},{"required":false,"desc":"Amazon Billing Agreement ID","default":"","type":"string","name":"amazon_billing_agreement_id","_id":"5581ce0ea5474a0d00d94690","ref":"","in":"query"},{"type":"string","name":"first_name","_id":"5581ce0ea5474a0d00d946a1","ref":"","in":"query","required":false,"desc":"First name","default":""},{"desc":"Customer's VAT number","default":"","type":"string","name":"vat_number","_id":"5581ce0ea5474a0d00d94699","ref":"","in":"query","required":false},{"_id":"5581ce0ea5474a0d00d9469f","ref":"","in":"query","required":false,"desc":"Address line 1","default":"","type":"string","name":"address1"},{"_id":"5581ce0ea5474a0d00d94696","ref":"","in":"query","required":false,"desc":"Credit card number, first six digits","default":"","type":"int","name":"first_six"},{"_id":"5581ce0ea5474a0d00d94693","ref":"","in":"query","required":false,"desc":"Expiration month","default":"","type":"int","name":"month"},{"_id":"5581ce0ea5474a0d00d94692","ref":"","in":"query","required":false,"desc":"Expiration year","default":"","type":"int","name":"year"},{"ref":"","in":"query","required":false,"desc":"Credit card number, last four digits","default":"","type":"int","name":"last_four","_id":"5581ce0ea5474a0d00d94695"},{"_id":"5581ce0ea5474a0d00d94697","ref":"","in":"query","required":false,"desc":"Country of IP address, if known by Recurly","default":"","type":"string","name":"ip_address_country"},{"_id":"5581ce0ea5474a0d00d9468f","ref":"","in":"query","required":false,"desc":"The name associated with the account. This may be a person's full name or a business name. name_on_account is used instead of first_name and last_name if the payment method is Bank Account.","default":"","type":"string","name":"name_on_account"},{"name":"routing_number","_id":"5581ce0ea5474a0d00d9468e","ref":"","in":"query","required":false,"desc":"U.S. bank account routing number","default":"","type":"int"},{"ref":"","in":"query","required":false,"desc":"Bank account number","default":"","type":"int","name":"account_number","_id":"5581ce0ea5474a0d00d9468d"},{"default":"","type":"string","name":"account_type","_id":"5581ce0ea5474a0d00d9468c","ref":"","in":"query","required":false,"desc":"Either 'checking' or 'savings'"},{"default":"","type":"string","name":"currency","_id":"57606120dc8f9f0e00c5977c","ref":"","in":"query","required":false,"desc":"A 3-letter currency to override your site default (if you know this, setting it may save you an extra verification call)"}],"apiSetting":"59497f16b9248d0024fe3f31"},"body":"","category":"57803084827bd50e006b045e","createdAt":"2015-06-17T19:44:14.605Z","parentDoc":null,"title":"Lookup an Account's Billing Info","sync_unique":"","__v":15,"editedParams":true,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","editedParams2":true,"excerpt":"Returns only the account's current billing information.","hidden":false,"isReference":true,"slug":"lookup-an-accounts-billing-info","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getLookup an Account's Billing Info

Returns only the account's current billing information.

Path Params

account_code:
required
string
Account's unique code.

Query Params

ip_address:
string
Customer's IP address when updating their billing information
zip:
string
Zip or postal code
country:
string
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements)
state:
string
State
card_type:
string
Visa, MasterCard, American Express, Discover, JCB, etc
company:
string
Company name
paypal_billing_agreement_id:
string
PayPal Billing Agreement ID
address2:
string
Address line 2
city:
string
City
last_name:
string
Last name
amazon_billing_agreement_id:
string
Amazon Billing Agreement ID
first_name:
string
First name
vat_number:
string
Customer's VAT number
address1:
string
Address line 1
first_six:
integer
Credit card number, first six digits
month:
integer
Expiration month
year:
integer
Expiration year
last_four:
integer
Credit card number, last four digits
ip_address_country:
string
Country of IP address, if known by Recurly
name_on_account:
string
The name associated with the account. This may be a person's full name or a business name. name_on_account is used instead of first_name and last_name if the payment method is Bank Account.
routing_number:
integer
U.S. bank account routing number
account_number:
integer
Bank account number
account_type:
string
Either 'checking' or 'savings'
currency:
string
A 3-letter currency to override your site default (if you know this, setting it may save you an extra verification call)

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = Recurly_BillingInfo::get('b6f5783');
  print "Billing Info: $billing_info";
} catch (Recurly_NotFoundError $e) {
  // Could not find account or account
  // doesn't have billing info
  print "Not found: $e";
}
account = Recurly::Account.find('1')
billing_info = account.billing_info
account = Account.get('1')
billing_info = account.billing_info
var account = Accounts.Get("1");
var info = account.BillingInfo;

Result Format

<billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info" type="credit_card">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"/>
  <address1>123 Main St.</address1>
  <address2 nil="nil"/>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"/>
  <vat_number nil="nil"/>
  <ip_address>127.0.0.1</ip_address>
  <ip_address_country nil="nil"/>
  <card_type>Visa</card_type>
  <year type="integer">2019</year>
  <month type="integer">11</month>
  <first_six>411111</first_six>
  <last_four>1111</last_four>
</billing_info>


{"_id":"57803084827bd50e006b0495","excerpt":"Creates an account's Billing Information using a [token generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns the account's created Billing Information.","parentDoc":null,"type":"post","updates":["56799b95239fac0d00c7e019"],"api":{"method":"post","params":[{"in":"path","name":"account_code","ref":"","required":true,"type":"string","_id":"55944f99ccc3052300569885","default":"","desc":"Account's unique code."},{"default":"","desc":"A token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token)","in":"body","name":"token_id","ref":"","required":true,"type":"string","_id":"5581ced4a5474a0d00d946a5"},{"type":"string","name":"currency","in":"body","_id":"56d0e86f40d36e1d00bc14c9","ref":"","required":false,"desc":"Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.","default":""}],"results":{"codes":[{"status":201,"language":"xml","code":"<billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</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 nil=\"nil\"></phone>\n  <vat_number>US1234567890</vat_number>\n  <ip_address>127.0.0.1</ip_address>\n  <ip_address_country>US</ip_address_country>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2019</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info","auth":"required","examples":{"codes":[{"code":"<?php\n\ntry {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->token_id = '7z6furn4jvb9'; // From Recurly.js\n  $billing_info->create();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account or token is invalid or expired\n  print \"Not Found: $e\";\n}","name":"","language":"php"},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  token_id: 'TOKEN_ID'\n}\naccount.billing_info.save!"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.token_id = 'TOKEN_ID'\naccount.update_billing_info(billing_info)"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.TokenId = \"TOKEN_ID\";\ninfo.Create();"},{"language":"xml","code":"<billing_info>\n  <token_id>TOKEN_ID</token_id>\n</billing_info>"}]},"apiSetting":"59497f16b9248d0024fe3f31"},"category":"57803084827bd50e006b045e","githubsync":"","link_external":false,"order":1,"sync_unique":"","title":"Create an Account's Billing Info (Token)","__v":1,"createdAt":"2015-06-17T19:47:32.787Z","editedParams2":true,"isReference":true,"slug":"create-an-accounts-billing-info-token","user":"55648cf93b87582b003ab8b1","version":"57803084827bd50e006b0457","body":"","editedParams":true,"hidden":false,"link_url":"","project":"555fbba928249c1900618a82","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate an Account's Billing Info (Token)

Creates an account's Billing Information using a [token generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns the account's created Billing Information.

Path Params

account_code:
required
string
Account's unique code.

Body Params

token_id:
required
string
A token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token)
currency:
string
Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = new Recurly_BillingInfo();
  $billing_info->account_code = 'b6f5783';
  $billing_info->token_id = '7z6furn4jvb9'; // From Recurly.js
  $billing_info->create();

  print "Billing Info: $billing_info";
} catch (Recurly_NotFoundError $e) {
  // Could not find account or token is invalid or expired
  print "Not Found: $e";
}
account = Recurly::Account.find('1')
account.billing_info = {
  token_id: 'TOKEN_ID'
}
account.billing_info.save!
account = Account.get('1')
billing_info = account.billing_info
billing_info.token_id = 'TOKEN_ID'
account.update_billing_info(billing_info)
var account = Accounts.Get("1");
var info = new BillingInfo(account);
info.TokenId = "TOKEN_ID";
info.Create();
<billing_info>
  <token_id>TOKEN_ID</token_id>
</billing_info>

Result Format

<billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info" type="credit_card">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"></company>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"></phone>
  <vat_number>US1234567890</vat_number>
  <ip_address>127.0.0.1</ip_address>
  <ip_address_country>US</ip_address_country>
  <card_type>Visa</card_type>
  <year type="integer">2019</year>
  <month type="integer">11</month>
  <first_six>411111</first_six>
  <last_four>1111</last_four>
</billing_info>


{"_id":"57803084827bd50e006b0496","version":"57803084827bd50e006b0457","api":{"auth":"required","examples":{"codes":[{"code":"<?php\n\ntry {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->first_name = 'Verena';\n  $billing_info->last_name = 'Example';\n  $billing_info->number = '4111-1111-1111-1111';\n  $billing_info->verification_value = '123';\n  $billing_info->month = 11;\n  $billing_info->year = 2017;\n  $billing_info->create();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_ValidationError $e) {\n  // The data or card are invalid\n  print \"Invalid data or card: $e\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account\n  print \"Not Found: $e\";\n}","name":"","language":"php"},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  :first_name         => 'Verena',\n  :last_name          => 'Example',\n  :number             => '4111-1111-1111-1111',\n  :verification_value => '123',\n  :month              => 11,\n  :year               => 2015\n}\naccount.billing_info.save!"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.first_name = 'Verena'\nbilling_info.last_name = 'Example'\nbilling_info.number = '4111-1111-1111-1111'\nbilling_info.verification_value = '123'\nbilling_info.month = 11\nbilling_info.year = 2015\naccount.update_billing_info(billing_info)"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.FirstName = \"Verana\";\ninfo.LastName = \"Example\";\ninfo.CreditCardNumber = \"4111-1111-1111-1111\";\ninfo.VerificationValue = \"123\";\ninfo.ExpirationMonth = 11;\ninfo.ExpirationYear = 2015;\ninfo.Create();"},{"language":"xml","code":"<billing_info>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\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  <number>4111-1111-1111-1111</number>\n  <verification_value>123</verification_value>\n  <month>11</month>\n  <year>2019</year>\n  <ip_address>127.0.0.1</ip_address>\n</billing_info>"}]},"method":"post","params":[{"desc":"Account's unique code.","in":"path","name":"account_code","ref":"","required":true,"type":"string","_id":"55944fab5c9eaa2300a8633c","default":""},{"default":"","type":"string","name":"first_name","in":"body","_id":"5581d09a8625220d00429e4d","ref":"","required":true,"desc":"First name"},{"in":"body","_id":"5581d09a8625220d00429e4c","ref":"","required":true,"desc":"Last name","default":"","type":"string","name":"last_name"},{"name":"number","in":"body","_id":"5581d09a8625220d00429e42","ref":"","required":true,"desc":"Credit card number, spaces and dashes are accepted","default":"","type":"string"},{"desc":"Expiration month","default":"","type":"string","name":"month","in":"body","_id":"5581d09a8625220d00429e41","ref":"","required":true},{"ref":"","required":true,"desc":"Expiration year","default":"","type":"string","name":"year","in":"body","_id":"5581d09a8625220d00429e40"},{"required":false,"desc":"Address line 1, recommended for address validation","default":"","type":"string","name":"address1","in":"body","_id":"5581d09a8625220d00429e4b","ref":""},{"desc":"Address line 2.","default":"","type":"string","name":"address2","in":"body","_id":"5581d09a8625220d00429e4a","ref":"","required":false},{"ref":"","required":false,"desc":"City","default":"","type":"string","name":"city","in":"body","_id":"5581d09a8625220d00429e49"},{"required":false,"desc":"State","default":"","type":"string","name":"state","in":"body","_id":"5581d09a8625220d00429e48","ref":""},{"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country","in":"body","_id":"5581d09a8625220d00429e47","ref":"","required":false},{"ref":"","required":false,"desc":"Zip or postal code, recommended for address validation","default":"","type":"string","name":"zip","in":"body","_id":"5581d09a8625220d00429e46"},{"type":"string","name":"phone","in":"body","_id":"5581d09a8625220d00429e45","ref":"","required":false,"desc":"Phone number","default":""},{"required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number","in":"body","_id":"5581d09a8625220d00429e44","ref":""},{"desc":"Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.","default":"","type":"string","name":"currency","in":"body","_id":"56c3c1ce70187b17005f4395","ref":"","required":false},{"name":"verification_value","in":"body","_id":"5581d09a8625220d00429e3f","ref":"","required":false,"desc":"Security code or CVV, 3-4 digits **STRONGLY RECOMMENDED**","default":"","type":"string"},{"default":"","type":"string","name":"ip_address","in":"body","_id":"5581d09a8625220d00429e43","ref":"","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**"}],"results":{"codes":[{"language":"xml","code":"<billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company nil=\"nil\"/>\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  <vat_number nil=\"nil\"/>\n  <ip_address>127.0.0.1</ip_address>\n  <ip_address_country nil=\"nil\"/>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2019</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":"","status":201}]},"settings":"","url":"/accounts/:account_code/billing_info","apiSetting":"59497f16b9248d0024fe3f31"},"editedParams":true,"excerpt":"Creates the account's Billing Information.","link_external":false,"parentDoc":null,"project":"555fbba928249c1900618a82","category":"57803084827bd50e006b045e","isReference":true,"sync_unique":"","user":"55648cf93b87582b003ab8b1","__v":1,"body":"Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when creating Billing Information.\n\nWhen Billing Information is submitted, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.\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.\n[block:callout]\n{\n  \"type\": \"warning\",\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 credit card details.\",\n  \"title\": \"Please note\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.\",\n  \"title\": \"Please note\"\n}\n[/block]","githubsync":"","link_url":"","order":2,"title":"Create an Account's Billing Info (Credit Card)","createdAt":"2015-06-17T19:55:06.712Z","editedParams2":true,"hidden":false,"slug":"create-an-accounts-billing-info-credit-card","type":"post","updates":["55d336260168850d0073f054","562944f61a92870d0002c301","56bb59bae59a312b00a15bac"],"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate an Account's Billing Info (Credit Card)

Creates the account's Billing Information.

Path Params

account_code:
required
string
Account's unique code.

Body Params

first_name:
required
string
First name
last_name:
required
string
Last name
number:
required
string
Credit card number, spaces and dashes are accepted
month:
required
string
Expiration month
year:
required
string
Expiration year
address1:
string
Address line 1, recommended for address validation
address2:
string
Address line 2.
city:
string
City
state:
string
State
country:
string
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**
zip:
string
Zip or postal code, recommended for address validation
phone:
string
Phone number
vat_number:
string
Customer's VAT Number
currency:
string
Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.
verification_value:
string
Security code or CVV, 3-4 digits **STRONGLY RECOMMENDED**
ip_address:
string
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**

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

When Billing Information is submitted, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.

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.

Please note

Recurly strongly recommends using a token generated by Recurly.js rather than directly handling your customer's credit card details.

Please note

This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = new Recurly_BillingInfo();
  $billing_info->account_code = 'b6f5783';
  $billing_info->first_name = 'Verena';
  $billing_info->last_name = 'Example';
  $billing_info->number = '4111-1111-1111-1111';
  $billing_info->verification_value = '123';
  $billing_info->month = 11;
  $billing_info->year = 2017;
  $billing_info->create();

  print "Billing Info: $billing_info";
} catch (Recurly_ValidationError $e) {
  // The data or card are invalid
  print "Invalid data or card: $e";
} catch (Recurly_NotFoundError $e) {
  // Could not find account
  print "Not Found: $e";
}
account = Recurly::Account.find('1')
account.billing_info = {
  :first_name         => 'Verena',
  :last_name          => 'Example',
  :number             => '4111-1111-1111-1111',
  :verification_value => '123',
  :month              => 11,
  :year               => 2015
}
account.billing_info.save!
account = Account.get('1')
billing_info = account.billing_info
billing_info.first_name = 'Verena'
billing_info.last_name = 'Example'
billing_info.number = '4111-1111-1111-1111'
billing_info.verification_value = '123'
billing_info.month = 11
billing_info.year = 2015
account.update_billing_info(billing_info)
var account = Accounts.Get("1");
var info = new BillingInfo(account);
info.FirstName = "Verana";
info.LastName = "Example";
info.CreditCardNumber = "4111-1111-1111-1111";
info.VerificationValue = "123";
info.ExpirationMonth = 11;
info.ExpirationYear = 2015;
info.Create();
<billing_info>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <number>4111-1111-1111-1111</number>
  <verification_value>123</verification_value>
  <month>11</month>
  <year>2019</year>
  <ip_address>127.0.0.1</ip_address>
</billing_info>

Result Format

<billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info" type="credit_card">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"/>
  <address1>123 Main St.</address1>
  <address2 nil="nil"/>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"/>
  <vat_number nil="nil"/>
  <ip_address>127.0.0.1</ip_address>
  <ip_address_country nil="nil"/>
  <card_type>Visa</card_type>
  <year type="integer">2019</year>
  <month type="integer">11</month>
  <first_six>411111</first_six>
  <last_four>1111</last_four>
</billing_info>


{"_id":"57803084827bd50e006b0497","category":"57803084827bd50e006b045e","githubsync":"","order":3,"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]","editedParams2":true,"hidden":false,"parentDoc":null,"title":"Create an Account's Billing Info (Bank Account)","type":"post","updates":["56ec2580df213e1700f77836"],"version":"57803084827bd50e006b0457","__v":1,"api":{"params":[{"required":true,"type":"string","_id":"55944fbb0c33bd0d0005964b","default":"","desc":"Account's unique code.","in":"path","name":"account_code","ref":""},{"default":"","type":"string","name":"name_on_account","in":"body","_id":"5581d1f08625220d00429e6d","ref":"","required":true,"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 . ' & , -"},{"_id":"5581d1f08625220d00429e63","ref":"","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","in":"body"},{"_id":"5581d1f08625220d00429e62","ref":"","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","in":"body"},{"_id":"5581d1f08625220d00429e61","ref":"","required":true,"desc":"Either 'checking' or 'savings'","default":"","type":"string","name":"account_type","in":"body"},{"_id":"5581d1f08625220d00429e6c","ref":"","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","in":"body"},{"_id":"5581d1f08625220d00429e6b","ref":"","required":false,"desc":"Address line 2, this field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address2","in":"body"},{"in":"body","_id":"5581d1f08625220d00429e6a","ref":"","required":false,"desc":"City, this field has a 50 character max and can include: letters digits space . , -","default":"","type":"string","name":"city"},{"ref":"","required":false,"desc":"State, this field has a 2 character max and can be lowercase or uppercase.","default":"","type":"string","name":"state","in":"body","_id":"5581d1f08625220d00429e69"},{"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","in":"body","_id":"5581d1f08625220d00429e68","ref":""},{"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":"zip","in":"body","_id":"5581d1f08625220d00429e67","ref":"","required":false},{"ref":"","required":false,"desc":"Phone number, this field can be 10 digits.","default":"","type":"string","name":"phone","in":"body","_id":"5581d1f08625220d00429e66"},{"type":"string","name":"vat_number","in":"body","_id":"5581d1f08625220d00429e65","ref":"","required":false,"desc":"Customer's VAT Number","default":""},{"type":"string","name":"ip_address","in":"body","_id":"5581d1f08625220d00429e64","ref":"","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**","default":""}],"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</billing_info>"}]},"settings":"","url":"/accounts/:account_code/billing_info","auth":"required","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","apiSetting":"59497f16b9248d0024fe3f31"},"editedParams":true,"isReference":true,"link_external":false,"link_url":"","createdAt":"2015-06-17T20:00:48.689Z","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.","project":"555fbba928249c1900618a82","slug":"create-an-accounts-billing-info-bank-account","sync_unique":"","user":"55648cf93b87582b003ab8b1","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate an 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.
country:
string
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements). **STRONGLY RECOMMENDED**
zip:
string
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).
phone:
string
Phone number, this field can be 10 digits.
vat_number:
string
Customer's VAT Number
ip_address:
string
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**

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.

Please note

Recurly strongly recommends using a token generated by Recurly.js rather than directly handling your customer's bank account details.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = new Recurly_BillingInfo();
  $billing_info->account_code = 'b6f5783';
  $billing_info->name_on_account = 'Acme Inc.';
  $billing_info->routing_number = '065400137';
  $billing_info->account_number = '4444000000005555';
  $billing_info->account_type = 'checking';
  $billing_info->address1 = '123 Main St.';
  $billing_info->city = 'San Francisco';
  $billing_info->state ='CA';
  $billing_info->country = 'US';
  $billing_info->zip = '94105';
  $billing_info->create();

  print "Billing Info: $billing_info";
} catch (Recurly_ValidationError $e) {
  // The data or bank account are invalid
  print "Invalid data or card: $e";
} catch (Recurly_NotFoundError $e) {
  // Could not find account
  print "Account Not Found: $e";
}
account = Recurly::Account.find('1')
account.billing_info = {
  name_on_account: 'Acme, Inc.',
  routing_number: '065400137',
  account_number: '4444000000005555',
  address1: '123 Main St.',
  city: 'San Francisco',
  state: 'CA',
  country: 'US',
  zip: '94105'
}
account.billing_info.save!
account = Account.get('1')
billing_info = recurly.BillingInfo(
  name_on_account = 'Acme, Inc.',
  routing_number = '065400137',
  account_number = '4444000000005555',
  account_type = 'checking',
  address1 = '123 Main St.',
  city = 'San Francisco',
  state ='CA',
  country = 'US',
  zip = '94105'
  )
account.update_billing_info(billing_info)
var account = Accounts.Get("1");
var info = new BillingInfo(account);
info.NameOnAccount = "Acme, Inc.";
info.RoutingNumber = "065400137";
info.AccountNumber = "4444000000005555";
info.AccountType = BillingInfo.BankAccountType.Checking;
info.Address1 = "123 Main St.";
info.City = "San Francisco";
info.State = "CA";
info.Country = "US";
info.PostalCode = "94105";
info.Create();
<billing_info>
  <name_on_account>Acme, Inc.</name_on_account>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <routing_number>065400137</routing_number>
  <account_number>4444000000005555</account_number>
  <account_type>checking</account_type>
  <ip_address>127.0.0.1</ip_address>
</billing_info>

Result Format

<billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info" type="bank_account">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <name_on_account>Acme, Inc.</name_on_account>
  <first_name nil="nil"></first_name>
  <last_name nil="nil"></last_name>
  <company nil="nil"></company>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone></phone>
  <vat_number></vat_number>
  <ip_address>127.0.0.1</ip_address>
  <ip_address_country>US</ip_address_country>
  <account_type>checking</account_type>
  <last_four>5555</last_four>
  <routing_number>065400137</routing_number>
</billing_info>


{"_id":"57803084827bd50e006b0498","slug":"create-an-accounts-billing-info-using-external-token","body":"Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when creating Billing Information.\n\nWhen Billing Information is submitted, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.\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.\n[block:callout]\n{\n  \"type\": \"warning\",\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 credit card details.\",\n  \"title\": \"Please note\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.\",\n  \"title\": \"Please note\"\n}\n[/block]","category":"57803084827bd50e006b045e","createdAt":"2016-04-29T21:58:10.697Z","editedParams":true,"link_external":false,"order":4,"project":"555fbba928249c1900618a82","user":"56c3c01334df460d00c2beb3","__v":1,"link_url":"","sync_unique":"","api":{"params":[{"required":true,"type":"string","_id":"55944fab5c9eaa2300a8633c","default":"","desc":"Account's unique code.","in":"path","name":"account_code","ref":""},{"desc":"First name","default":"","type":"string","name":"first_name","in":"body","_id":"5581d09a8625220d00429e4d","ref":"","required":true},{"name":"last_name","in":"body","_id":"5581d09a8625220d00429e4c","ref":"","required":true,"desc":"Last name","default":"","type":"string"},{"default":"","type":"string","name":"address1","in":"body","_id":"5581d09a8625220d00429e4b","ref":"","required":false,"desc":"Address line 1, recommended for address validation"},{"_id":"5581d09a8625220d00429e4a","ref":"","required":false,"desc":"Address line 2.","default":"","type":"string","name":"address2","in":"body"},{"_id":"5581d09a8625220d00429e49","ref":"","required":false,"desc":"City","default":"","type":"string","name":"city","in":"body"},{"_id":"5581d09a8625220d00429e48","ref":"","required":false,"desc":"State","default":"","type":"string","name":"state","in":"body"},{"_id":"5581d09a8625220d00429e47","ref":"","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","in":"body"},{"_id":"5581d09a8625220d00429e46","ref":"","required":false,"desc":"Zip or postal code, recommended for address validation","default":"","type":"string","name":"zip","in":"body"},{"in":"body","_id":"5581d09a8625220d00429e45","ref":"","required":false,"desc":"Phone number","default":"","type":"string","name":"phone"},{"ref":"","required":false,"desc":"Paypal's billing agreement","default":"","type":"string","name":"paypal_billing_agreement_id","in":"body","_id":"5723d8f2110e570e00486c2f"},{"required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number","in":"body","_id":"5581d09a8625220d00429e44","ref":""},{"desc":"Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.","default":"","type":"string","name":"currency","in":"body","_id":"56c3c1ce70187b17005f4395","ref":"","required":false},{"ref":"","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address","in":"body","_id":"5581d09a8625220d00429e43"}],"results":{"codes":[{"status":201,"language":"xml","code":"<billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</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 nil=\"nil\"></phone>\n  <paypal_billing_agreement_id>BA-0HS87238YB688345C</paypal_billing_agreement_id>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info","auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->first_name = 'Verena';\n  $billing_info->last_name = 'Example';\n  $billing_info->paypal_billing_agreement_id = 'BA-0HS87238YB688345C';\n  $billing_info->create();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_ValidationError $e) {\n  // The paypal billing agreement provided is invalid\n  print \"Invalid paypal billing agreement: $e\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account\n  print \"Not Found: $e\";\n}","name":""},{"code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  :first_name         => 'Verena',\n  :last_name          => 'Example',\n  :paypal_billing_agreement_id             => 'BA-0HS87238YB688345C'\n}\naccount.billing_info.save!","language":"ruby"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.first_name = 'Verena'\nbilling_info.last_name = 'Example'\nbilling_info.paypal_billing_agreement_id = 'BA-0HS87238YB688345C'\naccount.update_billing_info(billing_info)"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.FirstName = \"Verana\";\ninfo.LastName = \"Example\";\ninfo.PaypalBillingAgreementId = \"BA-0HS87238YB688345C\";\ninfo.Create();"},{"language":"xml","code":"<billing_info>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\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  <paypal_billing_agreement_id>BA-0HS87238YB688345C</paypal_billing_agreement_id>\n  <ip_address>127.0.0.1</ip_address>\n</billing_info>"}]},"method":"post","apiSetting":"59497f16b9248d0024fe3f31"},"editedParams2":true,"parentDoc":null,"updates":[],"version":"57803084827bd50e006b0457","excerpt":"Creates the account's Billing Information using external token for example: Paypal billing agreement","githubsync":"","hidden":false,"isReference":true,"title":"Create an Account's Billing Info (using external token)","type":"post","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate an Account's Billing Info (using external token)

Creates the account's Billing Information using external token for example: Paypal billing agreement

Path Params

account_code:
required
string
Account's unique code.

Body Params

first_name:
required
string
First name
last_name:
required
string
Last name
address1:
string
Address line 1, recommended for address validation
address2:
string
Address line 2.
city:
string
City
state:
string
State
country:
string
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**
zip:
string
Zip or postal code, recommended for address validation
phone:
string
Phone number
paypal_billing_agreement_id:
string
Paypal's billing agreement
vat_number:
string
Customer's VAT Number
currency:
string
Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.
ip_address:
string
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**

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

When Billing Information is submitted, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.

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.

Please note

Recurly strongly recommends using a token generated by Recurly.js rather than directly handling your customer's credit card details.

Please note

This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = new Recurly_BillingInfo();
  $billing_info->account_code = 'b6f5783';
  $billing_info->first_name = 'Verena';
  $billing_info->last_name = 'Example';
  $billing_info->paypal_billing_agreement_id = 'BA-0HS87238YB688345C';
  $billing_info->create();

  print "Billing Info: $billing_info";
} catch (Recurly_ValidationError $e) {
  // The paypal billing agreement provided is invalid
  print "Invalid paypal billing agreement: $e";
} catch (Recurly_NotFoundError $e) {
  // Could not find account
  print "Not Found: $e";
}
account = Recurly::Account.find('1')
account.billing_info = {
  :first_name         => 'Verena',
  :last_name          => 'Example',
  :paypal_billing_agreement_id             => 'BA-0HS87238YB688345C'
}
account.billing_info.save!
account = Account.get('1')
billing_info = account.billing_info
billing_info.first_name = 'Verena'
billing_info.last_name = 'Example'
billing_info.paypal_billing_agreement_id = 'BA-0HS87238YB688345C'
account.update_billing_info(billing_info)
var account = Accounts.Get("1");
var info = new BillingInfo(account);
info.FirstName = "Verana";
info.LastName = "Example";
info.PaypalBillingAgreementId = "BA-0HS87238YB688345C";
info.Create();
<billing_info>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <paypal_billing_agreement_id>BA-0HS87238YB688345C</paypal_billing_agreement_id>
  <ip_address>127.0.0.1</ip_address>
</billing_info>

Result Format

<billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info" type="credit_card">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"></company>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"></phone>
  <paypal_billing_agreement_id>BA-0HS87238YB688345C</paypal_billing_agreement_id>
</billing_info>


{"_id":"57803084827bd50e006b0499","editedParams":true,"excerpt":"Updates an account's Billing Information using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns the account's current Billing Information.","githubsync":"","parentDoc":null,"user":"55648cf93b87582b003ab8b1","category":"57803084827bd50e006b045e","order":5,"sync_unique":"","slug":"update-an-accounts-billing-info-token","title":"Update an Account's Billing Info (Token)","__v":1,"api":{"examples":{"codes":[{"name":"","language":"php","code":"<?php\n\ntry {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->token_id = '7z6furn4jvb9'; // From Recurly.js\n  $billing_info->update();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account or token is invalid or expired\n  print \"Not Found: $e\";\n}"},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info.token_id = 'TOKEN_ID'\naccount.billing_info.save!"},{"code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.token_id = 'TOKEN_ID'\naccount.update_billing_info(billing_info)","language":"python"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.TokenId = \"TOKEN_ID\";\ninfo.Update();"},{"language":"xml","code":"<billing_info>\n  <token_id>TOKEN_ID</token_id>\n</billing_info>"}]},"method":"put","params":[{"ref":"","required":true,"type":"string","_id":"55944fca5c9eaa2300a8633e","default":"","desc":"Account's unique code.","in":"path","name":"account_code"},{"desc":"A token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token).","in":"body","name":"token_id","ref":"","required":true,"type":"string","_id":"5581d2f8a5474a0d00d946bc","default":""},{"default":"","type":"string","name":"currency","in":"body","_id":"56d0e7b07c2e100b000afa25","ref":"","required":false,"desc":"Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default."}],"results":{"codes":[{"status":200,"language":"xml","code":"<billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</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 nil=\"nil\"></phone>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2019</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info","auth":"required","apiSetting":"59497f16b9248d0024fe3f31"},"body":"[Recurly.js](https://js.recurly.com/) allows you to collect customer Billing Information and tokenize it, preventing your servers from having to handle credit card information. When you send these tokens to Recurly through our API, we unpack the token and update Billing Information accordingly.\n\nWhen Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.\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 info with your request.","hidden":false,"isReference":true,"project":"555fbba928249c1900618a82","type":"put","version":"57803084827bd50e006b0457","createdAt":"2015-06-17T20:05:12.621Z","editedParams2":true,"link_external":false,"link_url":"","updates":[],"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

putUpdate an Account's Billing Info (Token)

Updates an account's Billing Information using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns the account's current Billing Information.

Path Params

account_code:
required
string
Account's unique code.

Body Params

token_id:
required
string
A token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token).
currency:
string
Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.

Recurly.js allows you to collect customer Billing Information and tokenize it, preventing your servers from having to handle credit card information. When you send these tokens to Recurly through our API, we unpack the token and update Billing Information accordingly.

When Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.

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

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = new Recurly_BillingInfo();
  $billing_info->account_code = 'b6f5783';
  $billing_info->token_id = '7z6furn4jvb9'; // From Recurly.js
  $billing_info->update();

  print "Billing Info: $billing_info";
} catch (Recurly_NotFoundError $e) {
  // Could not find account or token is invalid or expired
  print "Not Found: $e";
}
account = Recurly::Account.find('1')
account.billing_info.token_id = 'TOKEN_ID'
account.billing_info.save!
account = Account.get('1')
billing_info = account.billing_info
billing_info.token_id = 'TOKEN_ID'
account.update_billing_info(billing_info)
var account = Accounts.Get("1");
var info = new BillingInfo(account);
info.TokenId = "TOKEN_ID";
info.Update();
<billing_info>
  <token_id>TOKEN_ID</token_id>
</billing_info>

Result Format

<billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info" type="credit_card">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"></company>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"></phone>
  <card_type>Visa</card_type>
  <year type="integer">2019</year>
  <month type="integer">11</month>
  <first_six>411111</first_six>
  <last_four>1111</last_four>
</billing_info>


{"_id":"57803084827bd50e006b049a","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->first_name = 'Verena';\n  $billing_info->last_name = 'Example';\n  $billing_info->number = '4111-1111-1111-1111';\n  $billing_info->verification_value = '123';\n  $billing_info->month = 11;\n  $billing_info->year = 2017;\n  $billing_info->update();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_ValidationError $e) {\n  // The data or card are invalid\n  print \"Invalid data or card: $e\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account\n  print \"Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  :first_name         => 'Verena',\n  :last_name          => 'Example',\n  :number             => '4111-1111-1111-1111',\n  :verification_value => '123',\n  :month              => 11,\n  :year               => 2015\n}\naccount.billing_info.save!"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.first_name = 'Verena'\nbilling_info.last_name = 'Example'\nbilling_info.number = '4111-1111-1111-1111'\nbilling_info.verification_value = '123'\nbilling_info.month = 11\nbilling_info.year = 2015\naccount.update_billing_info(billing_info)"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.FirstName = \"Verana\";\ninfo.LastName = \"Example\";\ninfo.CreditCardNumber = \"4111-111-1111-1111\";\ninfo.VerificationValue = \"123\";\ninfo.ExpirationMonth = 11;\ninfo.ExpirationYear = 2015;\ninfo.Update();"},{"language":"xml","code":"<billing_info>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <number>4111-1111-1111-1111</number>\n  <verification_value>123</verification_value>\n  <month>11</month>\n  <year>2019</year>\n  <ip_address>127.0.0.1</ip_address>\n</billing_info>"}]},"method":"put","params":[{"required":true,"type":"string","_id":"55944fdb5c9eaa2300a8633f","default":"","desc":"Account's unique code.","in":"path","name":"account_code","ref":""},{"default":"","type":"string","name":"first_name","in":"body","_id":"5581d46f8625220d00429e81","ref":"","required":false,"desc":"First name"},{"in":"body","_id":"5581d46f8625220d00429e80","ref":"","required":false,"desc":"Last name","default":"","type":"string","name":"last_name"},{"ref":"","required":false,"desc":"Address line 1, recommended for address validation","default":"","type":"string","name":"address1","in":"body","_id":"5581d46f8625220d00429e7f"},{"type":"string","name":"address2","in":"body","_id":"5581d46f8625220d00429e7e","ref":"","required":false,"desc":"Address line 2","default":""},{"required":false,"desc":"City","default":"","type":"string","name":"city","in":"body","_id":"5581d46f8625220d00429e7d","ref":""},{"default":"","type":"string","name":"state","in":"body","_id":"5581d46f8625220d00429e7c","ref":"","required":false,"desc":"State"},{"in":"body","_id":"5581d46f8625220d00429e7b","ref":"","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"},{"name":"zip","in":"body","_id":"5581d46f8625220d00429e7a","ref":"","required":false,"desc":"Zip or postal code, recommended for address validation","default":"","type":"string"},{"desc":"Phone number","default":"","type":"string","name":"phone","in":"body","_id":"5581d46f8625220d00429e79","ref":"","required":false},{"name":"vat_number","in":"body","_id":"5581d46f8625220d00429e78","ref":"","required":false,"desc":"Customer's VAT Number","default":"","type":"string"},{"desc":"Credit card number, spaces and dashes are accepted","default":"","type":"string","name":"number","in":"body","_id":"5581d46f8625220d00429e76","ref":"","required":false},{"ref":"","required":false,"desc":"Expiration month","default":"","type":"string","name":"month","in":"body","_id":"5581d46f8625220d00429e75"},{"type":"string","name":"year","in":"body","_id":"5581d46f8625220d00429e74","ref":"","required":false,"desc":"Expiration year","default":""},{"type":"string","name":"verification_value","in":"body","_id":"5581d46f8625220d00429e73","ref":"","required":false,"desc":"Security code or CVV, 3-4 digits **STRONGLY RECOMMENDED**","default":""},{"type":"string","name":"ip_address","in":"body","_id":"5581d46f8625220d00429e77","ref":"","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**","default":""},{"type":"string","name":"currency","in":"body","_id":"56c3c273c0c4630d004e86a8","ref":"","required":false,"desc":"Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.","default":""}],"results":{"codes":[{"code":"<billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company nil=\"nil\"/>\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  <vat_number nil=\"nil\"/>\n  <ip_address>127.0.0.1</ip_address>\n  <ip_address_country nil=\"nil\"/>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2019</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":"","status":200,"language":"xml"}]},"settings":"","url":"/accounts/:account_code/billing_info","apiSetting":"59497f16b9248d0024fe3f31"},"githubsync":"","hidden":false,"isReference":true,"project":"555fbba928249c1900618a82","title":"Update an Account's Billing Info (Credit Card)","updates":["55d337a4f77e6d0d00b1afab","562945ab1a92870d0002c302"],"__v":1,"body":"Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when updating Billing Information. Non PCI sensitive billing info can be updated by api without re-submitting the token. This can be done in two ways: 1)Through the billing info api (docs. link: https://docs.recurly.com/api/billing-info#update-billing-info-credit-card ) whereby you submit only the information that needs to be updated. In that way, all other information remains unchanged on the account. 2) Providing the end user a unique url link to their billing info page, where they can update their own billing info securly. This link can be found in the configuration window of the subscriber's account. https://SUBDOMAIN.recurly.com/accounts/:account_code/edit. You will see a hosted billing information URL that takes the user to their billing site hosted by Recurly.\n\nWhen Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.\n\nIf you want to create an account at the same time, you should use the [Account API](https://docs.recurly.com/api/accounts#create-account) end-point instead and include Billing Information with your request.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Please note\",\n  \"body\": \"This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\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 credit card details. You can, however, use this API call to update the billing address associated with an account.\",\n  \"title\": \"Please note\"\n}\n[/block]","parentDoc":null,"sync_unique":"","user":"55648cf93b87582b003ab8b1","editedParams":true,"editedParams2":true,"link_external":false,"order":6,"slug":"update-an-accounts-billing-info-credit-card","type":"put","version":"57803084827bd50e006b0457","category":"57803084827bd50e006b045e","createdAt":"2015-06-17T20:11:27.639Z","excerpt":"Returns the account's updated Billing Information.","link_url":"","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

putUpdate an Account's Billing Info (Credit Card)

Returns the account's updated Billing Information.

Path Params

account_code:
required
string
Account's unique code.

Body Params

first_name:
string
First name
last_name:
string
Last name
address1:
string
Address line 1, recommended for address validation
address2:
string
Address line 2
city:
string
City
state:
string
State
country:
string
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**
zip:
string
Zip or postal code, recommended for address validation
phone:
string
Phone number
vat_number:
string
Customer's VAT Number
number:
string
Credit card number, spaces and dashes are accepted
month:
string
Expiration month
year:
string
Expiration year
verification_value:
string
Security code or CVV, 3-4 digits **STRONGLY RECOMMENDED**
ip_address:
string
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**
currency:
string
Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.

Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when updating Billing Information. Non PCI sensitive billing info can be updated by api without re-submitting the token. This can be done in two ways: 1)Through the billing info api (docs. link: https://docs.recurly.com/api/billing-info#update-billing-info-credit-card ) whereby you submit only the information that needs to be updated. In that way, all other information remains unchanged on the account. 2) Providing the end user a unique url link to their billing info page, where they can update their own billing info securly. This link can be found in the configuration window of the subscriber's account. https://SUBDOMAIN.recurly.com/accounts/:account_code/edit. You will see a hosted billing information URL that takes the user to their billing site hosted by Recurly.

When Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.

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.

Please note

This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.

Please note

Recurly strongly recommends using a token generated by Recurly.js rather than directly handling your customer's credit card details. You can, however, use this API call to update the billing address associated with an account.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = new Recurly_BillingInfo();
  $billing_info->account_code = 'b6f5783';
  $billing_info->first_name = 'Verena';
  $billing_info->last_name = 'Example';
  $billing_info->number = '4111-1111-1111-1111';
  $billing_info->verification_value = '123';
  $billing_info->month = 11;
  $billing_info->year = 2017;
  $billing_info->update();

  print "Billing Info: $billing_info";
} catch (Recurly_ValidationError $e) {
  // The data or card are invalid
  print "Invalid data or card: $e";
} catch (Recurly_NotFoundError $e) {
  // Could not find account
  print "Not Found: $e";
}
account = Recurly::Account.find('1')
account.billing_info = {
  :first_name         => 'Verena',
  :last_name          => 'Example',
  :number             => '4111-1111-1111-1111',
  :verification_value => '123',
  :month              => 11,
  :year               => 2015
}
account.billing_info.save!
account = Account.get('1')
billing_info = account.billing_info
billing_info.first_name = 'Verena'
billing_info.last_name = 'Example'
billing_info.number = '4111-1111-1111-1111'
billing_info.verification_value = '123'
billing_info.month = 11
billing_info.year = 2015
account.update_billing_info(billing_info)
var account = Accounts.Get("1");
var info = new BillingInfo(account);
info.FirstName = "Verana";
info.LastName = "Example";
info.CreditCardNumber = "4111-111-1111-1111";
info.VerificationValue = "123";
info.ExpirationMonth = 11;
info.ExpirationYear = 2015;
info.Update();
<billing_info>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <number>4111-1111-1111-1111</number>
  <verification_value>123</verification_value>
  <month>11</month>
  <year>2019</year>
  <ip_address>127.0.0.1</ip_address>
</billing_info>

Result Format

<billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info" type="credit_card">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"/>
  <address1>123 Main St.</address1>
  <address2 nil="nil"/>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"/>
  <vat_number nil="nil"/>
  <ip_address>127.0.0.1</ip_address>
  <ip_address_country nil="nil"/>
  <card_type>Visa</card_type>
  <year type="integer">2019</year>
  <month type="integer">11</month>
  <first_six>411111</first_six>
  <last_four>1111</last_four>
</billing_info>


{"_id":"57803084827bd50e006b049b","api":{"url":"/accounts/:account_code/billing_info","auth":"required","examples":{"codes":[{"language":"php","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->update();\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}","name":""},{"language":"ruby","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":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.name_on_account = 'Acme, Inc.'\nbilling_info.routing_number = '065400137'\nbilling_info.account_number = '4444000000005555'\nbilling_info.account_type = 'checking'\nbilling_info.address1 = '123 Main St.'\nbilling_info.city = 'San Francisco'\nbilling_info.state ='CA'\nbilling_info.country = 'US'\nbilling_info.zip = '94105'\naccount.update_billing_info(billing_info)"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = account.BillingInfo;\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.Update();"},{"language":"xml","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>"}]},"method":"put","params":[{"required":true,"type":"string","_id":"55944ff05c9eaa2300a86341","default":"","desc":"Account's unique code.","in":"path","name":"account_code","ref":""},{"default":"","type":"string","name":"name_on_account","in":"body","_id":"5581dafd8625220d00429ea7","ref":"","required":true,"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 . ' & , -"},{"in":"body","_id":"5581dafd8625220d00429e9d","ref":"","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"},{"name":"account_number","in":"body","_id":"5581dafd8625220d00429e9c","ref":"","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"},{"desc":"Either 'checking' or 'savings'","default":"","type":"int","name":"account_type","in":"body","_id":"5581dafd8625220d00429e9b","ref":"","required":true},{"ref":"","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","in":"body","_id":"5581dafd8625220d00429ea6"},{"required":false,"desc":"Address line 2, this field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address2","in":"body","_id":"5581dafd8625220d00429ea5","ref":""},{"desc":"City, this field has a 50 character max and can include: letters digits space . , -","default":"","type":"string","name":"city","in":"body","_id":"5581dafd8625220d00429ea4","ref":"","required":false},{"ref":"","required":false,"desc":"State, this field has a 2 character max and can be lowercase or uppercase.","default":"","type":"string","name":"state","in":"body","_id":"5581dafd8625220d00429ea3"},{"type":"string","name":"country","in":"body","_id":"5581dafd8625220d00429ea2","ref":"","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements). **STRONGLY RECOMMENDED**","default":""},{"type":"string","name":"zip","in":"body","_id":"5581dafd8625220d00429ea1","ref":"","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","in":"body","_id":"5581dafd8625220d00429ea0","ref":"","required":false,"desc":"Phone number, this field can be 10 digits.","default":""},{"type":"string","name":"vat_number","in":"body","_id":"5581dafd8625220d00429e9f","ref":"","required":false,"desc":"Customer's VAT Number","default":""},{"type":"string","name":"ip_address","in":"body","_id":"5581dafd8625220d00429e9e","ref":"","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**","default":""}],"results":{"codes":[{"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</billing_info>","language":"xml","status":200}]},"settings":"","apiSetting":"59497f16b9248d0024fe3f31"},"createdAt":"2015-06-17T20:39:25.270Z","project":"555fbba928249c1900618a82","slug":"update-an-accounts-billing-info-bank-account","title":"Update an Account's Billing Info (Bank Account)","category":"57803084827bd50e006b045e","link_external":false,"sync_unique":"","version":"57803084827bd50e006b0457","editedParams":true,"excerpt":"Returns the account's updated Billing Information. You will need to have the ACH feature on your site for this call to work.","isReference":true,"link_url":"","parentDoc":null,"type":"put","updates":["55d336d80168850d0073f056","55d33926f77e6d0d00b1afb5"],"user":"55648cf93b87582b003ab8b1","__v":1,"body":"Instead of using a token generated by Recurly.js, you can instead submit full bank account and address information when updating Billing Information.\n\nWhen Billing Information is updated, 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\nIf you need to set a back dated subscription authorization 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  \"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. You can, however, use this API call to update the billing address associated with an account.\",\n  \"title\": \"Please note\"\n}\n[/block]","editedParams2":true,"githubsync":"","hidden":false,"order":7,"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

putUpdate an Account's Billing Info (Bank Account)

Returns the account's updated Billing Information. 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
integer
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.
country:
string
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements). **STRONGLY RECOMMENDED**
zip:
string
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).
phone:
string
Phone number, this field can be 10 digits.
vat_number:
string
Customer's VAT Number
ip_address:
string
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**

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

When Billing Information is updated, 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.

If you need to set a back dated subscription authorization date for the NACHA three year re-authorization rule, do so on the Create Subscription call using the "bank_account_authorized_at" attribute.

Please note

Recurly strongly recommends using a token generated by Recurly.js rather than directly handling your customer's bank account details. You can, however, use this API call to update the billing address associated with an account.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = new Recurly_BillingInfo();
  $billing_info->account_code = 'b6f5783';
  $billing_info->name_on_account = 'Acme Inc.';
  $billing_info->routing_number = '065400137';
  $billing_info->account_number = '4444000000005555';
  $billing_info->account_type = 'checking';
  $billing_info->address1 = '123 Main St.';
  $billing_info->city = 'San Francisco';
  $billing_info->state ='CA';
  $billing_info->country = 'US';
  $billing_info->zip = '94105';
  $billing_info->update();

  print "Billing Info: $billing_info";
} catch (Recurly_ValidationError $e) {
  // The data or bank account are invalid
  print "Invalid data or card: $e";
} catch (Recurly_NotFoundError $e) {
  // Could not find account
  print "Account Not Found: $e";
}
account = Recurly::Account.find('1')
account.billing_info = {
  name_on_account: 'Acme, Inc.',
  routing_number: '065400137',
  account_number: '4444000000005555',
  address1: '123 Main St.',
  city: 'San Francisco',
  state: 'CA',
  country: 'US',
  zip: '94105'
}
account.billing_info.save!
account = Account.get('1')
billing_info = account.billing_info
billing_info.name_on_account = 'Acme, Inc.'
billing_info.routing_number = '065400137'
billing_info.account_number = '4444000000005555'
billing_info.account_type = 'checking'
billing_info.address1 = '123 Main St.'
billing_info.city = 'San Francisco'
billing_info.state ='CA'
billing_info.country = 'US'
billing_info.zip = '94105'
account.update_billing_info(billing_info)
var account = Accounts.Get("1");
var info = account.BillingInfo;
info.NameOnAccount = "Acme, Inc.";
info.RoutingNumber = "065400137";
info.AccountNumber = "4444000000005555";
info.AccountType = BillingInfo.BankAccountType.Checking;
info.Address1 = "123 Main St.";
info.City = "San Francisco";
info.State = "CA";
info.Country = "US";
info.PostalCode = "94105";
info.Update();
<billing_info>
  <name_on_account>Acme, Inc.</name_on_account>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <routing_number>065400137</routing_number>
  <account_number>4444000000005555</account_number>
  <account_type>checking</account_type>
  <ip_address>127.0.0.1</ip_address>
</billing_info>

Result Format

<billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info" type="bank_account">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <name_on_account>Acme, Inc.</name_on_account>
  <first_name nil="nil"></first_name>
  <last_name nil="nil"></last_name>
  <company nil="nil"></company>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone></phone>
  <vat_number></vat_number>
  <ip_address>127.0.0.1</ip_address>
  <ip_address_country>US</ip_address_country>
  <account_type>checking</account_type>
  <last_four>5555</last_four>
  <routing_number>065400137</routing_number>
</billing_info>


{"_id":"57803084827bd50e006b049c","editedParams2":true,"parentDoc":null,"title":"Update an Account's Billing Info (using external token)","category":"57803084827bd50e006b045e","editedParams":true,"githubsync":"","hidden":false,"order":8,"project":"555fbba928249c1900618a82","slug":"update-an-accounts-billing-info-using-external-token","__v":1,"version":"57803084827bd50e006b0457","type":"put","createdAt":"2016-04-29T21:59:52.047Z","excerpt":"Updates the account's Billing Information using external token for example: Paypal billing agreement","link_external":false,"link_url":"","api":{"method":"put","params":[{"name":"account_code","ref":"","required":true,"type":"string","_id":"55944fab5c9eaa2300a8633c","default":"","desc":"Account's unique code.","in":"path"},{"in":"body","_id":"5581d09a8625220d00429e4d","ref":"","required":true,"desc":"First name","default":"","type":"string","name":"first_name"},{"name":"last_name","in":"body","_id":"5581d09a8625220d00429e4c","ref":"","required":true,"desc":"Last name","default":"","type":"string"},{"default":"","type":"string","name":"address1","in":"body","_id":"5581d09a8625220d00429e4b","ref":"","required":false,"desc":"Address line 1, recommended for address validation"},{"_id":"5581d09a8625220d00429e4a","ref":"","required":false,"desc":"Address line 2.","default":"","type":"string","name":"address2","in":"body"},{"in":"body","_id":"5581d09a8625220d00429e49","ref":"","required":false,"desc":"City","default":"","type":"string","name":"city"},{"name":"state","in":"body","_id":"5581d09a8625220d00429e48","ref":"","required":false,"desc":"State","default":"","type":"string"},{"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country","in":"body","_id":"5581d09a8625220d00429e47","ref":"","required":false},{"ref":"","required":false,"desc":"Zip or postal code, recommended for address validation","default":"","type":"string","name":"zip","in":"body","_id":"5581d09a8625220d00429e46"},{"required":false,"desc":"Phone number","default":"","type":"string","name":"phone","in":"body","_id":"5581d09a8625220d00429e45","ref":""},{"desc":"Paypal's billing agreement","default":"","type":"string","name":"paypal_billing_agreement_id","in":"body","_id":"5723d8f2110e570e00486c2f","ref":"","required":false},{"name":"vat_number","in":"body","_id":"5581d09a8625220d00429e44","ref":"","required":false,"desc":"Customer's VAT Number","default":"","type":"string"},{"desc":"Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.","default":"","type":"string","name":"currency","in":"body","_id":"56c3c1ce70187b17005f4395","ref":"","required":false},{"ref":"","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address","in":"body","_id":"5581d09a8625220d00429e43"}],"results":{"codes":[{"code":"<billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</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 nil=\"nil\"></phone>\n  <paypal_billing_agreement_id>BA-0HS87238YB688345C</paypal_billing_agreement_id>\n</billing_info>","name":"","status":201,"language":"xml"}]},"settings":"","url":"/accounts/:account_code/billing_info","auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->first_name = 'Verena';\n  $billing_info->last_name = 'Example';\n  $billing_info->paypal_billing_agreement_id = 'BA-0HS87238YB688345C';\n  $billing_info->create();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_ValidationError $e) {\n  // The paypal billing agreement provided is invalid\n  print \"Invalid paypal billing agreement: $e\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account\n  print \"Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  :first_name         => 'Verena',\n  :last_name          => 'Example',\n  :paypal_billing_agreement_id             => 'BA-0HS87238YB688345C'\n}\naccount.billing_info.save!"},{"code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.first_name = 'Verena'\nbilling_info.last_name = 'Example'\nbilling_info.paypal_billing_agreement_id = 'BA-0HS87238YB688345C'\naccount.update_billing_info(billing_info)","language":"python"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.FirstName = \"Verana\";\ninfo.LastName = \"Example\";\ninfo.PaypalBillingAgreementId = \"BA-0HS87238YB688345C\";\ninfo.Create();"},{"language":"xml","code":"<billing_info>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\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  <paypal_billing_agreement_id>BA-0HS87238YB688345C</paypal_billing_agreement_id>\n  <ip_address>127.0.0.1</ip_address>\n</billing_info>"}]},"apiSetting":"59497f16b9248d0024fe3f31"},"isReference":true,"sync_unique":"","updates":[],"user":"56c3c01334df460d00c2beb3","body":"Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when creating Billing Information.\n\nWhen Billing Information is submitted, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.\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.\n[block:callout]\n{\n  \"type\": \"warning\",\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 credit card details.\",\n  \"title\": \"Please note\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.\",\n  \"title\": \"Please note\"\n}\n[/block]","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

putUpdate an Account's Billing Info (using external token)

Updates the account's Billing Information using external token for example: Paypal billing agreement

Path Params

account_code:
required
string
Account's unique code.

Body Params

first_name:
required
string
First name
last_name:
required
string
Last name
address1:
string
Address line 1, recommended for address validation
address2:
string
Address line 2.
city:
string
City
state:
string
State
country:
string
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**
zip:
string
Zip or postal code, recommended for address validation
phone:
string
Phone number
paypal_billing_agreement_id:
string
Paypal's billing agreement
vat_number:
string
Customer's VAT Number
currency:
string
Currency in which invoices will be posted. Only applicable if this account is enrolled in a plan has a different currency than your site's default.
ip_address:
string
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**

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

When Billing Information is submitted, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.

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.

Please note

Recurly strongly recommends using a token generated by Recurly.js rather than directly handling your customer's credit card details.

Please note

This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = new Recurly_BillingInfo();
  $billing_info->account_code = 'b6f5783';
  $billing_info->first_name = 'Verena';
  $billing_info->last_name = 'Example';
  $billing_info->paypal_billing_agreement_id = 'BA-0HS87238YB688345C';
  $billing_info->create();

  print "Billing Info: $billing_info";
} catch (Recurly_ValidationError $e) {
  // The paypal billing agreement provided is invalid
  print "Invalid paypal billing agreement: $e";
} catch (Recurly_NotFoundError $e) {
  // Could not find account
  print "Not Found: $e";
}
account = Recurly::Account.find('1')
account.billing_info = {
  :first_name         => 'Verena',
  :last_name          => 'Example',
  :paypal_billing_agreement_id             => 'BA-0HS87238YB688345C'
}
account.billing_info.save!
account = Account.get('1')
billing_info = account.billing_info
billing_info.first_name = 'Verena'
billing_info.last_name = 'Example'
billing_info.paypal_billing_agreement_id = 'BA-0HS87238YB688345C'
account.update_billing_info(billing_info)
var account = Accounts.Get("1");
var info = new BillingInfo(account);
info.FirstName = "Verana";
info.LastName = "Example";
info.PaypalBillingAgreementId = "BA-0HS87238YB688345C";
info.Create();
<billing_info>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <paypal_billing_agreement_id>BA-0HS87238YB688345C</paypal_billing_agreement_id>
  <ip_address>127.0.0.1</ip_address>
</billing_info>

Result Format

<billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info" type="credit_card">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"></company>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"></phone>
  <paypal_billing_agreement_id>BA-0HS87238YB688345C</paypal_billing_agreement_id>
</billing_info>


{"_id":"57803084827bd50e006b049d","isReference":true,"title":"Clear an Account's Billing Info","createdAt":"2015-06-17T20:40:02.831Z","project":"555fbba928249c1900618a82","slug":"clear-an-accounts-billing-info","updates":[],"excerpt":"You may remove any stored billing information for an account. If the account has a subscription, the renewal will go into past due unless you update the billing info before the renewal occurs.","editedParams2":true,"hidden":false,"link_url":"","sync_unique":"","type":"delete","api":{"examples":{"codes":[{"language":"php","code":"<?php\n\ntry {\n  $billing_info = Recurly_BillingInfo::get('b6f5783');\n  $billing_info->delete();\n\n  // Or, in a single API request:\n  // Recurly_BillingInfo::deleteForAccount('b6f5783');\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_NotFoundError $e) {\n  // Account not found or account does not have billing info\n  print \"Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\nif billing_info = account.billing_info\n  billing_info.destroy\nend"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nif billing_info\n  billing_info.delete()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\naccount.DeleteBillingInfo();"}]},"method":"delete","params":[{"type":"string","_id":"55944ffb0c33bd0d0005964c","default":"","desc":"Account's unique code.","in":"path","name":"account_code","ref":"","required":true}],"results":{"codes":[{"code":"Status: 204 No Content","name":"","status":204,"language":"json"}]},"settings":"","url":"/accounts/:account_code/billing_info","auth":"required","apiSetting":"59497f16b9248d0024fe3f31"},"body":"","category":"57803084827bd50e006b045e","editedParams":true,"githubsync":"","link_external":false,"order":9,"__v":1,"user":"55648cf93b87582b003ab8b1","version":"57803084827bd50e006b0457","parentDoc":null,"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

deleteClear an Account's Billing Info

You may remove any stored billing information for an account. If the account has a subscription, the renewal will go into past due unless you update the billing info before the renewal occurs.

Path Params

account_code:
required
string
Account's unique code.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $billing_info = Recurly_BillingInfo::get('b6f5783');
  $billing_info->delete();

  // Or, in a single API request:
  // Recurly_BillingInfo::deleteForAccount('b6f5783');

  print "Billing Info: $billing_info";
} catch (Recurly_NotFoundError $e) {
  // Account not found or account does not have billing info
  print "Not Found: $e";
}
account = Recurly::Account.find('1')
if billing_info = account.billing_info
  billing_info.destroy
end
account = Account.get('1')
billing_info = account.billing_info
if billing_info
  billing_info.delete()
var account = Accounts.Get("1");
account.DeleteBillingInfo();

Result Format

Status: 204 No Content


{"_id":"57803085827bd50e006b04b8","title":"List Active Coupons","editedParams2":true,"excerpt":"Returns a list of all the coupons.","api":{"method":"get","params":[{"name":"state","ref":"","required":false,"type":"string","_id":"5581f3c38625220d00429ee7","default":"all","desc":"The state of coupons to return: `redeemable`, `expired`, `maxed_out`, or `inactive`.","in":"query"},{"in":"query","_id":"5581f3c38625220d00429ee6","ref":"","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"},{"ref":"","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page","in":"query","_id":"5581f3c38625220d00429ee5"}],"results":{"codes":[{"name":"","status":200,"language":"xml","code":"<coupons type=\"array\">\n  <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n    <coupon_code>special</coupon_code>\n    <name>Special 10% off</name>\n    <state>redeemable</state>\n    <description nil=\"nil\"/>\n    <discount_type>percent</discount_type>\n    <discount_percent type=\"integer\">10</discount_percent>\n    <invoice_description nil=\"nil\"/>\n    <redeem_by_date type=\"datetime\">2017-12-31T00:00:00Z</redeem_by_date>\n    <single_use type=\"boolean\">true</single_use>\n    <applies_for_months nil=\"nil\"/>\n    <max_redemptions type=\"integer\">200</max_redemptions>\n    <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n    <created_at type=\"datetime\">2016-07-11T18:50:17Z</created_at>\n    <updated_at type=\"datetime\">2016-07-11T18:50:17Z</updated_at>\n    <deleted_at nil=\"nil\"/>\n    <duration>single_use</duration>\n    <temporal_unit nil=\"nil\"/>\n    <temporal_amount nil=\"nil\"/>\n    <applies_to_non_plan_charges type=\"boolean\">false</applies_to_non_plan_charges>\n    <redemption_resource>account</redemption_resource>\n    <max_redemptions_per_account nil=\"nil\"/>\n    <coupon_type>single_code</coupon_type>\n    <plan_codes type=\"array\">\n      <plan_code>gold</plan_code>\n      <plan_code>platinum</plan_code>\n    </plan_codes>\n    <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n  </coupon>\n  <!-- Continued... -->\n</coupons>"}]},"settings":"","url":"/coupons","auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\n$coupons = Recurly_CouponList::get();\nforeach ($coupons as $coupon) {\n  print \"Coupon: $coupon\\n\";\n}","name":""},{"language":"ruby","code":"Recurly::Coupon.find_each do |coupon|\n  puts \"Coupon: #{coupon.inspect}\"\nend"},{"language":"python","code":"#client version 2.1.6+\nfor coupon in Coupon.all():\n    print 'Coupon: %s' % coupon\n\n#client version <= 2.1.5\ncoupons = Coupon.all()\nwhile coupons:\n    for coupon in coupons:\n        print 'Coupon: %s' % coupon\n    try:\n        coupons = coupons.next_page()\n    except PageError:\n        coupons = ()\n"},{"language":"csharp","code":"using System.Linq;\n\nvar coupons = Coupons.List();\nwhile (coupons.Any())\n{\n\tforeach (var coupon in coupons)\n\t\tConsole.WriteLine(\"Coupon: \" + coupon);\n\tcoupons = coupons.Next;\n}"}]},"apiSetting":"59497f16b9248d0024fe3f31"},"body":"","githubsync":"","hidden":false,"order":1,"type":"get","__v":1,"editedParams":true,"isReference":true,"link_external":false,"parentDoc":null,"slug":"list-active-coupons","sync_unique":"","category":"57803084827bd50e006b045f","createdAt":"2015-06-17T22:25:07.292Z","user":"55648cf93b87582b003ab8b1","updates":[],"version":"57803084827bd50e006b0457","link_url":"","project":"555fbba928249c1900618a82","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getList Active Coupons

Returns a list of all the coupons.

Query Params

state:
stringall
The state of coupons to return: `redeemable`, `expired`, `maxed_out`, or `inactive`.
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.
per_page:
integer50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

$coupons = Recurly_CouponList::get();
foreach ($coupons as $coupon) {
  print "Coupon: $coupon\n";
}
Recurly::Coupon.find_each do |coupon|
  puts "Coupon: #{coupon.inspect}"
end
#client version 2.1.6+
for coupon in Coupon.all():
    print 'Coupon: %s' % coupon

#client version <= 2.1.5
coupons = Coupon.all()
while coupons:
    for coupon in coupons:
        print 'Coupon: %s' % coupon
    try:
        coupons = coupons.next_page()
    except PageError:
        coupons = ()
using System.Linq;

var coupons = Coupons.List();
while (coupons.Any())
{
	foreach (var coupon in coupons)
		Console.WriteLine("Coupon: " + coupon);
	coupons = coupons.Next;
}

Result Format

<coupons type="array">
  <coupon href="https://your-subdomain.recurly.com/v2/coupons/special">
    <redemptions href="https://your-subdomain.recurly.com/v2/coupons/special/redemptions"/>
    <coupon_code>special</coupon_code>
    <name>Special 10% off</name>
    <state>redeemable</state>
    <description nil="nil"/>
    <discount_type>percent</discount_type>
    <discount_percent type="integer">10</discount_percent>
    <invoice_description nil="nil"/>
    <redeem_by_date type="datetime">2017-12-31T00:00:00Z</redeem_by_date>
    <single_use type="boolean">true</single_use>
    <applies_for_months nil="nil"/>
    <max_redemptions type="integer">200</max_redemptions>
    <applies_to_all_plans type="boolean">false</applies_to_all_plans>
    <created_at type="datetime">2016-07-11T18:50:17Z</created_at>
    <updated_at type="datetime">2016-07-11T18:50:17Z</updated_at>
    <deleted_at nil="nil"/>
    <duration>single_use</duration>
    <temporal_unit nil="nil"/>
    <temporal_amount nil="nil"/>
    <applies_to_non_plan_charges type="boolean">false</applies_to_non_plan_charges>
    <redemption_resource>account</redemption_resource>
    <max_redemptions_per_account nil="nil"/>
    <coupon_type>single_code</coupon_type>
    <plan_codes type="array">
      <plan_code>gold</plan_code>
      <plan_code>platinum</plan_code>
    </plan_codes>
    <a name="redeem" href="https://your-subdomain.recurly.com/v2/coupons/special/redeem" method="post"/>
  </coupon>
  <!-- Continued... -->
</coupons>


{"_id":"57803085827bd50e006b04ba","body":"**DISCOUNT IN DOLLARS**\nWhen specifying a discount amount as a flat amount, the currency must be specified with the amount in an array. For example:\n```\n<discount_type>dollars</discount_type>\n<discount_in_cents>\n  <USD>500</USD>\n  <EUR>400</EUR>\n  <GBP>300</GBP>\n</discount_in_cents>\n```\n**DISCOUNT IN PERCENTAGE**\nPercentage discounts only need to specify the discount percentage. For example:\n```\n<discount_type>percent</discount_type>\n<discount_percent>10</discount_percent>\n```\n**LIMITING TO SPECIFIC PLANS**\nIf a coupon applies to all plans, it will also apply to any plans created in the future. To limit a coupon to specific plans, you may specify an array of plan codes. For example:\n```\n<applies_to_all_plans>false</applies_to_all_plans>\n<plan_codes>\n  <plan_code>silver</plan_code>\n  <plan_code>gold</plan_code>\n</plan_codes>\n```\n**CREATING UNIQUE CODE TEMPLATES**\nIf you are creating a bulk coupon, you will need to create a unique_code_template. Here are the rules:\n1. You must start the template with your coupon_code wrapped in single quotes.\n2. Outside of single quotes, use a 9 for a character that you want to be a random number.\n3. Outside of single quotes, use an \"x\" for a character that you want to be a random letter.\n4. Outside of single quotes, use an * for a character that you want to be a random number or letter.\n5. Use single quotes ' ' for characters that you want to remain static. These strings can be alphanumeric and may contain a - _ or +.\n\n```\n<coupon_code>thankyou</coupon_code>\n<coupon_type>bulk</coupon_type>\n<unique_code_template>'thankyou'99999999</unique_code_template>\n```\nThis example will create a unique code like: thankyou41863675","parentDoc":null,"slug":"create-coupon","type":"post","category":"57803084827bd50e006b045f","editedParams":true,"sync_unique":"","user":"5581f6648625220d00429ef6","api":{"auth":"required","examples":{"codes":[{"name":"","code":"<?php\n\ntry {\n  $coupon = new Recurly_Coupon();\n  $coupon->coupon_code = 'gorby1';\n  $coupon->redeem_by_date = '2016-07-04';\n  $coupon->duration = 'single_use';\n  $coupon->redemption_resource = 'subscription';\n  $coupon->max_redemptions_per_account = 1;\n  $coupon->applies_to_non_plan_charges = true;\n\n  // $2 off...\n  $coupon->name = 'Special $2 off coupon';\n  $coupon->discount_type = 'dollars';\n  $coupon->discount_in_cents->addCurrency('USD',200); // $2.00 discount\n\n  // ...or 10% off.\n  $coupon->name = 'Special 10% off';\n  $coupon->discount_type = 'percent';\n  $coupon->discount_percent = 10;\n\n  // Limit to gold and platinum plans only.\n  $coupon->applies_to_all_plans = false;\n  $coupon->plan_codes = array('gold', 'platinum');\n\n  $coupon->create();\n\n  print \"Coupon: $coupon\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid data: $e\";\n}","language":"php"},{"code":"coupon = Recurly::Coupon.new(\n  :coupon_code    => 'special',\n  :redeem_by_date => Date.new(2014, 1, 1),\n  :duration     => 'single_use'\n)\n\n# $2 off...\ncoupon.name = 'Special $2 off coupon'\ncoupon.discount_type = 'dollars'\ncoupon.discount_in_cents = 2_00\n\n# ...or 10% off.\ncoupon.name = 'Special 10% off'\ncoupon.discount_type = 'percent'\ncoupon.discount_percent = 10\n\n# Limit to gold and platinum plans only.\ncoupon.applies_to_all_plans = false\ncoupon.plan_codes = %w(gold platinum)\n\n# Limit redemption to specific subscription on account.\ncoupon.redemption_resource = 'subscription'\n\n# Limit redemptions per account to a specific number.\ncoupon.max_redemptions_per_account = 1\n\n# Discount should include one-time charges.\ncoupon.applies_to_non_plan_charges = true\n\ncoupon.save","language":"ruby"},{"language":"python","code":"coupon = Coupon(\n  coupon_code='special',\n  redeem_by_date=datetime.date(2014, 1, 1),\n  duration='single_use'\n)\n\n# $2 off...\ncoupon.name = 'Special $2 off coupon'\ncoupon.discount_type = 'dollars'\ncoupon.discount_in_cents = Money(200)\n\n# ...or 10% off.\ncoupon.name = 'Special 10% off'\ncoupon.discount_type = 'percent'\ncoupon.discount_percent = 10\n\n# Limit to gold and platinum plans only.\ncoupon.applies_to_all_plans = False\ncoupon.plan_codes = ['gold', 'platinum']\n\n# Limit redemption to specific subscription on account.\ncoupon.redemption_resource = 'subscription'\n\n# Limit redemptions per account to a specific number.\ncoupon.max_redemptions_per_account = 1\n\n# Discount should include one-time charges.\ncoupon.applies_to_non_plan_charges = True\n\ncoupon.save()"},{"code":"// new Coupon(<code>, <name>, <discount>)\n\n// $2 off...\nvar coupon = new Coupon(\"special\",\n        \"Special $2 off coupon\", new Dictionary<string, int>() { { \"USD\", 200 } });\n\n// ... or 10% off...\nvar coupon = new Coupon(\"special\",\n        \"Special 10% off coupon\", 10);\n\ncoupon.RedeemByDate = new DateTime(2017, 1, 1);\ncoupon.SingleUse = true;\n\n// Limit to gold and platinum plans only.\ncoupon.AppliesToAllPlans = false;\ncoupon.Plans.Add(\"gold\");\ncoupon.Plans.Add(\"silver\");\n\n// Other properties\ncoupon.RedeemByDate = new DateTime(2014, 1, 1);\ncoupon.SingleUse = true;\ncoupon.RedemptionResource = Coupon.RedemptionResourceType.Subscription;\ncoupon.MaxRedemptionsPerAccount = 1;\ncoupon.AppliesToNonPlanCharges = true;\n\ncoupon.Create();","language":"csharp"},{"code":"<!-- For All Plans -->\n<coupon>\n  <coupon_code>special</coupon_code>\n  <name>Special $2 off coupon</name>\n  <discount_type>dollars</discount_type>\n    <discount_in_cents>\n    <USD>200</USD>\n  </discount_in_cents>\n  <redeem_by_date>2017-12-31</redeem_by_date>\n  <duration>temporal</duration>\n  <temporal_unit>day</temporal_unit>\n  <temporal_amount>28</temporal_amount>\n  <max_redemptions>200</max_redemptions>\n  <max_redemptions_per_account>1</max_redemptions_per_account>\n  <applies_to_all_plans>true</applies_to_all_plans>\n</coupon>\n\n<!-- For specific plan codes -->\n<coupon>\n  <coupon_code>subscription_special</coupon_code>\n  <name>Special 10% off</name>\n  <discount_type>percent</discount_type>\n  <discount_percent>10</discount_percent>\n  <redeem_by_date>2017-12-31</redeem_by_date>\n  <max_redemptions>200</max_redemptions>\n  <applies_to_all_plans>false</applies_to_all_plans>\n  <plan_codes>\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n  <redemption_resource>subscription</redemption_resource>\n</coupon>","language":"xml","name":""}]},"method":"post","params":[{"name":"coupon_code","in":"body","_id":"5581fc9c8625220d00429f13","ref":"","required":true,"desc":"Unique code to identify and redeem the coupon. This code may only contain the following characters: [a-z A-Z 0-9 + - _ ]. Max of 50 characters.","default":"","type":"string"},{"in":"body","name":"name","ref":"","required":true,"type":"string","_id":"5581fc9c8625220d00429f12","default":"","desc":"Coupon name."},{"default":"","desc":"Description of the coupon on the hosted payment pages.","in":"body","name":"description","ref":"","required":false,"type":"string","_id":"5581fc9c8625220d00429f11"},{"ref":"","required":true,"type":"string","_id":"5581fc9c8625220d00429f0a","default":"","desc":"`percent` or `dollars`.","in":"body","name":"discount_type"},{"ref":"","required":false,"type":"int","_id":"5581fc9c8625220d00429f08","default":"","desc":"Mapping of discount amounts by currency if discount_type is `dollars`. Max 10000000.","in":"body","name":"discount_in_cents"},{"ref":"","required":false,"type":"int","_id":"5581fc9c8625220d00429f09","default":"","desc":"Discount percentage if discount_type is `percent`.","in":"body","name":"discount_percent"},{"ref":"","required":false,"type":"string","_id":"5581fc9c8625220d00429f10","default":"","desc":"Description of the coupon on the invoice.","in":"body","name":"invoice_description"},{"desc":"Last date to redeem the coupon, defaults to no date.","in":"body","name":"redeem_by_date","ref":"","required":false,"type":"datetime","_id":"5581fc9c8625220d00429f0f","default":""},{"name":"single_use","ref":"","required":false,"type":"boolean","_id":"5581fc9c8625220d00429f0e","default":"","desc":"DEPRECATED: Please use `duration`. If true, the coupon applies to the first invoice only.","in":"body"},{"type":"int","_id":"5581fc9c8625220d00429f0d","default":"","desc":"DEPRECATED: Please use `temporal_unit` and `temporal_amount`. Number of months after redemption that the coupon is valid, defaults to no date.","in":"body","name":"applies_for_months","ref":"","required":false},{"default":"","desc":"Maximum number of accounts that may use the coupon before it can no longer be redeemed.","in":"body","name":"max_redemptions","ref":"","required":false,"type":"int","_id":"5581fc9c8625220d00429f0c"},{"ref":"","required":false,"type":"boolean","_id":"5581fc9c8625220d00429f0b","default":"true","desc":"The coupon is valid for all plans if true, defaults to true.","in":"body","name":"applies_to_all_plans"},{"ref":"","required":false,"type":"string","_id":"55babe051b0d663700781631","default":"forever","desc":"`forever`, `single_use`, or `temporal`.  If `single_use`, the coupon applies to the first invoice only.  If `temporal` the coupon will apply to invoices for the duration determined by the `temporal_unit` and `temporal_amount` attributes.","in":"body","name":"duration"},{"ref":"","required":false,"type":"string","_id":"55babe051b0d663700781630","default":"","desc":"`day`, `week`, `month`, or `year`.  If duration is `temporal` then `temporal_unit` is multiplied by `temporal_amount` to define the duration that the coupon will be applied to invoices for.","in":"body","name":"temporal_unit"},{"desc":"If duration is `temporal` then `temporal_amount` is an integer which is multiplied by `temporal_unit` to define the duration that the coupon will be applied to invoices for.","in":"body","name":"temporal_amount","ref":"","required":false,"type":"int","_id":"55babe051b0d66370078162f","default":""},{"in":"body","name":"applies_to_non_plan_charges","ref":"","required":false,"type":"boolean","_id":"5612aac709bdc51700697025","default":"false","desc":"The coupon is valid for one-time, non-plan charges if `true`, defaults to `false`."},{"required":false,"type":"string","_id":"5612aac709bdc51700697024","default":"account","desc":"Whether the discount is for all eligible charges on the account, or only a specific subscription. Values are `account` or `subscription`.","in":"body","name":"redemption_resource","ref":""},{"in":"body","name":"max_redemptions_per_account","ref":"","required":false,"type":"int","_id":"5612aac709bdc51700697023","default":"","desc":"The number of times the coupon can be redeemed on a specific account. `null` is the default and means unlimited."},{"required":false,"type":"string","_id":"5612aac709bdc51700697022","default":"single_code","desc":"Whether the coupon is `single_code` or `bulk`. Bulk coupons will require a `unique_code_template` and will generate unique codes through the generate endpoint.","in":"body","name":"coupon_type","ref":""},{"default":"","type":"string","name":"unique_code_template","in":"body","_id":"5612aac709bdc51700697021","ref":"","required":false,"desc":"The template for generating unique codes. See rules below for creating unique code templates."},{"type":"array_string","_id":"5581fc9c8625220d00429f07","default":"","desc":"Array of `plan_codes` the coupon applies to, if `applies_to_all_plans` is false.","in":"body","name":"plan_codes","ref":"","required":false}],"results":{"codes":[{"status":201,"name":"","code":"<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n  <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n  <coupon_code>special</coupon_code>\n  <name>Special 10% off</name>\n  <state>redeemable</state>\n  <description nil=\"nil\"/>\n  <discount_type>percent</discount_type>\n  <discount_percent type=\"integer\">10</discount_percent>\n  <invoice_description nil=\"nil\"/>\n  <redeem_by_date type=\"datetime\">2017-12-31T00:00:00Z</redeem_by_date>\n  <single_use type=\"boolean\">true</single_use>\n  <applies_for_months nil=\"nil\"/>\n  <max_redemptions type=\"integer\">200</max_redemptions>\n  <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n  <created_at type=\"datetime\">2016-07-11T18:50:17Z</created_at>\n  <updated_at type=\"datetime\">2016-07-11T18:50:17Z</updated_at>\n  <deleted_at nil=\"nil\"/>\n  <duration>single_use</duration>\n  <temporal_unit nil=\"nil\"/>\n  <temporal_amount nil=\"nil\"/>\n  <applies_to_non_plan_charges type=\"boolean\">false</applies_to_non_plan_charges>\n  <redemption_resource>account</redemption_resource>\n  <max_redemptions_per_account nil=\"nil\"/>\n  <coupon_type>single_code</coupon_type>\n  <plan_codes type=\"array\">\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n  <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n</coupon>","language":"xml"}]},"settings":"","url":"/coupons","apiSetting":"59497f16b9248d0024fe3f31"},"createdAt":"2015-06-17T23:02:52.933Z","editedParams2":true,"excerpt":"Creates a new coupon. Please note: coupons cannot be updated after being created.","githubsync":"","hidden":false,"isReference":true,"link_external":false,"link_url":"","order":2,"title":"Create Coupon","updates":[],"__v":1,"project":"555fbba928249c1900618a82","version":"57803084827bd50e006b0457","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate Coupon

Creates a new coupon. Please note: coupons cannot be updated after being created.

Body Params

coupon_code:
required
string
Unique code to identify and redeem the coupon. This code may only contain the following characters: [a-z A-Z 0-9 + - _ ]. Max of 50 characters.
name:
required
string
Coupon name.
description:
string
Description of the coupon on the hosted payment pages.
discount_type:
required
string
`percent` or `dollars`.
discount_in_cents:
integer
Mapping of discount amounts by currency if discount_type is `dollars`. Max 10000000.
discount_percent:
integer
Discount percentage if discount_type is `percent`.
invoice_description:
string
Description of the coupon on the invoice.
redeem_by_date:
datetime
Last date to redeem the coupon, defaults to no date.
single_use:
boolean
DEPRECATED: Please use `duration`. If true, the coupon applies to the first invoice only.
applies_for_months:
integer
DEPRECATED: Please use `temporal_unit` and `temporal_amount`. Number of months after redemption that the coupon is valid, defaults to no date.
max_redemptions:
integer
Maximum number of accounts that may use the coupon before it can no longer be redeemed.
applies_to_all_plans:
booleantrue
The coupon is valid for all plans if true, defaults to true.
duration:
stringforever
`forever`, `single_use`, or `temporal`. If `single_use`, the coupon applies to the first invoice only. If `temporal` the coupon will apply to invoices for the duration determined by the `temporal_unit` and `temporal_amount` attributes.
temporal_unit:
string
`day`, `week`, `month`, or `year`. If duration is `temporal` then `temporal_unit` is multiplied by `temporal_amount` to define the duration that the coupon will be applied to invoices for.
temporal_amount:
integer
If duration is `temporal` then `temporal_amount` is an integer which is multiplied by `temporal_unit` to define the duration that the coupon will be applied to invoices for.
applies_to_non_plan_charges:
booleanfalse
The coupon is valid for one-time, non-plan charges if `true`, defaults to `false`.
redemption_resource:
stringaccount
Whether the discount is for all eligible charges on the account, or only a specific subscription. Values are `account` or `subscription`.
max_redemptions_per_account:
integer
The number of times the coupon can be redeemed on a specific account. `null` is the default and means unlimited.
coupon_type:
stringsingle_code
Whether the coupon is `single_code` or `bulk`. Bulk coupons will require a `unique_code_template` and will generate unique codes through the generate endpoint.
unique_code_template:
string
The template for generating unique codes. See rules below for creating unique code templates.
plan_codes:
array of strings
Array of `plan_codes` the coupon applies to, if `applies_to_all_plans` is false.

DISCOUNT IN DOLLARS
When specifying a discount amount as a flat amount, the currency must be specified with the amount in an array. For example:

<discount_type>dollars</discount_type>
<discount_in_cents>
  <USD>500</USD>
  <EUR>400</EUR>
  <GBP>300</GBP>
</discount_in_cents>

DISCOUNT IN PERCENTAGE
Percentage discounts only need to specify the discount percentage. For example:

<discount_type>percent</discount_type>
<discount_percent>10</discount_percent>

LIMITING TO SPECIFIC PLANS
If a coupon applies to all plans, it will also apply to any plans created in the future. To limit a coupon to specific plans, you may specify an array of plan codes. For example:

<applies_to_all_plans>false</applies_to_all_plans>
<plan_codes>
  <plan_code>silver</plan_code>
  <plan_code>gold</plan_code>
</plan_codes>

CREATING UNIQUE CODE TEMPLATES
If you are creating a bulk coupon, you will need to create a unique_code_template. Here are the rules:

  1. You must start the template with your coupon_code wrapped in single quotes.
  2. Outside of single quotes, use a 9 for a character that you want to be a random number.
  3. Outside of single quotes, use an "x" for a character that you want to be a random letter.
  4. Outside of single quotes, use an * for a character that you want to be a random number or letter.
  5. Use single quotes ' ' for characters that you want to remain static. These strings can be alphanumeric and may contain a - _ or +.
<coupon_code>thankyou</coupon_code>
<coupon_type>bulk</coupon_type>
<unique_code_template>'thankyou'99999999</unique_code_template>

This example will create a unique code like: thankyou41863675

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $coupon = new Recurly_Coupon();
  $coupon->coupon_code = 'gorby1';
  $coupon->redeem_by_date = '2016-07-04';
  $coupon->duration = 'single_use';
  $coupon->redemption_resource = 'subscription';
  $coupon->max_redemptions_per_account = 1;
  $coupon->applies_to_non_plan_charges = true;

  // $2 off...
  $coupon->name = 'Special $2 off coupon';
  $coupon->discount_type = 'dollars';
  $coupon->discount_in_cents->addCurrency('USD',200); // $2.00 discount

  // ...or 10% off.
  $coupon->name = 'Special 10% off';
  $coupon->discount_type = 'percent';
  $coupon->discount_percent = 10;

  // Limit to gold and platinum plans only.
  $coupon->applies_to_all_plans = false;
  $coupon->plan_codes = array('gold', 'platinum');

  $coupon->create();

  print "Coupon: $coupon";
} catch (Recurly_ValidationError $e) {
  print "Invalid data: $e";
}
coupon = Recurly::Coupon.new(
  :coupon_code    => 'special',
  :redeem_by_date => Date.new(2014, 1, 1),
  :duration     => 'single_use'
)

# $2 off...
coupon.name = 'Special $2 off coupon'
coupon.discount_type = 'dollars'
coupon.discount_in_cents = 2_00

# ...or 10% off.
coupon.name = 'Special 10% off'
coupon.discount_type = 'percent'
coupon.discount_percent = 10

# Limit to gold and platinum plans only.
coupon.applies_to_all_plans = false
coupon.plan_codes = %w(gold platinum)

# Limit redemption to specific subscription on account.
coupon.redemption_resource = 'subscription'

# Limit redemptions per account to a specific number.
coupon.max_redemptions_per_account = 1

# Discount should include one-time charges.
coupon.applies_to_non_plan_charges = true

coupon.save
coupon = Coupon(
  coupon_code='special',
  redeem_by_date=datetime.date(2014, 1, 1),
  duration='single_use'
)

# $2 off...
coupon.name = 'Special $2 off coupon'
coupon.discount_type = 'dollars'
coupon.discount_in_cents = Money(200)

# ...or 10% off.
coupon.name = 'Special 10% off'
coupon.discount_type = 'percent'
coupon.discount_percent = 10

# Limit to gold and platinum plans only.
coupon.applies_to_all_plans = False
coupon.plan_codes = ['gold', 'platinum']

# Limit redemption to specific subscription on account.
coupon.redemption_resource = 'subscription'

# Limit redemptions per account to a specific number.
coupon.max_redemptions_per_account = 1

# Discount should include one-time charges.
coupon.applies_to_non_plan_charges = True

coupon.save()
// new Coupon(<code>, <name>, <discount>)

// $2 off...
var coupon = new Coupon("special",
        "Special $2 off coupon", new Dictionary<string, int>() { { "USD", 200 } });

// ... or 10% off...
var coupon = new Coupon("special",
        "Special 10% off coupon", 10);

coupon.RedeemByDate = new DateTime(2017, 1, 1);
coupon.SingleUse = true;

// Limit to gold and platinum plans only.
coupon.AppliesToAllPlans = false;
coupon.Plans.Add("gold");
coupon.Plans.Add("silver");

// Other properties
coupon.RedeemByDate = new DateTime(2014, 1, 1);
coupon.SingleUse = true;
coupon.RedemptionResource = Coupon.RedemptionResourceType.Subscription;
coupon.MaxRedemptionsPerAccount = 1;
coupon.AppliesToNonPlanCharges = true;

coupon.Create();
<!-- For All Plans -->
<coupon>
  <coupon_code>special</coupon_code>
  <name>Special $2 off coupon</name>
  <discount_type>dollars</discount_type>
    <discount_in_cents>
    <USD>200</USD>
  </discount_in_cents>
  <redeem_by_date>2017-12-31</redeem_by_date>
  <duration>temporal</duration>
  <temporal_unit>day</temporal_unit>
  <temporal_amount>28</temporal_amount>
  <max_redemptions>200</max_redemptions>
  <max_redemptions_per_account>1</max_redemptions_per_account>
  <applies_to_all_plans>true</applies_to_all_plans>
</coupon>

<!-- For specific plan codes -->
<coupon>
  <coupon_code>subscription_special</coupon_code>
  <name>Special 10% off</name>
  <discount_type>percent</discount_type>
  <discount_percent>10</discount_percent>
  <redeem_by_date>2017-12-31</redeem_by_date>
  <max_redemptions>200</max_redemptions>
  <applies_to_all_plans>false</applies_to_all_plans>
  <plan_codes>
    <plan_code>gold</plan_code>
    <plan_code>platinum</plan_code>
  </plan_codes>
  <redemption_resource>subscription</redemption_resource>
</coupon>

Result Format

<coupon href="https://your-subdomain.recurly.com/v2/coupons/special">
  <redemptions href="https://your-subdomain.recurly.com/v2/coupons/special/redemptions"/>
  <coupon_code>special</coupon_code>
  <name>Special 10% off</name>
  <state>redeemable</state>
  <description nil="nil"/>
  <discount_type>percent</discount_type>
  <discount_percent type="integer">10</discount_percent>
  <invoice_description nil="nil"/>
  <redeem_by_date type="datetime">2017-12-31T00:00:00Z</redeem_by_date>
  <single_use type="boolean">true</single_use>
  <applies_for_months nil="nil"/>
  <max_redemptions type="integer">200</max_redemptions>
  <applies_to_all_plans type="boolean">false</applies_to_all_plans>
  <created_at type="datetime">2016-07-11T18:50:17Z</created_at>
  <updated_at type="datetime">2016-07-11T18:50:17Z</updated_at>
  <deleted_at nil="nil"/>
  <duration>single_use</duration>
  <temporal_unit nil="nil"/>
  <temporal_amount nil="nil"/>
  <applies_to_non_plan_charges type="boolean">false</applies_to_non_plan_charges>
  <redemption_resource>account</redemption_resource>
  <max_redemptions_per_account nil="nil"/>
  <coupon_type>single_code</coupon_type>
  <plan_codes type="array">
    <plan_code>gold</plan_code>
    <plan_code>platinum</plan_code>
  </plan_codes>
  <a name="redeem" href="https://your-subdomain.recurly.com/v2/coupons/special/redeem" method="post"/>
</coupon>


{"_id":"57803085827bd50e006b04b9","editedParams":true,"title":"Lookup a Coupon","type":"get","updates":["5654b5aa48b4df0d00f67d9d","570fc426277cba22000c87d4"],"version":"57803084827bd50e006b0457","user":"5581f6648625220d00429ef6","excerpt":"Returns information about an active coupon.","githubsync":"","isReference":true,"link_external":false,"project":"555fbba928249c1900618a82","sync_unique":"","order":3,"parentDoc":null,"slug":"lookup-a-coupon","link_url":"","__v":2,"api":{"results":{"codes":[{"name":"Single Code","code":"<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n  <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n  <coupon_code>special</coupon_code>\n  <name>Special 10% off</name>\n  <state>redeemable</state>\n  <description nil=\"nil\"/>\n  <discount_type>percent</discount_type>\n  <discount_percent type=\"integer\">10</discount_percent>\n  <invoice_description nil=\"nil\"/>\n  <redeem_by_date type=\"datetime\">2017-12-31T00:00:00Z</redeem_by_date>\n  <single_use type=\"boolean\">true</single_use>\n  <applies_for_months nil=\"nil\"/>\n  <max_redemptions type=\"integer\">200</max_redemptions>\n  <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n  <created_at type=\"datetime\">2016-07-11T18:50:17Z</created_at>\n  <updated_at type=\"datetime\">2016-07-11T18:50:17Z</updated_at>\n  <deleted_at nil=\"nil\"/>\n  <duration>single_use</duration>\n  <temporal_unit nil=\"nil\"/>\n  <temporal_amount nil=\"nil\"/>\n  <applies_to_non_plan_charges type=\"boolean\">false</applies_to_non_plan_charges>\n  <redemption_resource>account</redemption_resource>\n  <max_redemptions_per_account nil=\"nil\"/>\n  <coupon_type>single_code</coupon_type>\n  <plan_codes type=\"array\">\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n  <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n</coupon>","language":"xml","status":200},{"status":200,"language":"xml","code":"<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/sprintdemos347\">\n  <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/savemore/redemptions\"/>\n  <unique_coupon_codes href=\"https://your-subdomain.recurly.com/v2/coupons/savemore/unique_coupon_codes\"/>\n  <coupon_code>savemore</coupon_code>\n  <name>Save More Annual Sale</name>\n  <state>redeemable</state>\n  <description nil=\"nil\"></description>\n  <discount_type>dollars</discount_type>\n  <discount_in_cents>\n  \t<USD type=\"integer\">2000</USD>\n  </discount_in_cents>\n  <invoice_description nil=\"nil\"></invoice_description>\n  <redeem_by_date nil=\"nil\"></redeem_by_date>\n  <single_use type=\"boolean\">false</single_use>\n  <applies_for_months nil=\"nil\"></applies_for_months>\n  <max_redemptions nil=\"nil\"></max_redemptions>\n  <applies_to_all_plans type=\"boolean\">true</applies_to_all_plans>\n  <created_at type=\"datetime\">2015-10-05T16:42:50Z</created_at>\n  <duration>temporal</duration>\n  <temporal_unit>day</temporal_unit>\n  <temporal_amount type=\"integer\">28</temporal_amount>\n  <applies_to_non_plan_charges type=\"boolean\">false</applies_to_non_plan_charges>\n  <redemption_resource>account</redemption_resource>\n  <max_redemptions_per_account type=\"integer\">1</max_redemptions_per_account>\n  <coupon_type>bulk</coupon_type>\n  <unique_code_template>'savemore'99999999</unique_code_template>\n  <deleted_at nil=\"nil\"></deleted_at>\n  <unique_coupon_codes_count type=\"integer\">100</unique_coupon_codes_count>\n  <plan_codes type=\"array\"></plan_codes>\n  <a name=\"generate\" href=\"https://your-subdomain.recurly.com/v2/coupons/savemore/generate\" method=\"post\"/>\n</coupon>","name":"Bulk Coupon"},{"name":"Unique Code","status":200,"language":"xml","code":"<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/savemore28945343\">\n  <bulk_coupon href=\"https://your-subdomain.recurly.com/v2/coupons/savemore\"/>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/coupons/savemore28945343/redemption\"/>\n  <coupon_code>savemore28945343</coupon_code>\n  <name>Save More Annual Sale</name>\n  <state>maxed_out</state>\n  <description></description>\n  <discount_type>dollar</discount_type>\n  <discount_percent type=\"integer\">2000</discount_percent>\n  <invoice_description></invoice_description>\n  <redeem_by_date nil=\"nil\"></redeem_by_date>\n  <single_use type=\"boolean\">true</single_use>\n  <applies_for_months nil=\"nil\"></applies_for_months>\n  <max_redemptions nil=\"nil\"></max_redemptions>\n  <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n  <created_at type=\"datetime\">2015-10-05T16:42:50Z</created_at>\n  <duration>temporal</duration>\n  <temporal_unit>day</temporal_unit>\n  <temporal_amount type=\"integer\">28</temporal_amount>\n  <applies_to_non_plan_charges type=\"boolean\">false</applies_to_non_plan_charges>\n  <redemption_resource>account</redemption_resource>\n  <max_redemptions_per_account type=\"integer\">1</max_redemptions_per_account>\n  <coupon_type>unique_code</coupon_type>\n  <redeemed_at type=\"datetime\">2015-10-07T18:48:12Z</redeemed_at>\n  <deleted_at nil=\"nil\"></deleted_at>\n  <plan_codes type=\"array\"></plan_codes>\n  <a name=\"restore\" href=\"https://your-subdomain.recurly.com/v2/coupons/savemore28945343/restore\" method=\"put\"/>\n</coupon>"}]},"settings":"","url":"/coupons/:coupon_code","auth":"required","examples":{"codes":[{"name":"","language":"php","code":"<?php\n\ntry {\n  $coupon = Recurly_Coupon::get('special');\n  print \"Coupon: $coupon\\n\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Coupon does not exist\";\n}"},{"language":"ruby","code":"coupon = Recurly::Coupon.find('special')"},{"language":"python","code":"coupon = Coupon.get('special')"},{"language":"csharp","code":"var coupon = Coupons.Get(\"special\");"}]},"method":"get","params":[{"_id":"5783c9e36bcaf40e00a5d872","default":"","desc":"Unique code to identify and redeem the coupon.","name":"coupon_code","ref":"","required":true,"type":"string","in":"path"}],"apiSetting":"59497f16b9248d0024fe3f31"},"body":"","category":"57803084827bd50e006b045f","createdAt":"2015-06-17T22:55:45.346Z","editedParams2":true,"hidden":false,"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getLookup a Coupon

Returns information about an active coupon.

Path Params

coupon_code:
required
string
Unique code to identify and redeem the coupon.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $coupon = Recurly_Coupon::get('special');
  print "Coupon: $coupon\n";
} catch (Recurly_NotFoundError $e) {
  print "Coupon does not exist";
}
coupon = Recurly::Coupon.find('special')
coupon = Coupon.get('special')
var coupon = Coupons.Get("special");

Result Format

<coupon href="https://your-subdomain.recurly.com/v2/coupons/special">
  <redemptions href="https://your-subdomain.recurly.com/v2/coupons/special/redemptions"/>
  <coupon_code>special</coupon_code>
  <name>Special 10% off</name>
  <state>redeemable</state>
  <description nil="nil"/>
  <discount_type>percent</discount_type>
  <discount_percent type="integer">10</discount_percent>
  <invoice_description nil="nil"/>
  <redeem_by_date type="datetime">2017-12-31T00:00:00Z</redeem_by_date>
  <single_use type="boolean">true</single_use>
  <applies_for_months nil="nil"/>
  <max_redemptions type="integer">200</max_redemptions>
  <applies_to_all_plans type="boolean">false</applies_to_all_plans>
  <created_at type="datetime">2016-07-11T18:50:17Z</created_at>
  <updated_at type="datetime">2016-07-11T18:50:17Z</updated_at>
  <deleted_at nil="nil"/>
  <duration>single_use</duration>
  <temporal_unit nil="nil"/>
  <temporal_amount nil="nil"/>
  <applies_to_non_plan_charges type="boolean">false</applies_to_non_plan_charges>
  <redemption_resource>account</redemption_resource>
  <max_redemptions_per_account nil="nil"/>
  <coupon_type>single_code</coupon_type>
  <plan_codes type="array">
    <plan_code>gold</plan_code>
    <plan_code>platinum</plan_code>
  </plan_codes>
  <a name="redeem" href="https://your-subdomain.recurly.com/v2/coupons/special/redeem" method="post"/>
</coupon>
<coupon href="https://your-subdomain.recurly.com/v2/coupons/sprintdemos347">
  <redemptions href="https://your-subdomain.recurly.com/v2/coupons/savemore/redemptions"/>
  <unique_coupon_codes href="https://your-subdomain.recurly.com/v2/coupons/savemore/unique_coupon_codes"/>
  <coupon_code>savemore</coupon_code>
  <name>Save More Annual Sale</name>
  <state>redeemable</state>
  <description nil="nil"></description>
  <discount_type>dollars</discount_type>
  <discount_in_cents>
  	<USD type="integer">2000</USD>
  </discount_in_cents>
  <invoice_description nil="nil"></invoice_description>
  <redeem_by_date nil="nil"></redeem_by_date>
  <single_use type="boolean">false</single_use>
  <applies_for_months nil="nil"></applies_for_months>
  <max_redemptions nil="nil"></max_redemptions>
  <applies_to_all_plans type="boolean">true</applies_to_all_plans>
  <created_at type="datetime">2015-10-05T16:42:50Z</created_at>
  <duration>temporal</duration>
  <temporal_unit>day</temporal_unit>
  <temporal_amount type="integer">28</temporal_amount>
  <applies_to_non_plan_charges type="boolean">false</applies_to_non_plan_charges>
  <redemption_resource>account</redemption_resource>
  <max_redemptions_per_account type="integer">1</max_redemptions_per_account>
  <coupon_type>bulk</coupon_type>
  <unique_code_template>'savemore'99999999</unique_code_template>
  <deleted_at nil="nil"></deleted_at>
  <unique_coupon_codes_count type="integer">100</unique_coupon_codes_count>
  <plan_codes type="array"></plan_codes>
  <a name="generate" href="https://your-subdomain.recurly.com/v2/coupons/savemore/generate" method="post"/>
</coupon>
<coupon href="https://your-subdomain.recurly.com/v2/coupons/savemore28945343">
  <bulk_coupon href="https://your-subdomain.recurly.com/v2/coupons/savemore"/>
  <redemption href="https://your-subdomain.recurly.com/v2/coupons/savemore28945343/redemption"/>
  <coupon_code>savemore28945343</coupon_code>
  <name>Save More Annual Sale</name>
  <state>maxed_out</state>
  <description></description>
  <discount_type>dollar</discount_type>
  <discount_percent type="integer">2000</discount_percent>
  <invoice_description></invoice_description>
  <redeem_by_date nil="nil"></redeem_by_date>
  <single_use type="boolean">true</single_use>
  <applies_for_months nil="nil"></applies_for_months>
  <max_redemptions nil="nil"></max_redemptions>
  <applies_to_all_plans type="boolean">false</applies_to_all_plans>
  <created_at type="datetime">2015-10-05T16:42:50Z</created_at>
  <duration>temporal</duration>
  <temporal_unit>day</temporal_unit>
  <temporal_amount type="integer">28</temporal_amount>
  <applies_to_non_plan_charges type="boolean">false</applies_to_non_plan_charges>
  <redemption_resource>account</redemption_resource>
  <max_redemptions_per_account type="integer">1</max_redemptions_per_account>
  <coupon_type>unique_code</coupon_type>
  <redeemed_at type="datetime">2015-10-07T18:48:12Z</redeemed_at>
  <deleted_at nil="nil"></deleted_at>
  <plan_codes type="array"></plan_codes>
  <a name="restore" href="https://your-subdomain.recurly.com/v2/coupons/savemore28945343/restore" method="put"/>
</coupon>


{"_id":"57803085827bd50e006b04bb","slug":"generate-unique-codes","type":"post","link_url":"","body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"View Unique Codes\"\n}\n[/block]\nThe response will include the location of the unique codes as link in the header:\n\n```\nhttps://your-subdomain.recurly.com/v2/coupons/savemore/unique_coupon_codes?cursor=1792526747654056328&per_page=200\n```","editedParams":true,"githubsync":"","order":4,"sync_unique":"","title":"Generate Unique Codes","editedParams2":true,"excerpt":"Create unique codes for a bulk coupon. A bulk coupon can have up to 100,000 unique codes total. The generate endpoint allows up to 200 unique codes at a time. The endpoint can be called multiple times to create then number of unique codes you need.","parentDoc":null,"project":"555fbba928249c1900618a82","updates":[],"api":{"results":{"codes":[{"code":"<error>\n  <symbol>number_of_unique_codes</symbol>\n  <description>You are limited to generating 200 at a time</description>\n</error>","language":"xml","status":400,"name":"Request Too High"},{"language":"xml","status":400,"name":"Request In Progress","code":"<error>\n  <symbol>number_of_unique_codes</symbol>\n  <description>Number of unique codes cannot be generated; unique code creation is in progress, please wait for it to finish and try again</description>\n</error>"},{"code":"<error>\n  <symbol>number_of_unique_codes</symbol>\n  <description>Number of unique codes can only generate a total of 100000 codes</description>\n</error>","language":"xml","status":400,"name":"Max Reached"},{"code":"<error>\n  <symbol>number_of_unique_codes</symbol>\n  <description>Coupon must be of type bulk to generate unique codes</description>\n</error>","language":"xml","status":400,"name":"Not Bulk Coupon"}]},"settings":"","url":"/coupons/:coupon_code/generate","auth":"required","examples":{"codes":[{"language":"xml","code":"<coupon>\n  <number_of_unique_codes>200</number_of_unique_codes>\n</coupon>","name":"XML"}]},"method":"post","params":[{"ref":"","in":"body","required":false,"desc":"Number of unique codes you want to generate for the bulk coupon. Must be between 1 and 200.","default":"","type":"int","name":"number_of_unique_codes","_id":"5618a0ab9420c40d00510833"},{"ref":"","required":true,"type":"string","_id":"578d05a3d9c55c2000d4f1e1","default":"","desc":"Unique code to identify and redeem the coupon.","in":"path","name":"coupon_code"}],"apiSetting":"59497f16b9248d0024fe3f31"},"category":"57803084827bd50e006b045f","createdAt":"2015-10-10T05:22:51.540Z","hidden":false,"isReference":true,"link_external":false,"user":"55b66dba6127b1250036446f","version":"57803084827bd50e006b0457","__v":2,"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postGenerate Unique Codes

Create unique codes for a bulk coupon. A bulk coupon can have up to 100,000 unique codes total. The generate endpoint allows up to 200 unique codes at a time. The endpoint can be called multiple times to create then number of unique codes you need.

Path Params

coupon_code:
required
string
Unique code to identify and redeem the coupon.

Body Params

number_of_unique_codes:
integer
Number of unique codes you want to generate for the bulk coupon. Must be between 1 and 200.

View Unique Codes

The response will include the location of the unique codes as link in the header:

https://your-subdomain.recurly.com/v2/coupons/savemore/unique_coupon_codes?cursor=1792526747654056328&per_page=200

Definition

{{ api_url }}{{ page_api_url }}

Examples

<coupon>
  <number_of_unique_codes>200</number_of_unique_codes>
</coupon>

Result Format

<error>
  <symbol>number_of_unique_codes</symbol>
  <description>You are limited to generating 200 at a time</description>
</error>
<error>
  <symbol>number_of_unique_codes</symbol>
  <description>Number of unique codes cannot be generated; unique code creation is in progress, please wait for it to finish and try again</description>
</error>
<error>
  <symbol>number_of_unique_codes</symbol>
  <description>Number of unique codes can only generate a total of 100000 codes</description>
</error>
<error>
  <symbol>number_of_unique_codes</symbol>
  <description>Coupon must be of type bulk to generate unique codes</description>
</error>


{"_id":"57803085827bd50e006b04bc","category":"57803084827bd50e006b045f","githubsync":"","link_external":false,"type":"delete","updates":[],"api":{"params":[{"type":"string","name":"coupon_code","_id":"578d05b984f5cd0e00891689","ref":"","in":"path","required":true,"desc":"Unique code to identify and redeem the coupon.","default":""}],"results":{"codes":[{"status":204,"language":"xml","code":"Status: 204 No Content"}]},"settings":"","url":"/coupons/:coupon_code","auth":"required","examples":{"codes":[{"name":"","code":"<?php\n\ntry {\n  $coupon = Recurly_Coupon::get('special');\n  $coupon->delete();\n\n  print \"Coupon: $coupon\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Coupon not found: $e\";\n}","language":"php"},{"code":"coupon = Recurly::Coupon.find('special')\ncoupon.destroy","language":"ruby"},{"code":"coupon = Coupon.get('special')\ncoupon.delete()","language":"python"},{"code":"var coupon = Coupons.Get(\"special\");\ncoupon.Deactivate();","language":"csharp"}]},"method":"delete","apiSetting":"59497f16b9248d0024fe3f31"},"createdAt":"2015-06-17T23:28:22.499Z","version":"57803084827bd50e006b0457","parentDoc":null,"project":"555fbba928249c1900618a82","body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Bulk Unique Coupons\",\n  \"body\": \"Use the coupon_code of the main coupon campaign, also known as the prefix, to expire all not yet redeemed unique codes in the campaign. Use the unique code's coupon_code in order to expire just the specific unique code.\"\n}\n[/block]","hidden":false,"isReference":true,"link_url":"","order":5,"slug":"deactivate-coupon","sync_unique":"","title":"Expire Coupon","__v":2,"excerpt":"Expire the coupon so customers can no longer redeem the coupon.","user":"5581f6648625220d00429ef6","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

deleteExpire Coupon

Expire the coupon so customers can no longer redeem the coupon.

Path Params

coupon_code:
required
string
Unique code to identify and redeem the coupon.

Bulk Unique Coupons

Use the coupon_code of the main coupon campaign, also known as the prefix, to expire all not yet redeemed unique codes in the campaign. Use the unique code's coupon_code in order to expire just the specific unique code.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $coupon = Recurly_Coupon::get('special');
  $coupon->delete();

  print "Coupon: $coupon";
} catch (Recurly_NotFoundError $e) {
  print "Coupon not found: $e";
}
coupon = Recurly::Coupon.find('special')
coupon.destroy
coupon = Coupon.get('special')
coupon.delete()
var coupon = Coupons.Get("special");
coupon.Deactivate();

Result Format

Status: 204 No Content


{"_id":"57803085827bd50e006b04bd","link_url":"","order":6,"slug":"edit-coupon","sync_unique":"","title":"Edit Coupon","githubsync":"","isReference":true,"type":"put","updates":[],"editedParams2":true,"hidden":false,"link_external":false,"parentDoc":null,"project":"555fbba928249c1900618a82","api":{"results":{"codes":[{"language":"xml","code":"<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n  <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n  <coupon_code>special</coupon_code>\n  <name>New Coupon Name</name>\n  <state>redeemable</state>\n  <description>New coupon description for the hosted pages.</description>\n  <discount_type>percent</discount_type>\n  <discount_percent type=\"integer\">10</discount_percent>\n  <invoice_description>New coupon description for the invoice.</invoice_description>\n  <redeem_by_date type=\"datetime\">2017-12-31T00:00:00Z</redeem_by_date>\n  <single_use type=\"boolean\">true</single_use>\n  <applies_for_months nil=\"nil\"/>\n  <max_redemptions type=\"integer\">500</max_redemptions>\n  <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n  <created_at type=\"datetime\">2016-07-11T18:50:17Z</created_at>\n  <updated_at type=\"datetime\">2016-07-11T18:52:29Z</updated_at>\n  <deleted_at nil=\"nil\"/>\n  <duration>single_use</duration>\n  <temporal_unit nil=\"nil\"/>\n  <temporal_amount nil=\"nil\"/>\n  <applies_to_non_plan_charges type=\"boolean\">false</applies_to_non_plan_charges>\n  <redemption_resource>account</redemption_resource>\n  <max_redemptions_per_account type=\"integer\">1</max_redemptions_per_account>\n  <coupon_type>single_code</coupon_type>\n  <plan_codes type=\"array\">\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n  <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n</coupon>","name":"","status":200},{"code":"<error>\n    <symbol>attributes_not_allowed</symbol>\n    <description>You are not allowed to edit attributes discount_type.</description>\n</error>","name":"Field Not Editable","status":400,"language":"xml"}]},"settings":"","url":"/coupons/:coupon_code","auth":"required","examples":{"codes":[{"language":"xml","code":"<coupon>\n  <name>New Coupon Name</name>\n  <description>New coupon description for the hosted pages.</description>\n  <invoice_description>New coupon description for the invoice.</invoice_description>\n  <redeem_by_date>2017-12-31</redeem_by_date>\n  <max_redemptions>500</max_redemptions>\n  <max_redemptions_per_account>1</max_redemptions_per_account>\n</coupon>","name":""}]},"method":"put","params":[{"default":"","desc":"Coupon name.","in":"body","name":"name","ref":"","required":false,"type":"string","_id":"561738644d9e4a17002a0de5"},{"ref":"","required":false,"type":"string","_id":"561738644d9e4a17002a0de4","default":"","desc":"Description of the coupon on the hosted payment pages.","in":"body","name":"description"},{"desc":"Description of the coupon on the invoice.","in":"body","name":"invoice_description","ref":"","required":false,"type":"string","_id":"561738644d9e4a17002a0de3","default":""},{"name":"redeem_by_date","ref":"","required":false,"type":"datetime","_id":"561738644d9e4a17002a0de2","default":"","desc":"Last date to redeem the coupon, defaults to no date.","in":"body"},{"type":"int","_id":"561738644d9e4a17002a0de1","default":"","desc":"Maximum number of accounts that may use the coupon before it can no longer be redeemed.","in":"body","name":"max_redemptions","ref":"","required":false},{"default":"","desc":"The number of times the coupon can be redeemed on a specific account. `null` is the default and means unlimited.","in":"body","name":"max_redemptions_per_account","ref":"","required":false,"type":"int","_id":"561738644d9e4a17002a0de0"},{"in":"path","required":true,"desc":"Unique code to identify and redeem the coupon.","default":"","type":"string","name":"coupon_code","_id":"578d05d52c6ddb0e003fd005","ref":""}],"apiSetting":"59497f16b9248d0024fe3f31"},"category":"57803084827bd50e006b045f","editedParams":true,"user":"55b66dba6127b1250036446f","version":"57803084827bd50e006b0457","excerpt":"Edit a redeemable coupon to extend redemption rules. Only redeemable coupons can be edited and only the below params are editable.","__v":2,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Editing Bulk Coupons and Unique Codes\"\n}\n[/block]\nYou can edit a bulk coupon to change the rules of the campaign, but you cannot edit a unique code within the campaign.","createdAt":"2015-10-09T03:45:40.895Z","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

putEdit Coupon

Edit a redeemable coupon to extend redemption rules. Only redeemable coupons can be edited and only the below params are editable.

Path Params

coupon_code:
required
string
Unique code to identify and redeem the coupon.

Body Params

name:
string
Coupon name.
description:
string
Description of the coupon on the hosted payment pages.
invoice_description:
string
Description of the coupon on the invoice.
redeem_by_date:
datetime
Last date to redeem the coupon, defaults to no date.
max_redemptions:
integer
Maximum number of accounts that may use the coupon before it can no longer be redeemed.
max_redemptions_per_account:
integer
The number of times the coupon can be redeemed on a specific account. `null` is the default and means unlimited.

Editing Bulk Coupons and Unique Codes

You can edit a bulk coupon to change the rules of the campaign, but you cannot edit a unique code within the campaign.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<coupon>
  <name>New Coupon Name</name>
  <description>New coupon description for the hosted pages.</description>
  <invoice_description>New coupon description for the invoice.</invoice_description>
  <redeem_by_date>2017-12-31</redeem_by_date>
  <max_redemptions>500</max_redemptions>
  <max_redemptions_per_account>1</max_redemptions_per_account>
</coupon>

Result Format

<coupon href="https://your-subdomain.recurly.com/v2/coupons/special">
  <redemptions href="https://your-subdomain.recurly.com/v2/coupons/special/redemptions"/>
  <coupon_code>special</coupon_code>
  <name>New Coupon Name</name>
  <state>redeemable</state>
  <description>New coupon description for the hosted pages.</description>
  <discount_type>percent</discount_type>
  <discount_percent type="integer">10</discount_percent>
  <invoice_description>New coupon description for the invoice.</invoice_description>
  <redeem_by_date type="datetime">2017-12-31T00:00:00Z</redeem_by_date>
  <single_use type="boolean">true</single_use>
  <applies_for_months nil="nil"/>
  <max_redemptions type="integer">500</max_redemptions>
  <applies_to_all_plans type="boolean">false</applies_to_all_plans>
  <created_at type="datetime">2016-07-11T18:50:17Z</created_at>
  <updated_at type="datetime">2016-07-11T18:52:29Z</updated_at>
  <deleted_at nil="nil"/>
  <duration>single_use</duration>
  <temporal_unit nil="nil"/>
  <temporal_amount nil="nil"/>
  <applies_to_non_plan_charges type="boolean">false</applies_to_non_plan_charges>
  <redemption_resource>account</redemption_resource>
  <max_redemptions_per_account type="integer">1</max_redemptions_per_account>
  <coupon_type>single_code</coupon_type>
  <plan_codes type="array">
    <plan_code>gold</plan_code>
    <plan_code>platinum</plan_code>
  </plan_codes>
  <a name="redeem" href="https://your-subdomain.recurly.com/v2/coupons/special/redeem" method="post"/>
</coupon>
<error>
    <symbol>attributes_not_allowed</symbol>
    <description>You are not allowed to edit attributes discount_type.</description>
</error>


{"_id":"57803085827bd50e006b04be","editedParams":true,"excerpt":"Make an expired coupon redeemable again. You can change editable fields in this call.","githubsync":"","isReference":true,"parentDoc":null,"sync_unique":"","type":"put","createdAt":"2015-10-09T16:38:55.663Z","version":"57803084827bd50e006b0457","body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If you aren't going to change anything in the restore action, include the coupon parameter: <coupon/>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Restore Coupon That Reached Redeem By Date\"\n}\n[/block]\nIf your coupon has a redeem by date in the past, you must remove the date or change it to a future date, otherwise you will get this error:\n\n```\n<errors>\n    <error field=\"coupon.redeem_by_date\" symbol=\"in_past\">must be in the future</error>\n</errors>\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Restore Coupon That Reached Max Redemptions\"\n}\n[/block]\nIf your coupon has reached it's max redemptions, you must remove the max redemptions or change it to a greater number. You cannot set max redemptions to anything less than the number of redemptions you have. If you do not update max redemptions in this case, you will get this error.\n\n```\n<errors>\n    <error field=\"coupon.max_redemptions\" symbol=\"too_low\">must be greater than 100</error>\n</errors>\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Restoring Bulk Coupons or Unique Codes\"\n}\n[/block]\nRestoring a bulk coupon will restore the coupon campaign and all unique codes that have not been redeemed or individually expired.\n\nYou can restore an individual unique code if the bulk coupon is active by using the unique code's coupon code in the call.","link_external":false,"link_url":"","slug":"restore-coupon","title":"Restore Coupon","updates":[],"api":{"auth":"required","examples":{"codes":[{"language":"xml","code":"<coupon>\n  <name>New Coupon Name</name>\n  <description>New coupon description for the hosted pages.</description>\n  <invoice_description>New coupon description for the invoice.</invoice_description>\n  <redeem_by_date>2017-12-31</redeem_by_date>\n  <max_redemptions>500</max_redemptions>\n  <max_redemptions_per_account>1</max_redemptions_per_account>\n</coupon>","name":""}]},"method":"put","params":[{"default":"","desc":"Coupon name.","in":"body","name":"name","ref":"","required":false,"type":"string","_id":"5617ed9f26e3db230054fc1c"},{"ref":"","required":false,"type":"string","_id":"5617ed9f26e3db230054fc1b","default":"","desc":"Description of the coupon on the hosted payment pages.","in":"body","name":"description"},{"ref":"","required":false,"type":"string","_id":"5617ed9f26e3db230054fc1a","default":"","desc":"Description of the coupon on the invoice.","in":"body","name":"invoice_description"},{"desc":"Last date to redeem the coupon, defaults to no date.","in":"body","name":"redeem_by_date","ref":"","required":false,"type":"datetime","_id":"5617ed9f26e3db230054fc19","default":""},{"name":"max_redemptions","ref":"","required":false,"type":"int","_id":"5617ed9f26e3db230054fc18","default":"","desc":"Maximum number of accounts that may use the coupon before it can no longer be redeemed.","in":"body"},{"_id":"5617ed9f26e3db230054fc17","default":"","desc":"The number of times the coupon can be redeemed on a specific account. `null` is the default and means unlimited.","in":"body","name":"max_redemptions_per_account","ref":"","required":false,"type":"int"},{"_id":"578d05e384f5cd0e0089168b","ref":"","in":"path","required":true,"desc":"Unique code to identify and redeem the coupon.","default":"","type":"string","name":"coupon_code"}],"results":{"codes":[{"status":200,"language":"xml","code":"<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/sprintdemos3456\">\n  <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/savemore/redemptions\" />\n  <coupon_code>savemore</coupon_code>\n  <name>New Coupon Name</name>\n  <state>redeemable</state>\n  <description>New coupon description for the hosted pages.</description>\n  <discount_type>percent</discount_type>\n  <discount_percent type=\"integer\">10</discount_percent>\n  <invoice_description>New coupon description for the invoice.</invoice_description>\n  <redeem_by_date type=\"datetime\">2017-12-31T00:00:00Z</redeem_by_date>\n  <single_use type=\"boolean\">false</single_use>\n  <applies_for_months nil=\"nil\" />\n  <max_redemptions type=\"integer\">500</max_redemptions>\n  <applies_to_all_plans type=\"boolean\">true</applies_to_all_plans>\n  <created_at type=\"datetime\">2016-06-05T16:42:32Z</created_at>\n  <duration>forever</duration>\n  <temporal_unit nil=\"nil\" />\n  <temporal_amount nil=\"nil\" />\n  <applies_to_non_plan_charges type=\"boolean\">false</applies_to_non_plan_charges>\n  <redemption_resource>account</redemption_resource>\n  <max_redemptions_per_account type=\"integer\">1</max_redemptions_per_account>\n  <coupon_type>single_code</coupon_type>\n  <deleted_at nil=\"nil\" />\n  <plan_codes type=\"array\" />\n  <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/savemore/redeem\" method=\"post\" />\n</coupon>","name":""},{"status":400,"language":"xml","code":"<error>\n    <symbol>attributes_not_allowed</symbol>\n    <description>You are not allowed to edit attributes discount_type.</description>\n</error>","name":"Field Not Editable"},{"name":"Active Coupon","status":400,"language":"xml","code":"<error>\n    <symbol>active_coupon</symbol>\n    <description>Restoring an active coupon is not allowed</description>\n</error>"}]},"settings":"","url":"/coupons/:coupon_code/restore","apiSetting":"59497f16b9248d0024fe3f31"},"category":"57803084827bd50e006b045f","editedParams2":true,"hidden":false,"order":7,"__v":2,"user":"55b66dba6127b1250036446f","project":"555fbba928249c1900618a82","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

putRestore Coupon

Make an expired coupon redeemable again. You can change editable fields in this call.

Path Params

coupon_code:
required
string
Unique code to identify and redeem the coupon.

Body Params

name:
string
Coupon name.
description:
string
Description of the coupon on the hosted payment pages.
invoice_description:
string
Description of the coupon on the invoice.
redeem_by_date:
datetime
Last date to redeem the coupon, defaults to no date.
max_redemptions:
integer
Maximum number of accounts that may use the coupon before it can no longer be redeemed.
max_redemptions_per_account:
integer
The number of times the coupon can be redeemed on a specific account. `null` is the default and means unlimited.

If you aren't going to change anything in the restore action, include the coupon parameter: <coupon/>

Restore Coupon That Reached Redeem By Date

If your coupon has a redeem by date in the past, you must remove the date or change it to a future date, otherwise you will get this error:

<errors>
    <error field="coupon.redeem_by_date" symbol="in_past">must be in the future</error>
</errors>

Restore Coupon That Reached Max Redemptions

If your coupon has reached it's max redemptions, you must remove the max redemptions or change it to a greater number. You cannot set max redemptions to anything less than the number of redemptions you have. If you do not update max redemptions in this case, you will get this error.

<errors>
    <error field="coupon.max_redemptions" symbol="too_low">must be greater than 100</error>
</errors>

Restoring Bulk Coupons or Unique Codes

Restoring a bulk coupon will restore the coupon campaign and all unique codes that have not been redeemed or individually expired.

You can restore an individual unique code if the bulk coupon is active by using the unique code's coupon code in the call.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<coupon>
  <name>New Coupon Name</name>
  <description>New coupon description for the hosted pages.</description>
  <invoice_description>New coupon description for the invoice.</invoice_description>
  <redeem_by_date>2017-12-31</redeem_by_date>
  <max_redemptions>500</max_redemptions>
  <max_redemptions_per_account>1</max_redemptions_per_account>
</coupon>

Result Format

<coupon href="https://your-subdomain.recurly.com/v2/coupons/sprintdemos3456">
  <redemptions href="https://your-subdomain.recurly.com/v2/coupons/savemore/redemptions" />
  <coupon_code>savemore</coupon_code>
  <name>New Coupon Name</name>
  <state>redeemable</state>
  <description>New coupon description for the hosted pages.</description>
  <discount_type>percent</discount_type>
  <discount_percent type="integer">10</discount_percent>
  <invoice_description>New coupon description for the invoice.</invoice_description>
  <redeem_by_date type="datetime">2017-12-31T00:00:00Z</redeem_by_date>
  <single_use type="boolean">false</single_use>
  <applies_for_months nil="nil" />
  <max_redemptions type="integer">500</max_redemptions>
  <applies_to_all_plans type="boolean">true</applies_to_all_plans>
  <created_at type="datetime">2016-06-05T16:42:32Z</created_at>
  <duration>forever</duration>
  <temporal_unit nil="nil" />
  <temporal_amount nil="nil" />
  <applies_to_non_plan_charges type="boolean">false</applies_to_non_plan_charges>
  <redemption_resource>account</redemption_resource>
  <max_redemptions_per_account type="integer">1</max_redemptions_per_account>
  <coupon_type>single_code</coupon_type>
  <deleted_at nil="nil" />
  <plan_codes type="array" />
  <a name="redeem" href="https://your-subdomain.recurly.com/v2/coupons/savemore/redeem" method="post" />
</coupon>
<error>
    <symbol>attributes_not_allowed</symbol>
    <description>You are not allowed to edit attributes discount_type.</description>
</error>
<error>
    <symbol>active_coupon</symbol>
    <description>Restoring an active coupon is not allowed</description>
</error>


{"_id":"57803085827bd50e006b04bf","link_url":"","updates":[],"createdAt":"2015-06-17T23:45:47.017Z","editedParams":true,"excerpt":"Lookup information about the coupon redemptions on an account. Active and naturally expired limited  duration redemptions will be returned. Redemptions removed from the account or expired single use coupons will not be returned.","link_external":false,"githubsync":"","parentDoc":null,"sync_unique":"","__v":3,"api":{"method":"get","params":[{"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","_id":"5783cb895cbce30e0074e221","ref":"","in":"query","required":false},{"name":"per_page","_id":"5783cb895cbce30e0074e220","ref":"","in":"query","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int"},{"ref":"","in":"path","required":true,"desc":"Unique account identifier.","default":"","type":"string","name":"account_code","_id":"578d060e733f2f2000b1538f"}],"results":{"codes":[{"code":"<redemptions type=\"array\">\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemptions/316a4213e8fa9e97390aff4995bda9e6\">\n    <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\" />\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\" />\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/315fbd7a25b04f1333ea9f4418994fb5\" />\n    <uuid>316a4213e8fa9e97390aff4995bda9e6</uuid>\n    <single_use type=\"boolean\">false</single_use>\n    <total_discounted_in_cents type=\"integer\">0</total_discounted_in_cents>\n    <currency>USD</currency>\n    <state>active</state>\n    <created_at type=\"datetime\">2016-06-15T17:13:30Z</created_at>\n  </redemption>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemptions/3169fd6127ff82ccbfa08a442188d575\">\n    <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\" />\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\" />\n    <uuid>3169fd6127ff82ccbfa08a442188d575</uuid>\n    <single_use type=\"boolean\">false</single_use>\n    <total_discounted_in_cents type=\"integer\">1500</total_discounted_in_cents>\n    <currency>USD</currency>\n    <state>active</state>\n    <created_at type=\"datetime\">2016-05-27T12:34:56Z</created_at>\n  </redemption>\n</redemptions>","name":"","status":200,"language":"xml"}]},"settings":"","url":"/accounts/:account_code/redemptions","auth":"required","examples":{"codes":[{"code":"<?php\n\ntry {\n  $account = Recurly_Account::get('b6f5783');\n  if ($account->redemptions) {\n    $redemptions = $account->redemptions->get();\n    print \"Redemptions: $redemptions\";\n  }\n} catch (Recurly_NotFoundError $e) {\n  print \"Account not found: $e\";\n}","name":"","language":"php"},{"language":"ruby","code":"account = Recurly::Account.find('1')\nredemptions = account.redemptions"},{"language":"python","code":"account = Account.get('1')\nredemptions = account.redemptions()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar redemptions = account.GetActiveRedemptions();"}]},"apiSetting":"59497f16b9248d0024fe3f31"},"category":"57803084827bd50e006b0460","editedParams2":true,"isReference":true,"title":"Lookup a Coupon Redemption on an Account","user":"5581f6648625220d00429ef6","slug":"lookup-a-coupon-redemption-on-an-account","type":"get","version":"57803084827bd50e006b0457","body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"If you use the singular, \\\"redemption\\\", in the endpoint, you will only see the most recently redeemed redemption.\"\n}\n[/block]","hidden":false,"order":0,"project":"555fbba928249c1900618a82","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getLookup a Coupon Redemption on an Account

Lookup information about the coupon redemptions on an account. Active and naturally expired limited duration redemptions will be returned. Redemptions removed from the account or expired single use coupons will not be returned.

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.
per_page:
integer50
Number of records to return per page, up to a maximum of 200.

If you use the singular, "redemption", in the endpoint, you will only see the most recently redeemed redemption.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

try {
  $account = Recurly_Account::get('b6f5783');
  if ($account->redemptions) {
    $redemptions = $account->redemptions->get();
    print "Redemptions: $redemptions";
  }
} catch (Recurly_NotFoundError $e) {
  print "Account not found: $e";
}
account = Recurly::Account.find('1')
redemptions = account.redemptions
account = Account.get('1')
redemptions = account.redemptions()
var account = Accounts.Get("1");
var redemptions = account.GetActiveRedemptions();

Result Format

<redemptions type="array">
  <redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions/316a4213e8fa9e97390aff4995bda9e6">
    <coupon href="https://your-subdomain.recurly.com/v2/coupons/special" />
    <account href="https://your-subdomain.recurly.com/v2/accounts/1" />
    <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/315fbd7a25b04f1333ea9f4418994fb5" />
    <uuid>316a4213e8fa9e97390aff4995bda9e6</uuid>
    <single_use type="boolean">false</single_use>
    <total_discounted_in_cents type="integer">0</total_discounted_in_cents>
    <currency>USD</currency>
    <state>active</state>
    <created_at type="datetime">2016-06-15T17:13:30Z</created_at>
  </redemption>
  <redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions/3169fd6127ff82ccbfa08a442188d575">
    <coupon href="https://your-subdomain.recurly.com/v2/coupons/special" />
    <account href="https://your-subdomain.recurly.com/v2/accounts/1" />
    <uuid>3169fd6127ff82ccbfa08a442188d575</uuid>
    <single_use type="boolean">false</single_use>
    <total_discounted_in_cents type="integer">1500</total_discounted_in_cents>
    <currency>USD</currency>
    <state>active</state>
    <created_at type="datetime">2016-05-27T12:34:56Z</created_at>
  </redemption>
</redemptions>


{"_id":"57803085827bd50e006b04c0","excerpt":"Returns all coupon redemptions that discounted the invoice.","updates":["569fc5bf1082520d005c7096"],"version":"57803084827bd50e006b0457","api":{"url":"/invoices/:invoice_number/redemptions","auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\n$invoice = Recurly_Invoice::get('1');\nif($invoice->redemptions) {\n  $redemptions = $invoice->redemptions->get();\n}","name":""},{"language":"ruby","code":"invoice = Recurly::Invoice.find('1')\nredemptions = invoice.redemptions"},{"language":"python","code":"invoice = Invoice.get('1')\nredemptions = invoice.redemptions()"},{"language":"csharp","code":"var invoice = Invoices.Get(1);\nvar redemptions = invoice.GetRedemptions();"}]},"method":"get","params":[{"type":"string","_id":"5783ca39359cd219005453bd","default":"","desc":"Invoice number","in":"path","name":"invoice_number","ref":"","required":true},{"name":"cursor","in":"query","_id":"5783ca39359cd219005453bc","ref":"","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"},{"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page","in":"query","_id":"5783ca39359cd219005453bb","ref":"","required":false}],"results":{"codes":[{"status":200,"language":"xml","code":"<redemptions type=\"array\">\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemptions/316a4213e8fa9e97390aff4995bda9e6\">\n    <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\" />\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\" />\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/315fbd7a25b04f1333ea9f4418994fb5\" />\n    <uuid>316a4213e8fa9e97390aff4995bda9e6</uuid>\n    <single_use type=\"boolean\">false</single_use>\n    <total_discounted_in_cents type=\"integer\">100</total_discounted_in_cents>\n    <currency>USD</currency>\n    <state>active</state>\n    <created_at type=\"datetime\">2016-06-15T17:13:30Z</created_at>\n  </redemption>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemptions/3169fd6127ff82ccbfa08a442188d575\">\n    <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\" />\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\" />\n    <uuid>3169fd6127ff82ccbfa08a442188d575</uuid>\n    <single_use type=\"boolean\">false</single_use>\n    <total_discounted_in_cents type=\"integer\">1500</total_discounted_in_cents>\n    <currency>USD</currency>\n    <state>active</state>\n    <created_at type=\"datetime\">2016-05-27T12:34:56Z</created_at>\n  </redemption>\n</redemptions>","name":""}]},"settings":"","apiSetting":"59497f16b9248d0024fe3f31"},"editedParams":true,"githubsync":"","hidden":false,"parentDoc":null,"project":"555fbba928249c1900618a82","slug":"lookup-a-coupon-redemption-on-an-invoice","title":"Lookup a Coupon Redemption on an Invoice","type":"get","user":"5581f6648625220d00429ef6","__v":2,"category":"57803084827bd50e006b0460","createdAt":"2015-06-17T23:51:42.344Z","link_external":false,"link_url":"","order":1,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"If you use the singular, \\\"redemption\\\", in the endpoint, you will only see the first redemption applied to the invoice.\"\n}\n[/block]","editedParams2":true,"isReference":true,"sync_unique":"","next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getLookup a Coupon Redemption on an Invoice

Returns all coupon redemptions that discounted the invoice.

Path Params

invoice_number:
required
string
Invoice number

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.
per_page:
integer50
Number of records to return per page, up to a maximum of 200.

If you use the singular, "redemption", in the endpoint, you will only see the first redemption applied to the invoice.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

$invoice = Recurly_Invoice::get('1');
if($invoice->redemptions) {
  $redemptions = $invoice->redemptions->get();
}
invoice = Recurly::Invoice.find('1')
redemptions = invoice.redemptions
invoice = Invoice.get('1')
redemptions = invoice.redemptions()
var invoice = Invoices.Get(1);
var redemptions = invoice.GetRedemptions();

Result Format

<redemptions type="array">
  <redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions/316a4213e8fa9e97390aff4995bda9e6">
    <coupon href="https://your-subdomain.recurly.com/v2/coupons/special" />
    <account href="https://your-subdomain.recurly.com/v2/accounts/1" />
    <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/315fbd7a25b04f1333ea9f4418994fb5" />
    <uuid>316a4213e8fa9e97390aff4995bda9e6</uuid>
    <single_use type="boolean">false</single_use>
    <total_discounted_in_cents type="integer">100</total_discounted_in_cents>
    <currency>USD</currency>
    <state>active</state>
    <created_at type="datetime">2016-06-15T17:13:30Z</created_at>
  </redemption>
  <redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions/3169fd6127ff82ccbfa08a442188d575">
    <coupon href="https://your-subdomain.recurly.com/v2/coupons/special" />
    <account href="https://your-subdomain.recurly.com/v2/accounts/1" />
    <uuid>3169fd6127ff82ccbfa08a442188d575</uuid>
    <single_use type="boolean">false</single_use>
    <total_discounted_in_cents type="integer">1500</total_discounted_in_cents>
    <currency>USD</currency>
    <state>active</state>
    <created_at type="datetime">2016-05-27T12:34:56Z</created_at>
  </redemption>
</redemptions>


{"_id":"578d4261bd9f40200058dd41","createdAt":"2016-07-18T20:56:01.256Z","githubsync":"","link_url":"","parentDoc":null,"project":"555fbba928249c1900618a82","category":"57803084827bd50e006b0460","excerpt":"Returns an array of active coupon redemptions associated with the specific subscription. Coupon redemptions are only associated with a subscription if the coupon has a discount level of \"subscription\". Inactive coupon redemptions will not be returned.","sync_unique":"","user":"559d85d26b21311700fb0b7b","type":"get","version":"57803084827bd50e006b0457","__v":1,"body":"","isReference":true,"link_external":false,"slug":"lookup-a-coupon-redemption-on-a-subscription","title":"Lookup a Coupon Redemption on a Subscription","api":{"url":"/subscriptions/:uuid/redemptions","auth":"required","examples":{"codes":[]},"method":"get","params":[{"type":"string","_id":"5783ca39359cd219005453bd","default":"","desc":"Subscription's unique identifier.","in":"path","name":"uuid","ref":"","required":true},{"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","_id":"5783ca39359cd219005453bc"},{"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":"5783ca39359cd219005453bb","ref":""}],"results":{"codes":[{"status":200,"language":"xml","code":"<redemptions type=\"array\">\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemptions/376e95a50fd77b5da9a727411bab7c54\">\n    <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/subscription_special\"/>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/376e95a4e15229034db706494a8cf445\"/>\n    <uuid>376e95a50fd77b5da9a727411bab7c54</uuid>\n    <single_use type=\"boolean\">false</single_use>\n    <total_discounted_in_cents type=\"integer\">450</total_discounted_in_cents>\n    <currency>EUR</currency>\n    <state>active</state>\n    <coupon_code>subscription_special</coupon_code>\n    <created_at type=\"datetime\">2016-07-18T20:55:02Z</created_at>\n    <updated_at type=\"datetime\">2016-07-18T20:55:02Z</updated_at>\n  </redemption>\n</redemptions>","name":""}]},"settings":"","apiSetting":"59497f16b9248d0024fe3f31"},"hidden":false,"order":2,"updates":[],"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getLookup a Coupon Redemption on a Subscription

Returns an array of active coupon redemptions associated with the specific subscription. Coupon redemptions are only associated with a subscription if the coupon has a discount level of "subscription". Inactive coupon redemptions will not be returned.

Path Params

uuid:
required
string
Subscription's unique 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.
per_page:
integer50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

<redemptions type="array">
  <redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions/376e95a50fd77b5da9a727411bab7c54">
    <coupon href="https://your-subdomain.recurly.com/v2/coupons/subscription_special"/>
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/376e95a4e15229034db706494a8cf445"/>
    <uuid>376e95a50fd77b5da9a727411bab7c54</uuid>
    <single_use type="boolean">false</single_use>
    <total_discounted_in_cents type="integer">450</total_discounted_in_cents>
    <currency>EUR</currency>
    <state>active</state>
    <coupon_code>subscription_special</coupon_code>
    <created_at type="datetime">2016-07-18T20:55:02Z</created_at>
    <updated_at type="datetime">2016-07-18T20:55:02Z</updated_at>
  </redemption>
</redemptions>


{"_id":"57803085827bd50e006b04c1","editedParams":true,"hidden":false,"isReference":true,"project":"555fbba928249c1900618a82","version":"57803084827bd50e006b0457","title":"Redeem a Coupon on an Account","user":"5581f6648625220d00429ef6","__v":2,"editedParams2":true,"githubsync":"","parentDoc":null,"slug":"redeem-a-coupon-before-or-after-a-subscription","createdAt":"2015-06-17T23:34:25.304Z","link_external":false,"link_url":"","order":3,"sync_unique":"","api":{"params":[{"type":"int","name":"account_code","_id":"55820401a5474a0d00d94750","ref":"","in":"body","required":true,"desc":"Account code to apply redemption","default":""},{"name":"currency","ref":"","required":true,"type":"string","_id":"55820401a5474a0d00d9474f","default":"","desc":"Currency for the redemption.","in":"body"},{"type":"string","_id":"5612ba16cb0e892300d89229","default":"","desc":"If the coupon has a `redemption_resource` of `subscription`, you will need to specify the uuid of an existing subscription on the account, which you want to tie the redemption to.","in":"body","name":"subscription_uuid","ref":"","required":false},{"ref":"","in":"path","required":true,"desc":"Unique code to identify and redeem the coupon.","default":"","type":"string","name":"coupon_code","_id":"578d065dbd9f40200058dc73"}],"results":{"codes":[{"name":"","code":"<redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemptions/374a1c75374bd81493a3f7425db0a2b8\">\n  <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\" />\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\" />\n  <uuid>374a1c75374bd81493a3f7425db0a2b8</uuid>\n  <single_use type=\"boolean\">true</single_use>\n  <total_discounted_in_cents type=\"integer\">0</total_discounted_in_cents>\n  <currency>USD</currency>\n  <state>active</state>\n  <coupon_code>special</coupon_code>\n  <created_at type=\"datetime\">2016-07-11T18:56:20Z</created_at>\n  <updated_at type=\"datetime\">2016-07-11T18:56:20Z</updated_at>\n</redemption>","language":"xml","status":201},{"code":"<error>\n    <symbol>not_found</symbol>\n    <description lang=\"en-US\">Couldn't find Coupon with coupon_code = savemore</description>\n</error>","language":"xml","status":400,"name":"Expired/Invalid"}]},"settings":"","url":"/coupons/:coupon_code/redeem","auth":"required","examples":{"codes":[{"name":"","language":"php","code":"<?php\n\n$coupon = Recurly_Coupon::get('special');\n$redemption = $coupon->redeemCoupon('1', 'USD');"},{"language":"ruby","code":"account = Recurly::Account.find('1')\ncoupon = Recurly::Coupon.find('special')\nredemption = coupon.redeem(account)"},{"code":"coupon = Coupon.get('special')\nredemption = Redemption(account_code='1', currency='USD')\n\n# new redemption object returned from this method will contain the updates\n# so we overwrite the redemption variable\nredemption = coupon.redeem(redemption)","language":"python"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar redemption = account.RedeemCoupon(\"special\", \"USD\");"},{"language":"xml","code":"<redemption>\n  <account_code>1</account_code>\n  <currency>USD</currency>\n</redemption>"}]},"method":"post","apiSetting":"59497f16b9248d0024fe3f31"},"body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"If you want the coupon redemption to be rejected if a subscription signup fails, you must redeem the coupon within the Create Subscription call, not in the Redeem on Account call.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Redeeming Multiple Coupons\"\n}\n[/block]\nIf you have Multiple Coupons Per Account enabled in Coupon Settings, you can have multiple active redemptions on an account. Call this redeem endpoint multiple times to redeem more than one coupon.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Maxed Out Error\"\n}\n[/block]\nIf a coupon can only be redeemed on an account a specific number of times and you have already redeemed the coupon that number of times on the account, you will see a maxed out error letting you know the coupon can no longer be redeemed on the account.\n\n```\n<errors>\n    <error field=\"coupon.base\" symbol=\"maxed_out_for_account\">Coupon has reached max redemptions for this account</error>\n</errors>\n```\n\n The only way you would be able to redeem this coupon again on the account would be to update the main coupon campaign to allow more redemptions per account.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Subscription-Level Redemption\"\n}\n[/block]\nIf the coupon is subscription-level, meaning it has a redemption_resource of \"subscription\", you must specify the subscription_uuid of an existing subscription on the account that you want to tie the redemption to. Otherwise you will get this error:\n\n```\n<errors>\n    <error field=\"coupon.subscription\" symbol=\"must_be_present\">must be redeemed on a subscription</error>\n</errors>\n```\n\nIf the subscription_uuid you provide is for a subscription with a plan not eligible for the coupon, you will see this error:\n\n```\n<errors>\n    <error field=\"coupon.subscription_uuid\" symbol=\"not_valid_for_redemption\">not valid for this coupon</error>\n</errors>\n```","category":"57803084827bd50e006b0460","excerpt":"Redeem a coupon on an existing customer's account to apply to their next invoice.","type":"post","updates":[],"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postRedeem a Coupon on an Account

Redeem a coupon on an existing customer's account to apply to their next invoice.

Path Params

coupon_code:
required
string
Unique code to identify and redeem the coupon.

Body Params

account_code:
required
integer
Account code to apply redemption
currency:
required
string
Currency for the redemption.
subscription_uuid:
string
If the coupon has a `redemption_resource` of `subscription`, you will need to specify the uuid of an existing subscription on the account, which you want to tie the redemption to.

If you want the coupon redemption to be rejected if a subscription signup fails, you must redeem the coupon within the Create Subscription call, not in the Redeem on Account call.

Redeeming Multiple Coupons

If you have Multiple Coupons Per Account enabled in Coupon Settings, you can have multiple active redemptions on an account. Call this redeem endpoint multiple times to redeem more than one coupon.

Maxed Out Error

If a coupon can only be redeemed on an account a specific number of times and you have already redeemed the coupon that number of times on the account, you will see a maxed out error letting you know the coupon can no longer be redeemed on the account.

<errors>
    <error field="coupon.base" symbol="maxed_out_for_account">Coupon has reached max redemptions for this account</error>
</errors>

The only way you would be able to redeem this coupon again on the account would be to update the main coupon campaign to allow more redemptions per account.

Subscription-Level Redemption

If the coupon is subscription-level, meaning it has a redemption_resource of "subscription", you must specify the subscription_uuid of an existing subscription on the account that you want to tie the redemption to. Otherwise you will get this error:

<errors>
    <error field="coupon.subscription" symbol="must_be_present">must be redeemed on a subscription</error>
</errors>

If the subscription_uuid you provide is for a subscription with a plan not eligible for the coupon, you will see this error:

<errors>
    <error field="coupon.subscription_uuid" symbol="not_valid_for_redemption">not valid for this coupon</error>
</errors>

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

$coupon = Recurly_Coupon::get('special');
$redemption = $coupon->redeemCoupon('1', 'USD');
account = Recurly::Account.find('1')
coupon = Recurly::Coupon.find('special')
redemption = coupon.redeem(account)
coupon = Coupon.get('special')
redemption = Redemption(account_code='1', currency='USD')

# new redemption object returned from this method will contain the updates
# so we overwrite the redemption variable
redemption = coupon.redeem(redemption)
var account = Accounts.Get("1");
var redemption = account.RedeemCoupon("special", "USD");
<redemption>
  <account_code>1</account_code>
  <currency>USD</currency>
</redemption>

Result Format

<redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemptions/374a1c75374bd81493a3f7425db0a2b8">
  <coupon href="https://your-subdomain.recurly.com/v2/coupons/special" />
  <account href="https://your-subdomain.recurly.com/v2/accounts/1" />
  <uuid>374a1c75374bd81493a3f7425db0a2b8</uuid>
  <single_use type="boolean">true</single_use>
  <total_discounted_in_cents type="integer">0</total_discounted_in_cents>
  <currency>USD</currency>
  <state>active</state>
  <coupon_code>special</coupon_code>
  <created_at type="datetime">2016-07-11T18:56:20Z</created_at>
  <updated_at type="datetime">2016-07-11T18:56:20Z</updated_at>
</redemption>
<error>
    <symbol>not_found</symbol>
    <description lang="en-US">Couldn't find Coupon with coupon_code = savemore</description>
</error>


{"_id":"57803085827bd50e006b04c2","category":"57803084827bd50e006b0460","hidden":false,"type":"delete","updates":[],"version":"57803084827bd50e006b0457","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\n$redemption = Recurly_CouponRedemption::get('account_code');\n$redemption->delete();","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\nredemption = account.redemption\nredemption.destroy"},{"language":"python","code":"account = Account.get('1')\nredemption = account.redemption()\nredemption.delete()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar redemption = account.GetActiveRedemption();\nredemption.Delete();"}]},"method":"delete","params":[{"type":"string","name":"account_code","_id":"578d067f84f5cd0e0089168e","ref":"","in":"path","required":true,"desc":"Unique account identifier.","default":""},{"desc":"Unique code to identify and redeem the coupon.","default":"","type":"string","name":"coupon_ocde","_id":"578d067f84f5cd0e0089168d","ref":"","in":"path","required":true}],"results":{"codes":[{"code":"Status: 204 No Content","language":"xml","status":204}]},"settings":"","url":"/accounts/:account_code/redemptions/:uuid","apiSetting":"59497f16b9248d0024fe3f31"},"createdAt":"2015-06-17T23:48:14.667Z","excerpt":"Manually expire a coupon redemption on an account. Please note: the coupon redemption will still count towards the \"maximum redemption total\" of the coupon.","githubsync":"","link_url":"","parentDoc":null,"project":"555fbba928249c1900618a82","user":"5581f6648625220d00429ef6","slug":"remove-a-coupon-from-an-account","sync_unique":"","title":"Remove a Coupon Redemption from an Account","__v":2,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Specify the specific redemption uuid if you are allowing multiple active coupon redemptions on an account at a time. Otherwise, you can do a simple /redemption and automatically remove the most recent redemption on the account.\"\n}\n[/block]","isReference":true,"link_external":false,"order":4,"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

deleteRemove a Coupon Redemption from an Account

Manually expire a coupon redemption on an account. Please note: the coupon redemption will still count towards the "maximum redemption total" of the coupon.

Path Params

account_code:
required
string
Unique account identifier.
coupon_ocde:
required
string
Unique code to identify and redeem the coupon.

Specify the specific redemption uuid if you are allowing multiple active coupon redemptions on an account at a time. Otherwise, you can do a simple /redemption and automatically remove the most recent redemption on the account.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

$redemption = Recurly_CouponRedemption::get('account_code');
$redemption->delete();
account = Recurly::Account.find('1')
redemption = account.redemption
redemption.destroy
account = Account.get('1')
redemption = account.redemption()
redemption.delete()
var account = Accounts.Get("1");
var redemption = account.GetActiveRedemption();
redemption.Delete();

Result Format

Status: 204 No Content


{"_id":"57803085827bd50e006b04cf","excerpt":"Returns a list of all invoices.","hidden":false,"type":"get","user":"5581f6648625220d00429ef6","body":"**INVOICE STATES**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"State\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"Open, pending collection\",\n    \"0-0\": \"`open`\",\n    \"null-0\": \"`\",\n    \"1-0\": \"`collected`\",\n    \"1-1\": \"Collection completed successfully\",\n    \"2-0\": \"`failed`\",\n    \"2-1\": \"Failed to collect\",\n    \"3-0\": \"`past_due`\",\n    \"3-1\": \"Initial collection failed, still attempting collection\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Please note: an invoice will only be in one state.\"\n}\n[/block]","githubsync":"","isReference":true,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"list-invoices","version":"57803084827bd50e006b0457","createdAt":"2015-06-18T16:32:46.758Z","editedParams":true,"editedParams2":true,"title":"List Invoices","__v":1,"api":{"auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n\n$invoices = Recurly_InvoiceList::get();\nforeach ($invoices as $invoice) {\n  print \"Invoice: $invoice\\n\";\n}","name":""},{"code":"Recurly::Invoice.find_each do |invoice|\n  puts \"Invoice: #{invoice.inspect}\"\nend","language":"ruby"},{"code":"#client version 2.1.6+\nfor invoice in Invoice.all():\n    print 'Invoice: %s' % invoice\n\n#client version <= 2.1.5\ninvoices = Invoice.all()\nwhile invoices:\n    for invoice in invoices:\n        print 'Invoice: %s' % invoice\n    try:\n        invoices = invoices.next_page()\n    except PageError:\n        invoices = ()\n# ...or...\npast_due = Invoice.all_past_due()","language":"python"},{"code":"using System.Linq;\n\nvar invoices = Invoices.List();\nwhile (invoices.Any())\n{\n\tforeach (var invoice in invoices)\n\t\tConsole.WriteLine(\"Invoice: \" + invoice);\n\tinvoices = invoices.Next;\n}","language":"csharp"}]},"method":"get","params":[{"default":"all","desc":"The state of invoices to return: `open`, `collected`, `failed`, or `past_due`.","in":"query","name":"state","ref":"","required":false,"type":"string","_id":"5582f2ae81672a3900bb4fe3"},{"required":false,"type":"string","in":"query","_id":"5582f2ae81672a3900bb4fe2","default":"","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.","name":"cursor","ref":""},{"required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page","in":"query","_id":"5582f2ae81672a3900bb4fe1","ref":""}],"results":{"codes":[{"status":200,"language":"xml","code":"<invoices type=\"array\">\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1005\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <address>\n        <address1>400 Alabama St.</address1>\n        <address2></address2>\n        <city>San Francisco</city>\n        <state>CA</state>\n        <zip>94110</zip>\n        <country>US</country>\n        <phone></phone>\n    </address>\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n    <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n    <state>open</state>\n    <invoice_number_prefix></invoice_number_prefix> <!-- Only populated for VAT Country Invoice Sequencing. Shows a country code. -->\n    <invoice_number type=\"integer\">1005</invoice_number>\n    <po_number nil=\"nil\"></po_number>\n    <vat_number nil=\"nil\"></vat_number>\n    <subtotal_in_cents type=\"integer\">1200</subtotal_in_cents>\n    <tax_in_cents type=\"integer\">0</tax_in_cents>\n    <total_in_cents type=\"integer\">1200</total_in_cents>\n    <currency>USD</currency>\n    <created_at type=\"datetime\">2016-06-25T12:00:00Z</created_at>\n    <closed_at nil=\"nil\"></closed_at>\n    <terms_and_conditions></terms_and_conditions>\n    <customer_notes></customer_notes>\n    <vat_reverse_charge_notes></vat_reverse_charge_notes> <!-- Only shows if reverse charge invoice -->\n    <tax_type>usst</tax_type> <!-- Only shows if tax on invoice -->\n\t\t<tax_region>CA</tax_region> <!-- Only shows if tax on invoice -->\n    <tax_rate type=\"float\">0</tax_rate> <!-- Only shows if tax on invoice -->\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/invoices/e3f0a9e084a2468480d00ee61b090d4d/redemptions\"/>\n    <line_items type=\"array\">\n      <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/05a4bbdeda2a47348185270021e6087b\">\n        <!-- Detail. -->\n      </adjustment>\n    </line_items>\n    <transactions type=\"array\">\n    </transactions>\n  </invoice>\n  <!-- Continued... -->\n</invoices>","name":""}]},"settings":"","url":"/invoices","apiSetting":"59497f16b9248d0024fe3f31"},"category":"57803084827bd50e006b0461","parentDoc":null,"sync_unique":"","updates":["55b1055eb2405537003cd938"],"next":{"pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getList Invoices

Returns a list of all invoices.

Query Params

state:
stringall
The state of invoices to return: `open`, `collected`, `failed`, or `past_due`.
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.
per_page:
integer50
Number of records to return per page, up to a maximum of 200.

INVOICE STATES

State
Description

open

Open, pending collection

collected

Collection completed successfully

failed

Failed to collect

past_due

Initial collection failed, still attempting collection

Please note: an invoice will only be in one state.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

$invoices = Recurly_InvoiceList::get();
foreach ($invoices as $invoice) {
  print "Invoice: $invoice\n";
}
Recurly::Invoice.find_each do |invoice|
  puts "Invoice: #{invoice.inspect