POST /customers/{customer-id}/relationships

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

customer_id and parent_id must belong to the same business entity.
The Account Hierarchy limits must not be exceeded due to this operation.

Impacts

Customer

Sets the following attributes on the customer resource:
- relationship
- use_default_hierarchy_settings
- child_account_access
- parent_account_access

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.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`customer-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`parent_id`	String	No	ID of the customer intended to be set as the immediate parent of the customer identified by `customer_id` .
`use_default_hierarchy_settings`	Boolean	No	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. Default value: true
`child_account_access`	Object	No	Settings for the child account's access.
`child_account_access.send_subscription_emails`	Boolean	No	If set to `true` , the child account receives email notifications for its subscriptions.
`child_account_access.send_invoice_emails`	Boolean	No	If set to `true` , the child account receives email notifications for its invoices.
`child_account_access.portal_edit_subscriptions`	String	No	Determines the child's access to its own subscriptions in the Self-Serve Portal. * view_only - The child account can only view its subscriptions. * yes - The child account can view and edit its subscriptions. Valid values: `"yes"` `"view_only"`
`child_account_access.portal_download_invoices`	String	No	Determines the child's access to its own invoices in the Self-Serve Portal. * yes - The child account can both view and download its invoices. * view_only - The child account can view but not download its invoices. * no - The child account cannot view or download its own invoices. Valid values: `"yes"` `"view_only"` `"no"`
`child_account_access.send_payment_emails`	Boolean	No	If set to `true` , the child account receives email notifications for payment-related activities for its invoices.
`parent_account_access`	Object	No	Settings for the parent account's access.
`parent_account_access.portal_download_child_invoices`	String	No	Determines the parent's access to the child's invoices in the Self-Serve Portal. * no - The parent can't view or download the child's invoices. * view_only - The parent can view but not download the child's invoices. * yes - The parent can both view and download the child's invoices. Valid values: `"yes"` `"view_only"` `"no"`
`parent_account_access.send_subscription_emails`	Boolean	No	If set to `true` , the parent receives email notifications for the child's subscriptions.
`parent_account_access.send_invoice_emails`	Boolean	No	If set to `true` , the parent receives email notifications for the child's invoices.
`parent_account_access.portal_edit_child_subscriptions`	String	No	Determines the parent's access to the child's subscriptions in the Self-Serve Portal. * yes - The parent can view and edit the child's subscriptions. * no - The parent can't view or edit the child's subscriptions. * view_only - The parent can only view the child's subscriptions. Valid values: `"yes"` `"view_only"` `"no"`
`parent_account_access.send_payment_emails`	Boolean	No	If set to `true` , the parent receives email notifications for payment-related activities on the child's invoices.
`invoice_owner_id`	String	No	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.
`payment_owner_id`	String	No	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`.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.