{"_id":"5dd5f0b02d076f0220ca8c21","category":"5dd5f0b02d076f0220ca8b92","user":"5564a0073a61a72f0067cb22","project":"555fbba928249c1900618a82","parentDoc":null,"version":"5dd5f0b02d076f0220ca8c44","updates":["5595c7e9f44370190028891c","562aa244ed4bea0d00c11d8b","56bb4e10dabd992100b674f7","56f19a949791b22d0077ba0f"],"next":{"pages":[],"description":""},"createdAt":"2015-06-10T22:06:37.745Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"language":"json","status":200,"name":"","code":"{}"},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"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.22' \\\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.22\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.2](https://dev.recurly.com/v2.2/docs)**, **[2.3](https://dev.recurly.com/v2.3/docs)**, **[2.4](https://dev.recurly.com/v2.4/docs)**, **[2.5](https://dev.recurly.com/v2.5/docs)**, **[2.6](https://dev.recurly.com/v2.6/docs)**, **[2.7](https://dev.recurly.com/v2.7/docs)**, **[2.8](https://dev.recurly.com/v2.8/docs)**, **[2.9](https://dev.recurly.com/v2.9/docs)**, **[2.10](https://dev.recurly.com/v2.10/docs)**, **[2.11](https://dev.recurly.com/v2.11/docs)**, **[2.12](https://dev.recurly.com/v2.12/docs)**, **[2.13](https://dev.recurly.com/v2.13/docs)**, **[2.14](https://dev.recurly.com/v2.14/docs)**, **[2.15](https://dev.recurly.com/v2.15/docs)**, **[2.16](https://dev.recurly.com/v2.16/docs)**, **[2.17](https://dev.recurly.com/v2.17/docs)**, **[2.18](https://dev.recurly.com/v2.18/docs)**, **[2.19](https://dev.recurly.com/v2.19/docs)**, **[2.20](https://dev.recurly.com/v2.20/docs)**, **[2.21](https://dev.recurly.com/v2.21/docs)**,**[2.22](https://dev.recurly.com/v2.22/docs)**\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Public API Key\"\n}\n[/block]\nRecurly uses two types of API keys: public and private. The Public API key is used by [Recurly.js](doc:recurlyjs) to identify its requests as belonging to your Recurly site. This key can be safely included in Javascript code.\n\nRecurly provides each site with one Public Key. The Public API Key can be regenerated on the [API Credentials](https://app.recurly.com/go/developer/api_access) page.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Private API Keys\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Treat your Private API Keys like passwords!\",\n  \"body\": \"The API key allows access to your site's data. Do not include it in Javascript code exposed to browsers.\"\n}\n[/block]\nRecurly supports the use of multiple Private API keys, which can be used to integrate third party services using unique, controlled credentials.\n\n## Limits & Pricing\nMerchants on the Core or grandfathered Recurly plans or merchants in sandbox mode will be granted 5 private API keys. Merchants on Recurly’s Professional plan will be granted 10 private API keys.\n\n## Default Key\nYour default private API key should be used to integrate Recurly with your backend systems. There will be at least one key active at all times.\n\n## Additional Keys\nAdditional private API keys should be used to connect your Recurly data to additional sources, like analytics software, accounting packages, or email tools. Recurly recommends clearly labeling the name of each key to identify the associated vendor.\n\n## Regenerating Private API Keys\nYour API key can be regenerated by clicking on the Regenerate button on the [API credentials](https://app.recurly.com/go/developer/api_access) page. When you generate a private API key, you have two options:\n\n1. Block the old key immediately. This is primarily recommended when the security of a key has been compromised.\n2. Allow the old key access for 12 hours. This is primarily used when updating systems and a smooth transition between keys is needed.\n\n*If a private API key is changed, an email alert will be sent to your Recurly Site Technical Contact.*\n\n## Read-Only Keys\nWhen creating a private key, you will have the option to set the key to “read-only”. This means the API key may make GET requests but cannot not PUT, POST or DELETE requests.","excerpt":"","slug":"getting-started","type":"basic","title":"Authentication","__v":0,"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.22' \
     -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.22

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

Acceptable API versions

Recurly supports the following API versions: 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10, 2.11, 2.12, 2.13, 2.14, 2.15, 2.16, 2.17, 2.18, 2.19, 2.20, 2.21,2.22

Public API Key

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

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

Private API Keys

Treat your Private API Keys like passwords!

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

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

Limits & Pricing

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

Default Key

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

Additional Keys

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

Regenerating Private API Keys

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

  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 134 endpoints
{"_id":"5dd5f0b02d076f0220ca8c22","category":"5dd5f0b02d076f0220ca8b92","user":"559d85d26b21311700fb0b7b","parentDoc":null,"project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-18T22:26:12.882Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"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.22](https://dev.recurly.com/v2.22/docs),[2.21](https://dev.recurly.com/v2.21/docs), [2.20](https://dev.recurly.com/v2.20/docs), [2.19](https://dev.recurly.com/v2.19/docs), [2.18](https://dev.recurly.com/v2.18/docs), [2.17](https://dev.recurly.com/v2.17/docs), [2.16](https://dev.recurly.com/v2.16/docs), [2.15](https://dev.recurly.com/v2.15/docs), [2.14](https://dev.recurly.com/v2.14/docs), [2.13](https://dev.recurly.com/v2.13/docs), [2.12](https://dev.recurly.com/v2.12/docs), \n[2.11](https://dev.recurly.com/v2.11/docs), [2.10](https://dev.recurly.com/v2.10/docs), [2.9](https://dev.recurly.com/v2.9/docs), [2.8](https://dev.recurly.com/v2.8/docs),  [2.7](https://dev.recurly.com/v2.7/docs), [2.6](https://dev.recurly.com/v2.6/docs), [2.5](https://dev.recurly.com/v2.5/docs), [2.4](https://dev.recurly.com/v2.4/docs), [2.3](https://dev.recurly.com/v2.3/docs), [2.2](https://dev.recurly.com/v2.2/docs).\n\n## Requesting A Version\n\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"API Version Deprecation\",\n  \"body\": \"As a matter of policy, API versions are deprecated two years after the date that the subsequent version is released ( rounded to the nearest month) and they are retired six months after the deprecation date.\\n\\nAPI versions 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, and 2.6 will be deprecated on July 1st, 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 January 1, 2020. 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 support@recurly.com if you have any questions with this documentation.\"\n}\n[/block]\nWhen making requests to Recurly, your request should specify the desired API version using the `X-Api-Version` header:\n```\nX-Api-Version: 2.22\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.22\n\nRequest and Response changes:\n  - Changed Billing Info request format:\n    - Added optional `<transaction_type>` tag.\n      - description: Indicates type of resulting transaction\n      - type: string(enum), accepted_values: \"moto\"\n  - Changed Account request format:\n    - Added optional `<transaction_type>` tag.\n      - description: Indicates type of resulting transaction\n      - type: string(enum), accepted_values: \"moto\"\n  - Changed Subscription request format:\n    - Added optional `<transaction_type>` tag.\n      - description: Indicates type of resulting transaction\n      - type: string(enum), accepted_values: \"moto\"\n  - Changed Subscription Change request format:\n    - Added optional `<transaction_type>` tag.\n      - description: Indicates type of resulting transaction\n      - type: string(enum), accepted_values: \"moto\"\n  - Changed Purchase request format:\n    - Added optional `<transaction_type>` tag.\n      - description: Indicates type of resulting transaction\n      - type: string(enum), accepted_values: \"moto\"\n  - Changed Invoice collect request format:\n    - Added optional `<transaction_type>` tag.\n      - description: Indicates type of resulting transaction\n      - type: string(enum), accepted_values: \"moto\"","excerpt":"","slug":"versioning","type":"basic","title":"API Versioning","__v":0,"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.22,2.21, 2.20, 2.19, 2.18, 2.17, 2.16, 2.15, 2.14, 2.13, 2.12,
2.11, 2.10, 2.9, 2.8, 2.7, 2.6, 2.5, 2.4, 2.3, 2.2.

Requesting A Version

API Version Deprecation

As a matter of policy, API versions are deprecated two years after the date that the subsequent version is released ( rounded to the nearest month) and they are retired six months after the deprecation date.

API versions 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, and 2.6 will be deprecated on July 1st, 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 January 1, 2020. 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 support@recurly.com 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.22

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

Request and Response changes:

  • Changed Billing Info request format:
    • Added optional <transaction_type> tag.
      • description: Indicates type of resulting transaction
      • type: string(enum), accepted_values: "moto"
  • Changed Account request format:
    • Added optional <transaction_type> tag.
      • description: Indicates type of resulting transaction
      • type: string(enum), accepted_values: "moto"
  • Changed Subscription request format:
    • Added optional <transaction_type> tag.
      • description: Indicates type of resulting transaction
      • type: string(enum), accepted_values: "moto"
  • Changed Subscription Change request format:
    • Added optional <transaction_type> tag.
      • description: Indicates type of resulting transaction
      • type: string(enum), accepted_values: "moto"
  • Changed Purchase request format:
    • Added optional <transaction_type> tag.
      • description: Indicates type of resulting transaction
      • type: string(enum), accepted_values: "moto"
  • Changed Invoice collect request format:
    • Added optional <transaction_type> tag.
      • description: Indicates type of resulting transaction
      • type: string(enum), accepted_values: "moto"
{"_id":"5dd5f0b02d076f0220ca8c23","category":"5dd5f0b02d076f0220ca8b92","parentDoc":null,"project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-15T22:48:39.567Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"language":"json","status":400,"name":"","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Next Link\"\n}\n[/block]\nThe amount of records returned 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 \nLink: <https://your-subdomain.recurly.com/v2/accounts?cursor=1972702718353176814%3A1465932489>; rel=\"next\" \nETag: \"a4b0568a2278bc591ceb64b31547eb78\" \n```\n\nThe `cursor` parameter is a time-based pointer indicating where to resume the results. By using a cursor instead of page numbers, the API avoids returning duplicate records in the case where additional resources are added between pagination requests.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sorting and Filtering\"\n}\n[/block]\n Many endpoints support these advanced pagination parameters:\n\n* `sort` : String: The attribute that will be used to order records: `created_at`, `updated_at`. Defaults to `created_at`.\n* `order` : String : The order in which products will be returned: `asc` for ascending order, `desc` for descending order. Defaults to `desc`.\n* `begin_time` : Datetime : Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.\n* `end_time` : Datetime : Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.\n\nReview the parameters on each endpoint for more details.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"An account that was updated on `2016-01-19` and then again on `2016-03-23` would not be returned in a request for `sort=updated_at&end_time=2016-03-01`.\",\n  \"title\": \"Updated at really means last updated at\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Counting Records\"\n}\n[/block]\nStarting with API version 2.6, you must explicitly make a `HEAD` request to get the server count. Endpoints that return a list of resources will respond to this request and include a header indicating the total number of records available. They will not contain the xml body. The server count is specified with the `X-Records` header. E.g., for an endpoint with 14 records:\n\n```\nX-Records: 14\n```\n\nYou can pass filtering parameters (described above) to narrow down the resources you wish to count. Consider the example of counting all `collected` invoices in `2016`. You can send a `HEAD` request to this endpoint then parse the count from the X-Records response header:\n\n```\nhttps://your-subdomain.recurly.com/v2/invoices?begin_time=2016-01-01T00:00:00&end_time=2017-01-01T00:00:00&state=collected\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\nThis will return accounts that were created on or before 2016-01-01 0:00 UTC in descending order of creation date:\n```\nhttps://your-subdomain.recurly.com/v2/accounts?sort=created_at&order=desc&end_time=2016-01-01\n```\n\nThis will return accounts that were last updated on or after 2016-07-01 10:30:01 Mountain Daylight Time in ascending order of updated date:\n\n```\nhttps://your-subdomain.recurly.com/v2/accounts?sort=updated_at&order=asc&begin_time=2016-07-01T10:30:01-06:00\n```\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"It's important to be aware that when paging through records sorted by their `updated_at` value, the order will change if they are modified:\\n* In ascending order, changes to records in previous pages will cause them to move back the end of the list, meaning you may see them multiple times. This can be avoided by using the time the pagination starts as the `end_time`.\\n* In descending order, changes to records in later pages will cause them to move up to the beginning of the list, meaning you would miss results.\",\n  \"title\": \"Beware of changes to records when sorting by updated_at\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n// When accessing a sub resource with a many-to-one relation\\n// to the parent model, the attribute returns a Recurly_Stub.\\n// For example, take Account -> Invoices\\n\\n$account = Recurly_Account::get('my_account_code');\\n\\n// Calling ->invoices returns a Stub which allows lazily loading the list\\n$invoices = $account->invoices;\\n\\nprint $invoices;\\n// => <Recurly_Stub[invoices] href=https://api.recurly.com/v2/accounts/my_account_code/invoices>\\n\\n/**\\n * Prior to 2.5.0 calling ->get() would only return the first page\\n * of results. With 2.5.0 and later, all results will be returned.\\n */\\nforeach ($invoices->get() as $inv) {\\n   print $inv->invoice_number . \\\"\\\\n\\\";\\n}\\n\\n/**\\n * Creating a List object directly will also allow you to iterate\\n * through all pages\\n */\\n$invoices = Recurly_InvoiceList::getForAccount('my_account_code');\\n\\n// Prints all invoices on the account\\nforeach ($invoices as $inv) {\\n   print $inv->invoice_number . \\\"\\\\n\\\";\\n}\\n\",\n      \"language\": \"php\",\n      \"gist\": \"44632c432dce4f56a0fa\"\n    },\n    {\n      \"code\": \"# Pagination in the ruby client is done using\\n# the Recurly::Pager class.\\n\\n# You can also create a Pager directly from any resource\\nRecurly::Invoice.paginate.class\\n#=> Recurly::Resource::Pager\\n\\n# paginate optionally takes the sorting and filtering params\\n# if you want to specify them\\nopts = {\\n  begin_time: DateTime.new(2016,1,1),\\n  end_time: DateTime.new(2017,1,1),\\n  state: :collected,\\n  per_page: 10\\n}\\n\\n# find_each will fetch the pages for you\\n# until there are none left. It presents\\n# all the invoices on the server as a single enumerable\\nRecurly::Invoice.paginate(opts).find_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 do |invoice|\\n  puts invoice.invoice_number\\nend\\n\\n# 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\\naccount = Recurly::Account.find('my_account_code')\\n\\naccount.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      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"# When accessing a sub resource with a many-to-one relation\\n# to the parent model, the attribute returns a `relatiator` function.\\n# When called it returns a recurly.resource.Page.\\n# For example, take Account -> Invoices\\n\\naccount = recurly.Account.get('tester')\\n\\nprint account.invoices\\n# => <function relatitator at 0x1023628c0>\\n\\nprint account.invoices().__class__\\n# => <class 'recurly.resource.Page'>\\n\\n# To page through every invoice on the account\\nfor invoice in account.invoices():\\n    print invoice.invoice_number\\n\\n# You can also call the all() method on\\n# a resource to page through every resource\\n# on your site. For instance, to page through\\n# every invoice:\\nfor invoice in recurly.Invoice.all():\\n    print invoice.invoice_number\",\n      \"language\": \"python\",\n      \"name\": null\n    },\n    {\n      \"code\": \"using System.Linq;\\n\\nvar accounts = Accounts.List();\\nwhile (accounts.Any())\\n{\\n    foreach (var account in accounts)\\n        Console.WriteLine(account);\\n    accounts = accounts.Next;\\n}\",\n      \"language\": \"csharp\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The PHP `Recurly_Pager` class sets up an iterator across all the relevant records. It does not provide pagination functionality by default.\",\n  \"title\": \"PHP Pagination\"\n}\n[/block]","excerpt":"","slug":"pagination","type":"basic","title":"Pagination","__v":0,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Pagination


Next Link

The amount of records returned 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 
Link: <https://your-subdomain.recurly.com/v2/accounts?cursor=1972702718353176814%3A1465932489>; rel="next" 
ETag: "a4b0568a2278bc591ceb64b31547eb78"

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

Sorting and Filtering

Many endpoints support these advanced pagination parameters:

  • sort : String: The attribute that will be used to order records: created_at, updated_at. Defaults to created_at.
  • order : String : The order in which products will be returned: asc for ascending order, desc for descending order. Defaults to desc.
  • begin_time : Datetime : Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.
  • end_time : Datetime : Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.

Review the parameters on each endpoint for more details.

Updated at really means last updated at

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

Counting Records

Starting with API version 2.6, you must explicitly make a HEAD request to get the server count. Endpoints that return a list of resources will respond to this request and include a header indicating the total number of records available. They will not contain the xml body. The server count is specified with the X-Records header. E.g., for an endpoint with 14 records:

X-Records: 14

You can pass filtering parameters (described above) to narrow down the resources you wish to count. Consider the example of counting all collected invoices in 2016. You can send a HEAD request to this endpoint then parse the count from the X-Records response header:

https://your-subdomain.recurly.com/v2/invoices?begin_time=2016-01-01T00:00:00&end_time=2017-01-01T00:00:00&state=collected

Examples

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

https://your-subdomain.recurly.com/v2/accounts?sort=created_at&order=desc&end_time=2016-01-01

This will return accounts that were last updated on or after 2016-07-01 10:30:01 Mountain Daylight Time in ascending order of updated date:

https://your-subdomain.recurly.com/v2/accounts?sort=updated_at&order=asc&begin_time=2016-07-01T10:30:01-06:00

Beware of changes to records when sorting by updated_at

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

  • In ascending order, changes to records in previous pages will cause them to move back the end of the list, meaning you may see them multiple times. This can be avoided by using the time the pagination starts as the end_time.
  • In descending order, changes to records in later pages will cause them to move up to the beginning of the list, meaning you would miss results.
<?php
// When accessing a sub resource with a many-to-one relation
// to the parent model, the attribute returns a Recurly_Stub.
// For example, take Account -> Invoices

$account = Recurly_Account::get('my_account_code');

// Calling ->invoices returns a Stub which allows lazily loading the list
$invoices = $account->invoices;

print $invoices;
// => <Recurly_Stub[invoices] href=https://api.recurly.com/v2/accounts/my_account_code/invoices>

/**
 * Prior to 2.5.0 calling ->get() would only return the first page
 * of results. With 2.5.0 and later, all results will be returned.
 */
foreach ($invoices->get() as $inv) {
   print $inv->invoice_number . "\n";
}

/**
 * Creating a List object directly will also allow you to iterate
 * through all pages
 */
$invoices = Recurly_InvoiceList::getForAccount('my_account_code');

// Prints all invoices on the account
foreach ($invoices as $inv) {
   print $inv->invoice_number . "\n";
}
# Pagination in the ruby client is done using
# the Recurly::Pager class.

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

# paginate optionally takes the sorting and filtering params
# if you want to specify them
opts = {
  begin_time: DateTime.new(2016,1,1),
  end_time: DateTime.new(2017,1,1),
  state: :collected,
  per_page: 10
}

# find_each will fetch the pages for you
# until there are none left. It presents
# all the invoices on the server as a single enumerable
Recurly::Invoice.paginate(opts).find_each do |invoice|
  puts invoice.invoice_number
end

# You can also use #find_each directly on the resource
Recurly::Invoice.find_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 Recurly::Resource::Pager. 
# For example, take Account -> Invoices
account = Recurly::Account.find('my_account_code')

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
# 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
using System.Linq;

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

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

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

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

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":"5dd5f0b02d076f0220ca8c25","category":"5dd5f0b02d076f0220ca8b92","parentDoc":null,"user":"5564a0073a61a72f0067cb22","project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","updates":["56cd46e949abf10b0036a1e6","59b1583ffff23e00100d1937"],"next":{"pages":[],"description":""},"createdAt":"2015-06-10T22:06:26.211Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"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 either an array of the validation errors or a single error:\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```\n\n```\n<error>\n  <symbol>simultaneous_request</symbol>\n  <description>\n    A change for subscription 3cf89f0c3fcda0b15c50134f63856d4e is already in progress.\n  </description>\n</error>\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.","slug":"http-status-codes","type":"basic","title":"HTTP Status Codes","__v":0,"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 either an array of the validation errors or a single error:

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>
<error>
  <symbol>simultaneous_request</symbol>
  <description>
    A change for subscription 3cf89f0c3fcda0b15c50134f63856d4e is already in progress.
  </description>
</error>
{"_id":"5dd5f0b02d076f0220ca8c26","category":"5dd5f0b02d076f0220ca8b93","parentDoc":null,"user":"55648cf93b87582b003ab8b1","project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-26T18:21:30.595Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Recurly has a variety of integrations you should check out!\n\n[Webhooks API](https://dev.recurly.com/page/webhooks)\n\n[Customer Imports](https://dev.recurly.com/page/customer-imports)","excerpt":"","slug":"integrations","type":"basic","title":"Integrations","__v":0,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Integrations


Recurly has a variety of integrations you should check out!

Webhooks API

Customer Imports

{"_id":"5dd5f0b02d076f0220ca8be8","category":"5dd5f0b02d076f0220ca8b94","user":"55648cf93b87582b003ab8b1","project":"555fbba928249c1900618a82","parentDoc":null,"version":"5dd5f0b02d076f0220ca8c44","updates":["55940e20fd29b92300c262bf","55b2bfc0a74a380d00e290a6","55b2c0466862a10d00887adf","55bbb926a8400c2d00873f2a","565f689e413e06170093df6a","58d2b9a19c99c92f00646f8e","5977a75032f043002002f6d9","59b738dba50f750030f42a78","59ccac98e30e6c00300cef7d"],"next":{"pages":[],"description":""},"createdAt":"2015-06-26T18:25:56.960Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"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[GO](https://github.com/blacklightcms/recurly)\n[Node.js](https://github.com/ceejbot/recurring)\n[Elixir](https://github.com/bhelx/recurly-client-elixir)\n[Java](https://github.com/killbilling/recurly-java-library)","excerpt":"","slug":"client-libraries","type":"basic","title":"Client Libraries","__v":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:

GO
Node.js
Elixir
Java

{"_id":"5dd5f0b02d076f0220ca8bfb","category":"5dd5f0b02d076f0220ca8b95","parentDoc":null,"project":"555fbba928249c1900618a82","user":"5564a0073a61a72f0067cb22","version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-04T22:51:11.649Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"language":"json","status":400,"name":"","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"<img src=\"https://files.readme.io/kBrV8yRSzOKtvARQyP46_RecurlyJS_Logo-594.png\" alt=\"Recurly.js Logo\" width=\"300\">\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"**The documentation for Recurly.js has been moved to our new Developer Hub** [here](https://developers.recurly.com/pages/recurly-js.html)\"\n}\n[/block]\n<h3>Customize Your Checkout Process and Accept Payments Securely</h3>\n\nSecurely accept sensitive payment details within your checkout process with a fully customizable user experience. The Recurly.js JavaScript library secures your checkout forms. Create subscriptions, process one-time transactions, and update customer billing information worry-free.\n\n<h3>PCI Compliance through Hosted Fields</h3>\n\nRecurly provides transparent iframes that allow you to deliver a customized customer checkout experience, while ensuring you meet the latest PCI DSS SAQ A compliance requirements.","excerpt":"","slug":"recurlyjs","type":"basic","title":"Recurly.js Overview","__v":0,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Recurly.js Overview


Recurly.js Logo

The documentation for Recurly.js has been moved to our new Developer Hub here

Customize Your Checkout Process and Accept Payments Securely

Securely accept sensitive payment details within your checkout process with a fully customizable user experience. The Recurly.js JavaScript library secures your checkout forms. Create subscriptions, process one-time transactions, and update customer billing information worry-free.

PCI Compliance through Hosted Fields

Recurly provides transparent iframes that allow you to deliver a customized customer checkout experience, while ensuring you meet the latest PCI DSS SAQ A compliance requirements.

{"_id":"5dd5f0b02d076f0220ca8be5","category":"5dd5f0b02d076f0220ca8b96","project":"555fbba928249c1900618a82","user":"55957fd09b8d0a25005a7d30","parentDoc":null,"version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-16T20:47:47.026Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"method":"post","results":{"codes":[{"name":"","code":"<invoice_collection>\n  <charge_invoice>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions\"/>\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    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>\n    <state>paid</state>\n    <invoice_number_prefix/>\n    <invoice_number type=\"integer\">1007</invoice_number>\n    <po_number nil=\"nil\"/>\n    <vat_number nil=\"nil\"/>\n    <subtotal_in_cents type=\"integer\">2000</subtotal_in_cents>\n    <discount_in_cents type=\"integer\">0</discount_in_cents>\n    <due_on type=\"datetime\">2018-01-30T21:11:50Z</due_on>\n    <balance_in_cents type=\"integer\">0</balance_in_cents>\n    <type>charge</type>\n    <origin>purchase</origin>\n    <credit_invoices href=\"https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices\"/>\n    <refundable_total_in_cents type=\"integer\">2000</refundable_total_in_cents>\n    <credit_payments type=\"array\">\n    </credit_payments>\n    <tax_in_cents type=\"integer\">424</tax_in_cents>\n    <total_in_cents type=\"integer\">5274</total_in_cents>\n    <currency>EUR</currency>\n    <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n    <closed_at type=\"datetime\">2016-08-03T16:26:26Z</closed_at>\n    <terms_and_conditions nil=\"nil\"/>\n    <customer_notes nil=\"nil\"/>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.0875</tax_rate>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/redemptions\"/>\n    <line_items type=\"array\">\n      <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd\" type=\"charge\">\n        <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n        <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1007\"/>\n        <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41\"/>\n        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>\n        <state>invoiced</state>\n        <description>Setup fee: Gold plan</description>\n        <accounting_code nil=\"nil\"/>\n        <product_code>gold</product_code>\n        <origin>setup_fee</origin>\n        <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n        <quantity type=\"integer\">1</quantity>\n        <discount_in_cents type=\"integer\">0</discount_in_cents>\n        <tax_in_cents type=\"integer\">70</tax_in_cents>\n        <total_in_cents type=\"integer\">870</total_in_cents>\n        <currency>EUR</currency>\n        <taxable type=\"boolean\">false</taxable>\n        <tax_type>usst</tax_type>\n        <tax_region>CA</tax_region>\n        <tax_rate type=\"float\">0.0875</tax_rate>\n        <tax_exempt type=\"boolean\">false</tax_exempt>\n        <tax_code nil=\"nil\"/>\n        <shipping_address>\n          <first_name>Lon</first_name>\n          <last_name>Doner</last_name>\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          <nickname>home</nickname>\n        </shipping_address>\n        <start_date type=\"datetime\">2016-08-03T16:26:26Z</start_date>\n        <end_date nil=\"nil\"/>\n        <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n        <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n        <revenue_schedule_type>evenly</revenue_schedule_type>\n      </adjustment>\n      <!-- Continued... -->\n    </line_items>\n    <transactions type=\"array\">\n      <!-- Detail. -->\n    </transactions>\n    <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/invoices/1007/refund\" method=\"post\"/>\n  </charge_invoice>\n  <credit_invoices type=\"array\">\n  </credit_invoices>\n</invoice_collection>","language":"xml","status":200}]},"settings":"","examples":{"codes":[{"language":"xml","code":"<purchase>\n  <collection_method>automatic</collection_method>\n  <currency>USD</currency>\n  <customer_notes>Some notes for the customer.</customer_notes>\n  <terms_and_conditions>Our company terms and conditions.</terms_and_conditions>\n  <vat_reverse_charge_notes>Vat reverse charge notes.</vat_reverse_charge_notes>\n  <account>\n    <account_code>c442b36c-c64f-41d7-b8e1-9c04e7a6ff82</account_code>\n    <billing_info>\n      <address1>400 Alabama St</address1>\n      <city>San Francisco</city>\n      <country>US</country>\n      <first_name>Benjamin</first_name>\n      <last_name>Du Monde</last_name>\n      <month>12</month>\n      <number>4111-1111-1111-1111</number>\n      <state>CA</state>\n      <year>2019</year>\n      <zip>94110</zip>\n    </billing_info>\n  </account>\n  <adjustments>\n    <adjustment>\n      <product_code>4549449c-5870-4845-b672-1d07f15e87dd</product_code>\n      <quantity>1</quantity>\n      <revenue_schedule_type>at_invoice</revenue_schedule_type>\n      <unit_amount_in_cents>1000</unit_amount_in_cents>\n      <description>Description of this adjustment</description>\n    </adjustment>\n  </adjustments>\n  <subscriptions>\n    <subscription>\n      <plan_code>plan1</plan_code>\n    </subscription>\n  </subscriptions>\n  <shipping_fees>\n    <shipping_fee>\n      <shipping_method_code>fast_fast_fast</shipping_method_code>\n      <shipping_amount_in_cents>999</shipping_amount_in_cents>\n    </shipping_fee>\n  </shipping_fees>\n  <shipping_address>\n    <first_name>Lon</first_name>\n    <last_name>Doner</last_name>        \n    <address1>221B Baker St.</address1>\n    <city>London</city>\n    <state></state>\n    <zip>W1K 6AH</zip>\n    <country>GB</country>\n    <nickname>Home</nickname>\n  </shipping_address>\n  <coupon_codes>\n  \t<coupon_code>coupon1</coupon_code>\n    <coupon_code>coupon2</coupon_code>\n  </coupon_codes>\n  <gift_card>\n    <redemption_code>ABC1234</redemption_code>\n  </gift_card>\n</purchase>"},{"language":"php","code":"<?php\n\n$purchase = new Recurly_Purchase();\n$purchase->currency = 'USD';\n$purchase->collection_method = 'automatic';\n$purchase->account = new Recurly_Account();\n$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';\n$purchase->account->email = \"verena@example.com\";\n$purchase->account->first_name = \"Benjamin\";\n$purchase->account->last_name = \"Du Monde\";\n$purchase->account->address->phone = \"555-555-5555\";\n$purchase->account->address->address1 = \"123 Main St.\";\n$purchase->account->address->city = \"San Francisco\";\n$purchase->account->address->state = \"CA\";\n$purchase->account->address->zip = \"94110\";\n$purchase->account->address->country = \"US\";\n\n$billing_info = new Recurly_BillingInfo();\n$billing_info->number = '4111-1111-1111-1111';\n$billing_info->month = 12;\n$billing_info->year = 2019;\n$billing_info->verification_value = '123';\n$billing_info->address1 = '400 Alabama St';\n$billing_info->city = 'San Francisco';\n$billing_info->state = 'CA';\n$billing_info->country = 'US';\n$billing_info->zip = '94110';\n\n$purchase->account->billing_info = $billing_info;\n\n$shipping_address = new Recurly_ShippingAddress();\n$shipping_address->first_name = 'Lon';\n$shipping_address->last_name = 'Dorner';\n$shipping_address->address1 = '400 Dolores St';\n$shipping_address->city = 'San Francisco';\n$shipping_address->state = 'CA';\n$shipping_address->country = 'US';\n$shipping_address->zip = '94110';\n$shipping_address->nickname = 'Home';\n\n$purchase->account->shipping_addresses = array($shipping_address);\n\n$adjustment = new Recurly_Adjustment();\n$adjustment->unit_amount_in_cents = 1000;\n$adjustment->quantity = 1;\n\n$purchase->adjustments = array($adjustment);\n\n$subscription = new Recurly_Subscription();\n$subscription->plan_code = 'pp';\n\n$purchase->subscriptions = array($subscription);\n\n$shipping_fee = new Recurly_ShippingFee();\n$shipping_fee->shipping_method_code = 'fast_fast_fast';\n$shipping_fee->shipping_amount_in_cents = 999;\n\n$purchase->shipping_fees = array($shipping_fee);\n\n$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');\n\n$gift_card = new Recurly_GiftCard();\n$gift_card->redemption_code = \"FCJ7GEY4HO8WR16Q\";\n$purchase->gift_card = $gift_card;\n\n// Create an invoice collection\ntry {\n  $collection = Recurly_Purchase::invoice($purchase);\n} catch (Recurly_ValidationError $e) {\n  // You can get an idea why a purchase failed looking at these objects:\n  var_dump($e->errors->transaction_error);  // Recurly_TransactionError\n  var_dump($e->errors->transaction);   // Recurly_Transaction\n} \n","name":"PHP"},{"language":"ruby","code":"require 'securerandom'\n\npurchase = Recurly::Purchase.new({\n  currency: 'USD',\n  collection_method: :automatic,\n  account: {\n    account_code: SecureRandom.uuid,\n    billing_info: {\n      first_name: 'Benjamin',\n      last_name: 'Du Monde',\n      address1: '400 Alabama St',\n      city: 'San Francisco',\n      state: 'CA',\n      zip: '94110',\n      country: 'US',\n      number: '4111-1111-1111-1111',\n      month: 12,\n      year: 2019,\n    },\n    shipping_addresses: [\n      {\n        first_name: 'Lon',\n        last_name: 'Dorner',\n        address1: '400 Alabama St',\n        city: 'San Francisco',\n        state: 'CA',\n        zip: '94110',\n        country: 'US',\n        nickname: 'home',\n      }\n    ]\n  },\n  subscriptions: [\n    {\n      plan_code: \"gold\",\n    }\n  ],\n  adjustments: [\n    {product_code: SecureRandom.uuid, unit_amount_in_cents: 1_000, quantity: 1, revenue_schedule_type: :at_invoice},\n  ],\n  shipping_fees: [\n    {\n      shipping_method_code: 'fast_fast_fast',\n      shipping_amount_in_cents: '999'\n    }\n  ],\n  coupon_codes: [\n    \"COUPON123\",\n    \"COUPON345\",\n  ],\n  gift_card: {\n    redemption_code: \"BC3749AB38371F273\"\n  }\n})\n\nbegin\n  collection = Recurly::Purchase.invoice!(purchase)\n  puts collection.inspect\nrescue Recurly::Resource::Invalid => e\n  puts e.inspect\n  # Invalid data\nrescue Recurly::Transaction::Error => e\n  puts e.inspect\n  # Transaction error\n  # e.transaction\n  # e.transaction_error_code\nend\n","name":"Ruby"},{"language":"python","code":"purchase = recurly.Purchase(\n  currency = 'USD',\n  account = recurly.Account(\n    account_code = 'account-code-123',\n    billing_info = recurly.BillingInfo(\n        first_name = 'Benjamin',\n        last_name = 'DuMonde',\n        number = '4111-1111-1111-1111',\n        verification_value = '123',\n        month = 11,\n        year = 2020,\n        address1 = '123 Main St',\n        city = 'New Orleans',\n        state = 'LA',\n        zip = '70114',\n        country = 'US',\n    ),\n    shipping_addresses = [\n      recurly.ShippingAddress(\n          first_name = 'Lon',\n          last_name = 'Dorner',\n          address1 = '400 Alabama St',\n          city = 'San Francisco',\n          state = 'CA',\n          zip = '94110',\n          country = 'US',\n          nickname = 'home'\n      )\n    ]\n  ),\n  subscriptions = [\n      recurly.Subscription(plan_code = 'gold')\n  ],\n  adjustments = [\n      recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',\n                         quantity=1),\n      recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',\n                         quantity=2),\n  ],\n  shipping_fees = [\n    recurly.ShippingFee(\n      shipping_method_code = 'fast_fast_fast',\n      shipping_amount_in_cents = 999\n    )\n  ]\n)\n\ncollection = purchase.invoice()\nprint(collection)","name":"Python"},{"language":"csharp","code":"var accountCode = \"benjamin-du-monde\";\nvar currency = \"USD\";\nvar planCode = \"surveillance-pro\";\nvar couponCode = \"surveillance-podcast-promo\";\nvar giftCardRedemptionCode = \"8Z5VE6IRMWJDHU4P\";\n\n// We can create a purchase object from an account code or an Account object (first argument).\n// Use the Account object when you want create a new account. This works similar to Subscription.\nvar purchase = new Purchase(accountCode, currency);\n\nvar shipAddr = new ShippingAddress();\nshipAddr.Address1 = \"400 Alabama St\";\nshipAddr.City = \"San Francisco\";\nshipAddr.State = \"CA\";\nshipAddr.Country = \"US\";\nshipAddr.Zip = \"94110\";\nshipAddr.FirstName = \"Lon\";\nshipAddr.LastName = \"Dorner\";\nshipAddr.Nickname = \"home\";\npurchase.Account.ShippingAddresses.Add(shipAddr);\n\n// Add shipping fees\nvar shippingFee = new ShippingFee()\n{\n    ShippingMethodCode = \"fast_fast_fast\",\n    ShippingAmountInCents = 999\n};\npurchase.ShippingFees = new List<ShippingFee>();\npurchase.ShippingFees.Add(shippingFee);\n\n// Add multiple adjustments (optional if subscription[s] included)\npurchase.Adjustments.Add(new Adjustment(4000, \"HD Camera\", 5));\npurchase.Adjustments.Add(new Adjustment(1000, \"Motion Sensor\", 10));\n\n// Add multiple subscriptions (optional if adjustment[s] included)\npurchase.Subscriptions.Add(new Subscription(planCode));\n\n// Add multiple coupon codes the customer may have (optional)\npurchase.CouponCodes.Add(couponCode);\n\n// Redeem a gift card with this purchase if the customer has redemption code (optional)\npurchase.GiftCardRedemptionCode = giftCardRedemptionCode;\n\n// For manual invoicing\n// purchase.CollectionMethod = Invoice.Collection.Manual;\n// purchase.NetTerms = 30;\n\n// Executes the purchase and transactions\nvar collection = Purchase.Invoice(purchase);","name":"C#"}]},"auth":"required","params":[{"_id":"591b66df7d2cb40f00d471d6","ref":"","in":"body","required":true,"desc":"An account object. This can be an existing account or a new account. If using a new account and adding shipping addresses, the last shipping address in the list will apply to every subscription and adjustment in the purchase.","default":"","type":"object","name":"account"},{"_id":"591b66df7d2cb40f00d471d5","ref":"","in":"body","required":true,"desc":"This should be a list of Adjustment objects. Required if there are no subscriptions.","default":"","type":"array_object","name":"adjustments"},{"_id":"591b66df7d2cb40f00d471d4","ref":"","in":"body","required":false,"desc":"The collection method for the invoice (`automatic` or `manual`).","default":"","type":"string","name":"collection_method"},{"_id":"591b66df7d2cb40f00d471d3","ref":"","in":"body","required":true,"desc":"The 3 letter currency code for the adjustments.","default":"","type":"string","name":"currency"},{"_id":"591b66df7d2cb40f00d471d2","ref":"","in":"body","required":false,"desc":"A PO number for the resulting invoice. Manual invoicing must be enabled on your site to use po_number with this endpoint","default":"","type":"string","name":"po_number"},{"_id":"591b66df7d2cb40f00d471d1","ref":"","in":"body","required":false,"desc":"The net terms for the invoice","default":"","type":"int","name":"net_terms"},{"_id":"595575d48613d9002bc540c1","ref":"","in":"body","required":false,"desc":"A gift card with a redemption code to apply to this purchase","default":"","type":"object","name":"gift_card"},{"_id":"595575d48613d9002bc540c0","ref":"","in":"body","required":false,"desc":"A list of coupon codes to apply to this purchase","default":"","type":"array_string","name":"coupon_codes"},{"_id":"595575d48613d9002bc540bf","ref":"","in":"body","required":true,"desc":"A list of Subscriptions to invoice in this purchase. Required if there are no adjustments.","default":"","type":"array_object","name":"subscriptions"},{"_id":"59d696a76d3f930010332fd4","ref":"","in":"body","required":false,"desc":"Optional notes to show customer on the invoice. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.","default":"","type":"string","name":"customer_notes"},{"_id":"59d696a76d3f930010332fd3","ref":"","in":"body","required":false,"desc":"Optional terms and conditions to show customer on the invoice. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"terms_and_conditions"},{"_id":"59d696a76d3f930010332fd2","ref":"","in":"body","required":false,"desc":"Optional VAT reverse charge notes to show the customer on the invoice. Only appears if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"vat_reverse_charge_notes"},{"_id":"5abbd2c152432700129dca5a","ref":"","in":"body","required":false,"desc":"All subscriptions and adjustments on the purchase will use this shipping address unless they specify one of their own. Any subscriptions for which this address might apply will also use it in future renewals unless changed or removed. Cannot be used if a new shipping address is created at the account level.","default":"","type":"long","name":"shipping_address_id"},{"_id":"5bf59cdaa46f07003f486d47","ref":"","in":"body","required":false,"desc":"An alphanumeric code shown per gateway on your site's payment gateways page. Set this code to ensure that a given purchase targets a given gateway.","default":"","type":"string","name":"gateway_code"},{"_id":"5cd982fb6b52200039fcb1ae","ref":"","in":"body","required":false,"desc":"Array of `<shipping_fee>` objects, each containing a `shipping_method_code` and a `shipping_amount_in_cents`.","default":"","type":"array_object","name":"shipping_fees"},{"_id":"5d5c2262d0afe6011e55b3eb","ref":"","in":"body","required":false,"desc":"Indicates type of resulting transaction. accepted_values: \"moto\".","default":"","type":"string","name":"transaction_type"},{"_id":"5daf580d247eca03d9528ed8","ref":"","in":"body","required":false,"desc":"Add this single shipping address to the account and apply it to the purchase.","default":"","type":"object","name":"shipping_address"}],"url":"/purchases"},"isReference":true,"order":0,"body":"","excerpt":"A purchase is a checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type. If you plan to use a shipping address(es) for a purchase, please see https://docs.recurly.com/docs/shipping-address-per-line-item. For additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping","slug":"create-purchase","type":"post","title":"Create Purchase","__v":32,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate Purchase

A purchase is a checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type. If you plan to use a shipping address(es) for a purchase, please see https://docs.recurly.com/docs/shipping-address-per-line-item. For additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping

Body Params

account:
required
object
An account object. This can be an existing account or a new account. If using a new account and adding shipping addresses, the last shipping address in the list will apply to every subscription and adjustment in the purchase.
adjustments:
required
array of objects
This should be a list of Adjustment objects. Required if there are no subscriptions.
collection_method:
string
The collection method for the invoice (`automatic` or `manual`).
currency:
required
string
The 3 letter currency code for the adjustments.
po_number:
string
A PO number for the resulting invoice. Manual invoicing must be enabled on your site to use po_number with this endpoint
net_terms:
integer
The net terms for the invoice
gift_card:
object
A gift card with a redemption code to apply to this purchase
coupon_codes:
array of strings
A list of coupon codes to apply to this purchase
subscriptions:
required
array of objects
A list of Subscriptions to invoice in this purchase. Required if there are no adjustments.
customer_notes:
string
Optional notes to show customer on the invoice. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.
terms_and_conditions:
string
Optional terms and conditions to show customer on the invoice. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Custom notes will stay with a subscription on all renewals.
vat_reverse_charge_notes:
string
Optional VAT reverse charge notes to show the customer on the invoice. Only appears if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Custom notes will stay with a subscription on all renewals.
shipping_address_id:
long
All subscriptions and adjustments on the purchase will use this shipping address unless they specify one of their own. Any subscriptions for which this address might apply will also use it in future renewals unless changed or removed. Cannot be used if a new shipping address is created at the account level.
gateway_code:
string
An alphanumeric code shown per gateway on your site's payment gateways page. Set this code to ensure that a given purchase targets a given gateway.
shipping_fees:
array of objects
Array of `<shipping_fee>` objects, each containing a `shipping_method_code` and a `shipping_amount_in_cents`.
transaction_type:
string
Indicates type of resulting transaction. accepted_values: "moto".
shipping_address:
object
Add this single shipping address to the account and apply it to the purchase.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<purchase>
  <collection_method>automatic</collection_method>
  <currency>USD</currency>
  <customer_notes>Some notes for the customer.</customer_notes>
  <terms_and_conditions>Our company terms and conditions.</terms_and_conditions>
  <vat_reverse_charge_notes>Vat reverse charge notes.</vat_reverse_charge_notes>
  <account>
    <account_code>c442b36c-c64f-41d7-b8e1-9c04e7a6ff82</account_code>
    <billing_info>
      <address1>400 Alabama St</address1>
      <city>San Francisco</city>
      <country>US</country>
      <first_name>Benjamin</first_name>
      <last_name>Du Monde</last_name>
      <month>12</month>
      <number>4111-1111-1111-1111</number>
      <state>CA</state>
      <year>2019</year>
      <zip>94110</zip>
    </billing_info>
  </account>
  <adjustments>
    <adjustment>
      <product_code>4549449c-5870-4845-b672-1d07f15e87dd</product_code>
      <quantity>1</quantity>
      <revenue_schedule_type>at_invoice</revenue_schedule_type>
      <unit_amount_in_cents>1000</unit_amount_in_cents>
      <description>Description of this adjustment</description>
    </adjustment>
  </adjustments>
  <subscriptions>
    <subscription>
      <plan_code>plan1</plan_code>
    </subscription>
  </subscriptions>
  <shipping_fees>
    <shipping_fee>
      <shipping_method_code>fast_fast_fast</shipping_method_code>
      <shipping_amount_in_cents>999</shipping_amount_in_cents>
    </shipping_fee>
  </shipping_fees>
  <shipping_address>
    <first_name>Lon</first_name>
    <last_name>Doner</last_name>        
    <address1>221B Baker St.</address1>
    <city>London</city>
    <state></state>
    <zip>W1K 6AH</zip>
    <country>GB</country>
    <nickname>Home</nickname>
  </shipping_address>
  <coupon_codes>
  	<coupon_code>coupon1</coupon_code>
    <coupon_code>coupon2</coupon_code>
  </coupon_codes>
  <gift_card>
    <redemption_code>ABC1234</redemption_code>
  </gift_card>
</purchase>
<?php

$purchase = new Recurly_Purchase();
$purchase->currency = 'USD';
$purchase->collection_method = 'automatic';
$purchase->account = new Recurly_Account();
$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';
$purchase->account->email = "verena@example.com";
$purchase->account->first_name = "Benjamin";
$purchase->account->last_name = "Du Monde";
$purchase->account->address->phone = "555-555-5555";
$purchase->account->address->address1 = "123 Main St.";
$purchase->account->address->city = "San Francisco";
$purchase->account->address->state = "CA";
$purchase->account->address->zip = "94110";
$purchase->account->address->country = "US";

$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2019;
$billing_info->verification_value = '123';
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';

$purchase->account->billing_info = $billing_info;

$shipping_address = new Recurly_ShippingAddress();
$shipping_address->first_name = 'Lon';
$shipping_address->last_name = 'Dorner';
$shipping_address->address1 = '400 Dolores St';
$shipping_address->city = 'San Francisco';
$shipping_address->state = 'CA';
$shipping_address->country = 'US';
$shipping_address->zip = '94110';
$shipping_address->nickname = 'Home';

$purchase->account->shipping_addresses = array($shipping_address);

$adjustment = new Recurly_Adjustment();
$adjustment->unit_amount_in_cents = 1000;
$adjustment->quantity = 1;

$purchase->adjustments = array($adjustment);

$subscription = new Recurly_Subscription();
$subscription->plan_code = 'pp';

$purchase->subscriptions = array($subscription);

$shipping_fee = new Recurly_ShippingFee();
$shipping_fee->shipping_method_code = 'fast_fast_fast';
$shipping_fee->shipping_amount_in_cents = 999;

$purchase->shipping_fees = array($shipping_fee);

$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');

$gift_card = new Recurly_GiftCard();
$gift_card->redemption_code = "FCJ7GEY4HO8WR16Q";
$purchase->gift_card = $gift_card;

// Create an invoice collection
try {
  $collection = Recurly_Purchase::invoice($purchase);
} catch (Recurly_ValidationError $e) {
  // You can get an idea why a purchase failed looking at these objects:
  var_dump($e->errors->transaction_error);  // Recurly_TransactionError
  var_dump($e->errors->transaction);   // Recurly_Transaction
} 
require 'securerandom'

purchase = Recurly::Purchase.new({
  currency: 'USD',
  collection_method: :automatic,
  account: {
    account_code: SecureRandom.uuid,
    billing_info: {
      first_name: 'Benjamin',
      last_name: 'Du Monde',
      address1: '400 Alabama St',
      city: 'San Francisco',
      state: 'CA',
      zip: '94110',
      country: 'US',
      number: '4111-1111-1111-1111',
      month: 12,
      year: 2019,
    },
    shipping_addresses: [
      {
        first_name: 'Lon',
        last_name: 'Dorner',
        address1: '400 Alabama St',
        city: 'San Francisco',
        state: 'CA',
        zip: '94110',
        country: 'US',
        nickname: 'home',
      }
    ]
  },
  subscriptions: [
    {
      plan_code: "gold",
    }
  ],
  adjustments: [
    {product_code: SecureRandom.uuid, unit_amount_in_cents: 1_000, quantity: 1, revenue_schedule_type: :at_invoice},
  ],
  shipping_fees: [
    {
      shipping_method_code: 'fast_fast_fast',
      shipping_amount_in_cents: '999'
    }
  ],
  coupon_codes: [
    "COUPON123",
    "COUPON345",
  ],
  gift_card: {
    redemption_code: "BC3749AB38371F273"
  }
})

begin
  collection = Recurly::Purchase.invoice!(purchase)
  puts collection.inspect
rescue Recurly::Resource::Invalid => e
  puts e.inspect
  # Invalid data
rescue Recurly::Transaction::Error => e
  puts e.inspect
  # Transaction error
  # e.transaction
  # e.transaction_error_code
end
purchase = recurly.Purchase(
  currency = 'USD',
  account = recurly.Account(
    account_code = 'account-code-123',
    billing_info = recurly.BillingInfo(
        first_name = 'Benjamin',
        last_name = 'DuMonde',
        number = '4111-1111-1111-1111',
        verification_value = '123',
        month = 11,
        year = 2020,
        address1 = '123 Main St',
        city = 'New Orleans',
        state = 'LA',
        zip = '70114',
        country = 'US',
    ),
    shipping_addresses = [
      recurly.ShippingAddress(
          first_name = 'Lon',
          last_name = 'Dorner',
          address1 = '400 Alabama St',
          city = 'San Francisco',
          state = 'CA',
          zip = '94110',
          country = 'US',
          nickname = 'home'
      )
    ]
  ),
  subscriptions = [
      recurly.Subscription(plan_code = 'gold')
  ],
  adjustments = [
      recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',
                         quantity=1),
      recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',
                         quantity=2),
  ],
  shipping_fees = [
    recurly.ShippingFee(
      shipping_method_code = 'fast_fast_fast',
      shipping_amount_in_cents = 999
    )
  ]
)

collection = purchase.invoice()
print(collection)
var accountCode = "benjamin-du-monde";
var currency = "USD";
var planCode = "surveillance-pro";
var couponCode = "surveillance-podcast-promo";
var giftCardRedemptionCode = "8Z5VE6IRMWJDHU4P";

// We can create a purchase object from an account code or an Account object (first argument).
// Use the Account object when you want create a new account. This works similar to Subscription.
var purchase = new Purchase(accountCode, currency);

var shipAddr = new ShippingAddress();
shipAddr.Address1 = "400 Alabama St";
shipAddr.City = "San Francisco";
shipAddr.State = "CA";
shipAddr.Country = "US";
shipAddr.Zip = "94110";
shipAddr.FirstName = "Lon";
shipAddr.LastName = "Dorner";
shipAddr.Nickname = "home";
purchase.Account.ShippingAddresses.Add(shipAddr);

// Add shipping fees
var shippingFee = new ShippingFee()
{
    ShippingMethodCode = "fast_fast_fast",
    ShippingAmountInCents = 999
};
purchase.ShippingFees = new List<ShippingFee>();
purchase.ShippingFees.Add(shippingFee);

// Add multiple adjustments (optional if subscription[s] included)
purchase.Adjustments.Add(new Adjustment(4000, "HD Camera", 5));
purchase.Adjustments.Add(new Adjustment(1000, "Motion Sensor", 10));

// Add multiple subscriptions (optional if adjustment[s] included)
purchase.Subscriptions.Add(new Subscription(planCode));

// Add multiple coupon codes the customer may have (optional)
purchase.CouponCodes.Add(couponCode);

// Redeem a gift card with this purchase if the customer has redemption code (optional)
purchase.GiftCardRedemptionCode = giftCardRedemptionCode;

// For manual invoicing
// purchase.CollectionMethod = Invoice.Collection.Manual;
// purchase.NetTerms = 30;

// Executes the purchase and transactions
var collection = Purchase.Invoice(purchase);

Result Format

<invoice_collection>
  <charge_invoice>
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <subscriptions href="https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions"/>
    <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>
    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>
    <state>paid</state>
    <invoice_number_prefix/>
    <invoice_number type="integer">1007</invoice_number>
    <po_number nil="nil"/>
    <vat_number nil="nil"/>
    <subtotal_in_cents type="integer">2000</subtotal_in_cents>
    <discount_in_cents type="integer">0</discount_in_cents>
    <due_on type="datetime">2018-01-30T21:11:50Z</due_on>
    <balance_in_cents type="integer">0</balance_in_cents>
    <type>charge</type>
    <origin>purchase</origin>
    <credit_invoices href="https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices"/>
    <refundable_total_in_cents type="integer">2000</refundable_total_in_cents>
    <credit_payments type="array">
    </credit_payments>
    <tax_in_cents type="integer">424</tax_in_cents>
    <total_in_cents type="integer">5274</total_in_cents>
    <currency>EUR</currency>
    <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
    <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
    <closed_at type="datetime">2016-08-03T16:26:26Z</closed_at>
    <terms_and_conditions nil="nil"/>
    <customer_notes nil="nil"/>
    <tax_type>usst</tax_type>
    <tax_region>CA</tax_region>
    <tax_rate type="float">0.0875</tax_rate>
    <net_terms type="integer">0</net_terms>
    <collection_method>automatic</collection_method>
    <redemptions href="https://your-subdomain.recurly.com/v2/invoices/1007/redemptions"/>
    <line_items type="array">
      <adjustment href="https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd" type="charge">
        <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
        <invoice href="https://your-subdomain.recurly.com/v2/invoices/1007"/>
        <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41"/>
        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>
        <state>invoiced</state>
        <description>Setup fee: Gold plan</description>
        <accounting_code nil="nil"/>
        <product_code>gold</product_code>
        <origin>setup_fee</origin>
        <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
        <quantity type="integer">1</quantity>
        <discount_in_cents type="integer">0</discount_in_cents>
        <tax_in_cents type="integer">70</tax_in_cents>
        <total_in_cents type="integer">870</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"/>
        <shipping_address>
          <first_name>Lon</first_name>
          <last_name>Doner</last_name>
          <address1>400 Alabama St</address1>
          <address2></address2>
          <city>San Francisco</city>
          <state>CA</state>
          <zip>94110</zip>
          <country>US</country>
          <phone></phone>
          <nickname>home</nickname>
        </shipping_address>
        <start_date type="datetime">2016-08-03T16:26:26Z</start_date>
        <end_date nil="nil"/>
        <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
        <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
        <revenue_schedule_type>evenly</revenue_schedule_type>
      </adjustment>
      <!-- Continued... -->
    </line_items>
    <transactions type="array">
      <!-- Detail. -->
    </transactions>
    <a name="refund" href="https://your-subdomain.recurly.com/v2/invoices/1007/refund" method="post"/>
  </charge_invoice>
  <credit_invoices type="array">
  </credit_invoices>
</invoice_collection>


{"_id":"5dd5f0b02d076f0220ca8be6","category":"5dd5f0b02d076f0220ca8b96","user":"55957fd09b8d0a25005a7d30","project":"555fbba928249c1900618a82","parentDoc":null,"version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-17T16:39:29.580Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"<purchase>\n  <collection_method>automatic</collection_method>\n  <currency>USD</currency>\n  <customer_notes>Some notes for the customer.</customer_notes>\n  <terms_and_conditions>Our company terms and conditions.</terms_and_conditions>\n  <vat_reverse_charge_notes>Vat reverse charge notes.</vat_reverse_charge_notes>\n  <account>\n    <account_code>c442b36c-c64f-41d7-b8e1-9c04e7a6ff82</account_code>\n    <billing_info>\n      <address1>400 Alabama St</address1>\n      <city>San Francisco</city>\n      <country>US</country>\n      <first_name>Benjamin</first_name>\n      <last_name>Du Monde</last_name>\n      <month>12</month>\n      <number>4111-1111-1111-1111</number>\n      <state>CA</state>\n      <year>2019</year>\n      <zip>94110</zip>\n    </billing_info>\n  </account>\n  <adjustments>\n    <adjustment>\n      <product_code>4549449c-5870-4845-b672-1d07f15e87dd</product_code>\n      <quantity>1</quantity>\n      <revenue_schedule_type>at_invoice</revenue_schedule_type>\n      <unit_amount_in_cents>1000</unit_amount_in_cents>\n      <description>Description of this adjustment</description>\n    </adjustment>\n  </adjustments>\n  <subscriptions>\n    <subscription>\n      <plan_code>plan1</plan_code>\n    </subscription>\n  </subscriptions>\n  <shipping_fees>\n    <shipping_fee>\n      <shipping_method_code>fast_fast_fast</shipping_method_code>\n      <shipping_amount_in_cents>999</shipping_amount_in_cents>\n    </shipping_fee>\n  </shipping_fees>\n  <shipping_address>\n    <first_name>Lon</first_name>\n    <last_name>Doner</last_name>        \n    <address1>221B Baker St.</address1>\n    <city>London</city>\n    <state></state>\n    <zip>W1K 6AH</zip>\n    <country>GB</country>\n    <nickname>Home</nickname>\n  </shipping_address>\n  <coupon_codes>\n  \t<coupon_code>coupon1</coupon_code>\n    <coupon_code>coupon2</coupon_code>\n  </coupon_codes>\n  <gift_card>\n    <redemption_code>ABC1234</redemption_code>\n  </gift_card>\n</purchase>","language":"xml"},{"name":"PHP","code":"<?php\n\n$purchase = new Recurly_Purchase();\n$purchase->currency = 'USD';\n$purchase->collection_method = 'automatic';\n$purchase->account = new Recurly_Account();\n$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';\n$purchase->account->email = \"verena@example.com\";\n$purchase->account->first_name = \"Benjamin\";\n$purchase->account->last_name = \"Du Monde\";\n$purchase->account->address->phone = \"555-555-5555\";\n$purchase->account->address->address1 = \"123 Main St.\";\n$purchase->account->address->city = \"San Francisco\";\n$purchase->account->address->state = \"CA\";\n$purchase->account->address->zip = \"94110\";\n$purchase->account->address->country = \"US\";\n\n$billing_info = new Recurly_BillingInfo();\n$billing_info->number = '4111-1111-1111-1111';\n$billing_info->month = 12;\n$billing_info->year = 2019;\n$billing_info->verification_value = '123';\n$billing_info->address1 = '400 Alabama St';\n$billing_info->city = 'San Francisco';\n$billing_info->state = 'CA';\n$billing_info->country = 'US';\n$billing_info->zip = '94110';\n\n$purchase->account->billing_info = $billing_info;\n\n$shipping_address = new Recurly_ShippingAddress();\n$shipping_address->first_name = 'Lon';\n$shipping_address->last_name = 'Dorner';\n$shipping_address->address1 = '400 Dolores St';\n$shipping_address->city = 'San Francisco';\n$shipping_address->state = 'CA';\n$shipping_address->country = 'US';\n$shipping_address->zip = '94110';\n$shipping_address->nickname = 'Home';\n\n$purchase->account->shipping_addresses = array($shipping_address);\n\n$adjustment = new Recurly_Adjustment();\n$adjustment->unit_amount_in_cents = 1000;\n$adjustment->quantity = 1;\n\n$purchase->adjustments = array($adjustment);\n\n$subscription = new Recurly_Subscription();\n$subscription->plan_code = 'pp';\n\n$purchase->subscriptions = array($subscription);\n\n$shipping_fee = new Recurly_ShippingFee();\n$shipping_fee->shipping_method_code = 'fast_fast_fast';\n$shipping_fee->shipping_amount_in_cents = 999;\n\n$purchase->shipping_fees = array($shipping_fee);\n\n$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');\n\n$gift_card = new Recurly_GiftCard();\n$gift_card->redemption_code = \"FCJ7GEY4HO8WR16Q\";\n$purchase->gift_card = $gift_card;\n\n// Create a preview invoice collection\ntry {\n  $previewCollection = Recurly_Purchase::preview($purchase);\n} catch (Recurly_ValidationError $e) {\n  // You can get an idea why a purchase failed looking at these objects:\n  var_dump($e);\n} ","language":"php"},{"name":"Ruby","code":"require 'securerandom'\n\npurchase = Recurly::Purchase.new({\n  currency: 'USD',\n  collection_method: :automatic,\n  account: {\n    account_code: SecureRandom.uuid,\n    billing_info: {\n      first_name: 'Benjamin',\n      last_name: 'Du Monde',\n      address1: '400 Alabama St',\n      city: 'San Francisco',\n      state: 'CA',\n      zip: '94110',\n      country: 'US',\n      number: '4111-1111-1111-1111',\n      month: 12,\n      year: 2019,\n    },\n    shipping_addresses: [\n      {\n        first_name: 'Lon',\n        last_name: 'Dorner',\n        address1: '400 Alabama St',\n        city: 'San Francisco',\n        state: 'CA',\n        zip: '94110',\n        country: 'US',\n        nickname: 'home',\n      }\n    ]\n  },\n  subscriptions: [\n    {\n      plan_code: \"gold\",\n    }\n  ],\n  adjustments: [\n    {product_code: SecureRandom.uuid, unit_amount_in_cents: 1_000, quantity: 1, revenue_schedule_type: :at_invoice},\n  ],\n  shipping_fees: [\n    {\n      shipping_method_code: 'fast_fast_fast',\n      shipping_amount_in_cents: '999'\n    }\n  ],\n  coupon_codes: [\n    \"COUPON123\",\n    \"COUPON345\",\n  ],\n  gift_card: {\n    redemption_code: \"BC3749AB38371F273\"\n  }\n})\n\nbegin\n  preview_collection = Recurly::Purchase.preview!(purchase)\n  puts preview_collection.inspect\nrescue Recurly::Resource::Invalid => e\n  puts e.inspect\n  # Invalid data\nend","language":"ruby"},{"code":"purchase = recurly.Purchase(\n  currency = 'USD',\n  account = recurly.Account(\n    account_code = 'account-code-123',\n    billing_info = recurly.BillingInfo(\n        first_name = 'Benjamin',\n        last_name = 'DuMonde',\n        number = '4111-1111-1111-1111',\n        verification_value = '123',\n        month = 11,\n        year = 2020,\n        address1 = '123 Main St',\n        city = 'New Orleans',\n        state = 'LA',\n        zip = '70114',\n        country = 'US',\n    ),\n    shipping_addresses = [\n      recurly.ShippingAddress(\n          first_name = 'Lon',\n          last_name = 'Dorner',\n          address1 = '400 Alabama St',\n          city = 'San Francisco',\n          state = 'CA',\n          zip = '94110',\n          country = 'US',\n          nickname = 'home'\n      )\n    ]\n  ),\n  subscriptions = [\n      recurly.Subscription(plan_code = 'gold')\n  ],\n  adjustments = [\n      recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',\n                         quantity=1),\n      recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',\n                         quantity=2),\n  ],\n  shipping_fees = [\n    recurly.ShippingFee(\n      shipping_method_code = 'fast_fast_fast',\n      shipping_amount_in_cents = 999\n    )\n  ]\n)\n\npreview_collection = purchase.preview()\nprint(preview_collection)","language":"python"},{"code":"var accountCode = \"benjamin-du-monde\";\nvar currency = \"USD\";\nvar planCode = \"surveillance-pro\";\nvar couponCode = \"surveillance-podcast-promo\";\nvar giftCardRedemptionCode = \"8Z5VE6IRMWJDHU4P\";\n\n// We can create a purchase object from an account code or an Account object (first argument).\n// Use the Account object when you want create a new account. This works similar to Subscription.\nvar purchase = new Purchase(accountCode, currency);\n\nvar shipAddr = new ShippingAddress();\nshipAddr.Address1 = \"400 Alabama St\";\nshipAddr.City = \"San Francisco\";\nshipAddr.State = \"CA\";\nshipAddr.Country = \"US\";\nshipAddr.Zip = \"94110\";\nshipAddr.FirstName = \"Lon\";\nshipAddr.LastName = \"Dorner\";\nshipAddr.Nickname = \"home\";\npurchase.Account.ShippingAddresses.Add(shipAddr);\n\n// Add multiple adjustments (optional if subscription[s] included)\npurchase.Adjustments.Add(new Adjustment(4000, \"HD Camera\", 5));\npurchase.Adjustments.Add(new Adjustment(1000, \"Motion Sensor\", 10));\n\n// Add multiple subscriptions (optional if adjustment[s] included)\npurchase.Subscriptions.Add(new Subscription(planCode));\n\n// Add shipping fees\nvar shippingFee = new ShippingFee()\n{\n    ShippingMethodCode = \"fast_fast_fast\",\n    ShippingAmountInCents = 999\n};\npurchase.ShippingFees = new List<ShippingFee>();\npurchase.ShippingFees.Add(shippingFee);\n\n// Add multiple coupon codes the customer may have (optional)\npurchase.CouponCodes.Add(couponCode);\n\n// Redeem a gift card with this purchase if the customer has redemption code (optional)\npurchase.GiftCardRedemptionCode = giftCardRedemptionCode;\n\n// For manual invoicing\n// purchase.CollectionMethod = Invoice.Collection.Manual;\n// purchase.NetTerms = 30;\n\n// Previewing allows us to run all calculations and validations without running the\n// transactions yet. This allows us to check the information and show the customer\n// the the detailed invoices before they confirm the purchase.\nvar previewCollection = Purchase.Preview(purchase);","language":"csharp"}]},"method":"post","results":{"codes":[{"name":"","code":"<invoice_collection>\n  <charge_invoice>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions\"/>\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    <shipping_address>\n      <first_name>Lon</first_name>\n      <last_name>Doner</last_name>\n      <address1>221B Baker St.</address1>\n      <address2></address2>\n      <city>London</city>\n      <state></state>\n      <zip>W1K 6AH</zip>\n      <country>GB</country>\n      <phone></phone>\n    </shipping_address>\n    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>\n    <state>paid</state>\n    <invoice_number_prefix/>\n    <invoice_number type=\"integer\">1007</invoice_number>\n    <po_number nil=\"nil\"/>\n    <vat_number nil=\"nil\"/>\n    <subtotal_in_cents type=\"integer\">2000</subtotal_in_cents>\n    <discount_in_cents type=\"integer\">0</discount_in_cents>\n    <due_on type=\"datetime\">2018-01-30T21:11:50Z</due_on>\n    <balance_in_cents type=\"integer\">0</balance_in_cents>\n    <type>charge</type>\n    <origin>purchase</origin>\n    <credit_invoices href=\"https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices\"/>\n    <refundable_total_in_cents type=\"integer\">2000</refundable_total_in_cents>\n    <credit_payments type=\"array\">\n    </credit_payments>\n    <tax_in_cents type=\"integer\">424</tax_in_cents>\n    <total_in_cents type=\"integer\">5274</total_in_cents>\n    <currency>EUR</currency>\n    <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n    <closed_at type=\"datetime\">2016-08-03T16:26:26Z</closed_at>\n    <terms_and_conditions nil=\"nil\"/>\n    <customer_notes nil=\"nil\"/>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.0875</tax_rate>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/redemptions\"/>\n    <line_items type=\"array\">\n      <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd\" type=\"charge\">\n        <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n        <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1007\"/>\n        <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41\"/>\n        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>\n        <state>invoiced</state>\n        <description>Setup fee: Gold plan</description>\n        <accounting_code nil=\"nil\"/>\n        <product_code>gold</product_code>\n        <origin>setup_fee</origin>\n        <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n        <quantity type=\"integer\">1</quantity>\n        <discount_in_cents type=\"integer\">0</discount_in_cents>\n        <tax_in_cents type=\"integer\">70</tax_in_cents>\n        <total_in_cents type=\"integer\">870</total_in_cents>\n        <currency>EUR</currency>\n        <taxable type=\"boolean\">false</taxable>\n        <tax_type>usst</tax_type>\n        <tax_region>CA</tax_region>\n        <tax_rate type=\"float\">0.0875</tax_rate>\n        <tax_exempt type=\"boolean\">false</tax_exempt>\n        <tax_code nil=\"nil\"/>\n        <start_date type=\"datetime\">2016-08-03T16:26:26Z</start_date>\n        <end_date nil=\"nil\"/>\n        <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n        <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n        <revenue_schedule_type>evenly</revenue_schedule_type>\n      </adjustment>\n      <!-- Continued... -->\n    </line_items>\n    <transactions type=\"array\">\n      <!-- Detail. -->\n    </transactions>\n    <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/invoices/1007/refund\" method=\"post\"/>\n  </charge_invoice>\n  <credit_invoices type=\"array\">\n  </credit_invoices>\n</invoice_collection>","language":"xml","status":200}]},"settings":"","auth":"required","params":[{"_id":"591b66df7d2cb40f00d471d6","ref":"","in":"body","required":true,"desc":"An account object. This can be an existing account or a new account. If using a new account and adding shipping addresses, the last shipping address in the list will apply to every subscription and adjustment in the purchase.","default":"","type":"object","name":"account"},{"_id":"591b66df7d2cb40f00d471d5","ref":"","in":"body","required":true,"desc":"This should be a list of Adjustment objects. Required if there are no subscriptions.","default":"","type":"array_object","name":"adjustments"},{"_id":"591b66df7d2cb40f00d471d4","ref":"","in":"body","required":false,"desc":"The collection method for the invoice (`automatic` or `manual`).  Must be set to `manual` in order to preview a purchase for an Account that does not have payment information associated with the Billing Info.","default":"","type":"string","name":"collection_method"},{"_id":"591b66df7d2cb40f00d471d3","ref":"","in":"body","required":false,"desc":"The 3 letter currency code for the adjustments.","default":"","type":"string","name":"currency"},{"_id":"591b66df7d2cb40f00d471d2","ref":"","in":"body","required":false,"desc":"A po number for the resulting invoice.","default":"","type":"string","name":"po_number"},{"_id":"591b66df7d2cb40f00d471d1","ref":"","in":"body","required":false,"desc":"The net terms for the invoice","default":"","type":"int","name":"net_terms"},{"_id":"5955762bba6cff002966ae31","ref":"","in":"body","required":false,"desc":"A gift card with a redemption code to apply to this purchase","default":"","type":"object","name":"gift_card"},{"_id":"5955762bba6cff002966ae30","ref":"","in":"body","required":false,"desc":"A list of coupon codes to apply to this purchase","default":"","type":"array_string","name":"coupon_codes"},{"_id":"5955762bba6cff002966ae2f","ref":"","in":"body","required":true,"desc":"A list of Subscriptions to invoice in this purchase. Required if there are no adjustments.","default":"","type":"array_object","name":"subscriptions"},{"_id":"59d699316d3f930010333002","ref":"","in":"body","required":false,"desc":"Optional notes to show customer on the invoice. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.","default":"","type":"string","name":"customer_notes"},{"_id":"59d699316d3f930010333001","ref":"","in":"body","required":false,"desc":"Optional terms and conditions to show customer on the invoice. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"terms_and_conditions"},{"_id":"59d699316d3f930010333000","ref":"","in":"body","required":false,"desc":"Optional VAT reverse charge notes to show the customer on the invoice. Only appears if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"vat_reverse_charge_notes"},{"_id":"5abbd2e452432700129dca5b","ref":"","in":"body","required":false,"desc":"All subscriptions and adjustments on the purchase will use this shipping address unless they specify one of their own. Any subscriptions for which this address might apply will also use it in future renewals unless changed or removed. Cannot be used if a new shipping address is created at the account level.","default":"","type":"long","name":"shipping_address_id"},{"_id":"5ce43c6554f4b30206f43e11","ref":"","in":"body","required":false,"desc":"Array of `<shipping_fee>` objects, each containing a `shipping_method_code` and a `shipping_amount_in_cents`.","default":"","type":"array_object","name":"shipping_fees"},{"_id":"5daf5ac2a3b11905e3ad9baa","ref":"","in":"body","required":false,"desc":"Add this single shipping address to the account and apply it to the purchase.","default":"","type":"object","name":"shipping_address"}],"url":"/purchases/preview"},"isReference":true,"order":1,"body":"","excerpt":"A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type.\n\nPOSTing to the preview endpoint runs the validations and creates a preview invoice, but does not run the transactions.\n\nFor additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping","slug":"preview-purchase","type":"post","title":"Preview Purchase","__v":28,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postPreview Purchase

