Multiple Business Entities - API Change Summary

Owned by John M
Last updated: Mar 26, 2024
9 min read

Overview

Early Access

Multiple Business Entities is in early access.

Terms and conditions         Request access

This document summarizes the changes made to the Chargebee Billing APIs as part of the Business Entities feature.

business_entity resource

business_entity Resource

business_entity endpoints

Transfer a customer to another business entity

List business entity transfers

business_entity_transfer resource

business_entity_transfer Resource

customer resource

Attributes

Name

Description

Name

Description

id (description edited)

string max chars = 50

The unique identifier of the customer resource. You have the option to specify this value when creating a customer. If not specified, Chargebee automatically generates a unique identifier.

Note: When the customer resource is transferred to a different business_entity, Chargebee assigns a new random identifier to the id attribute. The original identifier is preserved for the transferred copy of the customer resource. (See also: Mechanics of business entity transfer.)

active_id (added)

string max chars = 50

Note: Present only when the customer has been transferred between business entities.

Represents the id of the current version of the customer resource.

business_entity_id (added)

string max chars = 50 always returned

The unique ID of the business entity of this customer.

 

customer endpoints

create_a_customer

Parameter added

Name

Description

Name

Description

business_entity_id

string max chars = 50 optional

The unique ID of the business entity this customer should be linked to. Applicable only when multiple business entities have been created for the site. When not provided, the customer is linked to the default business entity defined for the site.

merge_customers

Description updated

This API moves a customer's payment methods, subscriptions, invoices, credit notes, transactions, unbilled charges, and orders to another customer. Events and email logs will not be moved. The API execution is asynchronous.

link_a_customer

Description updated

Sets a customer into a hierarchical relationship with another. The path parameter customer_id is the id of the child in the relationship.

Note:

  • For theuse_default_hierarchy_settings,parent_account_accessandchild_account_accessparameters, the 'parent' is the customer whose id is payment_owner_id. However, if thepayment_owner_idis the child itself, then the parent is parent_id.

  • The parent and the child customers must belong to the same business entity.

subscription resource

Attributes

Name

Description

Name

Description

id (description edited)

The unique identifier of the subscription resource. You have the option to specify this value when creating a customer. If not specified, Chargebee automatically generates a unique identifier.

active_id (added)

Represents the id of the current version of the subscription resource.

business_entity_id (added)

string max chars = 50 always returned

The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.

subscription endpoints

create_subscription_for_items

Parameter added

Name

Description

Name

Description

business_entity_id

string max chars = 50 optional

The unique ID of the business entity this subscription should be linked to. Applicable only when multiple business entities have been created for the site. This must be the same as the business entity of the customer for the operation to be successful.

invoice resource

Attribute added

Name

Description

Name

Description

business_entity_id

string max chars = 50 always returned

The unique ID of the business entity of this invoice. Depending on whether the invoice was created directly for a customer or for a subscription, this is the business entity of the customer or the subscription respectively.

invoice endpoints

create_invoice_for_items_and_one-time_charges

Parameter descriptions updated

Name

Description

Name

Description

customer_id

string max chars = 50 optional

Unique ID of the customer this invoice should be created for. Either this or subscription_id must be provided.

subscription_id

string max chars = 50 optional

Unique ID of the subscription this invoice should be created for. Either this or customer_id must be provided.

credit_note resource

Attribute added

Name

Description

Name

Description

business_entity_id

string max chars = 50 always returned

The unique ID of the business entity of this credit_note. This is always the same as the business entity of the invoice referred to by reference_invoice_id.

payment_intent resource

Attribute added

Name

Description

Name

Description

business_entity_id

string max chars = 50 always returned

The unique ID of the business entity of this payment_intent.

payment_intent endpoints

create_a_payment_intent

Description updated

Creates a PaymentIntent object. This is to be used with Chargebee.js API to complete the 3DS flow for new or stored cards.

While creating, specify the appropriate gateway account and amount. The exact amount can be estimated using our Estimate API.

Customer resource lookup and creation

When customer[id] is provided for this operation, it is looked up by Chargebee, and if found, the payment_intent is created for it. If not found, a new customer resource is created with the ID provided, and the payment_intent is created.

Multiple business entities

If multiple business entities are created for the site, the customer resource lookup and creation happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context, and if not found, the resource is created for the default business entity of the site.

New parameter added

Name

Description

Name

Description

business_entity_id

string max chars = 50 optional

Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.

Parameter description updated

Name

Description

Name

Description

customer[id]

The unique ID of the customer for which this payment_intent should be created. If not provided, a new customer is created and its ID is autogenerated.

 

payment_source resource

Attribute added

Name

Description

Name

Description

business_entity_id

string max chars = 50 always returned

