Account Hierarchy lets you model real-world business structures — holding companies, franchises, agencies, enterprise divisions — directly in Recurly. Designate any account as a parent or child, choose who pays the bills, and get consolidated visibility across accounts, subscriptions, and invoices from a single hierarchy overview page.

Not included in Starter or Pro — contact Recurly Sales to upgrade

1Definition 2Key benefits 3Key details 4Billing configuration 5Modifying relationships 6Closing accounts 7Hosted account management 8Exports

Definition

Account Hierarchy is a Recurly feature that lets you establish parent-child relationships between accounts. It's designed for B2B merchants whose customers have multiple divisions, departments, or subsidiaries — giving you the flexibility to bill charges to either the child account or a central parent, with consolidated reporting across the entire hierarchy.

Key benefits

Flexible billing Assign billing responsibilities to the parent or child account — whichever fits your customers' financial structure.

Consolidated visibility View all child accounts, subscriptions, and invoices under a parent from a single hierarchy overview page.

Flexible subscription management Handle subscription changes, upgrades, downgrades, and terminations across parent-child accounts with ease.

Enhanced export tracking Track parent-child accounts and associated charges using dedicated export columns.

Key details

Hierarchy rules

Before setting up Account Hierarchy, note the following structural constraints:

Any account can be designated as a parent or a child
A child account can only have one parent — grandparent relationships are not supported
A child account (one that already has a parent) cannot itself be assigned as a parent to another account. These accounts won't appear in the parent dropdown and cannot be assigned via the API

Assigning a parent account

You can assign a parent during account creation or by editing an existing account.

Navigate to Accounts

Go to Customers, then Accounts. Create a new account or open an existing one to edit.

Open the Account Hierarchy section

Scroll to the Account Hierarchy section of the account form.

Enter the parent account code

Type the parent account's code or name to search for it.

Select the billing configuration

Choose whether charges should be billed to the child account or the parent account.

Save the account

Save the new or updated account to confirm the hierarchy link.

Viewing account hierarchy

After saving, hierarchy information is visible from both the parent and child account pages.

Child account view

The Account Information section displays a "Child" tag, along with the parent account name and a link to the parent account. A "View Account Hierarchy" link is also available, providing an overview of all child accounts, subscriptions, and invoices under the parent.

Account hierarchy overview page

Accessible from either the child's or parent's account page, the overview includes three index tabs:

Tab	What it shows
Accounts	All child accounts associated with the parent.
Subscriptions	All subscriptions belonging to the parent's child accounts.
Invoices	All invoices belonging to the parent and its child accounts.

You can filter accounts, subscriptions, and invoices by whether charges are billed to the child or the parent.

Billing configuration

After assigning a parent, you choose where charges are billed. The behavior of invoices, credits, coupons, refunds, and taxes differs depending on this setting.

Child bills to itself

The child account behaves like a standard Recurly account — it manages its own billing information and receives its own invoices. The only difference is its association with a parent, which is reflected in the UI and in exports.

Subscriptions

When adding a subscription for a child that bills to a parent, the subscription is created on the child account. If created immediately, the resulting invoice is created on the parent account. To access the invoice from the child account, go to the subscription details page.

Immediate subscription changes that result in an invoicing event also create the invoice on the parent. A change can produce both a charge invoice and a credit invoice — if a credit exists on the parent from a previous change (such as a downgrade), it will be applied to the new charge invoice.

Charges and credits

Invoice immediately

When a charge invoices immediately, the invoice is created on the parent account. The charge won't appear in the child's Charges & Credits table — access it from the parent's Invoices or Charges & Credits table.

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

API limitation for immediate charges The transactions endpoint does not fully support Account Hierarchy for custom charges that invoice immediately. For one-time charges to a child account that bills to a parent, use the Admin UI or the purchase endpoint in the API instead.

Credit invoices

Credit invoices created manually or from a subscription change are created on the parent account when the child bills to the parent. These credit invoices apply toward any charge invoice originating from any child of that parent.