A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type. POSTing to the preview endpoint runs the validations and creates a preview invoice, but does not run the transactions. For additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping

Body Params

account:
required
object
An account object. This can be an existing account or a new account. If using a new account and adding shipping addresses, the last shipping address in the list will apply to every subscription and adjustment in the purchase.
adjustments:
required
array of objects
This should be a list of Adjustment objects. Required if there are no subscriptions.
collection_method:
string
The collection method for the invoice (`automatic` or `manual`). Must be set to `manual` in order to preview a purchase for an Account that does not have payment information associated with the Billing Info.
currency:
string
The 3 letter currency code for the adjustments.
po_number:
string
A po number for the resulting invoice.
net_terms:
integer
The net terms for the invoice
gift_card:
object
A gift card with a redemption code to apply to this purchase
coupon_codes:
array of strings
A list of coupon codes to apply to this purchase
subscriptions:
required
array of objects
A list of Subscriptions to invoice in this purchase. Required if there are no adjustments.
customer_notes:
string
Optional notes to show customer on the invoice. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.
terms_and_conditions:
string
Optional terms and conditions to show customer on the invoice. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Custom notes will stay with a subscription on all renewals.
vat_reverse_charge_notes:
string
Optional VAT reverse charge notes to show the customer on the invoice. Only appears if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Custom notes will stay with a subscription on all renewals.
shipping_address_id:
long
All subscriptions and adjustments on the purchase will use this shipping address unless they specify one of their own. Any subscriptions for which this address might apply will also use it in future renewals unless changed or removed. Cannot be used if a new shipping address is created at the account level.
shipping_fees:
array of objects
Array of `<shipping_fee>` objects, each containing a `shipping_method_code` and a `shipping_amount_in_cents`.
shipping_address:
object
Add this single shipping address to the account and apply it to the purchase.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<purchase>
  <collection_method>automatic</collection_method>
  <currency>USD</currency>
  <customer_notes>Some notes for the customer.</customer_notes>
  <terms_and_conditions>Our company terms and conditions.</terms_and_conditions>
  <vat_reverse_charge_notes>Vat reverse charge notes.</vat_reverse_charge_notes>
  <account>
    <account_code>c442b36c-c64f-41d7-b8e1-9c04e7a6ff82</account_code>
    <billing_info>
      <address1>400 Alabama St</address1>
      <city>San Francisco</city>
      <country>US</country>
      <first_name>Benjamin</first_name>
      <last_name>Du Monde</last_name>
      <month>12</month>
      <number>4111-1111-1111-1111</number>
      <state>CA</state>
      <year>2019</year>
      <zip>94110</zip>
    </billing_info>
  </account>
  <adjustments>
    <adjustment>
      <product_code>4549449c-5870-4845-b672-1d07f15e87dd</product_code>
      <quantity>1</quantity>
      <revenue_schedule_type>at_invoice</revenue_schedule_type>
      <unit_amount_in_cents>1000</unit_amount_in_cents>
      <description>Description of this adjustment</description>
    </adjustment>
  </adjustments>
  <subscriptions>
    <subscription>
      <plan_code>plan1</plan_code>
    </subscription>
  </subscriptions>
  <shipping_fees>
    <shipping_fee>
      <shipping_method_code>fast_fast_fast</shipping_method_code>
      <shipping_amount_in_cents>999</shipping_amount_in_cents>
    </shipping_fee>
  </shipping_fees>
  <shipping_address>
    <first_name>Lon</first_name>
    <last_name>Doner</last_name>        
    <address1>221B Baker St.</address1>
    <city>London</city>
    <state></state>
    <zip>W1K 6AH</zip>
    <country>GB</country>
    <nickname>Home</nickname>
  </shipping_address>
  <coupon_codes>
  	<coupon_code>coupon1</coupon_code>
    <coupon_code>coupon2</coupon_code>
  </coupon_codes>
  <gift_card>
    <redemption_code>ABC1234</redemption_code>
  </gift_card>
