Recurly

Accounts API

Table of Contents

List Accounts

Returns a list of the accounts on your site.

GET https://:subdomain.recurly.com/v2/accounts

Query Parameters

Parameter Default Description
state active The state of accounts to return: "active" or "closed"
cursor Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page 50 Number of records to return per page, up to a maximum of 200.

Account States

active
Active accounts
closed
Closed accounts

Please note: an account may be in more than one state. For example, an account may be active and have a past-due invoice.

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 123
Link: <https://your-subdomain.recurly.com/v2/accounts?cursor=1304958672>; rel="next"
ETag: "0172c6c72335c9346256a5c483bf3066"
<?xml version="1.0" encoding="UTF-8"?>
<accounts type="array">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1">
    <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
    <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
    <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
    <redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemption"/>
    <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
    <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
    <account_code>1</account_code>
    <state>active</state>
    <username nil="nil"></username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name></company_name>
    <vat_number nil="nil"></vat_number>
    <tax_exempt type="boolean">false</tax_exempt>
    <address>
      <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>
    </address>
    <accept_language nil="nil"></accept_language>
    <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>
    <created_at type="datetime">2011-10-25T12:00:00</created_at>
  </account>
  <!-- Continued... -->
</accounts>
$accounts = Recurly_AccountList::getActive();
foreach ($accounts as $account) {
  print "Account: $account\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page.
Recurly::Account.find_each do |account|
  puts "Account: #{account.inspect}"
end
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page.
#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 = ()

#client version 2.1.6+
for account in Account.all():
    print 'Account: %s' % account

Get Account

Returns information about a single account.

GET https://:subdomain.recurly.com/v2/accounts/:account_code

Response Parameters

Parameter Description
account_code Your unique account identifier.
state "active" or "closed".
username Username, not used within Recurly.
email Email address.
first_name First name.
last_name Last name.
company_name Company name.
vat_number VAT number to avoid having the VAT applied (if applicable).
tax_exempt true exempts tax on the account, false applies tax on the account. If not defined, then defaults to the Plan and Site settings.
address Nested address information.
accept_language An ISO 639-1 language code from the user's browser, indicating their preferred language and locale.
hosted_login_token Unique token for automatically logging the account in to the hosted management pages.
created_at Date the user was created in Recurly.

Hosted Login Token

You may automatically log the user into their hosted management pages by directing the user to:

https://:subdomain.recurly.com/account/:hosted_login_token

Code Example

Response

<?xml version="1.0" encoding="UTF-8"?>
<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
  <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
  <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
  <redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemption"/>
  <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
  <account_code>1</account_code>
  <state>active</state>
  <username nil="nil"></username>
  <email>verena@example.com</email>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company_name></company_name>
  <vat_number nil="nil"></vat_number>
  <tax_exempt type="boolean">false</tax_exempt>
  <address>
    <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>
  </address>
  <accept_language nil="nil"></accept_language>
  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>
  <created_at type="datetime">2011-10-25T12:00:00</created_at>
</account>
try {
  $account = Recurly_Account::get('1');
  print "Account: $account\n";
} catch (Recurly_NotFoundError $e) {
  print "Account not found.\n";
}

Please note: the client library will raise an exception if the account is not found.

begin
  account = Recurly::Account.find '1'
  puts "Account: #{account.inspect}"
rescue Recurly::Resource::NotFound => e
  puts e.message
end

Please note: the client library will raise an exception if the account is not found.

try:
  account = Account.get('1')
  print "Account: %s" % account
except NotFoundError:
  print "Account not found.\n"

Please note: the client library will raise an exception if the account is not found.

Create Account

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

POST https://:subdomain.recurly.com/v2/accounts

Account Attributes

Parameter Description
account_code A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 50 characters.Required
username Username, ignore if you do not use usernames.
email Email address
first_name First name. Max of 50 characters.
last_name Last name. Max of 50 characters.
company_name Company name. Max of 50 characters.
vat_number VAT number to avoid having the VAT applied (if applicable).
tax_exempt true exempts tax on the account, false applies tax on the account. If not defined, then defaults to the Plan and Site settings.
billing_info Nested billing information. If present, the account will only be created after the billing information is validated.
address Nested address information.
accept_language An ISO 639-1 language code from the user's browser, indicating their preferred language and locale.

Account Code

We strongly recommend you use an account code unique to your system, such as the auto-incrementing ID from your users database. Email addresses change and are not guaranteed to be unique, so we discourage using emails for your account code.

Billing Info

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

Accept Language

The accept language header from the user's browser on signup. This can be used by Recurly to format PDF invoices in the customer's preferred locale and language.

Example

Request

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<account>
  <account_code>1</account_code>
  <email>verena@example.com</email>
  <first_name>verena</first_name>
  <last_name>example</last_name>
</account>

Response

Accept: application/xml
Status: 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/accounts/1
<?xml version="1.0" encoding="UTF-8"?>
<account href="https://your-subdomain.recurly.com/v2/accounts/1">
  <adjustments href="https://your-subdomain.recurly.com/v2/accounts/1/adjustments"/>
  <billing_info href="https://your-subdomain.recurly.com/v2/accounts/1/billing_info"/>
  <invoices href="https://your-subdomain.recurly.com/v2/accounts/1/invoices"/>
  <redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemption"/>
  <subscriptions href="https://your-subdomain.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://your-subdomain.recurly.com/v2/accounts/1/transactions"/>
  <account_code>1</account_code>
  <state>active</state>
  <username nil="nil"></username>
  <email>verena@example.com</email>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company_name></company_name>
  <vat_number nil="nil"></vat_number>
  <tax_exempt type="boolean">false</tax_exempt>
  <address>
    <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>
  </address>
  <accept_language nil="nil"></accept_language>
  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>
  <created_at type="datetime">2011-10-25T12:00:00</created_at>
</account>
$account = new Recurly_Account('1');
$account->email = 'verena@example.com';
$account->first_name = 'Verena';
$account->last_name = 'Example';
$account->create();
account = Recurly::Account.create(
  :account_code => '1',
  :email        => 'verena@example.com',
  :first_name   => 'Verena',
  :last_name    => 'Example'
)
account = Account(account_code='1')
account.email = 'verena@example.com'
account.first_name = 'Verena'
account.last_name = 'Example'
account.save()

Update Account

Updates an existing account.

PUT https://:subdomain.recurly.com/v2/accounts/:account_code

Updatable Account Attributes

Parameter Description
username Username, ignore if you do not use usernames
email Email address
first_name First name
last_name Last name
company_name Company name. Max of 50 characters.
vat_number VAT number to avoid having the VAT applied (if applicable).
tax_exempt true exempts tax on the account, false applies tax on the account. If not defined, then defaults to the Plan and Site settings.
billing_info Nested billing information. If present, the account will only be updated after the billing information is validated.
address Nested address information.
accept_language An ISO 639-1 language code from the user's browser, indicating their preferred language and locale.

Billing Info

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.

Close Account

Marks an account as closed and cancels any active subscriptions. Any saved billing information will also be permanently removed from the account.

DELETE https://:subdomain.recurly.com/v2/accounts/:account_code

Example

Response

Status: 204 No Content
$account = Recurly_Account::get('1');
$account->close();

// Or close an account without retrieving it first (1 api request vs. 2).
// $account = new Recurly_Account('1');
// $account->close();
account = Recurly::Account.find('1')
account.destroy
account = Account.get('1')
account.delete()

Reopen Account

Transitions a closed account back to active.

PUT https://:subdomain.recurly.com/v2/accounts/:account_code/reopen

Editing an account, creating a new transaction or subscription also reopens an account. Reopening an account does not modify any previously canceled or expired subscriptions.

Example

Response

Status: 204 No Content
$account = Recurly_Account::get('account_code');
$account->reopen();

//OR ...
$account = Recurly_Account::reopenAccount('account_code');
account = Recurly::Account.find '1'
account.reopen
account = Account.get('1')
account.reopen()

List Account Notes

Returns a list of the notes on an account sorted in descending order.

GET https://:subdomain.recurly.com/v2/accounts/:account/notes

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 4
Link: <https://your-subdomain.recurly.com/v2/accounts?cursor=1304958672>; rel="next"
ETag: "0172c6c72335c9346256a5c483bf3066"
<?xml version="1.0" encoding="UTF-8"?>
<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">2013-05-14T18:53:04Z</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">2013-05-14T18:52:50Z</created_at>
  </note>
  <!-- Continued... -->
</notes>
$notes = Recurly_NoteList::get('1');
foreach ($notes as $note) {
  print "Note: {$note->message}\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page.
#Coming Soon
try:
  account = Account.get('1')
  for note in account.notes():
   print "Note: %s" % note.message
except NotFoundError:
  print "Account not found.\n"