A credit invoice originating from one sibling child can apply to a charge invoice for another sibling child, as long as both bill to the same parent. A single credit invoice can be applied across multiple children until the credit is fully used.

Credit invoices from a custom credit or subscription change on the parent account itself also apply toward charge invoices from any child that bills to it.

Coupons

Coupons must be redeemed on the child account for discounts to apply to invoices billed to the parent. An account-level coupon on the child account will apply to eligible charges on the parent's invoice.

Coupons redeemed on the parent account only apply to subscriptions or charges created directly on the parent — not to invoices originating from children billing to it.

For full coupon logic, see the coupons documentation.

Refunds

Refunding an invoice on a parent account creates a refund credit invoice on the parent with credit line items against previously paid charges. The original charge invoice is never reopened. When refunding directly, you can issue a payment refund (cash back to the parent's payment method) or leave the amount as a credit balance for future invoices.

For more on how refunds work, see the invoices documentation.

Taxes

Invoice line items for a child billing to a parent are taxed based on the parent's taxable address.

Collection method

With automatic collection, line items are taxed using the parent's billing information address — unless your site settings specify to use the account address, in which case the parent's account address is used. With manual collection, the parent's account address is always used.

Tax exemption

If the parent is tax exempt, all invoices billed to the parent (including those originating from children) are not taxed
If a child is tax exempt but the parent is not, invoices generated for that child are not taxed

For details, see the tax exemption documentation.

Shipping address and child-based taxation

To tax line items based on the child's location rather than the parent's, specify a shipping address on the child account's subscription. The resulting invoice shows a Bill To address from the parent's billing info and a Ship To address from the child's shipping address.

Tax location validation Recurly only validates the parent account's taxable address — not the child's shipping address. If using the purchase endpoint to create subscriptions with a child shipping address for taxation, specify the shipping address at the account level so it applies to all line items.

If you use Recurly's EU VAT feature and the parent's taxable address is in the EU and in a different country from your business and VAT number, VAT reverse charges will be included on the invoice.

For shipping address setup options, see the shipping address documentation.

VAT

If you use Recurly's EU VAT feature and the parent's taxable address is in the EU and in a different country from your business and VAT number, VAT reverse charges will be included on the invoice.

Invoice display

On invoices within Account Hierarchy, the parent is labeled "Primary Account" and the child is labeled "Linked Account." This naming appears in invoice PDFs, customer emails, Hosted Account Management invoice displays, and the Admin UI.

Updating or removing billing information

Changes to the parent account's billing information affect all children that bill to that parent:

If the parent's billing information is removed, non-trial subscriptions for children billing to the parent expire at the next bill date. Trial subscriptions expire at trial end if no payment method is added to the parent
If billing information is updated, the updated payment method applies to all charges from children billing to the parent

Adding or removing billing information on a child account that bills to a parent has no impact on active subscriptions. However, if you plan to remove the parent, add a payment method to the child account first so subscriptions can renew after the parent is removed.

Dunning

When using Recurly Dunning Management, dunning notifications are sent to the parent account when invoices move to past due — since the parent is the invoice owner for children that bill to it.

Emails

Which account receives email notifications depends on the child's billing configuration.

Configuration	Email recipient	Email types
Child bills to itself	Child account email address	All enabled email templates
Child bills to parent	Parent account email address	Invoice emails (new invoice, credit invoice, payment confirmation, payment refunded), subscription emails (new, changed, canceled, expired, trial ending, renewal reminder, SEPA, CC expired), and dunning emails

If a parent or child logs in via Hosted Account Management, all account emails (account activation, password reset, password reset confirmation) go to the email address of the account initiating the action.

Modifying parent-child relationships

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

Removing a parent

Edit the child account and select Remove Parent before saving. Once removed, the child becomes an independent account — all charges and subscriptions are billed using billing information on the account itself.

Ensure the child has billing info After a parent is removed, subscriptions attempt to renew using billing information on the child account. If none is present, active subscriptions may expire at the next bill date and enter dunning. Add a payment method to the child before removing the parent.

After removal, the account is no longer listed in the hierarchy overview page or counted among the parent's children. The Accounts export is updated to reflect that the account no longer has a parent.

Changing a parent

Replacing a parent severs the child's association with the previous parent. The change cannot be made if there are outstanding invoices — resolve any open invoices before proceeding. After the change, the child appears in the new parent's hierarchy overview and child count, and the Accounts export is updated.

If the child bills to the parent, charge and credit invoices going forward are created on the new parent account, using the new parent's billing information.

Usage-based billing mid-cycle If a child has an active subscription with usage-based billing and you change the bill-to-account mid-cycle: any unbilled usage is billed to the new parent at the next bill date, and terminating the subscription mid-cycle bills unbilled usage to the previous parent. To avoid invoicing the previous parent for unbilled usage on termination, zero out the usage before terminating.

Subscription billing when the bill-to account has changed

When a parent is added, changed, or removed from an account with an active subscription, any immediate subscription change triggers a full prorated credit to the old bill-to account and a full prorated charge to the new bill-to account — not just the price difference.

Example: upgrade after parent change

A child is on a monthly Silver plan billed to Parent A. Mid-cycle, the parent is changed to Parent B. The subscription is then immediately upgraded to Gold. Parent A receives a credit for the remaining Silver time. Parent B receives a full prorated rebill to Gold for the remainder of the cycle.

Example: downgrade after parent change

A child is on a monthly Gold plan billed to Parent A. Mid-cycle, the parent is changed to Parent B. The subscription is then immediately downgraded to Silver. Parent A receives a credit for the remaining Gold time. Parent B receives a full prorated rebill to Silver.

Example: removing a parent with an active subscription

If a parent is removed from a child with active subscriptions, an immediate downgrade issues a credit invoice to the original parent. An immediate upgrade results in a charge invoice to the child account, provided valid billing information is available.

Refunding invoices after a billing account change

Invoices paid by a previous bill-to account are refunded to the account that originally paid them. For example, if Child A had invoices paid by Parent A and Parent A is later removed, those invoices can be refunded from Parent A's account — the refund goes to Parent A's payment method.

Closing accounts

Closing a child account

Before closing a child account, resolve any outstanding business — including open or past-due invoices. On closure, billing information is removed and active subscriptions are canceled (they remain active until the end of the current billing period). The child's relationship with its parent is maintained unless the parent is explicitly removed.

Closing a parent account

To close a parent account, you must first close all child accounts or remove the parent from each child. Once all children are closed or detached, close the parent. On closure, billing information is removed and active subscriptions are canceled at the next bill date. The parent-child relationship is retained — reopening the parent does not automatically reopen any child accounts.

Reopening a child whose parent is closed Reopening a child account whose parent is closed severs the parent-child relationship. To maintain the relationship, reopen the parent account first. If the parent is still active, reopening the child preserves the relationship.

Hosted account management

If you use Recurly's Hosted Account Management with Account Hierarchy, note that hosted pages don't display parent or child labels.

Account type	What they see in Hosted Account Management
Parent	Their own subscriptions (if any) and invoices originating from children that bill to the parent. Updating their payment method applies to all children billing to them.
Child billing to parent	Cannot access invoice or pricing information — the parent owns the invoices. If the parent is later removed, any invoices that were on the parent remain on the parent and are not accessible from the child's hosted page.
Child billing to itself	Full access to their own subscriptions and invoices. If later updated to bill to a parent, new invoices are created on the parent and are no longer visible from the child's hosted page.

Exports

Accounts export

The Accounts export (v3 and later) includes a parent_account_code column to identify parent-child relationships.

Column	Example value	Description
`parent_account_code`	`123456789`	When an account has a parent (i.e., is a child), this column contains the account code of the parent. Empty for accounts without a parent.