</purchase>
<?php

$purchase = new Recurly_Purchase();
$purchase->currency = 'USD';
$purchase->collection_method = 'automatic';
$purchase->account = new Recurly_Account();
$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';
$purchase->account->email = "verena@example.com";
$purchase->account->first_name = "Benjamin";
$purchase->account->last_name = "Du Monde";
$purchase->account->address->phone = "555-555-5555";
$purchase->account->address->address1 = "123 Main St.";
$purchase->account->address->city = "San Francisco";
$purchase->account->address->state = "CA";
$purchase->account->address->zip = "94110";
$purchase->account->address->country = "US";

$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2019;
$billing_info->verification_value = '123';
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';

$purchase->account->billing_info = $billing_info;

$shipping_address = new Recurly_ShippingAddress();
$shipping_address->first_name = 'Lon';
$shipping_address->last_name = 'Dorner';
$shipping_address->address1 = '400 Dolores St';
$shipping_address->city = 'San Francisco';
$shipping_address->state = 'CA';
$shipping_address->country = 'US';
$shipping_address->zip = '94110';
$shipping_address->nickname = 'Home';

$purchase->account->shipping_addresses = array($shipping_address);

$adjustment = new Recurly_Adjustment();
$adjustment->unit_amount_in_cents = 1000;
$adjustment->quantity = 1;

$purchase->adjustments = array($adjustment);

$subscription = new Recurly_Subscription();
$subscription->plan_code = 'pp';

$purchase->subscriptions = array($subscription);

$shipping_fee = new Recurly_ShippingFee();
$shipping_fee->shipping_method_code = 'fast_fast_fast';
$shipping_fee->shipping_amount_in_cents = 999;

$purchase->shipping_fees = array($shipping_fee);

$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');

$gift_card = new Recurly_GiftCard();
$gift_card->redemption_code = "FCJ7GEY4HO8WR16Q";
$purchase->gift_card = $gift_card;

// Create a preview invoice collection
try {
  $previewCollection = Recurly_Purchase::preview($purchase);
} catch (Recurly_ValidationError $e) {
  // You can get an idea why a purchase failed looking at these objects:
  var_dump($e);
} 
require 'securerandom'

purchase = Recurly::Purchase.new({
  currency: 'USD',
  collection_method: :automatic,
  account: {
    account_code: SecureRandom.uuid,
    billing_info: {
      first_name: 'Benjamin',
      last_name: 'Du Monde',
      address1: '400 Alabama St',
      city: 'San Francisco',
      state: 'CA',
      zip: '94110',
      country: 'US',
      number: '4111-1111-1111-1111',
      month: 12,
      year: 2019,
    },
    shipping_addresses: [
      {
        first_name: 'Lon',
        last_name: 'Dorner',
        address1: '400 Alabama St',
        city: 'San Francisco',
        state: 'CA',
        zip: '94110',
        country: 'US',
        nickname: 'home',
      }
    ]
  },
  subscriptions: [
    {
      plan_code: "gold",
    }
  ],
  adjustments: [
    {product_code: SecureRandom.uuid, unit_amount_in_cents: 1_000, quantity: 1, revenue_schedule_type: :at_invoice},
  ],
  shipping_fees: [
    {
      shipping_method_code: 'fast_fast_fast',
      shipping_amount_in_cents: '999'
    }
  ],
  coupon_codes: [
    "COUPON123",
    "COUPON345",
  ],
  gift_card: {
    redemption_code: "BC3749AB38371F273"
  }
})

begin
  preview_collection = Recurly::Purchase.preview!(purchase)
  puts preview_collection.inspect
rescue Recurly::Resource::Invalid => e
  puts e.inspect
  # Invalid data
end
purchase = recurly.Purchase(
  currency = 'USD',
  account = recurly.Account(
    account_code = 'account-code-123',
    billing_info = recurly.BillingInfo(
        first_name = 'Benjamin',
        last_name = 'DuMonde',
        number = '4111-1111-1111-1111',
        verification_value = '123',
        month = 11,
        year = 2020,
        address1 = '123 Main St',
        city = 'New Orleans',
        state = 'LA',
        zip = '70114',
        country = 'US',
    ),
    shipping_addresses = [
      recurly.ShippingAddress(
          first_name = 'Lon',
          last_name = 'Dorner',
          address1 = '400 Alabama St',
          city = 'San Francisco',
          state = 'CA',
          zip = '94110',
          country = 'US',
          nickname = 'home'
      )
    ]
  ),
  subscriptions = [
      recurly.Subscription(plan_code = 'gold')
  ],
  adjustments = [
      recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',
                         quantity=1),
      recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',
                         quantity=2),
  ],
  shipping_fees = [
    recurly.ShippingFee(
      shipping_method_code = 'fast_fast_fast',
      shipping_amount_in_cents = 999
    )
  ]
)

preview_collection = purchase.preview()
print(preview_collection)
var accountCode = "benjamin-du-monde";
var currency = "USD";
var planCode = "surveillance-pro";
var couponCode = "surveillance-podcast-promo";
var giftCardRedemptionCode = "8Z5VE6IRMWJDHU4P";

// We can create a purchase object from an account code or an Account object (first argument).
// Use the Account object when you want create a new account. This works similar to Subscription.
var purchase = new Purchase(accountCode, currency);

var shipAddr = new ShippingAddress();
shipAddr.Address1 = "400 Alabama St";
shipAddr.City = "San Francisco";
shipAddr.State = "CA";
shipAddr.Country = "US";
shipAddr.Zip = "94110";
shipAddr.FirstName = "Lon";
shipAddr.LastName = "Dorner";
shipAddr.Nickname = "home";
purchase.Account.ShippingAddresses.Add(shipAddr);

// Add multiple adjustments (optional if subscription[s] included)
purchase.Adjustments.Add(new Adjustment(4000, "HD Camera", 5));
purchase.Adjustments.Add(new Adjustment(1000, "Motion Sensor", 10));

// Add multiple subscriptions (optional if adjustment[s] included)
purchase.Subscriptions.Add(new Subscription(planCode));

// Add shipping fees
var shippingFee = new ShippingFee()
{
    ShippingMethodCode = "fast_fast_fast",
    ShippingAmountInCents = 999
};
purchase.ShippingFees = new List<ShippingFee>();
purchase.ShippingFees.Add(shippingFee);

// Add multiple coupon codes the customer may have (optional)
purchase.CouponCodes.Add(couponCode);

// Redeem a gift card with this purchase if the customer has redemption code (optional)
purchase.GiftCardRedemptionCode = giftCardRedemptionCode;

// For manual invoicing
// purchase.CollectionMethod = Invoice.Collection.Manual;
// purchase.NetTerms = 30;

// Previewing allows us to run all calculations and validations without running the
// transactions yet. This allows us to check the information and show the customer
// the the detailed invoices before they confirm the purchase.
var previewCollection = Purchase.Preview(purchase);

Result Format

<invoice_collection>
  <charge_invoice>
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <subscriptions href="https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions"/>
    <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>
    <shipping_address>
      <first_name>Lon</first_name>
      <last_name>Doner</last_name>
      <address1>221B Baker St.</address1>
      <address2></address2>
      <city>London</city>
      <state></state>
      <zip>W1K 6AH</zip>
      <country>GB</country>
      <phone></phone>
    </shipping_address>
    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>
    <state>paid</state>
    <invoice_number_prefix/>
    <invoice_number type="integer">1007</invoice_number>
    <po_number nil="nil"/>
    <vat_number nil="nil"/>
    <subtotal_in_cents type="integer">2000</subtotal_in_cents>
    <discount_in_cents type="integer">0</discount_in_cents>
    <due_on type="datetime">2018-01-30T21:11:50Z</due_on>
    <balance_in_cents type="integer">0</balance_in_cents>
    <type>charge</type>
    <origin>purchase</origin>
    <credit_invoices href="https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices"/>
    <refundable_total_in_cents type="integer">2000</refundable_total_in_cents>
    <credit_payments type="array">
    </credit_payments>
    <tax_in_cents type="integer">424</tax_in_cents>
    <total_in_cents type="integer">5274</total_in_cents>
    <currency>EUR</currency>
    <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
    <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
    <closed_at type="datetime">2016-08-03T16:26:26Z</closed_at>
    <terms_and_conditions nil="nil"/>
    <customer_notes nil="nil"/>
    <tax_type>usst</tax_type>
    <tax_region>CA</tax_region>
    <tax_rate type="float">0.0875</tax_rate>
    <net_terms type="integer">0</net_terms>
    <collection_method>automatic</collection_method>
    <redemptions href="https://your-subdomain.recurly.com/v2/invoices/1007/redemptions"/>
    <line_items type="array">
      <adjustment href="https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd" type="charge">
        <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
        <invoice href="https://your-subdomain.recurly.com/v2/invoices/1007"/>
        <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41"/>
        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>
        <state>invoiced</state>
        <description>Setup fee: Gold plan</description>
        <accounting_code nil="nil"/>
        <product_code>gold</product_code>
        <origin>setup_fee</origin>
        <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
        <quantity type="integer">1</quantity>
        <discount_in_cents type="integer">0</discount_in_cents>
        <tax_in_cents type="integer">70</tax_in_cents>
        <total_in_cents type="integer">870</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-08-03T16:26:26Z</start_date>
        <end_date nil="nil"/>
        <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
        <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
        <revenue_schedule_type>evenly</revenue_schedule_type>
      </adjustment>
      <!-- Continued... -->
    </line_items>
    <transactions type="array">
      <!-- Detail. -->
    </transactions>
    <a name="refund" href="https://your-subdomain.recurly.com/v2/invoices/1007/refund" method="post"/>
  </charge_invoice>
  <credit_invoices type="array">
  </credit_invoices>
</invoice_collection>


