📘

Account Hierarchy

• Use Recurly to manage your parent-child customer account relationships, billing and subscription ownership
• Assign a parent to a specific child account
• Configure billing for a child to bill and invoice all charges to its parent or to itself.

This feature is available on Recurly's Elite Plan. You must have the Credit Invoices, Only Bill What Changed, and Subscription Billing Terms features enabled on your site. If you use our Client Libraries, this feature will be available in version 2.18.

To enable Account Hierarchy for your site, please contact [email protected]

Getting Started

Any customer account on your Recurly site can become a parent account or a child account. There are a few ways to set up your child and parent accounts in Recurly. You can achieve this through the Admin UI or through the API. Below outlines the functionality through the Admin UI.

Assign a Parent Account

When assigning a parent account through the UI, the process to set up account hierarchy will be completed either during account creation or as an edit to the account. The steps to complete this during account creation, scroll to the Account Hierarchy section, make appropriate selections by either typing in the parent account's code (or name), and select how the billing should be processed (on either Child or Parent's account).

When assigning an account as a parent, a child account (e.g already has a parent) cannot also be assigned as a parent to another account. Child accounts will not be listed in the drop down menu and will not be allowed as parents through the API.

In terms of levels of hierarchy, a child can only ever have a single parent assigned to it. For example, a child cannot have a parent and a grandparent.

In order to edit already created accounts, access the account you desire to have as a child account. Once on the account, look on the right side of the page there you will see the Account Information box, and click the Edit hyperlink in upper right corner of the box.

On the page which displays, scroll down until you get to the Account Hierarchy section, here you will be able to search (type in account name or code) or click the drop down to locate the account (same as when creating connection during account creation) you desire to have as the Parent account. If you select the wrong account, you can click Remove Parent to select correct account. Also be sure to select if the transactions should bill to the child's or parent's account. Once you have the appropriate selections, scroll to the bottom and click Save Changes button.

Once you have completed these steps, you will be directed back to the account and it will appear this way, letting you know you have successfully added the account hierarchy link.​​

Assign a bill-to-account

After selecting an account as the parent, you must select where all charges should be billed. By default, all charges for a child will bill to itself. The other option, is to bill all charges to the Parent Account. This is most common in businesses where a parent organization or headquarters manages finances for multiple child companies.

For example, Pizza Planet headquarters is a parent account that owns multiple pizza parlors. Each pizza parlor is represented by a child customer account linked to the Pizza Planet Headquarters parent customer account. If this new child account is configured to Bill All Charges to: Parent Account , all charges will be billed to Jane Doe of Pizza Planet Headquarters.

View a Child or Parent Account

After saving a new child account or updating an existing account with a parent, you should see the relevant Account Hierarchy related information from both the child accounts and the parent account.

View Child Account Information

When viewing a child account, the Account Information includes a tag called "Child" to denote that the account is a child account.

Within the Account Information card, there is a section which includes the Parent Account name and links to the parent account. There also is a link to View Account Hierarchy, which takes you to an overview page of all children accounts, subscriptions, and invoices. This is also accessible from the parent account.

If a child account bills all charges to itself, the Bill To will reflect "This Account". If a child account bills all charges to its parent, the Bill To will reflect the Parent Account.

View Parent Account Information

When viewing a parent account, the Account Information includes a tag called "Parent" to denote that the account is a parent account.

The Account Information card unlike a child account, lists the number of children associated with this parent account. There is also a link to access the same overview page accessible from any child account of the parent.

Account Hierarchy Overview Page

This page is accessible from either the child's account information or the parent account information. This page includes several index pages:

• Accounts: lists all child accounts associated to the parent parent. The parent account is anchored to the top of the list of accounts
• Subscriptions: lists all subscriptions belonging to children associated to the parent. If a parent also has a subscription(s), it is anchored to the top of the index page.
• Invoices: lists all invoices belonging to children and the parent. If you want to filter for only invoices billed to the parent, you should use the Bill To filter.

In addition to the existing index filters, we also added the ability to filter based on the Bill To rule for an account. You can filter accounts, subscriptions, and invoices based on whether they are billed for a child account to a parent or if the are billed to itself.

Billing Configuration

Depending on whether a child account is configured to Bill Charges to itself or to a parent, Recurly will handle invoice and billing events differently.

Child Account that Bills to Itself

When a child account is configured to manage it's own billing information and responsibilities, there is no difference in how the account behaves from a regular customer account in Recurly. The main difference, is that the child account is associated to a parent account. For example, the child account will be included in the Overview Page in the Admin UI.

