Using AI coding agents like Claude Code or Cursor? Try the official Chargebee Agent Skills to speed up your development.Try now
ChargebeeAPI

Link a customer to an account hierarchy

Idempotency Supported

Creates a hierarchical relationship between two customers. The path parameter customer_id identifies the child in this relationship, and parent_id identifies the parent.

Note

For the use_default_hierarchy_settings, parent_account_access, and child_account_access parameters in this operation, the term "parent" usually refers to payment_owner_id. If payment_owner_id is the same as customer_id, then "parent" refers to parent_id.

Prerequisites & Constraints

Impacts

Customer

Invoices

  • For all invoices generated for customer_id after you link the customer, Chargebee sets invoice.customer_id to invoice_owner_id.

Transactions

  • When Chargebee generates invoices for customer_id, if auto_collection is on for invoice_owner_id, Chargebee uses the payment_source of the payment_owner_id to pay the invoices and creates transactions for the payment under payment_owner_id.

RevenueStory

  • The Customer Insights report in RevenueStory shows parent-level views for customers with hierarchy relationships.

Sample Request

creates a relationship for reporting purpose
creates a completely dependent relationship
creates a relationship and sets custom parent/child access settings
creates a partially dependent relationship

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/customers/{customer-id}/relationships

Input Parameters

parent_id
optional, string, max chars=50

ID of the customer intended to be set as the immediate parent of the customer identified by customer_id .

payment_owner_id
optional, string, max chars=50

The id of the customer responsible for paying the invoices for the customer identified by customer_id.

Constraints

  • If the invoice_owner_id is the same as the customer_id, then the payment_owner_id can be the customer_id or an ancestor of the customer_id.
  • If the invoice_owner_id is not the same as the customer_id, then the payment_owner_id must be the invoice_owner_id.
invoice_owner_id
optional, string, max chars=50

The id of the customer who receives the invoice for charges incurred by the customer identified by customer_id.

Constraint

  • This ID must match either customer_id or one of its ancestors.
use_default_hierarchy_settings
optional, boolean, default=true

Decides if Chargebee should apply settings from the Chargebee Billing UI or from this API request.

  • If set to true: Chargebee uses settings configured in the Chargebee Billing UI.
  • If set to false: Settings provided in the parent_account_access and child_account_access parameters are applied.
parent_account_access
Parameters for parent_account_access
pass parameters as parent_account_access[<param name>]
child_account_access
Parameters for child_account_access
pass parameters as child_account_access[<param name>]

Returns

customer
Customer object
Resource object representing customer