{"_id":"5dd5f0b02d076f0220ca8be7","category":"5dd5f0b02d076f0220ca8b96","project":"555fbba928249c1900618a82","user":"55957fd09b8d0a25005a7d30","parentDoc":null,"version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-11-20T19:03:04.216Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"name":"","code":"<invoice_collection>\n  <charge_invoice>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions\"/>\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    <shipping_address>\n      <first_name>Lon</first_name>\n      <last_name>Doner</last_name>\n      <address1>221B Baker St.</address1>\n      <address2></address2>\n      <city>London</city>\n      <state></state>\n      <zip>W1K 6AH</zip>\n      <country>GB</country>\n      <phone></phone>\n    </shipping_address>\n    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>\n    <state>paid</state>\n    <invoice_number_prefix/>\n    <invoice_number type=\"integer\">1007</invoice_number>\n    <po_number nil=\"nil\"/>\n    <vat_number nil=\"nil\"/>\n    <subtotal_in_cents type=\"integer\">2000</subtotal_in_cents>\n    <discount_in_cents type=\"integer\">0</discount_in_cents>\n    <due_on type=\"datetime\">2018-01-30T21:11:50Z</due_on>\n    <balance_in_cents type=\"integer\">0</balance_in_cents>\n    <type>charge</type>\n    <origin>purchase</origin>\n    <credit_invoices href=\"https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices\"/>\n    <refundable_total_in_cents type=\"integer\">2000</refundable_total_in_cents>\n    <credit_payments type=\"array\">\n    </credit_payments>\n    <tax_in_cents type=\"integer\">424</tax_in_cents>\n    <total_in_cents type=\"integer\">5274</total_in_cents>\n    <currency>EUR</currency>\n    <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n    <closed_at type=\"datetime\">2016-08-03T16:26:26Z</closed_at>\n    <terms_and_conditions nil=\"nil\"/>\n    <customer_notes nil=\"nil\"/>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.0875</tax_rate>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/redemptions\"/>\n    <line_items type=\"array\">\n      <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd\" type=\"charge\">\n        <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n        <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1007\"/>\n        <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41\"/>\n        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>\n        <state>invoiced</state>\n        <description>Setup fee: Gold plan</description>\n        <accounting_code nil=\"nil\"/>\n        <product_code>gold</product_code>\n        <origin>setup_fee</origin>\n        <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n        <quantity type=\"integer\">1</quantity>\n        <discount_in_cents type=\"integer\">0</discount_in_cents>\n        <tax_in_cents type=\"integer\">70</tax_in_cents>\n        <total_in_cents type=\"integer\">870</total_in_cents>\n        <currency>EUR</currency>\n        <taxable type=\"boolean\">false</taxable>\n        <tax_type>usst</tax_type>\n        <tax_region>CA</tax_region>\n        <tax_rate type=\"float\">0.0875</tax_rate>\n        <tax_exempt type=\"boolean\">false</tax_exempt>\n        <tax_code nil=\"nil\"/>\n        <start_date type=\"datetime\">2016-08-03T16:26:26Z</start_date>\n        <end_date nil=\"nil\"/>\n        <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n        <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n        <revenue_schedule_type>evenly</revenue_schedule_type>\n      </adjustment>\n      <!-- Continued... -->\n    </line_items>\n    <transactions type=\"array\">\n      <!-- Detail. -->\n    </transactions>\n    <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/invoices/1007/refund\" method=\"post\"/>\n  </charge_invoice>\n  <credit_invoices type=\"array\">\n  </credit_invoices>\n</invoice_collection>","language":"xml","status":200}]},"method":"post","examples":{"codes":[{"language":"xml","code":"<purchase>\n  <collection_method>automatic</collection_method>\n  <currency>USD</currency>\n  <customer_notes>Some notes for the customer.</customer_notes>\n  <terms_and_conditions>Our company terms and conditions.</terms_and_conditions>\n  <vat_reverse_charge_notes>Vat reverse charge notes.</vat_reverse_charge_notes>\n  <account>\n    <account_code>c442b36c-c64f-41d7-b8e1-9c04e7a6ff82</account_code>\n    <billing_info>\n      <address1>400 Alabama St</address1>\n      <city>San Francisco</city>\n      <country>US</country>\n      <first_name>Benjamin</first_name>\n      <last_name>Du Monde</last_name>\n      <month>12</month>\n      <number>4111-1111-1111-1111</number>\n      <state>CA</state>\n      <year>2019</year>\n      <zip>94110</zip>\n    </billing_info>\n  </account>\n  <adjustments>\n    <adjustment>\n      <product_code>4549449c-5870-4845-b672-1d07f15e87dd</product_code>\n      <quantity>1</quantity>\n      <revenue_schedule_type>at_invoice</revenue_schedule_type>\n      <unit_amount_in_cents>1000</unit_amount_in_cents>\n      <description>Description of this adjustment</description>\n    </adjustment>\n  </adjustments>\n  <subscriptions>\n    <subscription>\n      <plan_code>plan1</plan_code>\n    </subscription>\n  </subscriptions>\n  <shipping_fees>\n    <shipping_fee>\n      <shipping_method_code>fast_fast_fast</shipping_method_code>\n      <shipping_amount_in_cents>999</shipping_amount_in_cents>\n    </shipping_fee>\n  </shipping_fees>\n  <shipping_address>\n    <first_name>Lon</first_name>\n    <last_name>Doner</last_name>        \n    <address1>221B Baker St.</address1>\n    <city>London</city>\n    <state></state>\n    <zip>W1K 6AH</zip>\n    <country>GB</country>\n    <nickname>Home</nickname>\n  </shipping_address>\n  <coupon_codes>\n  \t<coupon_code>coupon1</coupon_code>\n    <coupon_code>coupon2</coupon_code>\n  </coupon_codes>\n  <gift_card>\n    <redemption_code>ABC1234</redemption_code>\n  </gift_card>\n</purchase>"},{"language":"php","code":"<?php\n\n$purchase = new Recurly_Purchase();\n$purchase->currency = 'USD';\n$purchase->collection_method = 'automatic';\n$purchase->account = new Recurly_Account();\n$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';\n$purchase->account->email = \"verena@example.com\";\n$purchase->account->first_name = \"Benjamin\";\n$purchase->account->last_name = \"Du Monde\";\n$purchase->account->address->phone = \"555-555-5555\";\n$purchase->account->address->address1 = \"123 Main St.\";\n$purchase->account->address->city = \"San Francisco\";\n$purchase->account->address->state = \"CA\";\n$purchase->account->address->zip = \"94110\";\n$purchase->account->address->country = \"US\";\n\n$billing_info = new Recurly_BillingInfo();\n$billing_info->number = '4111-1111-1111-1111';\n$billing_info->month = 12;\n$billing_info->year = 2019;\n$billing_info->verification_value = '123';\n$billing_info->address1 = '400 Alabama St';\n$billing_info->city = 'San Francisco';\n$billing_info->state = 'CA';\n$billing_info->country = 'US';\n$billing_info->zip = '94110';\n\n$purchase->account->billing_info = $billing_info;\n\n$shipping_address = new Recurly_ShippingAddress();\n$shipping_address->first_name = 'Lon';\n$shipping_address->last_name = 'Dorner';\n$shipping_address->address1 = '400 Dolores St';\n$shipping_address->city = 'San Francisco';\n$shipping_address->state = 'CA';\n$shipping_address->country = 'US';\n$shipping_address->zip = '94110';\n$shipping_address->nickname = 'Home';\n\n$purchase->account->shipping_addresses = array($shipping_address);\n\n$adjustment = new Recurly_Adjustment();\n$adjustment->unit_amount_in_cents = 1000;\n$adjustment->quantity = 1;\n\n$purchase->adjustments = array($adjustment);\n\n$subscription = new Recurly_Subscription();\n$subscription->plan_code = 'pp';\n\n$shipping_fee = new Recurly_ShippingFee();\n$shipping_fee->shipping_method_code = 'fast_fast_fast';\n$shipping_fee->shipping_amount_in_cents = 999;\n\n$purchase->shipping_fees = array($shipping_fee);\n\n$purchase->subscriptions = array($subscription);\n\n$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');\n\n$gift_card = new Recurly_GiftCard();\n$gift_card->redemption_code = \"FCJ7GEY4HO8WR16Q\";\n$purchase->gift_card = $gift_card;\n\n// Create a preview invoice collection\ntry {\n  $previewCollection = Recurly_Purchase::authorize($purchase);\n} catch (Recurly_ValidationError $e) {\n  // You can get an idea why a purchase failed looking at these objects:\n  var_dump($e);\n} "},{"language":"ruby","code":"require 'securerandom'\n\npurchase = Recurly::Purchase.new({\n  currency: 'USD',\n  collection_method: :automatic,\n  account: {\n    account_code: SecureRandom.uuid,\n    billing_info: {\n      first_name: 'Benjamin',\n      last_name: 'Du Monde',\n      address1: '400 Alabama St',\n      city: 'San Francisco',\n      state: 'CA',\n      zip: '94110',\n      country: 'US',\n      number: '4111-1111-1111-1111',\n      month: 12,\n      year: 2019,\n    },\n    shipping_addresses: [\n      {\n        first_name: 'Lon',\n        last_name: 'Dorner',\n        address1: '400 Alabama St',\n        city: 'San Francisco',\n        state: 'CA',\n        zip: '94110',\n        country: 'US',\n        nickname: 'home',\n      }\n    ]\n  },\n  subscriptions: [\n    {\n      plan_code: \"gold\",\n    }\n  ],\n  adjustments: [\n    {product_code: SecureRandom.uuid, unit_amount_in_cents: 1_000, quantity: 1, revenue_schedule_type: :at_invoice},\n  ],\n  shipping_fees: [\n    {\n      shipping_method_code: 'fast_fast_fast',\n      shipping_amount_in_cents: '999'\n    }\n  ],\n  coupon_codes: [\n    \"COUPON123\",\n    \"COUPON345\",\n  ],\n  gift_card: {\n    redemption_code: \"BC3749AB38371F273\"\n  }\n})\n\nbegin\n  preview_collection = Recurly::Purchase.authorize!(purchase)\n  puts preview_collection.inspect\nrescue Recurly::Resource::Invalid => e\n  puts e.inspect\n  # Invalid data\nend"},{"language":"python","code":"purchase = recurly.Purchase(\n  currency = 'USD',\n  account = recurly.Account(\n    account_code = 'account-code-123',\n    billing_info = recurly.BillingInfo(\n        first_name = 'Benjamin',\n        last_name = 'DuMonde',\n        number = '4111-1111-1111-1111',\n        verification_value = '123',\n        month = 11,\n        year = 2020,\n        address1 = '123 Main St',\n        city = 'New Orleans',\n        state = 'LA',\n        zip = '70114',\n        country = 'US',\n    ),\n    shipping_addresses = [\n      recurly.ShippingAddress(\n          first_name = 'Lon',\n          last_name = 'Dorner',\n          address1 = '400 Alabama St',\n          city = 'San Francisco',\n          state = 'CA',\n          zip = '94110',\n          country = 'US',\n          nickname = 'home'\n      )\n    ]\n  ),\n  subscriptions = [\n      recurly.Subscription(plan_code = 'gold')\n  ],\n  adjustments = [\n      recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',\n                         quantity=1),\n      recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',\n                         quantity=2),\n  ],\n  shipping_fees = [\n    recurly.ShippingFee(\n      shipping_method_code = 'fast_fast_fast',\n      shipping_amount_in_cents = 999\n    )\n  ]\n)\n\npreview_collection = purchase.authorize()\nprint(preview_collection)"},{"language":"csharp","code":"var accountCode = \"benjamin-du-monde\";\nvar currency = \"USD\";\nvar planCode = \"surveillance-pro\";\nvar couponCode = \"surveillance-podcast-promo\";\nvar giftCardRedemptionCode = \"8Z5VE6IRMWJDHU4P\";\n\n// We can create a purchase object from an account code or an Account object (first argument).\n// Use the Account object when you want create a new account. This works similar to Subscription.\nvar purchase = new Purchase(accountCode, currency);\n\nvar shipAddr = new ShippingAddress();\nshipAddr.Address1 = \"400 Alabama St\";\nshipAddr.City = \"San Francisco\";\nshipAddr.State = \"CA\";\nshipAddr.Country = \"US\";\nshipAddr.Zip = \"94110\";\nshipAddr.FirstName = \"Lon\";\nshipAddr.LastName = \"Dorner\";\nshipAddr.Nickname = \"home\";\npurchase.Account.ShippingAddresses.Add(shipAddr);\n\n// Add multiple adjustments (optional if subscription[s] included)\npurchase.Adjustments.Add(new Adjustment(4000, \"HD Camera\", 5));\npurchase.Adjustments.Add(new Adjustment(1000, \"Motion Sensor\", 10));\n\n// Add multiple subscriptions (optional if adjustment[s] included)\npurchase.Subscriptions.Add(new Subscription(planCode));\n\n// Add shipping fees\nvar shippingFee = new ShippingFee()\n{\n    ShippingMethodCode = \"fast_fast_fast\",\n    ShippingAmountInCents = 999\n};\npurchase.ShippingFees = new List<ShippingFee>();\npurchase.ShippingFees.Add(shippingFee);\n\n// Add multiple coupon codes the customer may have (optional)\npurchase.CouponCodes.Add(couponCode);\n\n// Redeem a gift card with this purchase if the customer has redemption code (optional)\npurchase.GiftCardRedemptionCode = giftCardRedemptionCode;\n\n// For manual invoicing\n// purchase.CollectionMethod = Invoice.Collection.Manual;\n// purchase.NetTerms = 30;\n\n// Previewing allows us to run all calculations and validations without running the\n// transactions yet. This allows us to check the information and show the customer\n// the the detailed invoices before they confirm the purchase.\nvar previewCollection = Purchase.Authorize(purchase);"}]},"auth":"required","params":[{"_id":"591b66df7d2cb40f00d471d6","ref":"","in":"body","required":true,"desc":"An account object. This can be an existing account or a new account. If using a new account and adding shipping addresses, the last shipping address in the list will apply to every subscription and adjustment in the purchase.","default":"","type":"object","name":"account"},{"_id":"591b66df7d2cb40f00d471d5","ref":"","in":"body","required":true,"desc":"This should be a list of Adjustment objects. Required if there are no subscriptions.","default":"","type":"array_object","name":"adjustments"},{"_id":"591b66df7d2cb40f00d471d4","ref":"","in":"body","required":false,"desc":"The collection method for the invoice (`automatic` or `manual`).","default":"","type":"string","name":"collection_method"},{"_id":"591b66df7d2cb40f00d471d3","ref":"","in":"body","required":false,"desc":"The 3 letter currency code for the adjustments.","default":"","type":"string","name":"currency"},{"_id":"591b66df7d2cb40f00d471d2","ref":"","in":"body","required":false,"desc":"A po number for the resulting invoice.","default":"","type":"string","name":"po_number"},{"_id":"591b66df7d2cb40f00d471d1","ref":"","in":"body","required":false,"desc":"The net terms for the invoice","default":"","type":"int","name":"net_terms"},{"_id":"5955762bba6cff002966ae31","ref":"","in":"body","required":false,"desc":"A gift card with a redemption code to apply to this purchase","default":"","type":"object","name":"gift_card"},{"_id":"5955762bba6cff002966ae30","ref":"","in":"body","required":false,"desc":"A list of coupon codes to apply to this purchase","default":"","type":"array_string","name":"coupon_codes"},{"_id":"5955762bba6cff002966ae2f","ref":"","in":"body","required":true,"desc":"A list of Subscriptions to invoice in this purchase. Required if there are no adjustments.","default":"","type":"array_object","name":"subscriptions"},{"_id":"59d699316d3f930010333002","ref":"","in":"body","required":false,"desc":"Optional notes to show customer on the invoice. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.","default":"","type":"string","name":"customer_notes"},{"_id":"59d699316d3f930010333001","ref":"","in":"body","required":false,"desc":"Optional terms and conditions to show customer on the invoice. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"terms_and_conditions"},{"_id":"59d699316d3f930010333000","ref":"","in":"body","required":false,"desc":"Optional VAT reverse charge notes to show the customer on the invoice. Only appears if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"vat_reverse_charge_notes"},{"_id":"5abbd2f4afef010029981f81","ref":"","in":"body","required":false,"desc":"All subscriptions and adjustments on the purchase will use this shipping address unless they specify one of their own. Any subscriptions for which this address might apply will also use it in future renewals unless changed or removed. Cannot be used if a new shipping address is created at the account level.","default":"","type":"long","name":"shipping_address_id"},{"_id":"5ce443826090c6013019d7d1","ref":"","in":"body","required":false,"desc":"Array of `<shipping_fee>` objects, each containing a `shipping_method_code` and a `shipping_amount_in_cents`.","default":"","type":"array_object","name":"shipping_fees"},{"_id":"5daf5ace53d47306873b0983","ref":"","in":"body","required":false,"desc":"Add this single shipping address to the account and apply it to the purchase.","default":"","type":"string","name":"shipping_address"}],"url":"/purchases/authorize"},"isReference":true,"order":2,"body":"","excerpt":"A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type.\n\nThe authorize endpoint will create a pending purchase that can be activated at a later time once payment has been completed on an external source (e.g. Adyen's Hosted Payment Pages).\n\nFor additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping","slug":"authorize-purchase","type":"post","title":"Authorize Purchase","__v":25,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postAuthorize Purchase

A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type. The authorize endpoint will create a pending purchase that can be activated at a later time once payment has been completed on an external source (e.g. Adyen's Hosted Payment Pages). For additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping

Body Params

account:
required
object
An account object. This can be an existing account or a new account. If using a new account and adding shipping addresses, the last shipping address in the list will apply to every subscription and adjustment in the purchase.
adjustments:
required
array of objects
This should be a list of Adjustment objects. Required if there are no subscriptions.
collection_method:
string
The collection method for the invoice (`automatic` or `manual`).
currency:
string
The 3 letter currency code for the adjustments.
po_number:
string
A po number for the resulting invoice.
net_terms:
integer
The net terms for the invoice
gift_card:
object
A gift card with a redemption code to apply to this purchase
coupon_codes:
array of strings
A list of coupon codes to apply to this purchase
subscriptions:
required
array of objects
A list of Subscriptions to invoice in this purchase. Required if there are no adjustments.
customer_notes:
string
Optional notes to show customer on the invoice. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.
terms_and_conditions:
string
Optional terms and conditions to show customer on the invoice. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Custom notes will stay with a subscription on all renewals.
vat_reverse_charge_notes:
string
Optional VAT reverse charge notes to show the customer on the invoice. Only appears if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Custom notes will stay with a subscription on all renewals.
shipping_address_id:
long
All subscriptions and adjustments on the purchase will use this shipping address unless they specify one of their own. Any subscriptions for which this address might apply will also use it in future renewals unless changed or removed. Cannot be used if a new shipping address is created at the account level.
shipping_fees:
array of objects
Array of `<shipping_fee>` objects, each containing a `shipping_method_code` and a `shipping_amount_in_cents`.
shipping_address:
string
Add this single shipping address to the account and apply it to the purchase.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<purchase>
  <collection_method>automatic</collection_method>
  <currency>USD</currency>
  <customer_notes>Some notes for the customer.</customer_notes>
  <terms_and_conditions>Our company terms and conditions.</terms_and_conditions>
  <vat_reverse_charge_notes>Vat reverse charge notes.</vat_reverse_charge_notes>
  <account>
    <account_code>c442b36c-c64f-41d7-b8e1-9c04e7a6ff82</account_code>
    <billing_info>
      <address1>400 Alabama St</address1>
      <city>San Francisco</city>
      <country>US</country>
      <first_name>Benjamin</first_name>
      <last_name>Du Monde</last_name>
      <month>12</month>
      <number>4111-1111-1111-1111</number>
      <state>CA</state>
      <year>2019</year>
      <zip>94110</zip>
    </billing_info>
  </account>
  <adjustments>
    <adjustment>
      <product_code>4549449c-5870-4845-b672-1d07f15e87dd</product_code>
      <quantity>1</quantity>
      <revenue_schedule_type>at_invoice</revenue_schedule_type>
      <unit_amount_in_cents>1000</unit_amount_in_cents>
      <description>Description of this adjustment</description>
    </adjustment>
  </adjustments>
  <subscriptions>
    <subscription>
      <plan_code>plan1</plan_code>
    </subscription>
  </subscriptions>
  <shipping_fees>
    <shipping_fee>
      <shipping_method_code>fast_fast_fast</shipping_method_code>
      <shipping_amount_in_cents>999</shipping_amount_in_cents>
    </shipping_fee>
  </shipping_fees>
  <shipping_address>
    <first_name>Lon</first_name>
    <last_name>Doner</last_name>        
    <address1>221B Baker St.</address1>
    <city>London</city>
    <state></state>
    <zip>W1K 6AH</zip>
    <country>GB</country>
    <nickname>Home</nickname>
  </shipping_address>
  <coupon_codes>
  	<coupon_code>coupon1</coupon_code>
    <coupon_code>coupon2</coupon_code>
  </coupon_codes>
  <gift_card>
    <redemption_code>ABC1234</redemption_code>
  </gift_card>
</purchase>
<?php

$purchase = new Recurly_Purchase();
$purchase->currency = 'USD';
$purchase->collection_method = 'automatic';
$purchase->account = new Recurly_Account();
$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';
$purchase->account->email = "verena@example.com";
$purchase->account->first_name = "Benjamin";
$purchase->account->last_name = "Du Monde";
$purchase->account->address->phone = "555-555-5555";
$purchase->account->address->address1 = "123 Main St.";
$purchase->account->address->city = "San Francisco";
$purchase->account->address->state = "CA";
$purchase->account->address->zip = "94110";
$purchase->account->address->country = "US";

$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2019;
$billing_info->verification_value = '123';
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';

$purchase->account->billing_info = $billing_info;

$shipping_address = new Recurly_ShippingAddress();
$shipping_address->first_name = 'Lon';
$shipping_address->last_name = 'Dorner';
$shipping_address->address1 = '400 Dolores St';
$shipping_address->city = 'San Francisco';
$shipping_address->state = 'CA';
$shipping_address->country = 'US';
$shipping_address->zip = '94110';
$shipping_address->nickname = 'Home';

$purchase->account->shipping_addresses = array($shipping_address);

$adjustment = new Recurly_Adjustment();
$adjustment->unit_amount_in_cents = 1000;
$adjustment->quantity = 1;

$purchase->adjustments = array($adjustment);

$subscription = new Recurly_Subscription();
$subscription->plan_code = 'pp';

$shipping_fee = new Recurly_ShippingFee();
$shipping_fee->shipping_method_code = 'fast_fast_fast';
$shipping_fee->shipping_amount_in_cents = 999;

$purchase->shipping_fees = array($shipping_fee);

$purchase->subscriptions = array($subscription);

$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');

$gift_card = new Recurly_GiftCard();
$gift_card->redemption_code = "FCJ7GEY4HO8WR16Q";
$purchase->gift_card = $gift_card;

// Create a preview invoice collection
try {
  $previewCollection = Recurly_Purchase::authorize($purchase);
} catch (Recurly_ValidationError $e) {
  // You can get an idea why a purchase failed looking at these objects:
  var_dump($e);
} 
require 'securerandom'

purchase = Recurly::Purchase.new({
  currency: 'USD',
  collection_method: :automatic,
  account: {
    account_code: SecureRandom.uuid,
    billing_info: {
      first_name: 'Benjamin',
      last_name: 'Du Monde',
      address1: '400 Alabama St',
      city: 'San Francisco',
      state: 'CA',
      zip: '94110',
      country: 'US',
      number: '4111-1111-1111-1111',
      month: 12,
      year: 2019,
    },
    shipping_addresses: [
      {
        first_name: 'Lon',
        last_name: 'Dorner',
        address1: '400 Alabama St',
        city: 'San Francisco',
        state: 'CA',
        zip: '94110',
        country: 'US',
        nickname: 'home',
      }
    ]
  },
  subscriptions: [
    {
      plan_code: "gold",
    }
  ],
  adjustments: [
    {product_code: SecureRandom.uuid, unit_amount_in_cents: 1_000, quantity: 1, revenue_schedule_type: :at_invoice},
  ],
  shipping_fees: [
    {
      shipping_method_code: 'fast_fast_fast',
      shipping_amount_in_cents: '999'
    }
  ],
  coupon_codes: [
    "COUPON123",
    "COUPON345",
  ],
  gift_card: {
    redemption_code: "BC3749AB38371F273"
  }
})

begin
  preview_collection = Recurly::Purchase.authorize!(purchase)
  puts preview_collection.inspect
rescue Recurly::Resource::Invalid => e
  puts e.inspect
  # Invalid data
end
purchase = recurly.Purchase(
  currency = 'USD',
  account = recurly.Account(
    account_code = 'account-code-123',
    billing_info = recurly.BillingInfo(
        first_name = 'Benjamin',
        last_name = 'DuMonde',
        number = '4111-1111-1111-1111',
        verification_value = '123',
        month = 11,
        year = 2020,
        address1 = '123 Main St',
        city = 'New Orleans',
        state = 'LA',
        zip = '70114',
        country = 'US',
    ),
    shipping_addresses = [
      recurly.ShippingAddress(
          first_name = 'Lon',
          last_name = 'Dorner',
          address1 = '400 Alabama St',
          city = 'San Francisco',
          state = 'CA',
          zip = '94110',
          country = 'US',
          nickname = 'home'
      )
    ]
  ),
  subscriptions = [
      recurly.Subscription(plan_code = 'gold')
  ],
  adjustments = [
      recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',
                         quantity=1),
      recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',
                         quantity=2),
  ],
  shipping_fees = [
    recurly.ShippingFee(
      shipping_method_code = 'fast_fast_fast',
      shipping_amount_in_cents = 999
    )
  ]
)

preview_collection = purchase.authorize()
print(preview_collection)
var accountCode = "benjamin-du-monde";
var currency = "USD";
var planCode = "surveillance-pro";
var couponCode = "surveillance-podcast-promo";
var giftCardRedemptionCode = "8Z5VE6IRMWJDHU4P";

// We can create a purchase object from an account code or an Account object (first argument).
// Use the Account object when you want create a new account. This works similar to Subscription.
var purchase = new Purchase(accountCode, currency);

var shipAddr = new ShippingAddress();
shipAddr.Address1 = "400 Alabama St";
shipAddr.City = "San Francisco";
shipAddr.State = "CA";
shipAddr.Country = "US";
shipAddr.Zip = "94110";
shipAddr.FirstName = "Lon";
shipAddr.LastName = "Dorner";
shipAddr.Nickname = "home";
purchase.Account.ShippingAddresses.Add(shipAddr);

// Add multiple adjustments (optional if subscription[s] included)
purchase.Adjustments.Add(new Adjustment(4000, "HD Camera", 5));
purchase.Adjustments.Add(new Adjustment(1000, "Motion Sensor", 10));

// Add multiple subscriptions (optional if adjustment[s] included)
purchase.Subscriptions.Add(new Subscription(planCode));

// Add shipping fees
var shippingFee = new ShippingFee()
{
    ShippingMethodCode = "fast_fast_fast",
    ShippingAmountInCents = 999
};
purchase.ShippingFees = new List<ShippingFee>();
purchase.ShippingFees.Add(shippingFee);

// Add multiple coupon codes the customer may have (optional)
purchase.CouponCodes.Add(couponCode);

// Redeem a gift card with this purchase if the customer has redemption code (optional)
purchase.GiftCardRedemptionCode = giftCardRedemptionCode;

// For manual invoicing
// purchase.CollectionMethod = Invoice.Collection.Manual;
// purchase.NetTerms = 30;

// Previewing allows us to run all calculations and validations without running the
// transactions yet. This allows us to check the information and show the customer
// the the detailed invoices before they confirm the purchase.
var previewCollection = Purchase.Authorize(purchase);

Result Format

<invoice_collection>
  <charge_invoice>
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <subscriptions href="https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions"/>
    <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>
    <shipping_address>
      <first_name>Lon</first_name>
      <last_name>Doner</last_name>
      <address1>221B Baker St.</address1>
      <address2></address2>
      <city>London</city>
      <state></state>
      <zip>W1K 6AH</zip>
      <country>GB</country>
      <phone></phone>
    </shipping_address>
    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>
    <state>paid</state>
    <invoice_number_prefix/>
    <invoice_number type="integer">1007</invoice_number>
    <po_number nil="nil"/>
    <vat_number nil="nil"/>
    <subtotal_in_cents type="integer">2000</subtotal_in_cents>
    <discount_in_cents type="integer">0</discount_in_cents>
    <due_on type="datetime">2018-01-30T21:11:50Z</due_on>
    <balance_in_cents type="integer">0</balance_in_cents>
    <type>charge</type>
    <origin>purchase</origin>
    <credit_invoices href="https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices"/>
    <refundable_total_in_cents type="integer">2000</refundable_total_in_cents>
    <credit_payments type="array">
    </credit_payments>
    <tax_in_cents type="integer">424</tax_in_cents>
    <total_in_cents type="integer">5274</total_in_cents>
    <currency>EUR</currency>
    <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
    <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
    <closed_at type="datetime">2016-08-03T16:26:26Z</closed_at>
    <terms_and_conditions nil="nil"/>
    <customer_notes nil="nil"/>
    <tax_type>usst</tax_type>
    <tax_region>CA</tax_region>
    <tax_rate type="float">0.0875</tax_rate>
    <net_terms type="integer">0</net_terms>
    <collection_method>automatic</collection_method>
    <redemptions href="https://your-subdomain.recurly.com/v2/invoices/1007/redemptions"/>
    <line_items type="array">
      <adjustment href="https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd" type="charge">
        <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
        <invoice href="https://your-subdomain.recurly.com/v2/invoices/1007"/>
        <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41"/>
        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>
        <state>invoiced</state>
        <description>Setup fee: Gold plan</description>
        <accounting_code nil="nil"/>
        <product_code>gold</product_code>
        <origin>setup_fee</origin>
        <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
        <quantity type="integer">1</quantity>
        <discount_in_cents type="integer">0</discount_in_cents>
        <tax_in_cents type="integer">70</tax_in_cents>
        <total_in_cents type="integer">870</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-08-03T16:26:26Z</start_date>
        <end_date nil="nil"/>
        <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
        <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
        <revenue_schedule_type>evenly</revenue_schedule_type>
      </adjustment>
      <!-- Continued... -->
    </line_items>
    <transactions type="array">
      <!-- Detail. -->
    </transactions>
    <a name="refund" href="https://your-subdomain.recurly.com/v2/invoices/1007/refund" method="post"/>
  </charge_invoice>
  <credit_invoices type="array">
  </credit_invoices>
</invoice_collection>