Additionally, the parent-child relationship will be exposed in our Exports so that you have insight into your customer relationships.

Child Account that Bills to Parent

A child can be configured to have payment information, invoices, charges, and credits belong to the parent. When a child account is set up in this way, all invoices are owned by the parent account and live on the parent account. By default, all charges originating from the child account will use the billing information on the parent account related to the child. With this configuration, a child account does not have to have billing information on its account in order for subscriptions or charges to be created.

📘

Adding Billing Information for a Child

A child account that bills to a parent can also have its own billing information. However, the billing information will not be used towards any charges for the child account.

In some cases, you may want to add billing information to a child account if a parent is going to be removed from the account. By doing so, any active subscriptions can be renewed using this billing information after the parent is removed.

Adding a Subscription

When you are adding a subscription for a child, the subscription will be created on child account. If the subscription is created immediately, the invoice will be created on the parent account. For example, if you are viewing the child account details, you will see the subscription on the account but the invoice will not be listed on the Charges & Credits table. In order to access the invoice, you will need to go to the Subscription Details to access a link to the invoice.

Subscription Changes

During immediate subscription changes that result in an invoicing event, an invoice will be created on the parent account. Immediate subscription changes can result in a charge invoice and a credit invoice. If a subscription change results in a charge invoice and a credit invoice for the child exists on the parent account, it will be applied on the charge invoice. For example, if a child account has a subscription downgrade that results in a credit invoice on its parent, if a new subscription is added to the child account a credit invoice from the downgrade will be applied to the charge invoice for the new subscription.

Adding a charge or credit

Posting custom charges or posting custom credits to the child account will post an invoice to the parent account immediately.

Invoice Immediately

If you are adding a charge that "Invoices Now", the invoice will be created immediately. The charge will not be available on child's Charges & Credits table on their account. You will be able to access the invoice from the parent account's Invoices table or Charges & Credits table.

Posting a custom credit from the child account will create a credit invoice immediately on the parent account.

The credit invoice will live on the parent account under the Charges & Credits table.

🚧

Using the API for transactions

Currently, we do not fully support the transactions endpoint in the API for custom charges that invoice immediately for Account Hierarchy. While It is possible to create a transaction for a child account that bills to itself, it is not supported for child account that bills to a parent. We recommend that if you want to create one-time charges for a child account who's bill-to-account is a parent, you create them using the Admin UI or the purchase endpoint in the API.

Invoice at Next Bill Date

Recurly allows creating custom charges through the Admin UI that can be invoiced at Next Bill Date. We also allow you to do this through the API using the adjustments API endpoint.

If you are creating a custom charge that invoices at the next bill date, the uninvoiced charge will live on the child account under Charges & Credits table until it is invoiced. This means that if you are looking at the Adjustments - Export filtered by uninvoiced adjustments, Account column will list the account code of the child associated with the uninvoiced adjustment.

Uninvoiced charges are picked up in any billing event (adding a subscription, renewing a subscription, posting a charge), except for immediate subscription changes. Once the uninvoiced charge is invoiced, the charge will be moved from the child account Charges & Credits table to the parent account's Charges & Credits table. Additionally, the Adjustments - Export will reflect the parent under the Account column for the invoiced adjustment. If the parent payment method is declined at the time the uninvoiced charge is invoiced, the charge invoice will still be generated on the parent account and marked as failed .

Credit Invoices

Credit invoices created manually or as a result of a subscription change, will be created on the parent account if the child bills to the parent. Credit invoices will be applied towards any charge invoice originating from any child.

Example

A child company called Pizza Planet-Oakland bills to a parent company Pizza Planet - Headquarters. A custom credit invoice is created for Pizza Planet-Oakland that is issued to the parent account. Pizza Planet - San Francisco is a sibling to child company Pizza Planet-Oakland and also bills to the parent company. If a subscription is added to Pizza Planet-San Francisco, the credit invoice originating from Pizza Planet-Oakland will be applied to the charge invoice billed to Pizza Planet-Headquarters.

Credit invoices created as a result of creating a custom credit on a parent account or originating from a subscription change or refund for a parent that may also have a subscription, will apply towards any charge invoices created from the parent's children that bill to it. This means that a single credit invoice can be applied across multiple children until the credit is used up entirely.

Coupons

Coupons can be redeemed in a number of ways. You can redeem individual coupons via the Admin UI to a child account or when adding a subscription to a child account. You can also redeem coupons via the API. In order for discounts to apply towards an invoice to a parent, the coupon must live on the child account. For example, a subscription is created on a child account and the child account has an eligible account-level coupon on its account. This coupon will be applied towards the eligible charge(s) on the invoice billed to its parent.