The unique ID of the business entity of this payment_source. This is always the same as the business entity of the customer.

 

transaction resource

Attribute added

Name

Description

Name

Description

business_entity_id

string max chars = 50 always returned

The unique ID of the business entity of this transaction. This is always the same as the business entity of the customer.

 

hosted_page resource

Attribute added

Name

Description

Name

Description

business_entity_id

string max chars = 50 always returned

The unique ID of the business entity of this hosted_page.

 

hosted_page endpoints

checkout_charge_items_and_one_time_charges

Description updated

Create a Chargebee hosted page to accept payment details from a customer and checkout charge-items and one-time charges.

The following steps describe how best to use this API:

  1. Call this endpoint, providing item prices, charges, coupons and a host of other details such as billing and shipping addresses of the customer, to be prefilled on the checkout page.

  2. Send the customer to the Checkout url received in the response.

  3. Once they complete checkout, the set of charge-items and one-time charges are automatically invoiced against the respective customer record in Chargebee, and they are redirected to the redirect_url with the id and state attributes passed as query string parameters.

  4. Retrieve the hosted page at this stage to get the invoice details.

Customer resource lookup and creation

When customer[id] is provided for this operation, it is looked up by Chargebee, and if found, the hosted page is created for it. If not found, a new customer resource is created with the ID provided, and the hosted page is created.

Multiple business entities

If multiple business entities are created for the site, the customer resource lookup and creation happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context, and if not found, the resource is created for the default business entity of the site.

New parameter added

Name

Description

Name

Description

business_entity_id

string max chars = 50 optional

Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.

Parameter description updated

Name

Description

Name

Description

customer[id]

The unique ID of the customer for which this hosted page should be created. If not provided, the ID of the newly created customer resource is autogenerated.

 

create_checkout_for_a_new_subscription

Description updated

Create a Chargebee hosted page to accept payment details from a customer and checkout a new subscription.

The following steps describe how best to use this API:

  1. Call this endpoint, providing item prices, coupons and a host of other details such as billing and shipping addresses to be prefilled for the customer on the checkout page.

  2. Send the customer to the Checkout url received in the response.

  3. Once they complete checkout, a new subscription is automatically created and the customer is redirected to the redirect_url with the id and state attributes passed as query string parameters.
    Although the customer will be redirected to the redirect_url after successful checkout, we do not recommend relying on it for completing critical post-checkout actions. This is because redirection may not happen due to unforeseen reasons. Chargebee recommends listening to appropriate webhooks such as subscription_created or invoice_generated to verify a successful checkout.

  4. Retrieve the hosted page at this stage to get the subscription and invoice details.

Customer resource lookup and creation

When the customer[id] parameter is provided and if a customer resource with the ID is found to be already created in Chargebee, the subscription is created under that customer resource. If not found, then a new customer resource is created with the ID provided and the subscription is created under it.

Multiple business entities

If multiple business entities are created for the site, the customer resource lookup and creation happens within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context and if not found, the resource is created for the default business entity of the site.

New parameter added

Name

Description

Name

Description

business_entity_id

string max chars = 50 optional

Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.

Parameter description updated

Name

Description

Name

Description

customer[id]

The unique identifier for the customer resource for which the subscription should be created.

When not provided, a new customer is created with the ID set to the value provided for subscription[id]. If subscription[id] is unavailable, then the customer ID is autogenerated.

 

checkout_gift_subscription_for_items

Description updated

Creates a hosted page for a customer (called the gifter) to gift a subscription to another customer (called the receiver).

Gifter customer resource lookup and creation

When gifter.customer_id is provided, it is looked up in Chargebee when the gifter completes the hosted page checkout. If not found, a new customer resource is created with this ID.

Multiple business entities

If multiple business entities are created for the site, the lookup and creation of the gifter customer resource happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context, and if not found, the resource is created for the default business entity of the site.

Gift receiver customer resource lookup and creation

Once the gifter checks out using the hosted page returned by this endpoint, Chargebee checks if a customer resource with the receiver’s email address exists. The first such customer record is considered the receiver’s customer resource. A new customer resource is created for the receiver if none are found.

Multiple business entities

If multiple business entities are created for the site, the lookup and creation of the gift receiver’s customer resource happen within the context of the business entity of the gifter.

New parameter added

Name

Description

Name

Description

business_entity_id

 

string max chars = 50 optional

Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.

Parameter description updated

Name

Description

Name

Description

gifter.customer_id

string max chars = 50 optional

The customer ID of the gifter. If not provided, the gifter customer resource is created with an autogenerated ID on checkout.

 

quotes resource

Attribute added

Name

Description

Name

Description

business_entity_id

string max chars = 50 always returned

The unique ID of the business entity of this quote.

 

 

ON THIS PAGE