{"_id":"5dd5f0b02d076f0220ca8c3b","project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","category":"5dd5f0b02d076f0220ca8b96","user":"55957fd09b8d0a25005a7d30","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-05-18T16:27:35.960Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"xml","code":"<purchase>\n  <collection_method>automatic</collection_method>\n  <currency>USD</currency>\n  <customer_notes>Some notes for the customer.</customer_notes>\n  <terms_and_conditions>Our company terms and conditions.</terms_and_conditions>\n  <vat_reverse_charge_notes>Vat reverse charge notes.</vat_reverse_charge_notes>\n  <account>\n    <account_code>c442b36c-c64f-41d7-b8e1-9c04e7a6ff82</account_code>\n    <!-- email is required for this endpoint -->\n    <email>benjamin.dumonde@example.com</email>\n    <billing_info>\n      <address1>400 Alabama St</address1>\n      <city>San Francisco</city>\n      <country>US</country>\n      <first_name>Benjamin</first_name>\n      <last_name>Du Monde</last_name>\n      <month>12</month>\n      <number>4111-1111-1111-1111</number>\n      <state>CA</state>\n      <year>2019</year>\n      <zip>94110</zip>\n    </billing_info>\n  </account>\n  <adjustments>\n    <adjustment>\n      <product_code>4549449c-5870-4845-b672-1d07f15e87dd</product_code>\n      <quantity>1</quantity>\n      <revenue_schedule_type>at_invoice</revenue_schedule_type>\n      <unit_amount_in_cents>1000</unit_amount_in_cents>\n      <description>Description of this adjustment</description>\n    </adjustment>\n  </adjustments>\n  <subscriptions>\n    <subscription>\n      <plan_code>plan1</plan_code>\n    </subscription>\n  </subscriptions>\n  <shipping_fees>\n    <shipping_fee>\n      <shipping_method_code>fast_fast_fast</shipping_method_code>\n      <shipping_amount_in_cents>999</shipping_amount_in_cents>\n    </shipping_fee>\n  </shipping_fees>\n  <shipping_address>\n    <first_name>Lon</first_name>\n    <last_name>Doner</last_name>        \n    <address1>221B Baker St.</address1>\n    <city>London</city>\n    <state></state>\n    <zip>W1K 6AH</zip>\n    <country>GB</country>\n    <nickname>Home</nickname>\n  </shipping_address>\n  <coupon_codes>\n  \t<coupon_code>coupon1</coupon_code>\n    <coupon_code>coupon2</coupon_code>\n  </coupon_codes>\n  <gift_card>\n    <redemption_code>ABC1234</redemption_code>\n  </gift_card>\n</purchase>"},{"language":"php","code":"<?php\n\n$purchase = new Recurly_Purchase();\n$purchase->currency = 'USD';\n$purchase->collection_method = 'automatic';\n$purchase->account = new Recurly_Account();\n$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';\n$purchase->account->email = \"verena@example.com\";\n$purchase->account->first_name = \"Benjamin\";\n$purchase->account->last_name = \"Du Monde\";\n$purchase->account->address->phone = \"555-555-5555\";\n$purchase->account->address->address1 = \"123 Main St.\";\n$purchase->account->address->city = \"San Francisco\";\n$purchase->account->address->state = \"CA\";\n$purchase->account->address->zip = \"94110\";\n$purchase->account->address->country = \"US\";\n\n$billing_info = new Recurly_BillingInfo();\n$billing_info->number = '4111-1111-1111-1111';\n$billing_info->month = 12;\n$billing_info->year = 2019;\n$billing_info->verification_value = '123';\n$billing_info->address1 = '400 Alabama St';\n$billing_info->city = 'San Francisco';\n$billing_info->state = 'CA';\n$billing_info->country = 'US';\n$billing_info->zip = '94110';\n\n$purchase->account->billing_info = $billing_info;\n\n$shipping_address = new Recurly_ShippingAddress();\n$shipping_address->first_name = 'Lon';\n$shipping_address->last_name = 'Dorner';\n$shipping_address->address1 = '400 Dolores St';\n$shipping_address->city = 'San Francisco';\n$shipping_address->state = 'CA';\n$shipping_address->country = 'US';\n$shipping_address->zip = '94110';\n$shipping_address->nickname = 'Home';\n\n$purchase->account->shipping_addresses = array($shipping_address);\n\n$adjustment = new Recurly_Adjustment();\n$adjustment->unit_amount_in_cents = 1000;\n$adjustment->quantity = 1;\n\n$purchase->adjustments = array($adjustment);\n\n$subscription = new Recurly_Subscription();\n$subscription->plan_code = 'pp';\n\n$shipping_fee = new Recurly_ShippingFee();\n$shipping_fee->shipping_method_code = 'fast_fast_fast';\n$shipping_fee->shipping_amount_in_cents = 999;\n\n$purchase->subscriptions = array($subscription);\n\n$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');\n\n$gift_card = new Recurly_GiftCard();\n$gift_card->redemption_code = \"FCJ7GEY4HO8WR16Q\";\n$purchase->gift_card = $gift_card;\n\n// Create a preview invoice collection\ntry {\n  $previewCollection = Recurly_Purchase::pending($purchase);\n} catch (Recurly_ValidationError $e) {\n  // You can get an idea why a purchase failed looking at these objects:\n  var_dump($e);\n} "},{"language":"ruby","code":"require 'securerandom'\n\npurchase = Recurly::Purchase.new({\n  currency: 'USD',\n  collection_method: :automatic,\n  account: {\n    account_code: SecureRandom.uuid,\n    billing_info: {\n      first_name: 'Benjamin',\n      last_name: 'Du Monde',\n      address1: '400 Alabama St',\n      city: 'San Francisco',\n      state: 'CA',\n      zip: '94110',\n      country: 'US',\n      number: '4111-1111-1111-1111',\n      month: 12,\n      year: 2019,\n    },\n    shipping_addresses: [\n      {\n        first_name: 'Lon',\n        last_name: 'Dorner',\n        address1: '400 Alabama St',\n        city: 'San Francisco',\n        state: 'CA',\n        zip: '94110',\n        country: 'US',\n        nickname: 'home',\n      }\n    ]\n  },\n  subscriptions: [\n    {\n      plan_code: \"gold\",\n    }\n  ],\n  adjustments: [\n    {product_code: SecureRandom.uuid, unit_amount_in_cents: 1_000, quantity: 1, revenue_schedule_type: :at_invoice},\n  ],\n  shipping_fees: [\n    {\n      shipping_method_code: 'fast_fast_fast',\n      shipping_amount_in_cents: '999'\n    }\n  ],\n  coupon_codes: [\n    \"COUPON123\",\n    \"COUPON345\",\n  ],\n  gift_card: {\n    redemption_code: \"BC3749AB38371F273\"\n  }\n})\n\nbegin\n  preview_collection = Recurly::Purchase.pending!(purchase)\n  puts preview_collection.inspect\nrescue Recurly::Resource::Invalid => e\n  puts e.inspect\n  # Invalid data\nend"},{"language":"python","code":"purchase = recurly.Purchase(\n  currency = 'USD',\n  account = recurly.Account(\n    account_code = 'account-code-123',\n    billing_info = recurly.BillingInfo(\n        first_name = 'Benjamin',\n        last_name = 'DuMonde',\n        number = '4111-1111-1111-1111',\n        verification_value = '123',\n        month = 11,\n        year = 2020,\n        address1 = '123 Main St',\n        city = 'New Orleans',\n        state = 'LA',\n        zip = '70114',\n        country = 'US',\n    ),\n    shipping_addresses = [\n      recurly.ShippingAddress(\n          first_name = 'Lon',\n          last_name = 'Dorner',\n          address1 = '400 Alabama St',\n          city = 'San Francisco',\n          state = 'CA',\n          zip = '94110',\n          country = 'US',\n          nickname = 'home'\n      )\n    ]\n  ),\n  subscriptions = [\n      recurly.Subscription(plan_code = 'gold')\n  ],\n  adjustments = [\n      recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',\n                         quantity=1),\n      recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',\n                         quantity=2),\n  ],\n  shipping_fees = [\n    recurly.ShippingFee(\n      shipping_method_code = 'fast_fast_fast',\n      shipping_amount_in_cents = 999\n    )\n  ]\n)\n\npreview_collection = purchase.pending()\nprint(preview_collection)"},{"language":"csharp","code":"var accountCode = \"benjamin-du-monde\";\nvar currency = \"USD\";\nvar planCode = \"surveillance-pro\";\nvar couponCode = \"surveillance-podcast-promo\";\nvar giftCardRedemptionCode = \"8Z5VE6IRMWJDHU4P\";\n\n// We can create a purchase object from an account code or an Account object (first argument).\n// Use the Account object when you want create a new account. This works similar to Subscription.\nvar purchase = new Purchase(accountCode, currency);\n\nvar shipAddr = new ShippingAddress();\nshipAddr.Address1 = \"400 Alabama St\";\nshipAddr.City = \"San Francisco\";\nshipAddr.State = \"CA\";\nshipAddr.Country = \"US\";\nshipAddr.Zip = \"94110\";\nshipAddr.FirstName = \"Lon\";\nshipAddr.LastName = \"Dorner\";\nshipAddr.Nickname = \"home\";\npurchase.Account.ShippingAddresses.Add(shipAddr);\n\n// Add multiple adjustments (optional if subscription[s] included)\npurchase.Adjustments.Add(new Adjustment(4000, \"HD Camera\", 5));\npurchase.Adjustments.Add(new Adjustment(1000, \"Motion Sensor\", 10));\n\n// Add multiple subscriptions (optional if adjustment[s] included)\npurchase.Subscriptions.Add(new Subscription(planCode));\n\n// Add shipping fees\nvar shippingFee = new ShippingFee()\n{\n    ShippingMethodCode = \"fast_fast_fast\",\n    ShippingAmountInCents = 999\n};\npurchase.ShippingFees = new List<ShippingFee>();\npurchase.ShippingFees.Add(shippingFee);\n\n// Add multiple coupon codes the customer may have (optional)\npurchase.CouponCodes.Add(couponCode);\n\n// Redeem a gift card with this purchase if the customer has redemption code (optional)\npurchase.GiftCardRedemptionCode = giftCardRedemptionCode;\n\n// For manual invoicing\n// purchase.CollectionMethod = Invoice.Collection.Manual;\n// purchase.NetTerms = 30;\n\n// Previewing allows us to run all calculations and validations without running the\n// transactions yet. This allows us to check the information and show the customer\n// the the detailed invoices before they confirm the purchase.\nvar previewCollection = Purchase.Pending(purchase);"}]},"method":"post","results":{"codes":[{"name":"","code":"<invoice_collection>\n  <charge_invoice>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions\"/>\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    <shipping_address>\n      <first_name>Lon</first_name>\n      <last_name>Doner</last_name>\n      <address1>221B Baker St.</address1>\n      <address2></address2>\n      <city>London</city>\n      <state></state>\n      <zip>W1K 6AH</zip>\n      <country>GB</country>\n      <phone></phone>\n    </shipping_address>\n    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>\n    <state>paid</state>\n    <invoice_number_prefix/>\n    <invoice_number type=\"integer\">1007</invoice_number>\n    <po_number nil=\"nil\"/>\n    <vat_number nil=\"nil\"/>\n    <subtotal_in_cents type=\"integer\">2000</subtotal_in_cents>\n    <discount_in_cents type=\"integer\">0</discount_in_cents>\n    <due_on type=\"datetime\">2018-01-30T21:11:50Z</due_on>\n    <balance_in_cents type=\"integer\">0</balance_in_cents>\n    <type>charge</type>\n    <origin>purchase</origin>\n    <credit_invoices href=\"https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices\"/>\n    <refundable_total_in_cents type=\"integer\">2000</refundable_total_in_cents>\n    <credit_payments type=\"array\">\n    </credit_payments>\n    <tax_in_cents type=\"integer\">424</tax_in_cents>\n    <total_in_cents type=\"integer\">5274</total_in_cents>\n    <currency>EUR</currency>\n    <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n    <closed_at type=\"datetime\">2016-08-03T16:26:26Z</closed_at>\n    <terms_and_conditions nil=\"nil\"/>\n    <customer_notes nil=\"nil\"/>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.0875</tax_rate>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/redemptions\"/>\n    <line_items type=\"array\">\n      <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd\" type=\"charge\">\n        <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n        <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1007\"/>\n        <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41\"/>\n        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>\n        <state>invoiced</state>\n        <description>Setup fee: Gold plan</description>\n        <accounting_code nil=\"nil\"/>\n        <product_code>gold</product_code>\n        <origin>setup_fee</origin>\n        <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n        <quantity type=\"integer\">1</quantity>\n        <discount_in_cents type=\"integer\">0</discount_in_cents>\n        <tax_in_cents type=\"integer\">70</tax_in_cents>\n        <total_in_cents type=\"integer\">870</total_in_cents>\n        <currency>EUR</currency>\n        <taxable type=\"boolean\">false</taxable>\n        <tax_type>usst</tax_type>\n        <tax_region>CA</tax_region>\n        <tax_rate type=\"float\">0.0875</tax_rate>\n        <tax_exempt type=\"boolean\">false</tax_exempt>\n        <tax_code nil=\"nil\"/>\n        <start_date type=\"datetime\">2016-08-03T16:26:26Z</start_date>\n        <end_date nil=\"nil\"/>\n        <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n        <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n        <revenue_schedule_type>evenly</revenue_schedule_type>\n      </adjustment>\n      <!-- Continued... -->\n    </line_items>\n    <transactions type=\"array\">\n      <!-- Detail. -->\n    </transactions>\n    <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/invoices/1007/refund\" method=\"post\"/>\n  </charge_invoice>\n  <credit_invoices type=\"array\">\n  </credit_invoices>\n</invoice_collection>","language":"xml","status":200}]},"settings":"","auth":"required","params":[{"_id":"591b66df7d2cb40f00d471d6","ref":"","in":"body","required":true,"desc":"An account object. This can be an existing account or a new account. If using a new account and adding shipping addresses, the last shipping address in the list will apply to every subscription and adjustment in the purchase.","default":"","type":"object","name":"account"},{"_id":"591b66df7d2cb40f00d471d5","ref":"","in":"body","required":true,"desc":"This should be a list of Adjustment objects. Required if there are no subscriptions.","default":"","type":"array_object","name":"adjustments"},{"_id":"591b66df7d2cb40f00d471d4","ref":"","in":"body","required":false,"desc":"The collection method for the invoice (`automatic` or `manual`).","default":"","type":"string","name":"collection_method"},{"_id":"591b66df7d2cb40f00d471d3","ref":"","in":"body","required":false,"desc":"The 3 letter currency code for the adjustments.","default":"","type":"string","name":"currency"},{"_id":"591b66df7d2cb40f00d471d2","ref":"","in":"body","required":false,"desc":"A po number for the resulting invoice.","default":"","type":"string","name":"po_number"},{"_id":"591b66df7d2cb40f00d471d1","ref":"","in":"body","required":false,"desc":"The net terms for the invoice","default":"","type":"int","name":"net_terms"},{"_id":"5955762bba6cff002966ae31","ref":"","in":"body","required":false,"desc":"A gift card with a redemption code to apply to this purchase","default":"","type":"object","name":"gift_card"},{"_id":"5955762bba6cff002966ae30","ref":"","in":"body","required":false,"desc":"A list of coupon codes to apply to this purchase","default":"","type":"array_string","name":"coupon_codes"},{"_id":"5955762bba6cff002966ae2f","ref":"","in":"body","required":true,"desc":"A list of Subscriptions to invoice in this purchase. Required if there are no adjustments.","default":"","type":"array_object","name":"subscriptions"},{"_id":"59d699316d3f930010333002","ref":"","in":"body","required":false,"desc":"Optional notes to show customer on the invoice. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.","default":"","type":"string","name":"customer_notes"},{"_id":"59d699316d3f930010333001","ref":"","in":"body","required":false,"desc":"Optional terms and conditions to show customer on the invoice. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"terms_and_conditions"},{"_id":"59d699316d3f930010333000","ref":"","in":"body","required":false,"desc":"Optional VAT reverse charge notes to show the customer on the invoice. Only appears if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"vat_reverse_charge_notes"},{"_id":"5abbd2f4afef010029981f81","ref":"","in":"body","required":false,"desc":"All subscriptions and adjustments on the purchase will use this shipping address unless they specify one of their own. Any subscriptions for which this address might apply will also use it in future renewals unless changed or removed. Cannot be used if a new shipping address is created at the account level.","default":"","type":"long","name":"shipping_address_id"},{"_id":"5ce443d79e6a78002aae5de5","ref":"","in":"body","required":false,"desc":"Array of `<shipping_fee>` objects, each containing a `shipping_method_code` and a `shipping_amount_in_cents`.","default":"","type":"array_object","name":"shipping_fees"},{"_id":"5daf5ad9bb1f4d038f94d438","ref":"","in":"body","required":false,"desc":"Add this single shipping address to the account and apply it to the purchase.","default":"","type":"object","name":"shipping_address"}],"url":"/purchases/pending"},"isReference":true,"order":3,"body":"","excerpt":"A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type.\n\nUse for Adyen HPP transaction requests. This runs the validations but not the transactions.\n\nFor additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping","slug":"pending-purchase","type":"post","title":"Pending Purchase","__v":13,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postPending Purchase

A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type. Use for Adyen HPP transaction requests. This runs the validations but not the transactions. For additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping

Body Params

account:
required
object
An account object. This can be an existing account or a new account. If using a new account and adding shipping addresses, the last shipping address in the list will apply to every subscription and adjustment in the purchase.
adjustments:
required
array of objects
This should be a list of Adjustment objects. Required if there are no subscriptions.
collection_method:
string
The collection method for the invoice (`automatic` or `manual`).
currency:
string
The 3 letter currency code for the adjustments.
po_number:
string
A po number for the resulting invoice.
net_terms:
integer
The net terms for the invoice
gift_card:
object
A gift card with a redemption code to apply to this purchase
coupon_codes:
array of strings
A list of coupon codes to apply to this purchase
subscriptions:
required
array of objects
A list of Subscriptions to invoice in this purchase. Required if there are no adjustments.
customer_notes:
string
Optional notes to show customer on the invoice. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.
terms_and_conditions:
string
Optional terms and conditions to show customer on the invoice. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Custom notes will stay with a subscription on all renewals.
vat_reverse_charge_notes:
string
Optional VAT reverse charge notes to show the customer on the invoice. Only appears if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Custom notes will stay with a subscription on all renewals.
shipping_address_id:
long
All subscriptions and adjustments on the purchase will use this shipping address unless they specify one of their own. Any subscriptions for which this address might apply will also use it in future renewals unless changed or removed. Cannot be used if a new shipping address is created at the account level.
shipping_fees:
array of objects
Array of `<shipping_fee>` objects, each containing a `shipping_method_code` and a `shipping_amount_in_cents`.
shipping_address:
object
Add this single shipping address to the account and apply it to the purchase.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<purchase>
  <collection_method>automatic</collection_method>
  <currency>USD</currency>
  <customer_notes>Some notes for the customer.</customer_notes>
  <terms_and_conditions>Our company terms and conditions.</terms_and_conditions>
  <vat_reverse_charge_notes>Vat reverse charge notes.</vat_reverse_charge_notes>
  <account>
    <account_code>c442b36c-c64f-41d7-b8e1-9c04e7a6ff82</account_code>
    <!-- email is required for this endpoint -->
    <email>benjamin.dumonde@example.com</email>
    <billing_info>
      <address1>400 Alabama St</address1>
      <city>San Francisco</city>
      <country>US</country>
      <first_name>Benjamin</first_name>
      <last_name>Du Monde</last_name>
      <month>12</month>
      <number>4111-1111-1111-1111</number>
      <state>CA</state>
      <year>2019</year>
      <zip>94110</zip>
    </billing_info>
  </account>
  <adjustments>
    <adjustment>
      <product_code>4549449c-5870-4845-b672-1d07f15e87dd</product_code>
      <quantity>1</quantity>
      <revenue_schedule_type>at_invoice</revenue_schedule_type>
      <unit_amount_in_cents>1000</unit_amount_in_cents>
      <description>Description of this adjustment</description>
    </adjustment>
  </adjustments>
  <subscriptions>
    <subscription>
      <plan_code>plan1</plan_code>
    </subscription>
  </subscriptions>
  <shipping_fees>
    <shipping_fee>
      <shipping_method_code>fast_fast_fast</shipping_method_code>
      <shipping_amount_in_cents>999</shipping_amount_in_cents>
    </shipping_fee>
  </shipping_fees>
  <shipping_address>
    <first_name>Lon</first_name>
    <last_name>Doner</last_name>        
    <address1>221B Baker St.</address1>
    <city>London</city>
    <state></state>
    <zip>W1K 6AH</zip>
    <country>GB</country>
    <nickname>Home</nickname>
  </shipping_address>
  <coupon_codes>
  	<coupon_code>coupon1</coupon_code>
    <coupon_code>coupon2</coupon_code>
  </coupon_codes>
  <gift_card>
    <redemption_code>ABC1234</redemption_code>
  </gift_card>
</purchase>
<?php

$purchase = new Recurly_Purchase();
$purchase->currency = 'USD';
$purchase->collection_method = 'automatic';
$purchase->account = new Recurly_Account();
$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';
$purchase->account->email = "verena@example.com";
$purchase->account->first_name = "Benjamin";
$purchase->account->last_name = "Du Monde";
$purchase->account->address->phone = "555-555-5555";
$purchase->account->address->address1 = "123 Main St.";
$purchase->account->address->city = "San Francisco";
$purchase->account->address->state = "CA";
$purchase->account->address->zip = "94110";
$purchase->account->address->country = "US";

$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2019;
$billing_info->verification_value = '123';
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';

$purchase->account->billing_info = $billing_info;

$shipping_address = new Recurly_ShippingAddress();
$shipping_address->first_name = 'Lon';
$shipping_address->last_name = 'Dorner';
$shipping_address->address1 = '400 Dolores St';
$shipping_address->city = 'San Francisco';
$shipping_address->state = 'CA';
$shipping_address->country = 'US';
$shipping_address->zip = '94110';
$shipping_address->nickname = 'Home';

$purchase->account->shipping_addresses = array($shipping_address);

$adjustment = new Recurly_Adjustment();
$adjustment->unit_amount_in_cents = 1000;
$adjustment->quantity = 1;

$purchase->adjustments = array($adjustment);

$subscription = new Recurly_Subscription();
$subscription->plan_code = 'pp';

$shipping_fee = new Recurly_ShippingFee();
$shipping_fee->shipping_method_code = 'fast_fast_fast';
$shipping_fee->shipping_amount_in_cents = 999;

$purchase->subscriptions = array($subscription);

$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');

$gift_card = new Recurly_GiftCard();
$gift_card->redemption_code = "FCJ7GEY4HO8WR16Q";
$purchase->gift_card = $gift_card;

// Create a preview invoice collection
try {
  $previewCollection = Recurly_Purchase::pending($purchase);
} catch (Recurly_ValidationError $e) {
  // You can get an idea why a purchase failed looking at these objects:
  var_dump($e);
} 
require 'securerandom'

purchase = Recurly::Purchase.new({
  currency: 'USD',
  collection_method: :automatic,
  account: {
    account_code: SecureRandom.uuid,
    billing_info: {
      first_name: 'Benjamin',
      last_name: 'Du Monde',
      address1: '400 Alabama St',
      city: 'San Francisco',
      state: 'CA',
      zip: '94110',
      country: 'US',
      number: '4111-1111-1111-1111',
      month: 12,
      year: 2019,
    },
    shipping_addresses: [
      {
        first_name: 'Lon',
        last_name: 'Dorner',
        address1: '400 Alabama St',
        city: 'San Francisco',
        state: 'CA',
        zip: '94110',
        country: 'US',
        nickname: 'home',
      }
    ]
  },
  subscriptions: [
    {
      plan_code: "gold",
    }
  ],
  adjustments: [
    {product_code: SecureRandom.uuid, unit_amount_in_cents: 1_000, quantity: 1, revenue_schedule_type: :at_invoice},
  ],
  shipping_fees: [
    {
      shipping_method_code: 'fast_fast_fast',
      shipping_amount_in_cents: '999'
    }
  ],
  coupon_codes: [
    "COUPON123",
    "COUPON345",
  ],
  gift_card: {
    redemption_code: "BC3749AB38371F273"
  }
})

begin
  preview_collection = Recurly::Purchase.pending!(purchase)
  puts preview_collection.inspect
rescue Recurly::Resource::Invalid => e
  puts e.inspect
  # Invalid data
end
purchase = recurly.Purchase(
  currency = 'USD',
  account = recurly.Account(
    account_code = 'account-code-123',
    billing_info = recurly.BillingInfo(
        first_name = 'Benjamin',
        last_name = 'DuMonde',
        number = '4111-1111-1111-1111',
        verification_value = '123',
        month = 11,
        year = 2020,
        address1 = '123 Main St',
        city = 'New Orleans',
        state = 'LA',
        zip = '70114',
        country = 'US',
    ),
    shipping_addresses = [
      recurly.ShippingAddress(
          first_name = 'Lon',
          last_name = 'Dorner',
          address1 = '400 Alabama St',
          city = 'San Francisco',
          state = 'CA',
          zip = '94110',
          country = 'US',
          nickname = 'home'
      )
    ]
  ),
  subscriptions = [
      recurly.Subscription(plan_code = 'gold')
  ],
  adjustments = [
      recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',
                         quantity=1),
      recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',
                         quantity=2),
  ],
  shipping_fees = [
    recurly.ShippingFee(
      shipping_method_code = 'fast_fast_fast',
      shipping_amount_in_cents = 999
    )
  ]
)

preview_collection = purchase.pending()
print(preview_collection)
var accountCode = "benjamin-du-monde";
var currency = "USD";
var planCode = "surveillance-pro";
var couponCode = "surveillance-podcast-promo";
var giftCardRedemptionCode = "8Z5VE6IRMWJDHU4P";

// We can create a purchase object from an account code or an Account object (first argument).
// Use the Account object when you want create a new account. This works similar to Subscription.
var purchase = new Purchase(accountCode, currency);

var shipAddr = new ShippingAddress();
shipAddr.Address1 = "400 Alabama St";
shipAddr.City = "San Francisco";
shipAddr.State = "CA";
shipAddr.Country = "US";
shipAddr.Zip = "94110";
shipAddr.FirstName = "Lon";
shipAddr.LastName = "Dorner";
shipAddr.Nickname = "home";
purchase.Account.ShippingAddresses.Add(shipAddr);

// Add multiple adjustments (optional if subscription[s] included)
purchase.Adjustments.Add(new Adjustment(4000, "HD Camera", 5));
purchase.Adjustments.Add(new Adjustment(1000, "Motion Sensor", 10));

// Add multiple subscriptions (optional if adjustment[s] included)
purchase.Subscriptions.Add(new Subscription(planCode));

// Add shipping fees
var shippingFee = new ShippingFee()
{
    ShippingMethodCode = "fast_fast_fast",
    ShippingAmountInCents = 999
};
purchase.ShippingFees = new List<ShippingFee>();
purchase.ShippingFees.Add(shippingFee);

// Add multiple coupon codes the customer may have (optional)
purchase.CouponCodes.Add(couponCode);

// Redeem a gift card with this purchase if the customer has redemption code (optional)
purchase.GiftCardRedemptionCode = giftCardRedemptionCode;

// For manual invoicing
// purchase.CollectionMethod = Invoice.Collection.Manual;
// purchase.NetTerms = 30;

// Previewing allows us to run all calculations and validations without running the
// transactions yet. This allows us to check the information and show the customer
// the the detailed invoices before they confirm the purchase.
var previewCollection = Purchase.Pending(purchase);

Result Format

<invoice_collection>
  <charge_invoice>
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <subscriptions href="https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions"/>
    <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>
    <shipping_address>
      <first_name>Lon</first_name>
      <last_name>Doner</last_name>
      <address1>221B Baker St.</address1>
      <address2></address2>
      <city>London</city>
      <state></state>
      <zip>W1K 6AH</zip>
      <country>GB</country>
      <phone></phone>
    </shipping_address>
    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>
    <state>paid</state>
    <invoice_number_prefix/>
    <invoice_number type="integer">1007</invoice_number>
    <po_number nil="nil"/>
    <vat_number nil="nil"/>
    <subtotal_in_cents type="integer">2000</subtotal_in_cents>
    <discount_in_cents type="integer">0</discount_in_cents>
    <due_on type="datetime">2018-01-30T21:11:50Z</due_on>
    <balance_in_cents type="integer">0</balance_in_cents>
    <type>charge</type>
    <origin>purchase</origin>
    <credit_invoices href="https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices"/>
    <refundable_total_in_cents type="integer">2000</refundable_total_in_cents>
    <credit_payments type="array">
    </credit_payments>
    <tax_in_cents type="integer">424</tax_in_cents>
    <total_in_cents type="integer">5274</total_in_cents>
    <currency>EUR</currency>
    <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
    <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
    <closed_at type="datetime">2016-08-03T16:26:26Z</closed_at>
    <terms_and_conditions nil="nil"/>
    <customer_notes nil="nil"/>
    <tax_type>usst</tax_type>
    <tax_region>CA</tax_region>
    <tax_rate type="float">0.0875</tax_rate>
    <net_terms type="integer">0</net_terms>
    <collection_method>automatic</collection_method>
    <redemptions href="https://your-subdomain.recurly.com/v2/invoices/1007/redemptions"/>
    <line_items type="array">
      <adjustment href="https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd" type="charge">
        <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
        <invoice href="https://your-subdomain.recurly.com/v2/invoices/1007"/>
        <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41"/>
        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>
        <state>invoiced</state>
        <description>Setup fee: Gold plan</description>
        <accounting_code nil="nil"/>
        <product_code>gold</product_code>
        <origin>setup_fee</origin>
        <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
        <quantity type="integer">1</quantity>
        <discount_in_cents type="integer">0</discount_in_cents>
        <tax_in_cents type="integer">70</tax_in_cents>
        <total_in_cents type="integer">870</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-08-03T16:26:26Z</start_date>
        <end_date nil="nil"/>
        <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
        <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
        <revenue_schedule_type>evenly</revenue_schedule_type>
      </adjustment>
      <!-- Continued... -->
    </line_items>
    <transactions type="array">
      <!-- Detail. -->
    </transactions>
    <a name="refund" href="https://your-subdomain.recurly.com/v2/invoices/1007/refund" method="post"/>
  </charge_invoice>
  <credit_invoices type="array">
  </credit_invoices>
</invoice_collection>


{"_id":"5dd5f0b02d076f0220ca8c3f","project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","category":"5dd5f0b02d076f0220ca8b96","user":"5b7ed56347fe1c0003545884","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-09-13T12:14:18.392Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"name":"","code":"<invoice_collection>\n  <charge_invoice>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions\"/>\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    <shipping_address>\n      <first_name>Lon</first_name>\n      <last_name>Doner</last_name>\n      <address1>221B Baker St.</address1>\n      <address2></address2>\n      <city>London</city>\n      <state></state>\n      <zip>W1K 6AH</zip>\n      <country>GB</country>\n      <phone></phone>\n    </shipping_address>\n    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>\n    <state>paid</state>\n    <invoice_number_prefix/>\n    <invoice_number type=\"integer\">1007</invoice_number>\n    <po_number nil=\"nil\"/>\n    <vat_number nil=\"nil\"/>\n    <subtotal_in_cents type=\"integer\">2000</subtotal_in_cents>\n    <discount_in_cents type=\"integer\">0</discount_in_cents>\n    <due_on type=\"datetime\">2018-01-30T21:11:50Z</due_on>\n    <balance_in_cents type=\"integer\">0</balance_in_cents>\n    <type>charge</type>\n    <origin>purchase</origin>\n    <credit_invoices href=\"https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices\"/>\n    <refundable_total_in_cents type=\"integer\">2000</refundable_total_in_cents>\n    <credit_payments type=\"array\">\n    </credit_payments>\n    <tax_in_cents type=\"integer\">424</tax_in_cents>\n    <total_in_cents type=\"integer\">5274</total_in_cents>\n    <currency>EUR</currency>\n    <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n    <closed_at type=\"datetime\">2016-08-03T16:26:26Z</closed_at>\n    <terms_and_conditions nil=\"nil\"/>\n    <customer_notes nil=\"nil\"/>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.0875</tax_rate>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/redemptions\"/>\n    <line_items type=\"array\">\n      <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd\" type=\"charge\">\n        <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n        <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1007\"/>\n        <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41\"/>\n        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>\n        <state>invoiced</state>\n        <description>Setup fee: Gold plan</description>\n        <accounting_code nil=\"nil\"/>\n        <product_code>gold</product_code>\n        <origin>setup_fee</origin>\n        <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n        <quantity type=\"integer\">1</quantity>\n        <discount_in_cents type=\"integer\">0</discount_in_cents>\n        <tax_in_cents type=\"integer\">70</tax_in_cents>\n        <total_in_cents type=\"integer\">870</total_in_cents>\n        <currency>EUR</currency>\n        <taxable type=\"boolean\">false</taxable>\n        <tax_type>usst</tax_type>\n        <tax_region>CA</tax_region>\n        <tax_rate type=\"float\">0.0875</tax_rate>\n        <tax_exempt type=\"boolean\">false</tax_exempt>\n        <tax_code nil=\"nil\"/>\n        <start_date type=\"datetime\">2016-08-03T16:26:26Z</start_date>\n        <end_date nil=\"nil\"/>\n        <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n        <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n        <revenue_schedule_type>evenly</revenue_schedule_type>\n      </adjustment>\n      <!-- Continued... -->\n    </line_items>\n    <transactions type=\"array\">\n      <!-- Detail. -->\n    </transactions>\n    <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/invoices/1007/refund\" method=\"post\"/>\n  </charge_invoice>\n  <credit_invoices type=\"array\">\n  </credit_invoices>\n</invoice_collection>","language":"xml","status":200}]},"method":"post","examples":{"codes":[{"language":"ruby","code":"captured_collection = Purchase.capture!(transaction_uuid)"}]},"auth":"required","params":[],"url":"/purchases/transaction-uuid-:transaction_uuid/capture"},"isReference":true,"order":4,"body":"","excerpt":"A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type.\n\nCapture an open Authorization request","slug":"capture-purchase","type":"post","title":"Capture Purchase","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCapture Purchase