Coupons that are redeemed on a parent account will not be applied towards invoices created as a result of a child billing to it's parent. If a parent has a coupon(s) on its account, they will only apply to subscriptions or charges created on the parent account for the parent (e.g if a parent has it's own subscription).

Coupon application rules are the same as existing coupon logic outlined here.

Refunds

Invoice refunds for an invoice on a parent account will create a refund credit invoice on the parent account, which includes credit line items against previously paid for charge line items. Refunding will never reopen the original charge invoice. When refunding an invoice directly, you can choose to distribute the resulting credit balance as a payment refund (cash back on the parent's payment method), or leave it as a credit balance to be used as payment on future invoices.

For more information on how refunds work, visit this page.

Taxes

If you are using Recurly taxes, line items on an invoice billed to a parent, will be taxed based on the parent's taxable address.

Collection Method

When automatic collection method is used, the invoice line items will be taxed based on the parent's billing information address unless your site setting's specify to use account address. If the latter is true, tax will be calculated based on the parent's account information address. If manual collection method is used, the invoice line items will be taxed using the parent's account information address.

Tax Exempt

If you are utilizing our tax exemption feature, the following rules will apply to account hierarchy accounts:

• if a parent is tax exempt, all parent’s invoices (e.g child that bill to parent invoices and the parent's own invoices if they have their own subscription) will not be taxed
• If a child is tax exempt but parent is not, the invoices generated for this child will not be taxed.

📘

Displaying Child Information on Invoice

If you would like to include information (such as name and address) on the invoice to the parent account, you will want to ensure that you pass in a shipping address when creating a subscription. The resulting invoice should display a Bill To based on the parent's billing information and a Ship To of the child's shipping address. Additionally, passing in a shipping address will ensure that the invoice is taxed based on the location of the child account.

Refer to the Shipping section below for more information.

Shipping Address

In some cases, you may want to use tax line items on an invoice based on the location of the child account. We recommend that for this use case, to specify a shipping address for the child account's subscription. The resulting invoice should display a Bill To based on the parent's billing information and a Ship To of the child's shipping address.

There a couple of ways to apply a shipping address to a subscription, which is outline in our existing shipping address documentation.

If you are using the purchase endpoint in our API to create subscriptions and custom charges and also want to use a child's shipping address for taxation, we recommend that you specify an account-level shipping address for the purchase. This means that all line items will be based on the account-level shipping address. Any new subscription(s) created will be associated with this shipping address.

VAT Reverse Charge Notes

If you are using Recurly's EU VAT feature, and the taxable address for parent invoice is based in the EU and is a different country than that of your business and VAT number, then VAT Reverse charges will be included on the invoice.

Tax Location Validation

Recurly's Tax Location Validation service is used at the time any account's taxable address is added to, or updated on, the account. For example, if a parent account's billing information address or account address was updated. Then at the time of invoicing, Recurly will check the status of the parent account and allow the invoice to be posted if the parent account is valid and blocks the invoice if the parent account is invalid.

Note: If you are using shipping address from the child account as the taxable address, Recurly will not validate shipping address. This means that Recurly will only evaluate a parent account's location evidence.

View Invoice

Updating or Removing billing information

If you are changing billing information or removing billing information for the parent account, this will directly impact any children that bill to this parent. If you remove a parent account's billing information, any non-trial subscriptions for those children that bill to the parent will expire at the next bill date. Trial subscriptions will expire when trial ends, if no payment method is added to the parent account. If billing information is updated, the updated payment method will be used for any charges originating from a child that bills to the parent account.

Adding or removing billing information for a child account that bills to a parent, has no impact on subscriptions being purchased or renewed. However, if you are planning to remove a parent from a child account, we recommend adding a payment method to the child account so that subscriptions are able to renew after the parent account (and therefore means of payment) is removed.

Dunning

If you are utilizing Recurly's Dunning Management, dunning notifications will be sent to the parent account when invoices move to past due, since the parent account is the invoice owner for children that bill to a parent.

Emails

If you are using Recurly automatic emails and Account Hierarchy, emails will be sent to a parent or child depending on how you've configured the billing responsibilities for the child account.

Child that Bills to Itself

For child accounts that bill to themselves and do not bill charges to their parent, any email template enabled will send an email to the child account's email address.

Child that Bills to Parent

For a child accounts that bill to their parent, it is important that only the parent receive email notifications that contain invoice information.

The following emails, if enabled, will be sent to a parent account's email address on behalf of events originating from child that bills to the parent:

• Invoice (New Invoice, New Credit Invoice, Payment Confirmation, Payment Refunded)
• Subscription (New Subscription, Subscription Change, Subscription Canceled, Subscription Expired, Expired for Non-Payment, Trial Ending, Renewal Reminder, SEPA, CC Expired)
• Dunning emails

If you allow a parent or child to log into their account via Hosted Account Management, Recurly will send the all Account emails to the email address of the account requesting the change.

For example, if a child account visits your hosted account management login page and requests to activate their account, Recurly will send an email to the child account. Similarly, if a parent account requests to activate account, Recurly will send an email to the parent account. Additionally, if a child or a parent requests for their account to have its Password Reset, the account requesting will receive the email to reset password. If password is reset, the account will also receive the Password Has Been Reset success email.

Removing a Parent or Changing a Parent

You can remove a parent or change a parent for a child either through the API or through the Admin UI.

Removing a Parent

When removing a parent from a child account, it's important to be aware that subscriptions on the child account may expire at the next bill date, unless a valid payment method is added to the account. You can remove the parent account the same way that you would change the parent, by editing the child account and selecting the "Remove Parent' Option before saving the change.

When a parent account is removed, the account effectively is no longer a child account. This means that all charges and subscriptions will be billed using the billing information on the account. If the account had existing billing information on its account (child billing information that existed while it was a child), any active subscriptions will attempt to renew at next bill date using this billing information. If billing information does not succeed, active subscriptions will go through the normal dunning process.

Going forward, the account will not be included in the Account Hierarchy Overview page nor included in the count of children for that parent. Accounts - Export will also reflect that the account has been modified and no longer has a parent account associated with it.

Changing a parent

Whenever a parent account is changed for a child, the child account will no longer be associated with the previous parent. You cannot make changes to the parent of an account if there are invoices past due. This is so that the account is in good standing (invoices paid, refunds issued to old parent if required) prior to changing the billing owner of the child. The child will be included in the count of children for the new parent and in the Account Hierarchy Overview page for the new parent and its children. The Accounts - Export will also reflect that the account has been modified and has a new parent account associated with it.

If the child account Bills to Parent, any charge or credit invoices will be created on the parent account. Charge invoices will bill using the new parent account's billing information.

🚧

Subscriptions with Usage Based Billing

If a child account has an active subscription that is billed using usage based billing and the you change the bill-to-account (e.g previously billed to Parent A and now bills to Parent B) in the middle of the current billing cycle, there are a few things that you should note if you decide to do so :

• any unbilled usage will be billed to the new parent at the next bill date.
• terminating the subscription in the middle of the current billing cycle will result in an invoice to the previous parent for any unbilled usage.

If you do not want the previous parent to be invoiced for unbilled usage when terminating the subscription mid-cycle, we recommend that you zero-out the usage prior to terminating.

Subscription Changes if Bill-to-Account Is Different

If you decide to add, change, or remove a parent from an account, it's important to understand how that will affect any existing subscriptions and/or past invoices on the impacted account. In particular, how an existing subscription(s) is invoiced, if a subscription change is made during the middle of the billing cycle.

If any subscription changes are applied effective immediately, and are made to a subscription where the account that paid the most recent invoice for the subscription doesn't match the current billing account, any change at all will cause a full prorated credit against the old account, and a new prorated charge against the new bill-to-account. In other words, if you upgrade or downgrade the subscription prior to the next bill date after changing the bill to account, the new bill-to-account is responsible for paying for the full prorated amount of the updated subscription for the remainder of the billing cycle, not just the difference between the old subscription price and the new subscription price.

Having a different original billing owner can occur in 3 ways:

• Adding a parent to an existing account with an active subscription
• Changing a parent of a child with an active subscription
• Removing a parent of a child with an active subscription

Upgrading subscription if billing account has changed since last recent invoice

Child is subscribed to monthly Silver subscription which is billed to Parent A. During the middle of the monthly billing period, the child's parent bill-to-account is changed to Parent B. The subscription is later upgraded to Gold with timing of change effective immediately. Parent A will receive a credit of the time remaining to Gold. Parent B will receive a full rebill of subscription to Gold.

Downgrading subscription if billing account has changed since last recent invoice

Child is subscribed to monthly Gold subscription which is billed to Parent A. During the middle of the monthly billing period, the child's parent bill-to-account is changed to Parent B. The subscription is later immediately downgraded to Silver. Parent A will receive a credit of the time remaining to Gold. Parent B will receive a full rebill of subscription to Silver.

Removing a parent of child with an active subscription

If an account that bills to a parent has its parent removed and there are any active subscriptions on the account, if immediately downgraded, will issue a credit invoice to the original parent account. Any immediate upgrades will result in a charge invoice to the account if there is valid billing information available.

📘

Refunding Invoice if Billing Account Has Changed

If an account has invoices and subscriptions that were previously paid for by a different account (e.g a parent or different parent from the one it has now), those invoices will be refunded to the original that paid for it. For example, Child A has an active subscription paid for by Parent A, but Parent A is removed. If you wish to refund any invoices that were issued prior to Parent A being removed, you can go to Parent A's account to refund any invoices associated with Child A. Those will be refunded to Parent A's payment method used for those transactions.

Closing a Child or Parent Account

If you need to close a child account, you must conclude any outstanding business with that child account (e.g close any past due invoices) before you can close the account. Upon closing the child account, any billing information on the account will be removed. Active subscriptions for that child will be canceled and expire at next bill date. The child account will maintain its relationship with the parent account, unless the parent is removed from the child.

In the event that a parent account needs to be closed (e.g the parent no longer requires subscription to your service for its children or business is shutting down), you must close all child accounts for this parent first or remove the parent from the child. As best practice, you should ensure that each child account has all invoices paid and/or any refunds issued prior to closing the child account. Once all child accounts have been closed, you can close the parent account. Once the parent account is closed, billing information will be removed and if the parent has any active subscriptions, they will be canceled and expire at next bill date. The parent account will maintain its relationship with the child accounts. Reopening the parent account will not automatically reopen the child accounts.

🚧

Reopening a child account

If you want to reopen a child account who's parent account is closed, reopening the child account effectively sever the parent relationship. We recommend that if you want to reopen the child account and maintain the parent, that you reopen the parent account first.

However, if a child's parent is still active, reopening the child account will maintain the parent-child relationship.

Hosted Account Management

If you are using Recurly's Hosted Account Management and you plan to allow parents and children with Account Login access, we've made some changes on what information is accessible, based on whether the account is a child or not. Unlike the Admin UI, Hosted Account Management pages do not include any labels denoting whether the account is a parent or a child.

Parent Account

When a parent logs into their account, they will be able to view any subscriptions (if the parent is subscribed to a plan) belonging to itself and any invoices created as a result of a child billing to the parent. In most cases, a parent will not have a subscription of their own, therefore a parent would only see invoices originating from a child that billed to it. If a parent updates their payment method, any child that currently bills to the parent, will use the updated billing information.

Child Account that Bills to Parent

When a child that bills to its parent logs into their account page, they will not be able to access any price or invoice information, unless the invoices were create prior to the child account billing to its parent.

For example, on a regular account in Hosted Account Management, we display both an invoice link and pricing information for each subscription within the Subscription card. We also include a table of invoices created for that account. For Account Hierarchy, a child that bills to parent will not have access to invoice or pricing information. This is due to the fact that the parent is the owner of the invoice and payment information. A child cannot view any parent information from the child account page.

If a child account that bills to its parent, eventually has its parent removed, any invoices belonging to the parent account that were associated with the child will remain on the parent account.

Child Account that Bills to Self

When a child that bills to itself (e.g uses its own payment method and does not use the parent account) logs into their account, they will be able to view all of their subscriptions and any invoices created for that child account. A child cannot view any parent information from the child account page.

If a child account is updated to "bill to parent", any invoices created using the parent's billing information will be created on the parent account and not accessible from the child hosted account page. Similarly, invoice and pricing information will not be displayed for any new subscriptions or invoices created for the child account.

Child Account's Parent Removed

If the parent is removed and the account is no longer a child, the account will reset to be its own billing owner and the invoices table should be present again. Any invoices that were created for the account when it previously billed to its parent will not be displayed on the account however, and continue to live on the parent account.

Exports

To support tracking data around your parent-child accounts and tracking the associated parent-child accounts to a charge, we've added some enhancements into Exports.

Accounts Export

We've added a new column to the Accounts export which can be used to identify a parent account associated with an account. An easy way to identify whether an account is a child, is if there is a parent account code populated in the new parent_account_code column. This is available in version v3 of the Accounts Export.

Adjustments Export

We recommend using the Adjustments export to track line items for an invoice that are billed for a child account and the parent account associated with the charge. We've added two new columns called which specify the account the adjustment was billed to and whom the adjustment was billed for.