Accounts API

List Accounts

Returns a list of the accounts on your site.

GET https://api.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://api.recurly.com/v2/accounts?cursor=1304958672>; rel="next"
ETag: "0172c6c72335c9346256a5c483bf3066"

<?xml version="1.0" encoding="UTF-8"?>
<accounts type="array">
  <account href="https://api.recurly.com/v2/accounts/1">
    <adjustments href="https://api.recurly.com/v2/accounts/1/adjustments"/>
    <billing_info href="https://api.recurly.com/v2/accounts/1/billing_info"/>
    <invoices href="https://api.recurly.com/v2/accounts/1/invoices"/>
    <redemption href="https://api.recurly.com/v2/accounts/1/redemption"/>
    <subscriptions href="https://api.recurly.com/v2/accounts/1/subscriptions"/>
    <transactions href="https://api.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.

accounts = Account.all()
while accounts:
    for account in accounts:
        print 'Account: %s' % account
    try:
        accounts = accounts.next_page()
    except PageError:
        accounts = ()

// TODO

Get Account

Returns information about a single account.

GET https://api.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://api.recurly.com/v2/accounts/1">
  <adjustments href="https://api.recurly.com/v2/accounts/1/adjustments"/>
  <billing_info href="https://api.recurly.com/v2/accounts/1/billing_info"/>
  <invoices href="https://api.recurly.com/v2/accounts/1/invoices"/>
  <redemption href="https://api.recurly.com/v2/accounts/1/redemption"/>
  <subscriptions href="https://api.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://api.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.

RecurlyAccount account = RecurlyAccount.Get("1");

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://api.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 A-Z 0-9 @ - _ .]. Required
`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 created or updated 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://api.recurly.com/v2/accounts/1

<?xml version="1.0" encoding="UTF-8"?>
<account href="https://api.recurly.com/v2/accounts/1">
  <adjustments href="https://api.recurly.com/v2/accounts/1/adjustments"/>
  <billing_info href="https://api.recurly.com/v2/accounts/1/billing_info"/>
  <invoices href="https://api.recurly.com/v2/accounts/1/invoices"/>
  <redemption href="https://api.recurly.com/v2/accounts/1/redemption"/>
  <subscriptions href="https://api.recurly.com/v2/accounts/1/subscriptions"/>
  <transactions href="https://api.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()

RecurlyAccount account = new RecurlyAccount("1");
account.Email = "verena@example.com";
account.FirstName = "Verena";
account.LastName = "Test";
account.Create();

Update Account

Updates an existing account.

PUT https://api.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

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://api.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 = Account.find('1')
account.destroy

account = Account.get('1')
account.delete()

RecurlyAccount account = RecurlyAccount.Get("1");
account.CloseAccount();

Reopen Account

Transitions a closed account back to active.

PUT https://api.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.