A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type. Capture an open Authorization request

Definition

{{ api_url }}{{ page_api_url }}

Examples

captured_collection = Purchase.capture!(transaction_uuid)

Result Format

<invoice_collection>
  <charge_invoice>
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <subscriptions href="https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions"/>
    <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>
    <shipping_address>
      <first_name>Lon</first_name>
      <last_name>Doner</last_name>
      <address1>221B Baker St.</address1>
      <address2></address2>
      <city>London</city>
      <state></state>
      <zip>W1K 6AH</zip>
      <country>GB</country>
      <phone></phone>
    </shipping_address>
    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>
    <state>paid</state>
    <invoice_number_prefix/>
    <invoice_number type="integer">1007</invoice_number>
    <po_number nil="nil"/>
    <vat_number nil="nil"/>
    <subtotal_in_cents type="integer">2000</subtotal_in_cents>
    <discount_in_cents type="integer">0</discount_in_cents>
    <due_on type="datetime">2018-01-30T21:11:50Z</due_on>
    <balance_in_cents type="integer">0</balance_in_cents>
    <type>charge</type>
    <origin>purchase</origin>
    <credit_invoices href="https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices"/>
    <refundable_total_in_cents type="integer">2000</refundable_total_in_cents>
    <credit_payments type="array">
    </credit_payments>
    <tax_in_cents type="integer">424</tax_in_cents>
    <total_in_cents type="integer">5274</total_in_cents>
    <currency>EUR</currency>
    <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
    <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
    <closed_at type="datetime">2016-08-03T16:26:26Z</closed_at>
    <terms_and_conditions nil="nil"/>
    <customer_notes nil="nil"/>
    <tax_type>usst</tax_type>
    <tax_region>CA</tax_region>
    <tax_rate type="float">0.0875</tax_rate>
    <net_terms type="integer">0</net_terms>
    <collection_method>automatic</collection_method>
    <redemptions href="https://your-subdomain.recurly.com/v2/invoices/1007/redemptions"/>
    <line_items type="array">
      <adjustment href="https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd" type="charge">
        <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
        <invoice href="https://your-subdomain.recurly.com/v2/invoices/1007"/>
        <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41"/>
        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>
        <state>invoiced</state>
        <description>Setup fee: Gold plan</description>
        <accounting_code nil="nil"/>
        <product_code>gold</product_code>
        <origin>setup_fee</origin>
        <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
        <quantity type="integer">1</quantity>
        <discount_in_cents type="integer">0</discount_in_cents>
        <tax_in_cents type="integer">70</tax_in_cents>
        <total_in_cents type="integer">870</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-08-03T16:26:26Z</start_date>
        <end_date nil="nil"/>
        <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
        <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
        <revenue_schedule_type>evenly</revenue_schedule_type>
      </adjustment>
      <!-- Continued... -->
    </line_items>
    <transactions type="array">
      <!-- Detail. -->
    </transactions>
    <a name="refund" href="https://your-subdomain.recurly.com/v2/invoices/1007/refund" method="post"/>
  </charge_invoice>
  <credit_invoices type="array">
  </credit_invoices>
</invoice_collection>


{"_id":"5dd5f0b02d076f0220ca8c40","project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","category":"5dd5f0b02d076f0220ca8b96","user":"5b7ed56347fe1c0003545884","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-09-13T12:22:19.541Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"ruby","code":"canceled_collection = Purchase.cancel!(tr_uuid)"}]},"method":"post","results":{"codes":[{"name":"","code":"<invoice_collection>\n  <charge_invoice>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions\"/>\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    <shipping_address>\n      <first_name>Lon</first_name>\n      <last_name>Doner</last_name>\n      <address1>221B Baker St.</address1>\n      <address2></address2>\n      <city>London</city>\n      <state></state>\n      <zip>W1K 6AH</zip>\n      <country>GB</country>\n      <phone></phone>\n    </shipping_address>\n    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>\n    <state>failed</state>\n    <invoice_number_prefix/>\n    <invoice_number type=\"integer\">1007</invoice_number>\n    <po_number nil=\"nil\"/>\n    <vat_number nil=\"nil\"/>\n    <subtotal_in_cents type=\"integer\">2000</subtotal_in_cents>\n    <discount_in_cents type=\"integer\">0</discount_in_cents>\n    <due_on type=\"datetime\">2018-01-30T21:11:50Z</due_on>\n    <balance_in_cents type=\"integer\">0</balance_in_cents>\n    <type>charge</type>\n    <origin>purchase</origin>\n    <credit_invoices href=\"https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices\"/>\n    <refundable_total_in_cents type=\"integer\">2000</refundable_total_in_cents>\n    <credit_payments type=\"array\">\n    </credit_payments>\n    <tax_in_cents type=\"integer\">424</tax_in_cents>\n    <total_in_cents type=\"integer\">5274</total_in_cents>\n    <currency>EUR</currency>\n    <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n    <closed_at type=\"datetime\">2016-08-03T16:26:26Z</closed_at>\n    <terms_and_conditions nil=\"nil\"/>\n    <customer_notes nil=\"nil\"/>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.0875</tax_rate>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/invoices/1007/redemptions\"/>\n    <line_items type=\"array\">\n      <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd\" type=\"charge\">\n        <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n        <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1007\"/>\n        <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41\"/>\n        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>\n        <state>invoiced</state>\n        <description>Setup fee: Gold plan</description>\n        <accounting_code nil=\"nil\"/>\n        <product_code>gold</product_code>\n        <origin>setup_fee</origin>\n        <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n        <quantity type=\"integer\">1</quantity>\n        <discount_in_cents type=\"integer\">0</discount_in_cents>\n        <tax_in_cents type=\"integer\">70</tax_in_cents>\n        <total_in_cents type=\"integer\">870</total_in_cents>\n        <currency>EUR</currency>\n        <taxable type=\"boolean\">false</taxable>\n        <tax_type>usst</tax_type>\n        <tax_region>CA</tax_region>\n        <tax_rate type=\"float\">0.0875</tax_rate>\n        <tax_exempt type=\"boolean\">false</tax_exempt>\n        <tax_code nil=\"nil\"/>\n        <start_date type=\"datetime\">2016-08-03T16:26:26Z</start_date>\n        <end_date nil=\"nil\"/>\n        <created_at type=\"datetime\">2016-08-03T16:26:26Z</created_at>\n        <updated_at type=\"datetime\">2016-08-03T16:26:26Z</updated_at>\n        <revenue_schedule_type>evenly</revenue_schedule_type>\n      </adjustment>\n      <!-- Continued... -->\n    </line_items>\n    <transactions type=\"array\">\n      <!-- Detail. -->\n    </transactions>\n    <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/invoices/1007/refund\" method=\"post\"/>\n  </charge_invoice>\n  <credit_invoices type=\"array\">\n  </credit_invoices>\n</invoice_collection>","language":"xml","status":200}]},"settings":"","auth":"required","params":[],"url":"/purchases/transaction-uuid-:transaction_uuid/cancel"},"isReference":true,"order":5,"body":"","excerpt":"A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type.\n\nCanel an open Authorization request","slug":"cancel-purchase","type":"post","title":"Cancel Purchase","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCancel Purchase

A purchase is a hybrid checkout containing at least one or more subscriptions or one-time charges (adjustments) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. A purchase is only a request data type and is not persistent in Recurly and an invoice collection will be the returned type. Canel an open Authorization request

Definition

{{ api_url }}{{ page_api_url }}

Examples

canceled_collection = Purchase.cancel!(tr_uuid)

Result Format

<invoice_collection>
  <charge_invoice>
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <subscriptions href="https://your-subdomain.recurly.com/v2/invoices/1007/subscriptions"/>
    <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>
    <shipping_address>
      <first_name>Lon</first_name>
      <last_name>Doner</last_name>
      <address1>221B Baker St.</address1>
      <address2></address2>
      <city>London</city>
      <state></state>
      <zip>W1K 6AH</zip>
      <country>GB</country>
      <phone></phone>
    </shipping_address>
    <uuid>37c0057d2f641f4e2fcbda4b5b833633</uuid>
    <state>failed</state>
    <invoice_number_prefix/>
    <invoice_number type="integer">1007</invoice_number>
    <po_number nil="nil"/>
    <vat_number nil="nil"/>
    <subtotal_in_cents type="integer">2000</subtotal_in_cents>
    <discount_in_cents type="integer">0</discount_in_cents>
    <due_on type="datetime">2018-01-30T21:11:50Z</due_on>
    <balance_in_cents type="integer">0</balance_in_cents>
    <type>charge</type>
    <origin>purchase</origin>
    <credit_invoices href="https://your-subdomain.recurly.com/v2/invoices/1325/credit_invoices"/>
    <refundable_total_in_cents type="integer">2000</refundable_total_in_cents>
    <credit_payments type="array">
    </credit_payments>
    <tax_in_cents type="integer">424</tax_in_cents>
    <total_in_cents type="integer">5274</total_in_cents>
    <currency>EUR</currency>
    <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
    <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
    <closed_at type="datetime">2016-08-03T16:26:26Z</closed_at>
    <terms_and_conditions nil="nil"/>
    <customer_notes nil="nil"/>
    <tax_type>usst</tax_type>
    <tax_region>CA</tax_region>
    <tax_rate type="float">0.0875</tax_rate>
    <net_terms type="integer">0</net_terms>
    <collection_method>automatic</collection_method>
    <redemptions href="https://your-subdomain.recurly.com/v2/invoices/1007/redemptions"/>
    <line_items type="array">
      <adjustment href="https://your-subdomain.recurly.com/v2/adjustments/37c0057d2a3ace0c3f3d674ae89fdabd" type="charge">
        <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
        <invoice href="https://your-subdomain.recurly.com/v2/invoices/1007"/>
        <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/37c0057cb105f67b6b8a1146f7b59c41"/>
        <uuid>37c0057d2a3ace0c3f3d674ae89fdabd</uuid>
        <state>invoiced</state>
        <description>Setup fee: Gold plan</description>
        <accounting_code nil="nil"/>
        <product_code>gold</product_code>
        <origin>setup_fee</origin>
        <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
        <quantity type="integer">1</quantity>
        <discount_in_cents type="integer">0</discount_in_cents>
        <tax_in_cents type="integer">70</tax_in_cents>
        <total_in_cents type="integer">870</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-08-03T16:26:26Z</start_date>
        <end_date nil="nil"/>
        <created_at type="datetime">2016-08-03T16:26:26Z</created_at>
        <updated_at type="datetime">2016-08-03T16:26:26Z</updated_at>
        <revenue_schedule_type>evenly</revenue_schedule_type>
      </adjustment>
      <!-- Continued... -->
    </line_items>
    <transactions type="array">
      <!-- Detail. -->
    </transactions>
    <a name="refund" href="https://your-subdomain.recurly.com/v2/invoices/1007/refund" method="post"/>
  </charge_invoice>
  <credit_invoices type="array">
  </credit_invoices>
</invoice_collection>


{"_id":"5dd5f0b02d076f0220ca8bd6","category":"5dd5f0b02d076f0220ca8b97","parentDoc":null,"project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","version":"5dd5f0b02d076f0220ca8c44","updates":["56cec52444c5700b0095c02b"],"next":{"pages":[],"description":""},"createdAt":"2015-08-31T20:16:33.273Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"","language":"text"}]},"method":"get","results":{"codes":[{"language":"xml","code":"<account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n  <parent_account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <child_accounts href=\"https://your-subdomain.recurly.com/v2/accounts/1/child_accounts\"/>\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  <notes href=\"https://your-subdomain.recurly.com/v2/accounts/1/notes\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username>verena1234</username>\n  <email>verena@example.com</email>\n  <cc_emails>bob@example.com,susan@example.com</cc_emails>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name>New Company Name</company_name>\n  <vat_number nil=\"nil\"/>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address1>\n    <address2 nil=\"nil\"/>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone nil=\"nil\"/>\n  </address>\n  <accept_language nil=\"nil\"/>\n  <has_live_subscription type=\"boolean\">true</has_live_subscription>\n  <has_active_subscription type=\"boolean\">true</has_active_subscription>\n  <has_future_subscription type=\"boolean\">false</has_future_subscription>\n  <has_canceled_subscription type=\"boolean\">false</has_canceled_subscription>\n  <has_past_due_invoice type=\"boolean\">false</has_past_due_invoice>\n  <hosted_login_token>96e74bd5e14d18e6da463a0d638a2621</hosted_login_token>\n  <created_at type=\"datetime\">2016-07-08T20:59:43Z</created_at>\n  <updated_at type=\"datetime\">2016-07-11T17:56:24Z</updated_at>\n  <closed_at nil=\"nil\"/>\n</account>","name":"","status":200}]},"settings":"","auth":"required","params":[{"_id":"5c88262989b0810013a466ad","ref":"","in":"body","required":false,"desc":"The URL of the parent for the specified account.","default":"","type":"string","name":"parent_account"},{"_id":"5c88262989b0810013a466ac","ref":"","in":"body","required":false,"desc":"The URL of the child accounts for the specified account.","default":"","type":"string","name":"child_accounts"},{"_id":"5ca523c1d177a40373ab99ff","ref":"","in":"body","required":false,"desc":"`self` or `parent`. Determines whether all charges are billed using parent’s billing information or the account itself.  If bill_to = parent, all invoices resulting in charges and credits originating from a child will be created on the parent account. (e.g creating a subscription on the child account will be billed to parent and invoiced on the parent account)","default":"self","type":"string","name":"bill_to"},{"_id":"557f45d07eafa719001d1c2b","ref":"","in":"body","required":false,"desc":"The URL of adjustments for the specified account.","default":"","type":"string","name":"adjustments"},{"_id":"57a21cf65220910e002a1764","ref":"","in":"body","required":false,"desc":"The URL of the account balance for the specified account.","default":"","type":"string","name":"account_balance"},{"_id":"557f45d07eafa719001d1c2a","ref":"","in":"body","required":false,"desc":"The URL of billing info for the specified account.","default":"","type":"string","name":"billing_info"},{"_id":"557f45d07eafa719001d1c29","ref":"","in":"body","required":false,"desc":"The URL of invoices for the specified account.","default":"","type":"string","name":"invoices"},{"_id":"55e4aa556f190c1900a40881","ref":"","in":"body","required":false,"desc":"The URL of the coupon redemption for the specified account.","default":"","type":"string","name":"redemption"},{"_id":"55e4aa556f190c1900a40880","ref":"","in":"body","required":false,"desc":"The URL of subscriptions for the specified account.","default":"","type":"string","name":"subscriptions"},{"_id":"55e4aa556f190c1900a4087f","ref":"","in":"body","required":false,"desc":"The URL of transactions for the specified account.","default":"","type":"string","name":"transactions"},{"_id":"5baa43e11828a9000363f805","ref":"","in":"body","required":false,"desc":"The URL of notes on the account","default":"","type":"string","name":"notes"},{"_id":"55e4aa556f190c1900a4087e","ref":"","in":"body","required":false,"desc":"The unique identifier of the account.","default":"","type":"string","name":"account_code"},{"_id":"55e4aa556f190c1900a4087d","ref":"","in":"body","required":false,"desc":"The state of accounts to return: `active` or `closed`.","default":"","type":"string","name":"state"},{"_id":"55e4aa556f190c1900a4087c","ref":"","in":"body","required":false,"desc":"The username of the account.","default":"","type":"string","name":"username"},{"_id":"55e4aa556f190c1900a4087b","ref":"","in":"body","required":false,"desc":"The email address of the account.","default":"","type":"string","name":"email"},{"_id":"560b18973bcbd80d0077d0c0","ref":"","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":"string","name":"cc_emails"},{"_id":"55e4aa556f190c1900a4087a","ref":"","in":"body","required":false,"desc":"The first name of the account.","default":"","type":"string","name":"first_name"},{"_id":"55e4aa556f190c1900a40879","ref":"","in":"body","required":false,"desc":"The last name of the account.","default":"","type":"string","name":"last_name"},{"_id":"55e4aa556f190c1900a40878","ref":"","in":"body","required":false,"desc":"The company name of the account.","default":"","type":"string","name":"company_name"},{"_id":"55e4aa556f190c1900a40877","ref":"","in":"body","required":false,"desc":"The VAT number of the account (to avoid having the VAT applied).","default":"","type":"string","name":"vat_number"},{"_id":"55e4aa556f190c1900a40876","ref":"","in":"body","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":"55e4aa556f190c1900a40875","ref":"","in":"body","required":false,"desc":"The nested address information of the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`.","default":"","type":"object","name":"address"},{"_id":"57fffdd8c7609a0f0063caaf","ref":"","in":"body","required":false,"desc":"The nested shipping address information of the account: `first_name`, `last_name`, `company_name`, `email`, `phone`, `vat_number`,  `address1`, `address2`, `city`, `state`, `zip`, `country`, `nickname`. You can pass in up to 20 account shipping addresses along with the request to create a new account. When providing a shipping address, the following are required: first_name, last_name, address1, city, state, zip, and country.","default":"","type":"object","name":"shipping_address"},{"_id":"55e4aa556f190c1900a40874","ref":"","in":"body","required":false,"desc":"The ISO 639-1 language code from the user's browser, indicating their preferred language and locale. This attribute is different from `preferred_locale` and does not determine which language emails sent on behalf of the merchant.","default":"","type":"string","name":"accept_language"},{"_id":"55e4aa556f190c1900a40873","ref":"","in":"body","required":false,"desc":"The unique token for automatically logging the account in to the hosted management pages. You may automatically log the user into their hosted management pages by directing the user to: `https://:subdomain.recurly.com/account/:hosted_login_token`.","default":"","type":"string","name":"hosted_login_token"},{"_id":"55e4aa556f190c1900a40872","ref":"","in":"body","required":false,"desc":"The date and time the account was created in Recurly.","default":"","type":"datetime","name":"created_at"},{"_id":"5783dc55359cd219005453ec","ref":"","in":"body","required":false,"desc":"The date and time the account or its billing info was last updated.","default":"","type":"datetime","name":"updated_at"},{"_id":"5783dcff359cd219005453ee","ref":"","in":"body","required":false,"desc":"For closed accounts, the date and time it was closed.","default":"","type":"datetime","name":"closed_at"},{"_id":"58c8255f5cb4fe1b00ec5679","ref":"","in":"body","required":false,"desc":"True if the account has at least one live subscription.","default":"","type":"boolean","name":"has_live_subscription"},{"_id":"58c8255f5cb4fe1b00ec5678","ref":"","in":"body","required":false,"desc":"True if the account has at least one active subscription.","default":"","type":"boolean","name":"has_active_subscription"},{"_id":"58c8255f5cb4fe1b00ec5677","ref":"","in":"body","required":false,"desc":"True if the account has at least one future subscription.","default":"","type":"boolean","name":"has_future_subscription"},{"_id":"58c8255f5cb4fe1b00ec5676","ref":"","in":"body","required":false,"desc":"True if the account has at least one canceled subscription.","default":"","type":"boolean","name":"has_canceled_subscription"},{"_id":"5ac2830272317b00330f50d6","ref":"","in":"body","required":false,"desc":"True if the account has at least one paused subscription.","default":"","type":"string","name":"has_paused_subscription"},{"_id":"58c8255f5cb4fe1b00ec5675","ref":"","in":"body","required":false,"desc":"True if the account has at least one past due invoice.","default":"","type":"boolean","name":"has_past_due_invoice"},{"_id":"5ad79af57097f700030f683c","ref":"","in":"body","required":false,"desc":"Used to determine the language and locale of emails sent on behalf of the merchant to the customer. The list of locales is restricted to those the merchant has enabled on the site.","default":"","type":"string","name":"preferred_locale"}],"url":"/accounts"},"isReference":true,"order":0,"body":"","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.","slug":"account-object","type":"get","title":"Account Object","__v":7,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getAccount Object

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

Body Params

