Recurly

Accounts API

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", "closed", or "past_due".
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
past_due
Accounts with at least one past-due invoice

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>
    <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
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>
  <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.
accept_language An ISO 639-1 language code from the user's browser, indicating their preferred language and locale
billing_info Nested billing information. If present, the account will only be created after the billing information is validated

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.

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.

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.

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>
  <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 First name
accept_language An ISO 639-1 language code from the user's browser, indicating their preferred language and locale
billing_info Nested billing information. If present, the account will only be updated after the billing information is validated

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');

#coming soon

#coming soon

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"