Recurly Accounts API

openapi: 3.2.0
info:
  title: Recurly Accounts API
  version: '1.0'
  description: 'Operations tagged accounts across 2 of this provider''s published API definitions: recurly-v2-api.yaml, recurly-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{subdomain}.recurly.com/v2
  variables:
    subdomain:
      description: Subdomain of your Recurly site.
      default: my-super-successful-company
security:
- api_key: []
tags:
- name: Accounts
  x-displayName: Accounts
paths:
  /accounts:
    get:
      summary: List Accounts
      description: 'Returns a list of accounts on your site.


        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.'
      tags:
      - Accounts
      operationId: listAccounts
      parameters:
      - in: query
        name: state
        schema:
          type: string
          default: all
        required: false
        description: 'The state of accounts to return: "active" or "closed"'
      - in: query
        name: cursor
        schema:
          type: string
          default: ''
        required: false
        description: Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
      - in: query
        name: per_page
        schema:
          type: integer
          default: '50'
        required: false
        description: Number of records to return per page, up to a maximum of 200.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<accounts type=\"array\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783\">\n    <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/adjustments\"/>\n    <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/billing_info\"/>\n    <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/invoices\"/>\n    <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/redemption\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/subscriptions\"/>\n    <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/transactions\"/>\n    <account_code>b6f5783</account_code>\n    <state>active</state>\n    <username nil=\"nil\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name></company_name>\n    <vat_number nil=\"nil\"></vat_number>\n    <tax_exempt type=\"boolean\">false</tax_exempt>\n    <address>\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    </address>\n    <accept_language nil=\"nil\"></accept_language>\n    <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n    <created_at type=\"datetime\">2015-02-25T12:00:00</created_at>\n  </account>\n  <!-- Continued... -->\n</accounts>\n"
      x-codeSamples:
      - lang: PHP
        source: "$accounts = Recurly_AccountList::getActive();\nforeach ($accounts as $account) {\n  print \"Account: $account\\n\";\n}"
      - lang: Ruby
        source: "Recurly::Account.find_each do |account|\n  puts \"Account: #{account.inspect}\"\nend"
      - lang: Python
        source: "#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 = ()\n\n#client version 2.1.6+\nfor account in Account.all():\n    print 'Account: %s' % account"
      - lang: Dotnet
        source: "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}"
    post:
      summary: Create an Account
      description: Creates a new account. You may optionally include billing information.
      tags:
      - Accounts
      operationId: createAnAccount
      parameters: []
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              properties:
                account_code:
                  type: string
                  default: ''
                  description: '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.'
                username:
                  type: string
                  default: ''
                  description: Username, ignore if you do not use usernames. Max of 255 characters.
                email:
                  type: string
                  default: ''
                  description: Email address.
                first_name:
                  type: string
                  default: ''
                  description: First name. Max of 255 characters.
                last_name:
                  type: string
                  default: ''
                  description: Last name. Max of 255 characters.
                company_name:
                  type: string
                  default: ''
                  description: Company name. Max of 255 characters.
                vat_number:
                  type: string
                  default: ''
                  description: VAT number to avoid having the VAT applied (if applicable).
                tax_exempt:
                  type: boolean
                  default: ''
                  description: true exempts tax on the account, false applies tax on the account. If not defined, then defaults to the Plan and Site settings.
                entity_use_code:
                  type: string
                  default: ''
                  description: Avalara AvaTax value that can be passed to identify the customer type for tax purposes. The range of values can be A - R (more info at Avalara). Value is case-sensitive.
                billing_info:
                  type: object
                  default: ''
                  description: Nested billing information. If present, the account will only be created after the billing information is validated.
                address:
                  type: object
                  default: ''
                  description: Nested address information.
                accept_language:
                  type: string
                  default: ''
                  description: An ISO 639-1 language code from the user's browser, indicating their preferred language and locale.
      responses:
        '201':
          description: ''
          content:
            application/xml:
              example: "Status: 201 Created\nContent-Type: application/xml; charset=utf-8\nLocation: https://your-subdomain.recurly.com/v2/accounts/b6f5783\n\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<account href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783\">\n  <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/adjustments\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/invoices\"/>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/redemption\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/transactions\"/>\n  <account_code>b6f5783</account_code>\n  <state>active</state>\n  <username nil=\"nil\"></username>\n  <email>verena@example.com</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name></company_name>\n  <vat_number nil=\"nil\"></vat_number>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address>\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  </address>\n  <accept_language nil=\"nil\"></accept_language>\n  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n  <created_at type=\"datetime\">2015-02-25T12:00:00</created_at>\n</account>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $account = new Recurly_Account('b6f5783');\n  $account->email = 'verena@example.com';\n  $account->first_name = 'Verena';\n  $account->last_name = 'Example';\n  $account->create();\n\n  print \"Account: $account\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Account: $e\";\n}"
      - lang: Ruby
        source: "account = Recurly::Account.create(\n  :account_code => '1',\n  :email        => 'verena@example.com',\n  :first_name   => 'Verena',\n  :last_name    => 'Example'\n)"
      - lang: Python
        source: 'account = Account(account_code=''1'')

          account.email = ''verena@example.com''

          account.first_name = ''Verena''

          account.last_name = ''Example''

          account.save()'
      - lang: Dotnet
        source: "var account = new Account(\"1\")\n{\n  Email = \"verena@example.com\",\n  FirstName = \"Verena\",\n  LastName = \"Example\"\n};\naccount.Create();"
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
  /accounts/{account_code}:
    get:
      summary: Get Account
      description: 'Returns information about a single account.


        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`


        ###### Please note


        The client library will raise an exception if the account is not found.'
      tags:
      - Accounts
      operationId: getAccount
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Your unique account identifier.
      - in: query
        name: state
        schema:
          type: string
          default: ''
        required: false
        description: '"active" or "closed"'
      - in: query
        name: username
        schema:
          type: string
          default: ''
        required: false
        description: Username, not used within Recurly.
      - in: query
        name: email
        schema:
          type: string
          default: ''
        required: false
        description: Email address.
      - in: query
        name: first_name
        schema:
          type: string
          default: ''
        required: false
        description: First name.
      - in: query
        name: last_name
        schema:
          type: string
          default: ''
        required: false
        description: Last name.
      - in: query
        name: company_name
        schema:
          type: string
          default: ''
        required: false
        description: Company name.
      - in: query
        name: vat_number
        schema:
          type: string
          default: ''
        required: false
        description: VAT number to avoid having the VAT applied (if applicable).
      - in: query
        name: tax_exempt
        schema:
          type: boolean
          default: ''
        required: false
        description: '`true` exempts tax on the account, `false` applies tax on the account. If not defined, then defaults to the Plan and Site settings.'
      - in: query
        name: address
        schema:
          type: object
          default: ''
        required: false
        description: Nested address information.
      - in: query
        name: accept_language
        schema:
          type: string
          default: ''
        required: false
        description: An ISO 639-1 language code from the user's browser, indicating their preferred language and locale.
      - in: query
        name: hosted_login_token
        schema:
          type: string
          default: ''
        required: false
        description: Unique token for automatically logging the account in to the hosted management pages.
      - in: query
        name: created_at
        schema:
          type: string
          format: date-time
          default: ''
        required: false
        description: Date the user was created in Recurly.
      - in: query
        name: vat_location_valid
        schema:
          type: string
          default: ''
        required: false
        description: Only shows if you have the VAT Location Validation feature turned on in Tax Settings. Returns `true` if valid, `false` if invalid, and nil (empty) if the account does not fit the requirements for validation.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<account href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783\">\n  <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/adjustments\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/invoices\"/>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/redemption\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/transactions\"/>\n  <account_code>b6f5783</account_code>\n  <state>active</state>\n  <username nil=\"nil\"></username>\n  <email>verena@example.com</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name></company_name>\n  <vat_number nil=\"nil\"></vat_number>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\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  </address>\n  <accept_language nil=\"nil\"></accept_language>\n  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n  <created_at type=\"datetime\">2014-02-25T12:00:00</created_at>\n</account>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $account = Recurly_Account::get('b6f5783');\n  print \"Account: $account\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Account not found\";\n}"
      - lang: Ruby
        source: "begin\n  account = Recurly::Account.find('b6f5783')\n  puts \"Account: #{account.inspect}\"\nrescue Recurly::Resource::NotFound => e\n  puts e.message\nend"
      - lang: Python
        source: "try:\n  account = Account.get('b6f5783')\n  print \"Account: %s\" % account\nexcept NotFoundError:\n  print \"Account not found.\\n\""
      - lang: Dotnet
        source: "try\n{\n\tvar account = Accounts.Get(\"b6f5783\");\n\tConsole.WriteLine(\"Account \" + account);\n}\ncatch (NotFoundException e)\n{\n\tConsole.WriteLine(\"Account not found.\");\n}"
    delete:
      summary: Close Account
      description: Marks an account as closed and cancels any active subscriptions. Any saved billing information will also be permanently removed from the account.
      tags:
      - Accounts
      operationId: closeAccount
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Your unique account identifier.
      responses:
        '204':
          description: ''
          content:
            application/xml:
              example: 'Status: 204 No Content'
      x-codeSamples:
      - lang: PHP
        source: "try {\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}"
      - lang: Ruby
        source: 'account = Recurly::Account.find(''1'')

          account.destroy!'
      - lang: Python
        source: 'account = Account.get(''1'')

          account.delete()'
      - lang: Dotnet
        source: 'var account = Accounts.Get("1");

          account.Close();'
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
  /{account_code}:
    put:
      summary: Update Account
      description: 'Updates an existing account.


        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.'
      tags:
      - Accounts
      operationId: updateAccount
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Your unique account identifier.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              properties:
                username:
                  type: string
                  default: ''
                  description: Username, ignore if you do not use usernames
                email:
                  type: string
                  default: ''
                  description: Email address.
                first_name:
                  type: string
                  default: ''
                  description: First name.
                last_name:
                  type: string
                  default: ''
                  description: Last name.
                company_name:
                  type: string
                  default: ''
                  description: Company name.
                vat_number:
                  type: string
                  default: ''
                  description: VAT number to avoid having the VAT applied (if applicable)
                tax_exempt:
                  type: string
                  default: ''
                  description: '`true` exempts tax on the account, `false` applies tax on the account. If not defined, then defaults to the Plan and Site settings.'
                entity_use_code:
                  type: string
                  default: ''
                  description: Avalara AvaTax value that can be passed to identify the customer type for tax purposes. The range of values can be A - R (more info at Avalara). Value is case-sensitive.
                billing_info:
                  type: object
                  default: ''
                  description: Nested billing information. If present, the account will only be updated after the billing information is validated.
                address:
                  type: object
                  default: ''
                  description: Nested address information.
                accept_language:
                  type: string
                  default: ''
                  description: An ISO 639-1 language code from the user's browser, indicating their preferred language and locale.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "Status: 200 OK\nContent-Type: application/xml; charset=utf-8\nLocation: https://your-subdomain.recurly.com/v2/accounts/b6f5783\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<account href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783\">\n  <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/adjustments\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/invoices\"/>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/redemption\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783/transactions\"/>\n  <account_code>b6f5783</account_code>\n  <state>active</state>\n  <username nil=\"nil\"></username>\n  <email>verena@example.com</email>\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\"></vat_number>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\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  </address>\n  <accept_language nil=\"nil\"></accept_language>\n  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n  <created_at type=\"datetime\">2011-10-25T12:00:00</created_at>\n</account>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $account = Recurly_Account::get('b6f5783');\n  $account->company_name = 'New Company Name';\n  $account->update();\n\n  print \"Account: $account\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid account code: $e\";\n}"
      - lang: Ruby
        source: 'account = Recurly::Account.find(''account_1'')

          account.company_name = ''New Company Name''

          account.save'
      - lang: Python
        source: 'account = Account.get(''account_1'')

          account.company_name = ''New Company Name''

          account.save()'
      - lang: Dotnet
        source: 'var account = Account.Get("account_1");

          account.CompanyName = "New Company Name";

          account.Update();'
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
  /accounts/{account_code}/reopen:
    put:
      summary: Reopen Account
      description: 'Transitions a closed account back to active.


        ###### Please note


        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.'
      tags:
      - Accounts
      operationId: reopenAccount
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Your unique account identifier.
      responses:
        '204':
          description: ''
          content:
            application/xml:
              example: 'Status: 204 No Content'
      x-codeSamples:
      - lang: PHP
        source: "try {\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}"
      - lang: Ruby
        source: 'account = Recurly::Account.find ''1''

          account.reopen'
      - lang: Python
        source: 'account = Account.get(''1'')

          account.reopen()'
      - lang: Dotnet
        source: 'var account = Accounts.Get("1");

          account.Reopen();'
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
  /accounts/{account_code}/notes:
    get:
      summary: List Account Notes
      description: Returns a list of the notes on an account sorted in descending order.
      tags:
      - Accounts
      operationId: listAccountNotes
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Your unique account identifier.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "Status: 200 OK\nContent-Type: application/xml; charset=utf-8\nX-Records: 4\nLink: <https://your-subdomain.recurly.com/v2/accounts?cursor=1304958672>; rel=\"next\"\nETag: \"0172c6c72335c9346256a5c483bf3066\"\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<notes type=\"array\">\n  <note>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783\"/>\n    <message>This is my second note</message>\n    <created_at type=\"datetime\">2013-05-14T18:53:04Z</created_at>\n  </note>\n  <note>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783\"/>\n    <message>This is my first note</message>\n    <created_at type=\"datetime\">2013-05-14T18:52:50Z</created_at>\n  </note>\n  <!-- Continued... -->\n</notes>"
      x-codeSamples:
      - lang: PHP
        source: "try {\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}"
      - lang: Python
        source: "try:\n  account = Account.get('1')\n  for note in account.notes():\n   print \"Note: %s\" % note.message\nexcept NotFoundError:\n  print \"Account not found.\\n\""
      - lang: Dotnet
        source: "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}"
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
components:
  securitySchemes:
    api_key:
      type: http
      description: Enter the API key as the username and set the password to an empty string. You can locate and manage your API keys from the [API Credentials](https://app.recurly.com/go/developer/api_keys) page.
      scheme: basic
x-refined-from:
- recurly-v2-api.yaml
- recurly-v2-openapi.yml
x-readme:
  explorer-enabled: false