Represents a customer, which can be an individual or organization that subscribes to your products or services. The customer resource associates with subscriptions, card information, and billing addresses. The customer details include their ID, name, contact information, and any custom attributes you'd like to associate with them.
Breaking Change:
billing_address
and vat_number
and replaces them with values from the request.billing_address
and vat_number
.{
"allow_direct_debit": false,
"auto_collection": "on",
"billing_address": {
"city": "Walnut",
"country": "US",
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"object": "billing_address",
"state": "California",
"state_code": "CA",
"validation_status": "not_validated",
"zip": "91789"
},
"card_status": "no_card",
"created_at": 1517505731,
"deleted": false,
"email": "john@test.com",
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl7eY2bl",
"last_name": "Doe",
"locale": "fr-CA",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505731000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505731
}
billing_address
country
as
XI
(which is United Kingdom - Northern Ireland), the first two characters of the full VAT
number can be overridden by setting
vat_number_prefix
. payment_method
of type
card
, this attribute determines whether to automatically charge the card whenever an invoice status
is payment_due
.This setting can be overridden for individual subscriptions of the customer.
Note
Applicable only when the customer’s billing_address.country
is New Zealand, Australia, or in the EU.
When the customer uses a card payment source, this attribute specifies whether the country of the customer and the card issuer are the same.
The following three location indicators are compared:
billing_address.country
.created_from_ip
belongs.When all three are the same, this attribute is set to true
, otherwise it is set to false
.
The IP address of the customer when this customer record was created. It’s mainly used for referral integrations and validating VAT if the customer is in the EU or UK.
Depending on the method used to create the customer record, the field is set as follows:
customer
resource through the API, you must include the customer’s IP address in a custom HTTP request header (chargebee-request-origin-ip
) for Chargebee to capture it.customer
resources created through Chargebee Checkout, Chargebee automatically captures the IP address of the customer.customer
resource via the Chargebee Billing UI, this field is not relevant and the value must be ignored.Applicable only when Calendar Billing with support for customer-specific billing date is enabled and billing_date_mode
is manually_set
.
item_price
resources where the item_type
is set to plan
and period_unit
is set to month
and year
respectively.Example
billing_date
is set to 15
, month-based renewals occur on the 15th of the month. It’s important to note that if the value is set to 31
, renewals align with the last day of the month. Additionally, in February, a billing_date
of 29
, 30
, or 31
aligns renewals for the last day of February.billing_date
of 15
and a billing_month
of 7
schedules the renewal on the 15th of July.Applicable only when Calendar Billing with support for customer-specific billing date is enabled and billing_date_mode
is manually_set
.
item_price
resources where item_type
is set to plan
and period_unit
is set to year
. The renewal date is 15th July when billing_date
is 15
and billing_month
is 7
.
Applicable only when Calendar Billing with support for customer-specific billing date is enabled and billing_date_mode
is manually_set
.
billing_date
and billing_month
values can be changed via the Change billing date API. customers
resource. When interacting with our API, the active_id
ensures you're always referencing the current and most up-to-date version of the customers
resource. This mechanism is in place to maintain consistent external references and data integrity across business entity changes and updates. active_id
is present on the resource after the resource is transferred to the destination business entity and it will refer to the most recent version of the resource. Learn more about the customer transfer feature and setup. Note:
active_id
and id
of the customer are the same, then it is the most recent version of the resource.active_id
and id
of the customer are different, then it is a transferred resource.active_id
is not present, then the resource is not transferred and there are no business entity-related changes.Applicable only when the Multi-Currency feature is enabled.
true
or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country
). When set to false
, the customer is not e-invoiced even if e-invoicing is enabled for their country.
Tip:
It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.
true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site. Indicates whether invoices raised on the same day for the customer
are consolidated. When present, this value overrides the default configuration at the site-level. This attribute is applicable only when Consolidated Invoicing is enabled.
Note:
Any invoices raised when a subscription activates from in_trial
or future
status
, are not consolidated by default. Contact Support to enable consolidation for such invoices.
Applicable only when the Chargebee's AvaTax for Communications integration is enabled.
Applicable only when the Chargebee's AvaTax for Communications integration is enabled.
Indicates whether the site-default settings are being used for controlling access to the customer’s information.
The level of access is for data falling into two categories:billing_address
country
as XI
(which is United Kingdom - Northern Ireland).billing_address
country
as XI
. That’s the code for United Kingdom - Northern
Ireland. The first two characters of the VAT number in such a case is
XI
by default. However, if the VAT number was registered in UK, the value should be GB
. Set
vat_number_prefix
to GB
for such cases. vat_number
of the customer. This helps identify the specific type of customer entity. For example, DE:VAT
is used for a German business entity while DE:LWID45
is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country
. See list of possible values.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
entity_identifier_scheme
. Currently only iso6523-actorid-upis
is supported and is used by default when not provided.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
entity_identifiers[]
array identifies a specific customer entity with the e-invoicing system. If the customer has only one entity identifier whose value
is the vat_number
, then this array is not needed as the scheme
can be provided via entity_identifier_scheme
. This array holds any additional entity identifiers that the customer may have.
When the customer is part of an account hierarchy, this attribute defines the level of access that the parent account has to the customer's information.
Note: the 'parent' is the customer whose id is payment_owner_id. However, if thepayment_owner_id
is the customer itself, then the parent is parent_id.Creates a customer. You can create a customer and then create subscriptions for the customer when required. When creating a customer, you can pass along the billing address and card details.
Passing raw card data via API involves PCI liability at your end due to the sensitivity of the data. Instead, you can use one of the following integration options as applicable:
Here’s some resources you can use to collect card information within your checkout form based on the payment gateway you use:
adyen.encrypted.data
as temp token in this API.When billing address is not passed (say, for customers making offline payments), you can always provide it later using the Update billing info for a customer API.
Note: When an invoice is generated for a customer, the billing address provided for the customer is stored with the invoice. If the First Name, Last Name, and Company fields of the billing address do not contain any information, they’re picked up from the customer details.
# creates a customer with billing address. curl https://{site}.chargebee.com/api/v2/customers \ -u {site_api_key}:\ -d first_name="John" \ -d last_name="Doe" \ -d email="john@test.com" \ -d locale="fr-CA" \ -d billing_address[first_name]="John" \ -d billing_address[last_name]="Doe" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[state]="California" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US"
# creates a customer with bank account. curl https://{site}.chargebee.com/api/v2/customers \ -u {site_api_key}:\ -d first_name="John" \ -d last_name="Doe" \ -d allow_direct_debit=true \ -d email="john@test.com" \ -d bank_account[account_number]="000222222227" \ -d bank_account[routing_number]="110000000" \ -d bank_account[bank_name]="US Bank" \ -d bank_account[account_holder_type]="INDIVIDUAL" \ -d bank_account[account_type]="SAVINGS" \ -d bank_account[first_name]="Shay" \ -d bank_account[last_name]="Liam" \ -d bank_account[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju"
# creates a customer with card details. curl https://{site}.chargebee.com/api/v2/customers \ -u {site_api_key}:\ -d first_name="John" \ -d last_name="Doe" \ -d email="john@test.com" \ -d card[first_name]="Richard" \ -d card[last_name]="Fox" \ -d card[number]="4012888888881881" \ -d card[expiry_month]=10 \ -d card[expiry_year]=2022 \ -d card[cvv]="999"
# creates a customer with payment source. # NOTE : The parameters paymentMethod[tmp_token] and paymentMethod[reference_id] should not be passed together. curl https://{site}.chargebee.com/api/v2/customers \ -u {site_api_key}:\ -d first_name="John" \ -d last_name="Doe" \ -d payment_method[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju" \ -d payment_method[type]="CARD" \ -d payment_method[reference_id]="cus_I58PkwpAskxXlJ"
billing_address
country
as
XI
(which is United Kingdom - Northern Ireland), the first two characters of the full VAT
number can be overridden by setting
vat_number_prefix
. billing_address
country
as XI
(which is United Kingdom - Northern Ireland).billing_address
country
as XI
. That’s the code for United Kingdom - Northern
Ireland. The first two characters of the VAT number in such a case is
XI
by default. However, if the VAT number was registered in UK, the value should be GB
. Set
vat_number_prefix
to GB
for such cases. vat_number
of the customer. This helps identify the specific type of customer entity. For example, DE:VAT
is used for a German business entity while DE:LWID45
is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country
. See list of possible values.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
entity_identifier_scheme
. Currently only iso6523-actorid-upis
is supported and is used by default when not provided.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site. true
or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country
). When set to false
, the customer is not e-invoiced even if e-invoicing is enabled for their country.
Tip:
It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.
Indicates whether invoices raised on the same day for the customer
are consolidated. When provided, this overrides the default configuration at the site-level. This parameter can be provided only when Consolidated Invoicing is enabled.
Note:
Any invoices raised when a subscription activates from in_trial
or future
status
, are not consolidated by default. Contact Support to enable consolidation for such invoices.
An alternative way of passing this parameter is by means of a custom HTTP header.
Retrieves a list of customers added to your Chargebee site. The list contains the necessary customer details such as First Name, Last Name and the Customer ID.
curl https://{site}.chargebee.com/api/v2/customers \ -G \ -u {site_api_key}:\ --data-urlencode first_name[is]="John" \ --data-urlencode last_name[is]="Doe" \ --data-urlencode email[is]="john@test.com"
updated_at
. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by
input parameter as updated_at
for a faster response. Retrieves the details of the desired customer. You can use the unique identifier for a particular customer to retrieve the desired details.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlF0Q2dg \ -u {site_api_key}:
Updates the customer resource. However, this method cannot be used for updating the 'Billing Info' - the Billing Address and 'vat_number' attributes - of the customer. To update the same, use our Update Billing Info API.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFGC2di \ -u {site_api_key}:\ -d first_name="Denise" \ -d last_name="Barone" \ -d locale="fr-CA"
Indicates whether invoices raised on the same day for the customer
are consolidated. When provided, this overrides the default configuration at the site-level. This parameter can be provided only when Consolidated Invoicing is enabled.
Note:
Any invoices raised when a subscription activates from in_trial
or future
status
, are not consolidated by default. Contact Support to enable consolidation for such invoices.
Updates payment method details for a customer.
Note: If you wish to pass the card number, CVV, or the single-use card tokens provided by gateways like Stripe, then use the Update card for a customer API under Cards resource. This API is not supported for Chargebee Test Gateway, it is provided to help you understand the billing workflow in Chargebee.
PayPal Express Checkout
You can use this API if you are directly integrating PayPal Express Checkout in your website instead of using Chargebee's hosted pages. When your customer updates his payment method using PayPal Express Checkout, you will be provided with the Billing Agreement ID by PayPal. You can update the payment method for that customer in Chargebee by passing type
as paypal_express_checkout
and reference_id
with the Billing Agreement ID.
Login and Pay with Amazon
You can use this API if you are directly integrating Login and Pay with Amazon in your website instead of using Chargebee's hosted pages. When your customer updates Amazon as a payment method, you will be provided with the Billing Agreement ID by Amazon. You can update the payment method for that customer in Chargebee by passing type
as amazon_payments
and reference_id
with the Billing Agreement ID.
Card Payments
When the card details of your customer are stored in the vault of gateways such as Stripe or Braintree, you can use this API to update the reference id provided by them in Chargebee. To use this API, pass
type
as card
. gateway
with the gateway associated with the card. If the gateway is not specified, the default gateway will be used. reference_id
with the identifier provided by the gateway/Spreedly to reference that specific card. Reference id format for Card Payments
The format of reference_id will differ based on where the card is stored.
Stripe: In case of Stripe, the reference_id consists of combination of Stripe Customer ID and Stripe Card ID separated by forward slash (e.g. cus_63MnDn0t6kfDW7/card_6WjCF20vT9WN1G). If you are passing Stripe Customer ID alone, then Chargebee will store the card marked as active for that customer in Stripe.
Braintree: In case of Braintree, the reference_id consists of combination of Braintree Customer ID and Braintree Payment Method Token separated by forward slash
(e.g. cus_63MnDn0t6kfDW7/card_6WjCF20vT9WN1G ). If you are passing Braintree Customer ID alone, then Chargebee will store the card marked as default for that customer in Braintree.
Spreedly Card vault: If the card details are stored in Spreedly vault, then you need to provide the Spreedly token as reference_id
.
Direct Debit Payments
When the bank account details of your customer are stored in the gateway vault, you can use this API to update the reference id provided by them in Chargebee. To use this API, pass
type
as direct_debit
. gateway
with the gateway where the bank account details are stored (e.g. authorize_net). If the gateway is not specified, the gateway supporting the direct debit will be used. reference_id
with the identifier provided by the gateway to reference the customer's bank account details. tmp_token
with the single use token provided by the gateway ( Should be passed only if reference_id is not passed ). Reference id format for Direct Debit Payments
The format of reference_id will differ based on where the bank account is stored.
Stripe: In case of Stripe, the reference_id consists of combination of Stripe Customer ID and Stripe Bank Account ID separated by forward slash
(e.g. cus_8suoHaLQH4G5AW/ba_18b8z2KmcbENlhgU03RznRYW). If you are passing Stripe Customer ID alone, then Chargebee will store the first bank account details present in payment profile list of that customer in Stripe.
Authorize.Net: The reference_id consists of combination of Authorize.Net's Customer Profile ID and Payment Profile ID separated by forward slash (e.g. 2384383/34834382). If you are passing Authorize.Net's Customer Profile ID alone, then Chargebee will store the first bank account details present in payment profile list of that customer in Authorize.Net.
GoCardless: The reference_id is the GoCardless Customer Mandate ID (e.g. MD0077Z99TTQXK).
Note: While using this API to update payment method details, Card Verification will not happen even if it is enabled for that particular gateway.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlHEO2eE/update_payment_method \ -u {site_api_key}:\ -d payment_method[type]="CARD" \ -d payment_method[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju" \ -d payment_method[reference_id]="cus_I58QViSiwuelqF"
This method is used for updating the billing_address
and vat_number
attributes of the customer
. For updating the other customer attributes use Update Customer API.
During this operation, if billing_address
and vat_number
are not already present, they’re added. Whereas if present, the existing values are replaced with the new values passed. The only exception here is for entity_identifiers[i]
when entity_identifiers[operation][i]
is passed as delete
.
Note: When an invoice is generated for a customer, the billing address provided for the customer will be stored with the invoice. If the First Name, Last Name, and Company fields do not contain any information under Billing Info, the same will be picked from Customer Details if the same is available there.Please ensure that the VAT number is provided whenever the billing address is updated, as failing to do so will override any existing VAT numbers if new values are not provided.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFY32dl/update_billing_info \ -u {site_api_key}:\ -d billing_address[first_name]="John" \ -d billing_address[last_name]="Doe" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[state]="California" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US"
billing_address
country
as
XI
(which is United Kingdom - Northern Ireland), the first two characters of the full VAT
number can be overridden by setting
vat_number_prefix
. billing_address
country
as XI
(which is United Kingdom - Northern Ireland).billing_address
country
as XI
. That’s the code for United Kingdom - Northern
Ireland. The first two characters of the VAT number in such a case is
XI
by default. However, if the VAT number was registered in UK, the value should be GB
. Set
vat_number_prefix
to GB
for such cases. vat_number
of the customer. This helps identify the specific type of customer entity. For example, DE:VAT
is used for a German business entity while DE:LWID45
is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country
. See list of possible values.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
entity_identifier_scheme
. Currently only iso6523-actorid-upis
is supported and is used by default when not provided.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site. true
or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country
). When set to false
, the customer is not e-invoiced even if e-invoicing is enabled for their country.
Tip:
It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlCK52cl/contacts \ -G \ -u {site_api_key}:
Assign Primary or Backup payment role or unassign role for the payment source based on the preference for the payment collection.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl4rs2au/assign_payment_role \ -u {site_api_key}:\ -d payment_source_id="pm___test__KyVnHhSBWl4te2ax" \ -d role="PRIMARY"
Adds the required contact to a customer. You can give the First Name, Last Name, Email ID and more details as input parameters to add them under the desired customer.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5C82b2/add_contact \ -u {site_api_key}:\ -d contact[first_name]="Jane" \ -d contact[last_name]="Doe" \ -d contact[email]="jane@test.com" \ -d contact[label]="dev" \ -d contact[enabled]=true \ -d contact[send_billing_email]=true \ -d contact[send_account_email]=true
Updates the details of a contact for a customer. You can give the field data to be updated as input parameters along with the Contact ID to update it.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFmo2do/update_contact \ -u {site_api_key}:\ -d contact[id]="contact___test__KyVnHhSBWlFnd2dq" \ -d contact[first_name]="Jane" \ -d contact[last_name]="Doe" \ -d contact[email]="jane@test.com" \ -d contact[label]="dev" \ -d contact[enabled]=true \ -d contact[send_billing_email]=true \ -d contact[send_account_email]=true
Deletes a particular contact for a customer. You can delete a contact by giving the Contact ID as the input parameter.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl9ta2cA/delete_contact \ -u {site_api_key}:\ -d contact[id]="contact___test__KyVnHhSBWl9uT2cC"
Use this API to record any excess payments made by the customer, such as advance payments. Such payments will be automatically applied to the future invoices. It can also be manually applied to the existing Not Paid or Payment Due invoices.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDEl2cz/record_excess_payment \ -u {site_api_key}:\ -d comment="Check payment received from John" \ -d transaction[amount]=500 \ -d transaction[date]=1600968152 \ -d transaction[payment_method]="CHECK"
This API can be used to collect the payments for customer’s payment_due and not_paid invoices. You can either choose to collect the payment from an existing payment source or a new payment source. You can choose to either retain or discard the new payment source, which is being used for payment. If the amount collected exceeds the invoice amount, the surplus will be counted in as excess payments.
# collects payment for the customer with the existing payment source. curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl6A32bF/collect_payment \ -X POST \ -u {site_api_key}:\ -d amount=100 \ -d payment_source_id="pm___test__KyVnHhSBWl6Q02bG" \ -d invoice_allocations[invoice_id][0]="__demo_inv__1"
# collects payment for the customer using new payment source. curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl78A2bV/collect_payment \ -X POST \ -u {site_api_key}:\ -d card[number]="378282246310005" \ -d card[expiry_month]=10 \ -d card[expiry_year]=2022 \ -d card[cvv]="999" \ -d invoice_allocations[invoice_id][0]="__demo_inv__2"
Deletes a particular customer identified by the a unique identifier.
This will delete the Payment Method from the gateway/vault. If you do not want the Payment Method to be deleted from the vault, set the value for the delete_payment_method parameter to false.
This operation is irreversible - all data related to the customer, such as subscriptions, invoices, transactions, and reports, will be deleted.
Note: This operation schedules the customer resource for deletion. It will be deleted in a few minutes.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl9ZA2c8/delete \ -X POST \ -u {site_api_key}:
This API copies a customer object from one site to another. The destination site (the site to which the customer is copied) is specified by the path parameter {site}
; whereas, the source site (the site from which the customer is copied) is specified by the query parameter from_site
.
Prerequisites
preferred_currency_code
must be enabled in the destination site. curl https://{site}.chargebee.com/api/v2/customers/move \ -u {site_api_key}:\ -d id_at_from_site="__test__KyVnHhSBWlCxa2cx" \ -d from_site="mannar"
Applicable when calendar billing (with customer specific billing date support) is enabled. Changes the customer's billing_date and/or billing_day_of_week.
During this operation the upcoming renewal dates are not updated to align immediately with the new date. The alignment will happen during subsequent renewals.
For example, a customer's upcoming renewal is scheduled for January 10th, when the customer's billing date is changed to the 15th, the next renewal date is still January 10th. The new billing date does not take effect until the subsequent renewal, which in this case is February 15th.
If you want to align with the new date immediately (in this example: you want the next renewal to be on January 15th and not January 10th) you need to manually change the subscription's term end.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5XP2b6/change_billing_date \ -u {site_api_key}:\ -d billing_date=15 \ -d billing_date_mode="MANUALLY_SET" \ -d billing_day_of_week="SUNDAY" \ -d billing_day_of_week_mode="MANUALLY_SET"
billing_month
, together with billing_date
, specify, for this customer, the day of the year when the renewals of all the year-based subscriptions take place.
For example, the renewals happen on 15th July when billing_month
is 7
and billing_date
is 15
.
Applicable when Calendar Billing (with customer-specific billing date support) is enabled and billing_date_mode
is manually_set
.
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.
curl https://{site}.chargebee.com/api/v2/customers/merge \ -u {site_api_key}:\ -d from_customer_id="__test__KyVnHhSBWlCbP2cp" \ -d to_customer_id="__test__KyVnHhSBWlCdz2cv"
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5qO2b9/clear_personal_data \ -X POST \ -u {site_api_key}:
Establish a hierarchical relationship between customers. The path parameter customer_id
identifies the child in this relationship.
Both parent and child customers must be part of the same business entity.
For the use_default_hierarchy_settings
, parent_account_access
, and child_account_access
parameters below, the term "parent" usually refers to the customer with the ID payment_owner_id
. However, if the payment_owner_id
is the same as the child's ID ({customer_id}
), the "parent" is identified by parent_id
.
# creates a relationship for reporting purpose curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDY12d5/relationships \ -u {site_api_key}:\ -d parent_id="__test__KyVnHhSBWlDa22d7" \ -d payment_owner_id="__test__KyVnHhSBWlDY12d5" \ -d invoice_owner_id="__test__KyVnHhSBWlDY12d5"
# creates a completely dependent relationship curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDwm2dJ/relationships \ -u {site_api_key}:\ -d parent_id="__test__KyVnHhSBWlDrp2dC" \ -d payment_owner_id="__test__KyVnHhSBWlDrp2dC" \ -d invoice_owner_id="__test__KyVnHhSBWlDrp2dC"
# creates a relationship and sets custom parent/child access settings curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlEhB2dd/relationships \ -u {site_api_key}:\ -d parent_id="__test__KyVnHhSBWlEc92dW" \ -d payment_owner_id="__test__KyVnHhSBWlEc92dW" \ -d invoice_owner_id="__test__KyVnHhSBWlEhB2dd" \ -d use_default_hierarchy_settings=false \ -d parent_account_access[portal_edit_child_subscriptions]="YES" \ -d parent_account_access[portal_download_child_invoices]="YES" \ -d parent_account_access[send_subscription_emails]=true \ -d parent_account_access[send_payment_emails]=false \ -d parent_account_access[send_invoice_emails]=false \ -d child_account_access[portal_edit_subscriptions]="VIEW_ONLY" \ -d child_account_access[portal_download_invoices]="VIEW_ONLY" \ -d child_account_access[send_subscription_emails]=true \ -d child_account_access[send_payment_emails]=true \ -d child_account_access[send_invoice_emails]=true
# creates a partially dependent relationship curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlEIc2dT/relationships \ -u {site_api_key}:\ -d parent_id="__test__KyVnHhSBWlEDb2dM" \ -d payment_owner_id="__test__KyVnHhSBWlEDb2dM" \ -d invoice_owner_id="__test__KyVnHhSBWlEIc2dT"
Decides if Chargebee should apply settings from the Chargebee Billing UI or from this API request.
true
: Chargebee uses settings configured in the Chargebee Billing UI.false
: Settings provided in the parent_account_access
and child_account_access
parameters are applied.# deletes a customer from hierarchy curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlAG12cF/delete_relationship \ -X POST \ -u {site_api_key}:
# List the nodes of the full hierarchy to which the customer belongs. curl https://{site}.chargebee.com/api/v2/customers/foo/hierarchy \ -u {site_api_key}:\ -d hierarchy_operation_type="COMPLETE_HIERARCHY"
# List the nodes along the path from the customer to the root of the full hierarchy. curl https://{site}.chargebee.com/api/v2/customers/foo/hierarchy \ -u {site_api_key}:\ -d hierarchy_operation_type="PATH_TO_ROOT"
# List all the nodes of the hierarchy formed by the customer and its subordinates. curl https://{site}.chargebee.com/api/v2/customers/foo/hierarchy \ -u {site_api_key}:\ -d hierarchy_operation_type="SUBORDINATES"
When the customer is part of an account hierarchy, this operation updates the access privileges that both the customer and its parent have to the customer's data.
The term "parent" usually refers to the customer with the ID payment_owner_id
. However, if the payment_owner_id
is the same as the child's ID (given by the path parameter), the "parent" is identified by parent_id
.
You cannot use this endpoint to change the parent_id
, invoice_owner_id
or payment_owner_id
for the customer. To change them, unlink the customer and then call Link a customer with the updated values.
# Deletes any custom parent/child access settings defined and applies the site defaults curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlG3y2dt/update_hierarchy_settings \ -u {site_api_key}:\ -d use_default_hierarchy_settings=true
# Updates all of the "parent_account_access" and "child_account_access" settings for a customer. curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlGoZ2e7/update_hierarchy_settings \ -u {site_api_key}:\ -d use_default_hierarchy_settings=false \ -d child_account_access[portal_edit_subscriptions]="YES" \ -d child_account_access[portal_download_invoices]="YES" \ -d child_account_access[send_subscription_emails]=true \ -d child_account_access[send_payment_emails]=true \ -d child_account_access[send_invoice_emails]=true \ -d parent_account_access[portal_edit_child_subscriptions]="VIEW_ONLY" \ -d parent_account_access[portal_download_child_invoices]="YES" \ -d parent_account_access[send_subscription_emails]=false \ -d parent_account_access[send_payment_emails]=false \ -d parent_account_access[send_invoice_emails]=false
# Updates only some of the "parent_account_access" and "child_account_access" settings for a customer curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlGQc2e0/update_hierarchy_settings \ -u {site_api_key}:\ -d use_default_hierarchy_settings=false \ -d parent_account_access[portal_edit_child_subscriptions]="YES" \ -d parent_account_access[portal_download_child_invoices]="YES" \ -d parent_account_access[send_invoice_emails]=false \ -d child_account_access[portal_download_invoices]="YES" \ -d child_account_access[send_invoice_emails]=true
Decides if Chargebee should apply settings from the Chargebee Billing UI or from this API request.
true
: Chargebee removes existing settings stored in the parent_account_access
and child_account_access
attributes of the customer. The settings configured in the Chargebee Billing UI apply for the customer.false
: Chargebee replaces existing settings stored in the parent_account_access
and child_account_access
parameters with those passed in this API call. If any of those parameters are not passed, they remain unchanged for the customer.