parent_account:
string
The URL of the parent for the specified account.
child_accounts:
string
The URL of the child accounts for the specified account.
bill_to:
stringself
`self` or `parent`. Determines whether all charges are billed using parent’s billing information or the account itself. If bill_to = parent, all invoices resulting in charges and credits originating from a child will be created on the parent account. (e.g creating a subscription on the child account will be billed to parent and invoiced on the parent account)
adjustments:
string
The URL of adjustments for the specified account.
account_balance:
string
The URL of the account balance for the specified account.
billing_info:
string
The URL of billing info for the specified account.
invoices:
string
The URL of invoices for the specified account.
redemption:
string
The URL of the coupon redemption for the specified account.
subscriptions:
string
The URL of subscriptions for the specified account.
transactions:
string
The URL of transactions for the specified account.
notes:
string
The URL of notes on the account
account_code:
string
The unique identifier of the account.
state:
string
The state of accounts to return: `active` or `closed`.
username:
string
The username of the account.
email:
string
The email address of the account.
cc_emails:
string
Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the `email` field also receives.
first_name:
string
The first name of the account.
last_name:
string
The last name of the account.
company_name:
string
The company name of the account.
vat_number:
string
The VAT number of the account (to avoid having the VAT applied).
tax_exempt:
boolean
The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account.
address:
object
The nested address information of the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`.
shipping_address:
object
The nested shipping address information of the account: `first_name`, `last_name`, `company_name`, `email`, `phone`, `vat_number`, `address1`, `address2`, `city`, `state`, `zip`, `country`, `nickname`. You can pass in up to 20 account shipping addresses along with the request to create a new account. When providing a shipping address, the following are required: first_name, last_name, address1, city, state, zip, and country.
accept_language:
string
The ISO 639-1 language code from the user's browser, indicating their preferred language and locale. This attribute is different from `preferred_locale` and does not determine which language emails sent on behalf of the merchant.
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.
has_live_subscription:
boolean
True if the account has at least one live subscription.
has_active_subscription:
boolean
True if the account has at least one active subscription.
has_future_subscription:
boolean
True if the account has at least one future subscription.
has_canceled_subscription:
boolean
True if the account has at least one canceled subscription.
has_paused_subscription:
string
True if the account has at least one paused subscription.
has_past_due_invoice:
boolean
True if the account has at least one past due invoice.
preferred_locale:
string
Used to determine the language and locale of emails sent on behalf of the merchant to the customer. The list of locales is restricted to those the merchant has enabled on the site.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <parent_account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <child_accounts href="https://your-subdomain.recurly.com/v2/accounts/1/child_accounts"/>
  <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"/>
  <notes href="https://your-subdomain.recurly.com/v2/accounts/1/notes"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>verena@example.com</email>
  <cc_emails>bob@example.com,susan@example.com</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"/>
  <has_live_subscription type="boolean">true</has_live_subscription>
  <has_active_subscription type="boolean">true</has_active_subscription>
  <has_future_subscription type="boolean">false</has_future_subscription>
  <has_canceled_subscription type="boolean">false</has_canceled_subscription>
  <has_past_due_invoice type="boolean">false</has_past_due_invoice>
  <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":"5dd5f0b02d076f0220ca8bd7","category":"5dd5f0b02d076f0220ca8b97","parentDoc":null,"user":"55648cf93b87582b003ab8b1","project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","updates":["55f1f9abd4d3160d00439b6c"],"next":{"pages":[],"description":""},"createdAt":"2015-06-15T21:38:24.720Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","status":200,"language":"xml","code":"<accounts type=\"array\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n    <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/1/adjustments\"/>\n    <account_acquisition href=\"https://your-subdomain.recurly.com/v2/accounts/1/acquisition\"/>\n    <account_balance href=\"https://your-subdomain.recurly.com/v2/accounts/1/balance\"/>\n    <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n    <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n    <shipping_addresses href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n    <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n    <notes href=\"https://your-subdomain.recurly.com/v2/accounts/1/notes\"/>\n    <account_code>1</account_code>\n    <state>active</state>\n    <username>verena1234</username>\n    <email>verena@example.com</email>\n    <cc_emails>bob@example.com,susan@example.com</cc_emails>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name>New Company Name</company_name>\n    <vat_number nil=\"nil\"/>\n    <tax_exempt type=\"boolean\">false</tax_exempt>\n    <address>\n      <address1>123 Main St.</address1>\n      <address2 nil=\"nil\"/>\n      <city>San Francisco</city>\n      <state>CA</state>\n      <zip>94105</zip>\n      <country>US</country>\n      <phone nil=\"nil\"/>\n    </address>\n    <accept_language nil=\"nil\"/>\n    <hosted_login_token>71c122cb16fc90252ff845eacf5d7814</hosted_login_token>\n    <created_at type=\"datetime\">2016-08-03T15:44:05Z</created_at>\n    <updated_at type=\"datetime\">2017-03-15T21:22:18Z</updated_at>\n    <closed_at nil=\"nil\"/>\n    <has_live_subscription type=\"boolean\">false</has_live_subscription>\n    <has_active_subscription type=\"boolean\">false</has_active_subscription>\n    <has_future_subscription type=\"boolean\">false</has_future_subscription>\n    <has_canceled_subscription type=\"boolean\">false</has_canceled_subscription>\n    <has_past_due_invoice type=\"boolean\">false</has_past_due_invoice>\n  </account>\n</accounts>"}]},"settings":"","examples":{"codes":[{"language":"php","code":"<?php\n\n$accounts = Recurly_AccountList::getActive();\nforeach ($accounts as $account) {\n  print \"Account: $account\\n\";\n}\n","name":""},{"language":"ruby","code":"Recurly::Account.find_each do |account|\n  puts \"Account: #{account.inspect}\"\nend"},{"language":"python","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 = ()"},{"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}","name":null,"language":"csharp"}]},"method":"get","auth":"required","params":[{"_id":"56465088054d8f0d00bc76aa","ref":"","in":"query","required":false,"desc":"The state of accounts to return: `active`, `closed`, `subscriber`, `non_subscriber`, `past_due`.","default":"","type":"string","name":"state"},{"_id":"578ea5b0c93aac0e00ec8899","ref":"","in":"query","required":false,"desc":"The attribute that will be used to order records: `created_at`, `updated_at`.","default":"created_at","type":"string","name":"sort"},{"_id":"578ea5b0c93aac0e00ec8898","ref":"","in":"query","required":false,"desc":"The order in which products will be returned: `asc` for ascending order, `desc` for descending order.","default":"desc","type":"string","name":"order"},{"_id":"578ea5b0c93aac0e00ec8897","ref":"","in":"query","required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.","default":"","type":"datetime","name":"begin_time"},{"_id":"578ea5b0c93aac0e00ec8896","ref":"","in":"query","required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.","default":"","type":"datetime","name":"end_time"},{"_id":"56d8bace7ce7550b00c81d77","ref":"","in":"query","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page"},{"_id":"56d8bace7ce7550b00c81d78","ref":"","in":"query","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"int","name":"cursor"}],"url":"/accounts"},"isReference":true,"order":1,"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]","excerpt":"Returns a list of accounts on your site. Results are ordered by the time created, sorted by newest first.","slug":"list-accounts","type":"get","title":"List Accounts","__v":1,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getList Accounts

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

Query Params

state:
string
The state of accounts to return: `active`, `closed`, `subscriber`, `non_subscriber`, `past_due`.
sort:
stringcreated_at
The attribute that will be used to order records: `created_at`, `updated_at`.
order:
stringdesc
The order in which products will be returned: `asc` for ascending order, `desc` for descending order.
begin_time:
datetime
Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.
end_time:
datetime
Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.
per_page:
integer50
Number of records to return per page, up to a maximum of 200.
cursor:
integer
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.

Account Query States

state
description

active

Open accounts.

closed

Accounts that are not open.

subscriber

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

non_subscriber

Accounts without subscriptions that are valid for the current time.

past_due

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

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

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"/>
    <account_acquisition href="https://your-subdomain.recurly.com/v2/accounts/1/acquisition"/>
    <account_balance href="https://your-subdomain.recurly.com/v2/accounts/1/balance"/>
    <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
    <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
    <shipping_addresses href="https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses"/>
    <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
    <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
    <notes href="https://your-subdomain.recurly.com/v2/accounts/1/notes"/>
    <account_code>1</account_code>
    <state>active</state>
    <username>verena1234</username>
    <email>verena@example.com</email>
    <cc_emails>bob@example.com,susan@example.com</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>71c122cb16fc90252ff845eacf5d7814</hosted_login_token>
    <created_at type="datetime">2016-08-03T15:44:05Z</created_at>
    <updated_at type="datetime">2017-03-15T21:22:18Z</updated_at>
    <closed_at nil="nil"/>
    <has_live_subscription type="boolean">false</has_live_subscription>
    <has_active_subscription type="boolean">false</has_active_subscription>
    <has_future_subscription type="boolean">false</has_future_subscription>
    <has_canceled_subscription type="boolean">false</has_canceled_subscription>
    <has_past_due_invoice type="boolean">false</has_past_due_invoice>
  </account>
</accounts>


{"_id":"5dd5f0b02d076f0220ca8bd8","category":"5dd5f0b02d076f0220ca8b97","project":"555fbba928249c1900618a82","parentDoc":null,"user":"55648cf93b87582b003ab8b1","version":"5dd5f0b02d076f0220ca8c44","updates":["562908002c0fd9190067da26"],"next":{"pages":[],"description":""},"createdAt":"2015-06-15T20:12:03.880Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"name":"","code":"<account>\n  <account_code>1</account_code>\n  <parent_account_code>2</parent_account_code>\n  <email>verena@example.com</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <username>verena1234</username>\n  <cc_emails>bob@example.com,susan@example.com</cc_emails>\n  <company_name>Recurly Inc</company_name>\n  <preferred_locale>en-US</preferred_locale>\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  <shipping_addresses>\n    <shipping_address>\n      <nickname>Work</nickname>\n      <first_name>Verena</first_name>\n      <last_name>Example</last_name>\n      <company>Recurly Inc</company>\n      <phone>555-222-1212</phone>\n      <email>verena@example.com</email>\n      <address1>123 Main St.</address1>\n      <address2>Suite 101</address2>\n      <city>San Francisco</city>\n      <state>CA</state>\n      <zip>94105</zip>\n      <country>US</country>\n    </shipping_address>\n    <shipping_address>\n      <nickname>Home</nickname>\n      <first_name>Verena</first_name>\n      <last_name>Example</last_name>\n      <phone>555-867-5309</phone>\n      <email>verena@example.com</email>\n      <address1>123 Fourth St.</address1>\n      <address2>Apt. 101</address2>\n      <city>San Francisco</city>\n      <state>CA</state>\n      <zip>94105</zip>\n      <country>US</country>\n    </shipping_address>\n  </shipping_addresses>\n</account>","language":"xml"},{"code":"<?php\n  \ntry {\n  $account = new Recurly_Account('b6f5783');\n  $account->email = 'verena@example.com';\n  $account->first_name = 'Verena';\n  $account->last_name = 'Example';\n  \n  // work shipping address\n  $shad1 = new Recurly_ShippingAddress();\n  $shad1->nickname = \"Work\";\n  $shad1->first_name = \"Verena\";\n  $shad1->last_name = \"Example\";\n  $shad1->company = \"Recurly Inc.\";\n  $shad1->phone = \"555-555-5555\";\n  $shad1->email = \"verena@example.com\";\n  $shad1->address1 = \"123 Main St.\";\n  $shad1->city = \"San Francisco\";\n  $shad1->state = \"CA\";\n  $shad1->zip = \"94110\";\n  $shad1->country = \"US\";\n\n  // home shipping address\n  $shad2 = new Recurly_ShippingAddress();\n  $shad2->nickname = \"Home\";\n  $shad2->first_name = \"Verena\";\n  $shad2->last_name = \"Example\";\n  $shad2->phone = \"555-555-5555\";\n  $shad2->email = \"verena@example.com\";\n  $shad2->address1 = \"123 Dolores St.\";\n  $shad2->city = \"San Francisco\";\n  $shad2->state = \"CA\";\n  $shad2->zip = \"94110\";\n  $shad2->country = \"US\";\n\n  $account->shipping_addresses = array($shad1, $shad2);\n  \n  $account->create();\n\n  print \"Account: $account\\n\";\n\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Account: $e\";\n}","language":"php"},{"code":"account = Recurly::Account.create(\n  :account_code => '1',\n  :email        => 'verena@example.com',\n  :first_name   => 'Verena',\n  :last_name    => 'Example',\n    :shipping_addresses => [\n      {\n          :nickname => 'Work',\n            :first_name => 'Verena',\n            :last_name => 'Example',\n            :company => 'Recurly Inc',\n            :phone => '555-222-1212',\n            :email => 'verena@example.com',\n            :address1 => '123 Main St.',\n            :address2 => 'Suite 101',\n            :city => 'San Francisco',\n            :state => 'CA',\n            :zip => '94105',\n            :country => 'US'\n        },\n        {\n          :nickname => 'Home',\n            :first_name => 'Verena',\n            :last_name => 'Example',\n            :phone => '555-867-5309',\n            :email => 'verena@example.com',\n            :address1 => '123 Fourth St.',\n            :address2 => 'Apt. 101',\n            :city => 'San Francisco',\n            :state => 'CA',\n            :zip => '94105',\n            :country => 'US'\n        }\n    ]\n)","language":"ruby"},{"code":"account = recurly.Account(account_code='1')\naccount.email = 'verena@example.com'\naccount.first_name = 'Verena'\naccount.last_name = 'Example'\naccount.save()","language":"python"},{"language":"csharp","code":"var account = new Account(\"1\")\n{\n  Email = \"verena@example.com\",\n  FirstName = \"Verena\",\n  LastName = \"Example\"\n};\naccount.Create();"}]},"method":"post","results":{"codes":[{"name":"","code":"<account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n  <parent_account href=\"https://your-subdomain.recurly.com/v2/accounts/2\"/>\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  <shipping_addresses href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n  <notes href=\"https://your-subdomain.recurly.com/v2/accounts/1/notes\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username>verena1234</username>\n  <email>verena@example.com</email>\n  <cc_emails>bob@example.com,susan@example.com</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":"","auth":"required","params":[{"_id":"557f3209e211d20d00601425","ref":"","in":"body","required":true,"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 or hyphen character. Max of 50 characters.","default":"","type":"string","name":"account_code"},{"_id":"5c882696fc99ab03360d7cf8","ref":"","in":"body","required":false,"desc":"The account code of the new parent account. Allows associating a new account to an existing account as its child.","default":"","type":"string","name":"parent_account_code"},{"_id":"5ca525338da0b30161c803d6","ref":"","in":"body","required":false,"desc":"`self` or `parent`. Determines whether all charges are billed using parent’s billing information or the account itself.  If bill_to = parent, all invoices resulting in charges and credits originating from a child will be created on the parent account. (e.g creating a subscription on the child account will be billed to parent and invoiced on the parent account)","default":"self","type":"string","name":"bill_to"},{"_id":"557f3209e211d20d00601424","ref":"","in":"body","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":"557f3209e211d20d00601423","ref":"","in":"body","required":false,"desc":"The email address for the account.","default":"","type":"string","name":"email"},{"_id":"557f32d1e211d20d00601430","ref":"","in":"body","required":false,"desc":"The first name for the account. Max of 255 characters.","default":"","type":"string","name":"first_name"},{"_id":"557f32d1e211d20d0060142f","ref":"","in":"body","required":false,"desc":"The last name for the account.  Max of 255 characters.","default":"","type":"string","name":"last_name"},{"_id":"557f32d1e211d20d0060142e","ref":"","in":"body","required":false,"desc":"The company name for the account. Max of 50 characters.","default":"","type":"string","name":"company_name"},{"_id":"557f32d1e211d20d0060142d","ref":"","in":"body","required":false,"desc":"The VAT number to avoid having the VAT applied (if applicable).","default":"","type":"string","name":"vat_number"},{"_id":"557f32d1e211d20d0060142c","ref":"","in":"body","required":false,"desc":"The tax status for the account.","default":"","type":"boolean","name":"tax_exempt"},{"_id":"5c1004996b23ca00130d6f6f","ref":"","in":"body","required":false,"desc":"Optional field for merchants taxing through Vertex. String of 1-30 characters. If an exemption_certificate is provided, tax_exempt must be true.","default":"","type":"string","name":"exemption_certificate"},{"_id":"557f32d1e211d20d0060142b","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"},{"_id":"58cffafa2cb80d1b005486a8","ref":"","in":"body","required":false,"desc":"The nested account acquisition information: `cost_in_cents`, `currency`, `channel`, `subchannel`, `campaign`","default":"","type":"object","name":"account_acquisition"},{"_id":"557f32d1e211d20d0060142a","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","name":"billing_info"},{"_id":"557f32d1e211d20d00601429","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":"58010a4657be4b1900eaf2a6","ref":"","in":"body","required":false,"desc":"The nested shipping address information of the account: `first_name`, `last_name`, `company_name`, `email`, `phone`, `vat_number`,  `address1`, `address2`, `city`, `state`, `zip`, `country`, `nickname`. You can pass in up to 20 account shipping addresses along with the request to create a new account. When providing a shipping address, the following are required: first_name, last_name, address1, city, state, zip, and country.","default":"","type":"object","name":"shipping_address"},{"_id":"557f32d1e211d20d00601428","ref":"","in":"body","required":false,"desc":"The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.","default":"","type":"string","name":"accept_language"},{"_id":"561c362cd308ee0d00749370","ref":"","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":"5ad79b55f7096b0003956a9d","ref":"","in":"body","required":false,"desc":"Used to determine the language and locale of emails sent on behalf of the merchant to the customer. The list of locales is restricted to those the merchant has enabled on the site.","default":"","type":"string","name":"preferred_locale"},{"_id":"5d5c228ff20ff50052c03fb5","ref":"","in":"body","required":false,"desc":"Indicates type of resulting transaction. accepted_values: \"moto\".","default":"","type":"string","name":"transaction_type"}],"url":"/accounts"},"isReference":true,"order":2,"body":"","excerpt":"Creates a new account. You may optionally include billing information.","slug":"create-an-account","type":"post","title":"Create Account","__v":9,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate Account

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

Body Params

account_code:
required
string
A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z 0-9 @ - _ .] but it may not begin with a dot or hyphen character. Max of 50 characters.
parent_account_code:
string
The account code of the new parent account. Allows associating a new account to an existing account as its child.
bill_to:
stringself
`self` or `parent`. Determines whether all charges are billed using parent’s billing information or the account itself. If bill_to = parent, all invoices resulting in charges and credits originating from a child will be created on the parent account. (e.g creating a subscription on the child account will be billed to parent and invoiced on the parent account)
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.
exemption_certificate:
string
Optional field for merchants taxing through Vertex. String of 1-30 characters. If an exemption_certificate is provided, tax_exempt must be true.
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.
account_acquisition:
object
The nested account acquisition information: `cost_in_cents`, `currency`, `channel`, `subchannel`, `campaign`
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`.
shipping_address:
object
The nested shipping address information of the account: `first_name`, `last_name`, `company_name`, `email`, `phone`, `vat_number`, `address1`, `address2`, `city`, `state`, `zip`, `country`, `nickname`. You can pass in up to 20 account shipping addresses along with the request to create a new account. When providing a shipping address, the following are required: first_name, last_name, address1, city, state, zip, and country.
accept_language:
string
The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.
cc_emails:
array of strings
Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the `email` field also receives.
preferred_locale:
string
Used to determine the language and locale of emails sent on behalf of the merchant to the customer. The list of locales is restricted to those the merchant has enabled on the site.
transaction_type:
string
Indicates type of resulting transaction. accepted_values: "moto".

Definition

{{ api_url }}{{ page_api_url }}

Examples

<account>
  <account_code>1</account_code>
  <parent_account_code>2</parent_account_code>
  <email>verena@example.com</email>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <username>verena1234</username>
  <cc_emails>bob@example.com,susan@example.com</cc_emails>
  <company_name>Recurly Inc</company_name>
  <preferred_locale>en-US</preferred_locale>
  <address>
    <address1>123 Main St.</address1>
    <city>San Francisco</city>
    <state>CA</state>
    <zip>94105</zip>
    <country>US</country>
  </address>
  <shipping_addresses>
    <shipping_address>
      <nickname>Work</nickname>
      <first_name>Verena</first_name>
      <last_name>Example</last_name>
      <company>Recurly Inc</company>
      <phone>555-222-1212</phone>
      <email>verena@example.com</email>
      <address1>123 Main St.</address1>
      <address2>Suite 101</address2>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94105</zip>
      <country>US</country>
    </shipping_address>
    <shipping_address>
      <nickname>Home</nickname>
      <first_name>Verena</first_name>
      <last_name>Example</last_name>
      <phone>555-867-5309</phone>
      <email>verena@example.com</email>
      <address1>123 Fourth St.</address1>
      <address2>Apt. 101</address2>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94105</zip>
      <country>US</country>
    </shipping_address>
  </shipping_addresses>
</account>
<?php
  
try {
  $account = new Recurly_Account('b6f5783');
  $account->email = 'verena@example.com';
  $account->first_name = 'Verena';
  $account->last_name = 'Example';
  
  // work shipping address
  $shad1 = new Recurly_ShippingAddress();
  $shad1->nickname = "Work";
  $shad1->first_name = "Verena";
  $shad1->last_name = "Example";
  $shad1->company = "Recurly Inc.";
  $shad1->phone = "555-555-5555";
  $shad1->email = "verena@example.com";
  $shad1->address1 = "123 Main St.";
  $shad1->city = "San Francisco";
  $shad1->state = "CA";
  $shad1->zip = "94110";
  $shad1->country = "US";

  // home shipping address
  $shad2 = new Recurly_ShippingAddress();
  $shad2->nickname = "Home";
  $shad2->first_name = "Verena";
  $shad2->last_name = "Example";
  $shad2->phone = "555-555-5555";
  $shad2->email = "verena@example.com";
  $shad2->address1 = "123 Dolores St.";
  $shad2->city = "San Francisco";
  $shad2->state = "CA";
  $shad2->zip = "94110";
  $shad2->country = "US";

  $account->shipping_addresses = array($shad1, $shad2);
  
  $account->create();

  print "Account: $account\n";

} catch (Recurly_ValidationError $e) {
  print "Invalid Account: $e";
}
account = Recurly::Account.create(
  :account_code => '1',
  :email        => 'verena@example.com',
  :first_name   => 'Verena',
  :last_name    => 'Example',
    :shipping_addresses => [
      {
          :nickname => 'Work',
            :first_name => 'Verena',
            :last_name => 'Example',
            :company => 'Recurly Inc',
            :phone => '555-222-1212',
            :email => 'verena@example.com',
            :address1 => '123 Main St.',
            :address2 => 'Suite 101',
            :city => 'San Francisco',
            :state => 'CA',
            :zip => '94105',
            :country => 'US'
        },
        {
          :nickname => 'Home',
            :first_name => 'Verena',
            :last_name => 'Example',
            :phone => '555-867-5309',
            :email => 'verena@example.com',
            :address1 => '123 Fourth St.',
            :address2 => 'Apt. 101',
            :city => 'San Francisco',
            :state => 'CA',
            :zip => '94105',
            :country => 'US'
        }
    ]
)
account = recurly.Account(account_code='1')
account.email = 'verena@example.com'
account.first_name = 'Verena'
account.last_name = 'Example'
account.save()
var account = new Account("1")
{
  Email = "verena@example.com",
  FirstName = "Verena",
  LastName = "Example"
};
account.Create();

Result Format

<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <parent_account href="https://your-subdomain.recurly.com/v2/accounts/2"/>
  <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"/>
  <shipping_addresses href="https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses"/>
  <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
  <notes href="https://your-subdomain.recurly.com/v2/accounts/1/notes"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>verena@example.com</email>
  <cc_emails>bob@example.com,susan@example.com</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":"5dd5f0b02d076f0220ca8bd9","category":"5dd5f0b02d076f0220ca8b97","parentDoc":null,"project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","version":"5dd5f0b02d076f0220ca8c44","updates":["55bbdd4e1067fc1700510eed"],"next":{"pages":[],"description":""},"createdAt":"2015-06-15T21:45:49.420Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"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}","language":"php","name":""},{"code":"begin\n  account = Recurly::Account.find '1'\n  puts \"Account: #{account.inspect}\"\nrescue Recurly::Resource::NotFound => e\n  puts e.message\nend","language":"ruby"},{"code":"try:\n  account = recurly.Account.get('1')\n  print \"Account: %s\" % account\nexcept NotFoundError:\n  print \"Account not found.\\n\"","language":"python"},{"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}","language":"csharp"}]},"method":"get","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  <account_acquisition href=\"https://your-subdomain.recurly.com/v2/accounts/1/acquisition\"/>\n  <account_balance href=\"https://your-subdomain.recurly.com/v2/accounts/1/balance\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n  <shipping_addresses href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n  <notes href=\"https://your-subdomain.recurly.com/v2/accounts/1/notes\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username>verena1234</username>\n  <email>verena@example.com</email>\n  <cc_emails>bob@example.com,susan@example.com</cc_emails>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name>New Company Name</company_name>\n  <vat_number nil=\"nil\"/>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address1>\n    <address2 nil=\"nil\"/>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone nil=\"nil\"/>\n  </address>\n  <accept_language nil=\"nil\"/>\n  <hosted_login_token>71c122cb16fc90252ff845eacf5d7814</hosted_login_token>\n  <created_at type=\"datetime\">2016-08-03T15:44:05Z</created_at>\n  <updated_at type=\"datetime\">2017-03-15T21:22:18Z</updated_at>\n  <closed_at nil=\"nil\"/>\n  <has_live_subscription type=\"boolean\">false</has_live_subscription>\n  <has_active_subscription type=\"boolean\">false</has_active_subscription>\n  <has_future_subscription type=\"boolean\">false</has_future_subscription>\n  <has_canceled_subscription type=\"boolean\">false</has_canceled_subscription>\n  <has_past_due_invoice type=\"boolean\">false</has_past_due_invoice>\n</account>","language":"xml","status":200}]},"settings":"","auth":"required","params":[{"_id":"557f478deb75d80d00af4086","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"}],"url":"/accounts/:account_code"},"isReference":true,"order":3,"body":"","excerpt":"Returns information about a single account.","slug":"get-account","type":"get","title":"Lookup Account","__v":1,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getLookup 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 = recurly.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"/>
  <account_acquisition href="https://your-subdomain.recurly.com/v2/accounts/1/acquisition"/>
  <account_balance href="https://your-subdomain.recurly.com/v2/accounts/1/balance"/>
  <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
  <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
  <shipping_addresses href="https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses"/>
  <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
  <notes href="https://your-subdomain.recurly.com/v2/accounts/1/notes"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>verena@example.com</email>
  <cc_emails>bob@example.com,susan@example.com</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>71c122cb16fc90252ff845eacf5d7814</hosted_login_token>
  <created_at type="datetime">2016-08-03T15:44:05Z</created_at>
  <updated_at type="datetime">2017-03-15T21:22:18Z</updated_at>
  <closed_at nil="nil"/>
  <has_live_subscription type="boolean">false</has_live_subscription>
  <has_active_subscription type="boolean">false</has_active_subscription>
  <has_future_subscription type="boolean">false</has_future_subscription>
  <has_canceled_subscription type="boolean">false</has_canceled_subscription>
  <has_past_due_invoice type="boolean">false</has_past_due_invoice>
</account>


{"_id":"5dd5f0b02d076f0220ca8bda","category":"5dd5f0b02d076f0220ca8b97","parentDoc":null,"user":"55648cf93b87582b003ab8b1","project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","updates":["568ffb69769f210d00132584"],"next":{"pages":[],"description":""},"createdAt":"2015-06-15T21:57:38.556Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"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  <account_balance href=\"https://your-subdomain.recurly.com/v2/accounts/1/balance\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n  <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  <notes href=\"https://your-subdomain.recurly.com/v2/accounts/1/notes\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username>verena1234</username>\n  <email>verena@example.com</email>\n  <cc_emails>bob@example.com,susan@example.com</cc_emails>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name>New Company Name</company_name>\n  <vat_number nil=\"nil\"/>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address1>\n    <address2 nil=\"nil\"/>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone nil=\"nil\"/>\n  </address>\n  <accept_language nil=\"nil\"/>\n  <hosted_login_token>71c122cb16fc90252ff845eacf5d7814</hosted_login_token>\n  <created_at type=\"datetime\">2016-08-03T15:44:05Z</created_at>\n  <updated_at type=\"datetime\">2016-08-03T16:30:50Z</updated_at>\n  <closed_at nil=\"nil\"/>\n</account>","language":"xml","status":200}]},"settings":"","examples":{"codes":[{"code":"<account>\n  <company_name>New Company Name</company_name>\n</account>","name":"","language":"xml"},{"language":"php","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":"ruby","code":"account = Recurly::Account.find('account_1')\naccount.company_name = 'New Company Name'\naccount.save"},{"language":"python","code":"account = recurly.Account.get('account_1')\naccount.company_name = 'New Company Name'\naccount.save()"},{"language":"csharp","code":"var account = Account.Get(\"account_1\");\naccount.CompanyName = 'New Company Name'\naccount.Update();"}]},"method":"put","auth":"required","params":[{"_id":"557f4a527eafa719001d1c43","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"},{"_id":"5c882709fe5ffb00f3884600","ref":"","in":"body","required":false,"desc":"The account code of the new parent account. Allows associating a new account to an existing account as its child. Sending an empty <parent_account_code> tag will remove an associated parent account from an existing account","default":"","type":"string","name":"parent_account_code"},{"_id":"557f4a527eafa719001d1c42","ref":"","in":"body","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":"557f4a527eafa719001d1c41","ref":"","in":"body","required":false,"desc":"The email address for the account.","default":"","type":"string","name":"email"},{"_id":"557f4a527eafa719001d1c40","ref":"","in":"body","required":false,"desc":"The first name for the account. Max of 255 characters.","default":"","type":"string","name":"first_name"},{"_id":"557f4a527eafa719001d1c3f","ref":"","in":"body","required":false,"desc":"The last name for the account. Max of 255 characters.","default":"","type":"string","name":"last_name"},{"_id":"557f4a527eafa719001d1c3e","ref":"","in":"body","required":false,"desc":"The company name for the account. Max of 50 characters.","default":"","type":"string","name":"company_name"},{"_id":"557f4a527eafa719001d1c3d","ref":"","in":"body","required":false,"desc":"The VAT number to avoid having the VAT applied (if applicable).","default":"","type":"string","name":"vat_number"},{"_id":"557f4a527eafa719001d1c3c","ref":"","in":"body","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":"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"},{"_id":"58cffb3be865c00f00f93dfb","ref":"","in":"body","required":false,"desc":"The nested account acquisition information: `cost_in_cents`, currency`, `channel`, `subchannel`, `campaign`","default":"","type":"object","name":"account_acquisition"},{"_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","name":"billing_info"},{"_id":"557f4a527eafa719001d1c39","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":"557f4a527eafa719001d1c38","ref":"","in":"body","required":false,"desc":"The ISO 639-1 language code from the user's browser, indicating their preferred language and locale.","default":"","type":"string","name":"accept_language"},{"_id":"561c3606d468a60d00f51ebe","ref":"","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":"5ad79b74f7096b0003956a9e","ref":"","in":"body","required":false,"desc":"Used to determine the language and locale of emails sent on behalf of the merchant to the customer. The list of locales is restricted to those the merchant has enabled on the site.","default":"","type":"string","name":"preferred_locale"}],"url":"/accounts/:account_code"},"isReference":true,"order":4,"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]","excerpt":"Updates an existing account.","slug":"update-account","type":"put","title":"Update Account","__v":4,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

putUpdate Account

Updates an existing account.

Path Params

account_code:
required
string
Account's unique code.

Body Params

parent_account_code:
string
The account code of the new parent account. Allows associating a new account to an existing account as its child. Sending an empty <parent_account_code> tag will remove an associated parent account from an existing account
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 of the account. `true` exempts tax on the account, `false` applies tax on 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.
account_acquisition:
object
The nested account acquisition information: `cost_in_cents`, currency`, `channel`, `subchannel`, `campaign`
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.
preferred_locale:
string
Used to determine the language and locale of emails sent on behalf of the merchant to the customer. The list of locales is restricted to those the merchant has enabled on the site.

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

<account>
  <company_name>New Company Name</company_name>
</account>
<?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 = recurly.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();

Result Format

<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
  <account_balance href="https://your-subdomain.recurly.com/v2/accounts/1/balance"/>
  <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"/>
  <notes href="https://your-subdomain.recurly.com/v2/accounts/1/notes"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>verena@example.com</email>
  <cc_emails>bob@example.com,susan@example.com</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>71c122cb16fc90252ff845eacf5d7814</hosted_login_token>
  <created_at type="datetime">2016-08-03T15:44:05Z</created_at>
  <updated_at type="datetime">2016-08-03T16:30:50Z</updated_at>
  <closed_at nil="nil"/>
</account>


{"_id":"5dd5f0b02d076f0220ca8bdb","category":"5dd5f0b02d076f0220ca8b97","parentDoc":null,"project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-15T22:00:42.004Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"name":"","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}","language":"php"},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.destroy"},{"code":"account = recurly.Account.get('1')\naccount.delete()","language":"python"},{"code":"var account = Accounts.Get(\"1\");\naccount.Close();","language":"csharp"}]},"method":"delete","results":{"codes":[{"name":"","code":"","language":"xml","status":200}]},"settings":"","auth":"required","params":[{"_id":"55944ebb5c9eaa2300a86337","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"}],"url":"/accounts/:account_code"},"isReference":true,"order":5,"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]","excerpt":"Marks an account as closed and cancels any active subscriptions. Paused subscriptions will be expired.","slug":"close-account","type":"delete","title":"Close Account","__v":1,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

deleteClose Account

Marks an account as closed and cancels any active subscriptions. Paused subscriptions will be expired.

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 = recurly.Account.get('1')
account.delete()
var account = Accounts.Get("1");
account.Close();


{"_id":"5dd5f0b02d076f0220ca8bdc","category":"5dd5f0b02d076f0220ca8b97","parentDoc":null,"project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-15T22:03:14.174Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"php","name":"","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}"},{"code":"account = Recurly::Account.find '1'\naccount.reopen","language":"ruby"},{"code":"account = recurly.Account.get('1')\naccount.reopen() ","language":"python"},{"code":"var account = Accounts.Get(\"1\");\naccount.Reopen();","language":"csharp"}]},"method":"put","results":{"codes":[{"name":"","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  <account_balance href=\"https://your-subdomain.recurly.com/v2/accounts/1/balance\"/>\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  <notes href=\"https://your-subdomain.recurly.com/v2/accounts/1/notes\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username>verena1234</username>\n  <email>verena@example.com</email>\n  <cc_emails>bob@example.com,susan@example.com</cc_emails>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name>New Company Name</company_name>\n  <vat_number nil=\"nil\"/>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address1>\n    <address2 nil=\"nil\"/>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone nil=\"nil\"/>\n  </address>\n  <accept_language nil=\"nil\"/>\n  <hosted_login_token>71c122cb16fc90252ff845eacf5d7814</hosted_login_token>\n  <created_at type=\"datetime\">2016-08-03T15:44:05Z</created_at>\n  <updated_at type=\"datetime\">2016-08-03T16:31:25Z</updated_at>\n  <closed_at nil=\"nil\"/>\n</account>"}]},"settings":"","auth":"required","params":[{"_id":"55944ed45c9eaa2300a86339","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"}],"url":"/accounts/:account_code/reopen"},"isReference":true,"order":6,"body":"[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Please note\",\n  \"body\": \"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]","excerpt":"Transitions a closed account back to active.","slug":"reopen-account","type":"put","title":"Reopen Account","__v":2,"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

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 = recurly.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"/>
  <account_balance href="https://your-subdomain.recurly.com/v2/accounts/1/balance"/>
  <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"/>
  <notes href="https://your-subdomain.recurly.com/v2/accounts/1/notes"/>
  <account_code>1</account_code>
  <state>active</state>
  <username>verena1234</username>
  <email>verena@example.com</email>
  <cc_emails>bob@example.com,susan@example.com</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>71c122cb16fc90252ff845eacf5d7814</hosted_login_token>
  <created_at type="datetime">2016-08-03T15:44:05Z</created_at>
  <updated_at type="datetime">2016-08-03T16:31:25Z</updated_at>
  <closed_at nil="nil"/>
</account>


{"_id":"5dd5f0b02d076f0220ca8bdd","category":"5dd5f0b02d076f0220ca8b97","user":"559d85d26b21311700fb0b7b","parentDoc":null,"project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-19T19:51:58.991Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"php","code":"<?php\n\n$balance = Recurly_AccountBalance::get('1');"},{"language":"ruby","code":"account = Recurly::Account.find '1'\naccount_balance = account.account_balance"},{"language":"python","code":"account = recurly.Account.get('1')\naccount_balance = account.account_balance()"},{"language":"csharp","code":"var balance = AccountBalance.Get(\"1\");"}]},"method":"get","results":{"codes":[{"code":"<account_balance href=\"https://your-subdomain.recurly.com/v2/accounts/1/balance\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <past_due type=\"boolean\">false</past_due>\n  <balance_in_cents>\n    <USD type=\"integer\">3000</USD>\n    <EUR type=\"integer\">0</EUR>\n  </balance_in_cents>\n</account_balance>","name":"","status":200,"language":"xml"},{"language":"json","code":"<error>\n  <symbol>unavailable_in_api_version</symbol>\n  <description>This request cannot be completed using this version of the API. It was added in version '2.3'.</description>\n</error>","name":"","status":400},{"code":"<error>\n  <symbol>not_found</symbol>\n  <description lang=\"en-US\">Couldn't find Account with account_code = not-1</description>\n</error>","status":404,"language":"text"}]},"settings":"","auth":"required","params":[{"_id":"578e888a36baeb17003fd5fb","ref":"","in":"query","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"}],"url":"/accounts/:account_code/balance"},"isReference":true,"order":7,"body":"","excerpt":"Returns the account's past due status and balance in each of the site's supported currencies.","slug":"lookup-account-balance","type":"get","title":"Lookup Account Balance","__v":1,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getLookup Account Balance

Returns the account's past due status and balance in each of the site's supported currencies.

Query Params

account_code:
required
string
Account's unique code.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<?php

$balance = Recurly_AccountBalance::get('1');
account = Recurly::Account.find '1'
account_balance = account.account_balance
account = recurly.Account.get('1')
account_balance = account.account_balance()
var balance = AccountBalance.Get("1");

Result Format

<account_balance href="https://your-subdomain.recurly.com/v2/accounts/1/balance">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <past_due type="boolean">false</past_due>
  <balance_in_cents>
    <USD type="integer">3000</USD>
    <EUR type="integer">0</EUR>
  </balance_in_cents>
</account_balance>
<error>
  <symbol>unavailable_in_api_version</symbol>
  <description>This request cannot be completed using this version of the API. It was added in version '2.3'.</description>
</error>
<error>
  <symbol>not_found</symbol>
  <description lang="en-US">Couldn't find Account with account_code = not-1</description>
</error>


{"_id":"5dd5f0b02d076f0220ca8bde","category":"5dd5f0b02d076f0220ca8b97","user":"55648cf93b87582b003ab8b1","parentDoc":null,"project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-15T22:04:40.352Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"name":"","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}","language":"php"},{"code":"acct = Recurly::Account.find '1'\nacct.notes.each do |note|\n  puts note.inspect\nend","language":"ruby"},{"code":"try:\n  account = recurly.Account.get('1')\n  for note in account.notes():\n   print \"Note: %s\" % note.message\nexcept NotFoundError:\n  print \"Account not found.\\n\"","language":"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}"}]},"method":"get","results":{"codes":[{"name":"","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>","language":"xml","status":200}]},"settings":"","auth":"required","params":[{"_id":"55944eddccc3052300569882","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"},{"_id":"5783c946ce802f0e0087d4bb","ref":"","in":"query","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"578ea620c93aac0e00ec889d","ref":"","in":"query","required":false,"desc":"The attribute that will be used to order records: `created_at`, `updated_at`.","default":"created_at","type":"string","name":"sort"},{"_id":"578ea620c93aac0e00ec889c","ref":"","in":"query","required":false,"desc":"The order in which products will be returned: `asc` for ascending order, `desc` for descending order.","default":"desc","type":"string","name":"order"},{"_id":"578ea620c93aac0e00ec889b","ref":"","in":"query","required":false,"desc":"Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.","default":"","type":"datetime","name":"begin_time"},{"_id":"578ea620c93aac0e00ec889a","ref":"","in":"query","required":false,"desc":"","default":"","type":"datetime","name":"end_time"},{"_id":"5783c946ce802f0e0087d4ba","ref":"","in":"query","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page"}],"url":"/accounts/:account_code/notes"},"isReference":true,"order":8,"body":"","excerpt":"Returns a list of the notes on an account sorted in descending order (most recently created first).","slug":"list-account-notes","type":"get","title":"List Account Notes","__v":3,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

getList Account Notes

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

Path Params

account_code:
required
string
Account's unique code.

Query Params

cursor:
string
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
sort:
stringcreated_at
The attribute that will be used to order records: `created_at`, `updated_at`.
order:
stringdesc
The order in which products will be returned: `asc` for ascending order, `desc` for descending order.
begin_time:
datetime
Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.
end_time:
datetime
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";
}
acct = Recurly::Account.find '1'
acct.notes.each do |note|
  puts note.inspect
end
try:
  account = recurly.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":"5dd5f0b02d076f0220ca8bfc","category":"5dd5f0b02d076f0220ca8b98","parentDoc":null,"project":"555fbba928249c1900618a82","user":"55648cf93b87582b003ab8b1","version":"5dd5f0b02d076f0220ca8c44","updates":["56799b95239fac0d00c7e019"],"next":{"pages":[],"description":""},"createdAt":"2015-06-17T19:47:32.787Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"name":"","code":"<billing_info>\n  <token_id>TOKEN_ID</token_id>\n</billing_info>","language":"xml"},{"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->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}"},{"code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  token_id: 'TOKEN_ID'\n}\naccount.billing_info.save!","language":"ruby"},{"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.Create();"}]},"method":"post","results":{"codes":[{"language":"xml","status":201,"name":"","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  <updated_at type=\"datetime\">2017-02-17T15:38:53Z</updated_at>\n</billing_info>"},{"status":404,"language":"xml","code":"<error>\n  <symbol>token_invalid</symbol>\n  <description>Token is either invalid or expired</description>\n</error>"}]},"settings":"","auth":"required","params":[{"_id":"55944f99ccc3052300569885","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"},{"_id":"5581ced4a5474a0d00d946a5","ref":"","in":"body","required":true,"desc":"A token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token)","default":"","type":"string","name":"token_id"},{"_id":"56d0e86f40d36e1d00bc14c9","ref":"","in":"body","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":"","type":"string","name":"currency"},{"_id":"5d13c771b8482c00417e00d0","ref":"","in":"body","required":false,"desc":"An id returned by Recurly.js referencing the result of the 3DS authentication for [PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2)","default":"","type":"string","name":"three_d_secure_action_result_token_id"},{"_id":"5d5dca14fd24750251b7db4c","ref":"","in":"body","required":false,"desc":"Indicates type of resulting transaction. accepted_values: \"moto\".","default":"","type":"string","name":"transaction_type"}],"url":"/accounts/:account_code/billing_info"},"isReference":true,"order":0,"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.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"[PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2) is a regulation from the EEA effective September 2019. It requires 3DS / SCA (strong customer authentication) on certain transactions. Recurly has updated our gateway integrations to support this flow as well as enable merchants to send Recurly the required parameters. \\n\\nThis feature enables the fetching of ThreeDSecureActionToken and the passing of a ThreeDSecureActionResultToken id through the API.\\n\\nThis change was made to facilitate the flow of information needed to 3D secure a transaction for transactions requiring SCA.\\n\\nMerchants with an acquiring bank in the EEA must comply with SCA. They must support 3DS2 in order to authenticate card holders and send authorizations for transactions that were subject to SCA.\",\n  \"title\": \"PSD2 and 3DS Authentication\"\n}\n[/block]","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.","slug":"create-an-accounts-billing-info-token","type":"post","title":"Create Account's Billing Info (Token)","__v":5,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate 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.
three_d_secure_action_result_token_id:
string
An id returned by Recurly.js referencing the result of the 3DS authentication for [PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2)
transaction_type:
string
Indicates type of resulting transaction. accepted_values: "moto".

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.

PSD2 and 3DS Authentication

PSD2 is a regulation from the EEA effective September 2019. It requires 3DS / SCA (strong customer authentication) on certain transactions. Recurly has updated our gateway integrations to support this flow as well as enable merchants to send Recurly the required parameters.

This feature enables the fetching of ThreeDSecureActionToken and the passing of a ThreeDSecureActionResultToken id through the API.

This change was made to facilitate the flow of information needed to 3D secure a transaction for transactions requiring SCA.

Merchants with an acquiring bank in the EEA must comply with SCA. They must support 3DS2 in order to authenticate card holders and send authorizations for transactions that were subject to SCA.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<billing_info>
  <token_id>TOKEN_ID</token_id>
</billing_info>
<?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();

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>
  <updated_at type="datetime">2017-02-17T15:38:53Z</updated_at>
</billing_info>
<error>
  <symbol>token_invalid</symbol>
  <description>Token is either invalid or expired</description>
</error>


{"_id":"5dd5f0b02d076f0220ca8bfd","category":"5dd5f0b02d076f0220ca8b98","parentDoc":null,"user":"55648cf93b87582b003ab8b1","project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","updates":["55d336260168850d0073f054","562944f61a92870d0002c301","56bb59bae59a312b00a15bac","57ed6ed3c4f64e17004e535d"],"next":{"pages":[],"description":""},"createdAt":"2015-06-17T19:55:06.712Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"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  <three_d_secure_action_result_token_id>3DS_TOKEN_ID</three_d_secure_action_result_token_id>\n</billing_info>","language":"xml","name":""},{"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->three_d_secure_action_result_token_id = '3DS_TOKEN_ID';\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}","language":"php"},{"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  :three_d_secure_action_result_token_id => '3DS_TOKEN_ID'\n}\naccount.billing_info.save!","language":"ruby"},{"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\nbilling_info.three_d_secure_action_result_token_id = '3DS_TOKEN_ID'\naccount.update_billing_info(billing_info)","language":"python"},{"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.ThreeDSecureActionResultTokenId = \"3DS_TOKEN_ID\";\ninfo.Create();","language":"csharp"}]},"method":"post","results":{"codes":[{"name":"","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  <updated_at type=\"datetime\">2017-02-17T15:38:53Z</updated_at>\n</billing_info>","language":"xml","status":201},{"status":422,"language":"xml","code":"<errors>\n  <transaction_error>\n    <error_code>declined</error_code>\n    <error_category>soft</error_category>\n    <merchant_message>The customer's bank has declined their card. The customer will need to contact their bank to learn the cause.</merchant_message>\n    <customer_message>Your transaction was declined. Please use a different card or contact your bank.</customer_message>\n    <gateway_error_code nil=\"nil\"/>\n  </transaction_error>\n  <error field=\"billing_info.base\" symbol=\"declined\">Your transaction was declined. Please use a different card or contact your bank.</error>\n  <transaction href=\"https://your-subdomain.recurly.com/v2/transactions/3c4293ccd7f7bce494f85e4d48beb22e\" type=\"credit_card\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <uuid>3c4293ccd7f7bce494f85e4d48beb22e</uuid>\n    <action>verify</action>\n    <amount_in_cents type=\"integer\">0</amount_in_cents>\n    <tax_in_cents type=\"integer\">0</tax_in_cents>\n    <currency>USD</currency>\n    <status>declined</status>\n    <payment_method>credit_card</payment_method>\n    <reference>676848</reference>\n    <source>billing_info</source>\n    <recurring type=\"boolean\">false</recurring>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">false</voidable>\n    <refundable type=\"boolean\">false</refundable>\n    <ip_address>127.0.0.1</ip_address>\n    <transaction_error>\n      <error_code>declined</error_code>\n      <error_category>soft</error_category>\n      <merchant_message>The customer's bank has declined their card. The customer will need to contact their bank to learn the cause.</merchant_message>\n      <customer_message>Your transaction was declined. Please use a different card or contact your bank.</customer_message>\n      <gateway_error_code nil=\"nil\"/>\n    </transaction_error>\n    <cvv_result code=\"\" nil=\"nil\"/>\n    <avs_result code=\"\" nil=\"nil\"/>\n    <avs_result_street nil=\"nil\"/>\n    <avs_result_postal nil=\"nil\"/>\n    <created_at type=\"datetime\">2017-03-15T21:03:40Z</created_at>\n    <updated_at type=\"datetime\">2017-03-15T21:03:40Z</updated_at>\n    <details>\n      <account>\n        <account_code>1</account_code>\n        <first_name>Verena</first_name>\n        <last_name>Example</last_name>\n        <company>New Company Name</company>\n        <email>verena@example.com</email>\n        <billing_info type=\"credit_card\">\n          <first_name>Verena</first_name>\n          <last_name>Example</last_name>\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          <card_type>Visa</card_type>\n          <year type=\"integer\">2019</year>\n          <month type=\"integer\">11</month>\n          <first_six>400000</first_six>\n          <last_four>0002</last_four>\n        </billing_info>\n      </account>\n    </details>\n  </transaction>\n</errors>"}]},"settings":"","auth":"required","params":[{"_id":"55944fab5c9eaa2300a8633c","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"},{"_id":"5581d09a8625220d00429e4d","ref":"","in":"body","required":true,"desc":"First name","default":"","type":"string","name":"first_name"},{"_id":"5581d09a8625220d00429e4c","ref":"","in":"body","required":true,"desc":"Last name","default":"","type":"string","name":"last_name"},{"_id":"5581d09a8625220d00429e42","ref":"","in":"body","required":true,"desc":"Credit card number, spaces and dashes are accepted","default":"","type":"string","name":"number"},{"_id":"5581d09a8625220d00429e41","ref":"","in":"body","required":true,"desc":"Expiration month","default":"","type":"string","name":"month"},{"_id":"5581d09a8625220d00429e40","ref":"","in":"body","required":true,"desc":"Expiration year","default":"","type":"string","name":"year"},{"_id":"5581d09a8625220d00429e4b","ref":"","in":"body","required":false,"desc":"Address line 1, recommended for address validation","default":"","type":"string","name":"address1"},{"_id":"5581d09a8625220d00429e4a","ref":"","in":"body","required":false,"desc":"Address line 2.","default":"","type":"string","name":"address2"},{"_id":"5581d09a8625220d00429e49","ref":"","in":"body","required":false,"desc":"City","default":"","type":"string","name":"city"},{"_id":"5581d09a8625220d00429e48","ref":"","in":"body","required":false,"desc":"State","default":"","type":"string","name":"state"},{"_id":"5581d09a8625220d00429e47","ref":"","in":"body","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country"},{"_id":"5581d09a8625220d00429e46","ref":"","in":"body","required":false,"desc":"Zip or postal code, recommended for address validation","default":"","type":"string","name":"zip"},{"_id":"5c4f40cb0cddf0002ca4c0d9","ref":"","in":"body","required":false,"desc":"Company name","default":"","type":"string","name":"company"},{"_id":"5581d09a8625220d00429e45","ref":"","in":"body","required":false,"desc":"Phone number","default":"","type":"string","name":"phone"},{"_id":"5581d09a8625220d00429e44","ref":"","in":"body","required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number"},{"_id":"56c3c1ce70187b17005f4395","ref":"","in":"body","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":"","type":"string","name":"currency"},{"_id":"5581d09a8625220d00429e3f","ref":"","in":"body","required":false,"desc":"Security code or CVV, 3-4 digits **STRONGLY RECOMMENDED**","default":"","type":"string","name":"verification_value"},{"_id":"5581d09a8625220d00429e43","ref":"","in":"body","required":false,"desc":"Customer's IPv4 address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address"},{"_id":"5d13bc71f68d8a0020e51f7c","ref":"","in":"body","required":false,"desc":"An id returned by Recurly.js referencing the result of the 3DS authentication for [PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2)","default":"","type":"string","name":"three_d_secure_action_result_token_id"},{"_id":"5d5dca1e28e72702694dc84c","ref":"","in":"body","required":false,"desc":"Indicates type of resulting transaction. accepted_values: \"moto\".","default":"","type":"string","name":"transaction_type"}],"url":"/accounts/:account_code/billing_info"},"isReference":true,"order":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]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"PSD2 and 3DS Authentication\",\n  \"body\": \"[PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2) is a regulation from the EEA effective September 2019. It requires 3DS / SCA (strong customer authentication) on certain transactions. Recurly has updated our gateway integrations to support this flow as well as enable merchants to send Recurly the required parameters. \\n\\nThis feature enables the fetching of ThreeDSecureActionToken and the passing of a ThreeDSecureActionResultToken id through the API.\\n\\nThis change was made to facilitate the flow of information needed to 3D secure a transaction for transactions requiring SCA.\\n\\nMerchants with an acquiring bank in the EEA must comply with SCA. They must support 3DS2 in order to authenticate card holders and send authorizations for transactions that were subject to SCA.\"\n}\n[/block]","excerpt":"Creates the account's Billing Information.","slug":"create-an-accounts-billing-info-credit-card","type":"post","title":"Create Account's Billing Info (Credit Card)","__v":13,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate 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
company:
string
Company name
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 IPv4 address when updating their Billing Information **STRONGLY RECOMMENDED**
three_d_secure_action_result_token_id:
string
An id returned by Recurly.js referencing the result of the 3DS authentication for [PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2)
transaction_type:
string
Indicates type of resulting transaction. accepted_values: "moto".

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.

PSD2 and 3DS Authentication

PSD2 is a regulation from the EEA effective September 2019. It requires 3DS / SCA (strong customer authentication) on certain transactions. Recurly has updated our gateway integrations to support this flow as well as enable merchants to send Recurly the required parameters.

This feature enables the fetching of ThreeDSecureActionToken and the passing of a ThreeDSecureActionResultToken id through the API.

This change was made to facilitate the flow of information needed to 3D secure a transaction for transactions requiring SCA.

Merchants with an acquiring bank in the EEA must comply with SCA. They must support 3DS2 in order to authenticate card holders and send authorizations for transactions that were subject to SCA.

Definition

{{ api_url }}{{ page_api_url }}

Examples

<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>
  <three_d_secure_action_result_token_id>3DS_TOKEN_ID</three_d_secure_action_result_token_id>
</billing_info>
<?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->three_d_secure_action_result_token_id = '3DS_TOKEN_ID';
  $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,
  :three_d_secure_action_result_token_id => '3DS_TOKEN_ID'
}
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
billing_info.three_d_secure_action_result_token_id = '3DS_TOKEN_ID'
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.ThreeDSecureActionResultTokenId = "3DS_TOKEN_ID";
info.Create();

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>
  <updated_at type="datetime">2017-02-17T15:38:53Z</updated_at>
</billing_info>
<errors>
  <transaction_error>
    <error_code>declined</error_code>
    <error_category>soft</error_category>
    <merchant_message>The customer's bank has declined their card. The customer will need to contact their bank to learn the cause.</merchant_message>
    <customer_message>Your transaction was declined. Please use a different card or contact your bank.</customer_message>
    <gateway_error_code nil="nil"/>
  </transaction_error>
  <error field="billing_info.base" symbol="declined">Your transaction was declined. Please use a different card or contact your bank.</error>
  <transaction href="https://your-subdomain.recurly.com/v2/transactions/3c4293ccd7f7bce494f85e4d48beb22e" type="credit_card">
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <uuid>3c4293ccd7f7bce494f85e4d48beb22e</uuid>
    <action>verify</action>
    <amount_in_cents type="integer">0</amount_in_cents>
    <tax_in_cents type="integer">0</tax_in_cents>
    <currency>USD</currency>
    <status>declined</status>
    <payment_method>credit_card</payment_method>
    <reference>676848</reference>
    <source>billing_info</source>
    <recurring type="boolean">false</recurring>
    <test type="boolean">true</test>
    <voidable type="boolean">false</voidable>
    <refundable type="boolean">false</refundable>
    <ip_address>127.0.0.1</ip_address>
    <transaction_error>
      <error_code>declined</error_code>
      <error_category>soft</error_category>
      <merchant_message>The customer's bank has declined their card. The customer will need to contact their bank to learn the cause.</merchant_message>
      <customer_message>Your transaction was declined. Please use a different card or contact your bank.</customer_message>
      <gateway_error_code nil="nil"/>
    </transaction_error>
    <cvv_result code="" nil="nil"/>
    <avs_result code="" nil="nil"/>
    <avs_result_street nil="nil"/>
    <avs_result_postal nil="nil"/>
    <created_at type="datetime">2017-03-15T21:03:40Z</created_at>
    <updated_at type="datetime">2017-03-15T21:03:40Z</updated_at>
    <details>
      <account>
        <account_code>1</account_code>
        <first_name>Verena</first_name>
        <last_name>Example</last_name>
        <company>New Company Name</company>
        <email>verena@example.com</email>
        <billing_info type="credit_card">
          <first_name>Verena</first_name>
          <last_name>Example</last_name>
          <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"/>
          <card_type>Visa</card_type>
          <year type="integer">2019</year>
          <month type="integer">11</month>
          <first_six>400000</first_six>
          <last_four>0002</last_four>
        </billing_info>
      </account>
    </details>
  </transaction>
</errors>


{"_id":"5dd5f0b02d076f0220ca8bfe","category":"5dd5f0b02d076f0220ca8b98","user":"55648cf93b87582b003ab8b1","project":"555fbba928249c1900618a82","parentDoc":null,"version":"5dd5f0b02d076f0220ca8c44","updates":["56ec2580df213e1700f77836"],"next":{"pages":[],"description":""},"createdAt":"2015-06-17T20:00:48.689Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"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>","name":""},{"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->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":"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 = 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":"csharp","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();"}]},"method":"post","results":{"codes":[{"code":"<billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\" type=\"bank_account\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <name_on_account>Acme, Inc.</name_on_account>\n  <first_name nil=\"nil\"></first_name>\n  <last_name nil=\"nil\"></last_name>\n  <company nil=\"nil\"></company>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone></phone>\n  <vat_number></vat_number>\n  <ip_address>127.0.0.1</ip_address>\n  <ip_address_country>US</ip_address_country>\n  <account_type>checking</account_type>\n  <last_four>5555</last_four>\n  <routing_number>065400137</routing_number>\n  <updated_at type=\"datetime\">2017-02-17T15:38:53Z</updated_at>\n</billing_info>","name":"","status":201,"language":"xml"},{"status":422,"language":"xml","code":"<errors>\n  <error field=\"billing_info.routing_number\" symbol=\"invalid\">is invalid</error>\n</errors>"}]},"settings":"","auth":"required","params":[{"_id":"55944fbb0c33bd0d0005964b","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"},{"_id":"5581d1f08625220d00429e6d","ref":"","in":"body","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 . ' & , -","default":"","type":"string","name":"name_on_account"},{"_id":"5581d1f08625220d00429e63","ref":"","in":"body","required":true,"desc":"Must be a real U.S. bank account routing number. All routing numbers are 9 digits.","default":"","type":"int","name":"routing_number"},{"_id":"5581d1f08625220d00429e62","ref":"","in":"body","required":true,"desc":"Bank account number between 4 and 17 digits. We do not validate this number until the first transaction, so we recommend you have the customer confirm their account number.","default":"","type":"int","name":"account_number"},{"_id":"5581d1f08625220d00429e61","ref":"","in":"body","required":true,"desc":"Either 'checking' or 'savings'","default":"","type":"string","name":"account_type"},{"_id":"5581d1f08625220d00429e6c","ref":"","in":"body","required":false,"desc":"Address line 1, recommended for address validation. This field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address1"},{"_id":"5581d1f08625220d00429e6b","ref":"","in":"body","required":false,"desc":"Address line 2, this field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address2"},{"_id":"5581d1f08625220d00429e6a","ref":"","in":"body","required":false,"desc":"City, this field has a 50 character max and can include: letters digits space . , -","default":"","type":"string","name":"city"},{"_id":"5581d1f08625220d00429e69","ref":"","in":"body","required":false,"desc":"State, this field has a 2 character max and can be lowercase or uppercase.","default":"","type":"string","name":"state"},{"_id":"5581d1f08625220d00429e68","ref":"","in":"body","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements). **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country"},{"_id":"5581d1f08625220d00429e67","ref":"","in":"body","required":false,"desc":"Zip or postal code, recommended for address validation. This field can be just 5 digits or can have an optional additional 4 digits separated by a hyphen (e.g. 12345-6789).","default":"","type":"string","name":"zip"},{"_id":"5c4f40e8cb87e500134c6eec","ref":"","in":"body","required":false,"desc":"Company name","default":"","type":"string","name":"company"},{"_id":"5581d1f08625220d00429e66","ref":"","in":"body","required":false,"desc":"Phone number, this field can be 10 digits.","default":"","type":"string","name":"phone"},{"_id":"5581d1f08625220d00429e65","ref":"","in":"body","required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number"},{"_id":"5581d1f08625220d00429e64","ref":"","in":"body","required":false,"desc":"Customer's IPv4 address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address"},{"_id":"5d5dca2ed2c6d4062a3d9d29","ref":"","in":"body","required":false,"desc":"Indicates type of resulting transaction. accepted_values: \"moto\".","default":"","type":"string","name":"transaction_type"}],"url":"/accounts/:account_code/billing_info"},"isReference":true,"order":2,"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]","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.","slug":"create-an-accounts-billing-info-bank-account","type":"post","title":"Create Account's Billing Info (Bank Account)","__v":3,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

postCreate Account's Billing Info (Bank Account)

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

Path Params

account_code:
required
string
Account's unique code.

Body Params

name_on_account:
required
string
The name associated with the account. This may be a person's full name or a business name. This field must be 1 to 50 characters and can include: letters digits space . ' & , -
routing_number:
required
integer
Must be a real U.S. bank account routing number. All routing numbers are 9 digits.
account_number:
required
integer
Bank account number between 4 and 17 digits. We do not validate this number until the first transaction, so we recommend you have the customer confirm their account number.
account_type:
required
string
Either 'checking' or 'savings'
address1:
string
Address line 1, recommended for address validation. This field has a 50 character max and can include: letters digits space . # / , -
address2:
string
Address line 2, this field has a 50 character max and can include: letters digits space . # / , -
city:
string
City, this field has a 50 character max and can include: letters digits space . , -
state:
string
State, this field has a 2 character max and can be lowercase or uppercase.
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).
company:
string
Company name
phone:
string
Phone number, this field can be 10 digits.
vat_number:
string
Customer's VAT Number
ip_address:
string
Customer's IPv4 address when updating their Billing Information **STRONGLY RECOMMENDED**
transaction_type:
string
Indicates type of resulting transaction. accepted_values: "moto".

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

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

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>
  <updated_at type="datetime">2017-02-17T15:38:53Z</updated_at>
</billing_info>
<errors>
  <error field="billing_info.routing_number" symbol="invalid">is invalid</error>
</errors>


{"_id":"5dd5f0b02d076f0220ca8bff","category":"5dd5f0b02d076f0220ca8b98","user":"56c3c01334df460d00c2beb3","parentDoc":null,"project":"555fbba928249c1900618a82","version":"5dd5f0b02d076f0220ca8c44","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-29T21:58:10.697Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"name":"","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>","language":"xml"},{"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}","language":"php"},{"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"},{"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"},{"code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.FirstName = \"Verana\";\ninfo.LastName = \"Example\";\ninfo.PaypalBillingAgreementId = \"BA-0HS87238YB688345C\";\ninfo.Create();","language":"csharp"}]},"method":"post","results":{"codes":[{"name":"","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  <updated_at type=\"datetime\">2017-02-17T15:38:53Z</updated_at>\n</billing_info>","language":"xml","status":201}]},"settings":"","auth":"required","params":[{"_id":"55944fab5c9eaa2300a8633c","ref":"","in":"path","required":true,"desc":"Account's unique code.","default":"","type":"string","name":"account_code"},{"_id":"5581d09a8625220d00429e4d","ref":"","in":"body","required":true,"desc":"First name","default":"","type":"string","name":"first_name"},{"_id":"5581d09a8625220d00429e4c","ref":"","in":"body","required":false,"desc":"Last name","default":"","type":"string","name":"last_name"},{"_id":"5581d09a8625220d00429e4b","ref":"","in":"body","required":false,"desc":"Address line 1, recommended for address validation","default":"","type":"string","name":"address1"},{"_id":"5581d09a8625220d00429e4a","ref":"","in":"body","required":false,"desc":"Address line 2.","default":"","type":"string","name":"address2"},{"_id":"5581d09a8625220d00429e49","ref":"","in":"body","required":false,"desc":"City","default":"","type":"string","name":"city"},{"_id":"5581d09a8625220d00429e48","ref":"","in":"body","required":false,"desc":"State","default":"","type":"string","name":"state"},{"_id":"5581d09a8625220d00429e47","ref":"","in":"body","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country"},{"_id":"5581d09a8625220d00429e46","ref":"","in":"body","required":false,"desc":"Zip or postal code, recommended for address validation","default":"","type":"string","name":"zip"},{"_id":"5581d09a8625220d00429e45","ref":"","in":"body","required":false,"desc":"Phone number","default":"","type":"string","name":"phone"},{"_id":"58ac88c71909810f00fda9a2","ref":"","in":"body","required":false,"desc":"Amazon's billing agreement","default":"","type":"string","name":"amazon_billing_agreement_id"},{"_id":"5c6c596abc446800511f61f0","ref":"","in":"body","required":false,"desc":"Denotes the originating region of the agreement. This attribute also tells the API how to route transactions based on the originating region. Possible values: `us`, `eu`, `uk`. Must be used in conjunction with amazon_billing_agreement.","default":"","type":"string","name":"amazon_region"},{"_id":"58b4adc1ed60c11900989b38","ref":"","in":"body","required":false,"desc":"Braintree's payment method nonce representing the Paypal billing agreement id. This is required when processing Paypal transactions through Braintree.","default":"","type":"string","name":"braintree_payment_nonce"},{"_id":"5723d8f2110e570e00486c2f","ref":"","in":"body","required":false,"desc":"Paypal's billing agreement","default":"","type":"string","name":"paypal_billing_agreement_id"},{"_id":"585886cd59b00a0f007f1b44","ref":"","in":"body","required":false,"desc":"Roku's CIB if billing through Roku","default":"","type":"string","name":"roku_billing_agreement_id"},{"_id":"5581d09a8625220d00429e44","ref":"","in":"body","required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number"},{"_id":"56c3c1ce70187b17005f4395","ref":"","in":"body","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":"","type":"string","name":"currency"},{"_id":"5581d09a8625220d00429e43","ref":"","in":"body","required":false,"desc":"Customer's IPv4 address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address"},{"_id":"5b97e46b78e3d800030f23ee","ref":"","in":"body","required":false,"desc":"A token used in place of a credit card in order to perform transactions. Must be used in conjunction with gateway_code.","default":"","type":"string","name":"gateway_token"},{"_id":"5b97e46b78e3d800030f23ed","ref":"","in":"body","required":false,"desc":"An identifier for a specific payment gateway. Must be used in conjunction with gateway_token.","default":"","type":"string","name":"gateway_code"},{"_id":"5baa498392f810000352226a","ref":"","in":"body","required":false,"desc":"Represents the card type associated with the billing info. Must be a supported card type.","default":"","type":"string","name":"card_type"},{"_id":"5c4f414ece360f011e93faaf","ref":"","in":"body","required":false,"desc":"Company name","default":"","type":"string","name":"company"},{"_id":"5d5dca3bfe803c006f39b70c","ref":"","in":"body","required":false,"desc":"Indicates type of resulting transaction. accepted_values: \"moto\".","default":"","type":"string","name":"transaction_type"}],"url":"/accounts/:account_code/billing_info"},"isReference":true,"order":3,"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]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Supported Gateway Tokens\",\n  \"body\": \"Recurly currently only supports `gateway_token` values from the following gateways:\\n\\n- Braintree\\n- Vantiv \\n\\nGateway tokens from other payment gateways are unsupported at this time.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Amazon Pay\",\n