Settings
Configure SDK
Customers
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:
- Sites created before March 1, 2014: updating the card deletes the customer's
billing_addressandvat_numberand replaces them with values from the request. - Sites created on or after March 1, 2014: updating the card doesn't change the
billing_addressandvat_number.
Sample customer [ JSON ]
{
"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
}API Index URL
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.
Tip
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.)
The VAT/tax registration number for the customer. For customers with 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
.
When the customer has a payment_method
of type
card
, this attribute determines whether to automatically charge the card whenever an invoice status
is payment_due
.
Note This setting can be overridden for individual subscriptions of the customer.
Represents the VAT validation status. This is applicable if you have configured EU, UK or Australian taxes and the VAT number validation is enabled.
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:
- The card issuer's country.
- The
billing_address.country. - The country to which
created_from_ipbelongs. - When all three are the same, this attribute is set to true, otherwise it is set to false.
When all three are the same, this attribute is set to
true, otherwise it is set tofalse.
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:
- API: When creating the
customerresource 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. - Checkout: For
customerresources created through Chargebee Checkout, Chargebee automatically captures the IP address of the customer. - UI: When creating a
customerresource via the Chargebee Billing UI, this field is not relevant and the value must be ignored.
Indicates the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use Chargebee's AvaTax for Communications integration. To know more about what values you need to provide, refer to this Avalara's API document .
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration .
Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's AvaTax for Sales integration .
Note
Applicable only when Calendar Billing with support for customer-specific billing date is enabled and billing_date_mode is manually_set.
Specifies the day of the month for subscription renewals on month-based or year-based plans. Month-based and year-based plans are item_price
resources where the item_type
is set to plan
and period_unit
is set to month
and year
respectively.
Example
- Month-based subscriptions: If
billing_dateis set to15, month-based renewals occur on the 15th of the month. It's important to note that if the value is set to31, renewals align with the last day of the month. Additionally, in February, abilling_dateof29,30, or31aligns renewals for the last day of February. - Year-based subscriptions: A
billing_dateof15and abilling_monthof7schedules the renewal on the 15th of July.
Note
Applicable only when Calendar Billing with support for customer-specific billing date is enabled and billing_date_mode is manually_set.
Specifies the renewal month for subscriptions on year-based plans. Year-based plans are item_price
resources where item_type
is set to plan
and period_unit
is set to year.
Example
The renewal date is 15th July when billing_date is 15 and billing_month is 7.
Note
Applicable only when Calendar Billing with support for customer-specific billing date is enabled and billing_date_mode is manually_set.
Indicates whether this customer's billing_date
and billing_month
values can be changed via the Change billing date API
.
Indicates whether this customer's billing_day_of_week value is derived as per configurations or its specifically set (overriden). When specifically set, the billing_day_of_week will not be reset even when all of the weekly subscriptions are cancelled.
Override for this customer, the site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute is also available at the subscription level which takes precedence.
Note: Present only when the customer has been transferred between business entities.
Represents the id of the active version of the customer resource.
Tip: If the id and active_id of a customer resource are the same, this indicates that you are working with the active version of that customer resource.
A note for the customer that appears on all their invoice PDFs. This is one of several notes displayed on the invoice PDF.
The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.
Note Applicable only when the Multi-Currency feature is enabled.
Specifies the customer's preferred currency in ISO 4217 format.
Determines whether the customer is e-invoiced. When set to 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.
A collection of key-value pairs that provides extra information about the customer.
Note: There's a character limit of 65,535.
Confirms that a customer is registered under GST. If set to 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.
Note Applicable only when the Chargebee's AvaTax for Communications integration is enabled.
Indicates the Avalara customer type .
Note Applicable only when the Chargebee's AvaTax for Communications integration is enabled.
The Avalara client profile ID assigned to the customer.
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: - Self-Serve Portal data: subscriptions and invoices of the customer.
- Email Notifications: subscription-, invoice- and payment-related notifications for the customer.
An overridden value for the first two characters of the full VAT number.
Only applicable specifically for customers with billing_address
country
as XI
(which is United Kingdom - Northern Ireland
).
When you have enabled EU VAT
in 2021 or have manually enabled
the Brexit configuration, you have the option of setting 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.
The Peppol BIS scheme associated with the 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.
The standard used for specifying the 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.
Billing address for a customer.
List of referral urls for the customer (if applicable)
contacts
Primary Payment Source of the customer.
The list of balances for this customer
Each element of the 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.
This represents information related to custom Tax Provider Fields. It includes the provider name, field Id, and its corresponding field value. It is used to send custom Tax provider fields to any tax provider.
The account hierarchy relationship that the customer is part of.
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 the payment_owner_id
is the customer itself, then the parent is parent_id
.
When the customer is part of an account hierarchy , this attribute defines the level of access that the customer has to its own information.
Create a customer ¶
Note: This operation optionally supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.
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, card details, and any custom attributes.
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:
- Stripe.js for Stripe users.
- Braintree.js for Braintree users.
- Accept.js, if you use Authorize.Net.
- If you are using the Adyen gateway, you will have to use the Adyen's Client-Side Encryption to encrypt sensitive cardholder data. Once the cardholder data is encrypted, pass the value in
adyen.encrypted.dataas temp token in this API. - You can also use our Hosted Pages based integration.
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
The VAT/tax registration number for the customer. For customers with 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
.
An overridden value for the first two characters of the full VAT number.
Only applicable specifically for customers with billing_address
country
as XI
(which is United Kingdom - Northern Ireland
).
When you have enabled EU VAT
in 2021 or have manually enabled
the Brexit configuration, you have the option of setting 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.
The Peppol BIS scheme associated with the 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.
.
The standard used for specifying the 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.
.
Confirms that a customer is registered under GST. If set to true
then the Reverse Charge Mechanism
is applicable. This field is applicable only when Australian GST is configured for your site.
Determines whether the customer is e-invoiced. When set to 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 the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use Chargebee's AvaTax for Communications integration. To know more about what values you need to provide, refer to this Avalara's API document .
Indicates the type of the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration .
Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's AvaTax for Sales integration .
A collection of key-value pairs that provides extra information about the customer.
Note: There's a character limit of 65,535.
Override for this customer, the site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute is also available at the subscription level which takes precedence.
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.
.
The Chargebee payment token generated by Chargebee JS.
Note:
The payment token created via Chargebee JS uses the gateway selected through Smart Routing.
Explicitly passing a gateway_id
in this API call will not override the gateway associated with the token.
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.
Note
An alternative way of passing this parameter is by means of a custom HTTP header.
.
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
pass parameters as card[<param name>]
pass parameters as bank_account[<param name>]
pass parameters as payment_method[<param name>]
pass parameters as payment_intent[<param name>]
pass parameters as billing_address[<param name>]
pass parameters as entity_identifiers[<param name>][<idx:0..n>]
pass parameters as tax_providers_fields[<param name>][<idx:0..n>]
Returns
List customers ¶
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.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Sorts based on the specified attribute.
Supported attributes : created_at, updated_at
Supported sort-orders : asc, desc
Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.
Filter Params
For operator usages, see the Pagination and Filtering section.
Email of the customer. Configured email notifications will be sent to this email. Supported operators : is, is_not, starts_with, is_present
Example → email[is] = "john@test.com"
Supported operators : is, is_not, starts_with, is_present
Example → email[is] = "john@test.com"
Timestamp indicating when this customer resource is created. Supported operators : after, before, on, between
Example → created_at[before] = "1435054328"
Supported operators : after, before, on, between
Example → created_at[after] = "1435054328"
To filter based on 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.
Supported operators :
after, before, on, between
Example → updated_at[after] = "1243545465"
Supported operators : after, before, on, between
Example → updated_at[after] = "1243545465"
The preferred offline payment method for the customer.
Possible values are : no_preference, cash, check, bank_transfer, ach_credit, sepa_credit, boleto, us_automated_bank_transfer, eu_automated_bank_transfer, uk_automated_bank_transfer, jp_automated_bank_transfer, mx_automated_bank_transfer, customSupported operators : is, is_not, in, not_in
Example → offline_payment_method[is] = "cash"
Override for this customer, the site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute is also available at the subscription level which takes precedence.
Possible values are : true, falseSupported operators : is
Example → auto_close_invoices[is] = "true"
The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.
Supported operators : is, is_not, starts_with
Example → business_entity_id[is_not] = "business_entity_id"
Supported operators : is
Example → business_entity_id[is] = "business_entity_id"
Parameters for relationship
pass parameters as relationship[<param name>][<operator>]
Returns
Resource object representing customer
Resource object representing card
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
Retrieve a customer ¶
Retrieves the details of the desired customer. You can use the unique identifier for a particular customer to retrieve the desired details.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing customer
Resource object representing card
Sample admin console URL
Update a customer ¶
Updates the details of the specified customer.
Use this API to modify customer information, including standard attributes and any configured custom attributes.
- To update the billing address or VAT number, use the Update billing info for a customer API instead.
- The Account Hierarchy (Parent-Child Relationship) cannot be updated using this API.
- To add a child to a Parent Account, use the Link a customer to an account API.
- To remove a child from a Parent Account, use the Unlink a customer from its parent account API.
Impacts
Invoices
- See
auto_collectionparameter to understand the impact on invoices. - See
taxabilityparameter to understand how taxes on invoices are impacted.
CRM integrations
When you update customer details in Chargebee using this API, the corresponding records are synced with integrated CRM systems, such as HubSpot or Salesforce, depending on your integration configuration.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Determines whether payments should be collected automatically for this customer.
Note This setting can be overridden at the subscription level.
Indicates the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use Chargebee's AvaTax for Communications integration. To know more about what values you need to provide, refer to this Avalara's API document .
Indicates the type of the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration .
Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's AvaTax for Sales integration .
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
Override for this customer, the site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute is also available at the subscription level which takes precedence.
A collection of key-value pairs that provides extra information about the customer.
Note: There's a character limit of 65,535.
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.
.
pass parameters as tax_providers_fields[<param name>][<idx:0..n>]
Returns
Update payment method for a customer ¶
Payment Sources comes with additional options and improvements to the Card APIs . For this operation, use the Create using temporary token API or Create using permanent token API under Payment Sources to update payment method for the customer.
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
typeascard.gatewaywith the gateway associated with the card. If the gateway is not specified, the default gateway will be used.reference_idwith 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
typeasdirect_debit.gatewaywith 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_idwith the identifier provided by the gateway to reference the customer's bank account details.tmp_tokenwith 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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as payment_method[<param name>]
Returns
Update billing info for a customer ¶
Updates a customer's billing information, including billing address and tax-related details such as VAT number.
Note
See Related APIs for other customer attributes that can be updated.
Prerequisites & Constraints
In some cases, passing the following parameters can cause the request to fail: vat_number, business_customer_without_vat_number, tax_providers_fields, and registered_for_gst. See Implementation Notes for more details.
Impacts
Customer
For certain parameters, if you do not include a parameter in the request, Chargebee removes the corresponding attribute from the customer object. To retain an existing attribute, you must explicitly include its parameter in your request.
Parameters that are affected by this behavior
billing_address.first_namebilling_address.last_namebilling_address.phonebilling_address.emailbilling_address.line1billing_address.line2billing_address.line3billing_address.citybilling_address.statebilling_address.countrybilling_address.zipvat_numbervat_number_prefixbusiness_customer_without_vat_numberregistered_for_gst
Example
Assume the customer object has these attributes set:
Current attributes:
billing_address.first_namebilling_address.last_namebilling_address.phonebilling_address.emailvat_number
You make an API call with only the following parameters:
Request parameters:
billing_address.first_namebilling_address.last_namebilling_address.phone
Result: The billing_address.email and vat_number attributes are removed from the customer object because they weren't included in the request. To preserve these attributes, include them in the request.
Invoices
- Chargebee uses the
billing_addressobject from the customer to set the values in thebilling_addressof the invoices generated for the customer. - If the
billing_addressobject does not include thefirst_name,last_name, orcompanyfields, Chargebee automatically uses the values fromcustomer.first_name,customer.last_name, andcustomer.company(if available) when generating invoices.
Implementation Notes
- Ensure that
vat_numberandbusiness_customer_without_vat_number=trueare not passed together in the same request. - Ensure that
tax_providers_fieldsis not passed if Indian GST is not configured for your site. - Ensure that
registered_for_gst=trueis not passed if Australian GST is not configured for your site.
Use Cases
Prevent tax provider errors due to missing billing information
After integrating tax providers, you might encounter unintended tax calculation failures during renewals. The error message typically states:
Unable to calculate the tax rate as the shipping/billing address is either invalid or incomplete. Please verify and try again.
This error can occur even if the is_taxable value of item prices is changed from true to false before subscription renewal and reactivation.
Solution
Use this operation to update the billing address attributes to ensure they are accurate and complete.
Troubleshooting
Error: 400: "Operation failed as the country entered in the billing address by the customer cannot be verified against IP address or card BIN number."
This error occurs when location validation is enabled in the tax settings and there's a mismatch between the customer's billing country and their IP address or the card issuing country.
Resolution
Choose one of the following solutions:
Option A: Fix IP address mismatch
Use the Update a card payment source API and include the correct IP address in the request header.
Option B: Fix BIN mismatch
Ask the customer to update their payment method with one whose BIN matches their country. You can do this using the Request Payment Method option or the Self-Serve Portal.
Option C: Disable location validation
- In Chargebee Billing, navigate to Settings > Configure Chargebee > Taxes.
- Select the country.
- In the right pane, clear the Enable location validation checkbox.
Sample Response [ JSON ]
URL Format POST
Input Parameters
The VAT/tax registration number for the customer.
For customers with billing_address as XI (United Kingdom - Northern Ireland), the first two characters of the full VAT number can be overridden by setting vat_number_prefix.
Warning
- If you don't pass this parameter, the value will be deleted from the customer object.
- If you pass this parameter and also pass
business_customer_without_vat_number=true, the request will fail.
An overridden value for the first two characters of the full VAT number.
Only applicable specifically for customers with billing_address as XI (United Kingdom - Northern Ireland).
Warning If you don't pass this parameter, the value will be deleted from the customer object.
The Peppol BIS scheme associated with the 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.
.
The standard used for specifying the 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.
.
Confirms that a customer is registered under GST. If set to true then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.
Warning
- If you don't pass this parameter, the value will be deleted from the customer object.
- If you pass this parameter as
trueand Australian GST is not configured for your site, the request will fail.
Confirms that a customer is a valid business without an EU/UK VAT number.
Warning
- If you don't pass this parameter, the value will be deleted from the customer object.
- If you pass this parameter as
trueand also passvat_number, the request will fail.
Determines whether the customer is e-invoiced. When set to 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.
.
pass parameters as billing_address[<param name>]
pass parameters as entity_identifiers[<param name>][<idx:0..n>]
pass parameters as tax_providers_fields[<param name>][<idx:0..n>]
Returns
List of contacts for a customer ¶
This API retrieves all the contacts for a customer.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Returns
Resource object representing contact
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
Assign payment role ¶
Assign or unassign the primary or backup payment role for a payment source.
Set role when creating a payment source
You can also assign a payment source as primary when you create it using APIs such as:
- Create a payment source using payment intent
- Create a payment source using temporary token
- Create a payment source using permanent token
Payment collection precedence
Chargebee uses the following precedence to determine which payment source to use when it collects payments for a subscription:
- The payment source attached to the subscription, if available.
- The primary payment source of the customer.
- The backup payment source of the customer, if available.
Prerequisites & Constraints
- The payment source must belong to the customer and must not be
deleted. - The payment source must not be the current primary payment source of the customer.
- This operation doesn't validate the
statusof the payment source. Check thestatusof the payment source before you assign it to the primary or backup role.
Impacts
Payment collection
The roles that you set using this API apply to all payments collected for the customer, except for subscriptions that have a payment source attached to them. Chargebee continues to collect such payments using the payment source attached to the subscription.
Customer
- When you assign a payment source as primary, Chargebee unassigns the existing primary payment source and doesn't affect the backup payment source.
- When you assign a payment source as backup, Chargebee unassigns the existing backup payment source and doesn't affect the primary payment source.
- You can set the role of a
backuppayment source toprimaryornone. - You cannot set the role of a
primarypayment source to eitherbackupornone.
Implementation Notes
Before you call this API, ensure the following:
- The
payment_source.customer_idmatches theidof the customer. - The
payment_source_idisn't the same as thecustomer.primary_payment_source_id. - Since this API doesn't validate the
statusof the payment source, check thepayment_source.statusto ensure it isn'texpired,invalid, orpending_verification.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing customer
Resource object representing payment_source
Add contacts to a customer ¶
Prerequisites & Constraints
- The customer must have fewer than 10 contacts already added.
Impacts
Email notifications
- If you set
contact[send_billing_email]totrue, the contact receives billing emails. - If you set
contact[send_account_email]totrue, the contact receives account emails.
Implementation Notes
Check the customer's contacts[] array and ensure it contains fewer than 10 contacts before calling this API.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as contact[<param name>]
Returns
Update contacts for a customer ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as contact[<param name>]
Returns
Delete contacts for a customer ¶
Deletes a particular contact for a customer. You can delete a contact by giving the Contact ID as the input parameter.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Record an excess payment for a customer ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as transaction[<param name>]
Returns
Resource object representing customer
Resource object representing transaction
Collect payment for customer ¶
Note: This operation optionally supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as payment_method[<param name>]
pass parameters as card[<param name>]
pass parameters as payment_intent[<param name>]
pass parameters as invoice_allocations[<param name>][<idx:0..n>]
Returns
Resource object representing customer
Resource object representing transaction
Delete a customer ¶
Deletes a specified customer.
This operation schedules the customer resource for deletion, and it is permanently deleted after a few minutes.
If you wish to retain the customer data but stop further subscription renewals, consider canceling or pausing the subscriptions instead.
Prerequisites & Constraints
- The customer must not be part of an account hierarchy (neither a parent nor a child).
- The customer record must not have any linked gift subscriptions (neither gifter nor recipient).
- None of the customer's invoices may be paid by a different customer.
- None of the customer's credit notes may be allocated to an invoice that belongs to a different customer.
Impacts
Subscriptions
- All the subscriptions belonging to the customer are deleted.
- See Delete a subscription API for more details on the impacts of deleting a subscription.
Invoices
- All the invoices belonging to the customer are deleted.
- See Delete an invoice API for more details on the impacts of deleting an invoice.
Credit notes
- All the credit notes belonging to the customer are deleted.
Payment sources
The payment sources linked to the customer are deleted and also removed from the payment gateway. To retain payment gateway records, pass delete_payment_method = false.
Reports
- The numbers in the following reports are modified when a customer is deleted: Payments, New Revenue, Signups, Activations, Cancellations, and Refunds.
Implementation Notes
Before deleting a customer, ensure the following:
- Check and remove account hierarchy linkage:
- Use the Get hierarchy API to check if the customer is part of an account hierarchy.
- If the customer is part of an account hierarchy, use the Unlink a customer from its parent account API to remove the customer from the hierarchy.
- Remove any payments by other customers:
- Use the List invoices API to retrieve all the invoices for this customer.
- For each invoice, look up all the linked payments (
invoice.linked_payments[]). - For each linked payment, check if the payer (
transaction.customer_id) is this customer. - If not, use the Remove payment from an invoice API to remove the payment from the invoice.
- Remove credit note allocations to other customers:
- Use the List credit notes API to retrieve all the credit notes for this customer.
- For each credit note, look up all the invoice allocations (
credit_note.allocations.invoice_id). - For all such invoices, check if the associated customer (
invoice.customer_id) is this customer. - If not, use the Remove credit note from an invoice API to remove the allocation.
- Remove credit note allocations from other customers:
- Use the List invoices API to retrieve all the invoices for this customer.
- For each invoice, look up all the applied credit notes (
credit_note.applied_credits.cn_id). - For all such credit notes, check if the associated customer (
credit_note.customer_id) is this customer. - If not, use the Remove credit note from an invoice API to remove the credit note allocation.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Move a customer ¶
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
- This endpoint is disabled by default. For the operation to work, the endpoint must be enabled for both the source and destination sites. Contact Chargebee Support to have it enabled.
- The customer's
preferred_currency_codemust be enabled in the destination site.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing resource_migration
Change billing date ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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.
Note
Applicable when Calendar Billing (with customer-specific billing date support) is enabled and billing_date_mode is manually_set.
Indicates whether this customer's billing_date value is derived as per configurations or its specifically set (overriden). When specifically set, the billing_date will not be reset even when all of the monthly/yearly subscriptions are cancelled.
Indicates whether this customer's billing_day_of_week value is derived as per configurations or its specifically set (overriden). When specifically set, the billing_day_of_week will not be reset even when all of the weekly subscriptions are cancelled.
Returns
Resource object representing customer
Merge customers ¶
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.
Note
- Moving virtual bank accounts from one customer to another is not supported in this API.
- Merging customers from different business entities is not permitted.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing customer
Clear Personal Data of a customer ¶
Clear personal details of a customer using this API.
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing customer
Link a customer to an account hierarchy ¶
Establish a hierarchical relationship between customers. The path parameter customer_id identifies the child in this relationship.
Prerequisite Both parent and child customers must be part of the same business entity.
Note
- A customer can have a maximum of 250 direct children.
- The hierarchy allows a maximum of 5 levels from the root node to the lowest child node.
Note
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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 theparent_account_accessandchild_account_accessparameters are applied.
pass parameters as parent_account_access[<param name>]
pass parameters as child_account_access[<param name>]
Returns
Resource object representing customer
Unlink a customer from its parent account ¶
When a customer belongs to an account hierarchy , this operation detaches the customer from its parent. The hierarchy, if any, beneath the customer remains unchanged.
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing customer
Get account hierarchy for a customer ¶
Retrieves the full or partial account hierarchy for a customer.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Returns
Resource object representing hierarchies
Get paginated account hierarchy for a customer ¶
Retrieves the account hierarchy tree for the customer.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Returns
Resource object representing hierarchy
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
Update account hierarchy access settings for a customer ¶
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.
Terminology
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.
Tip
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Decides if Chargebee should apply settings from the Chargebee Billing UI or from this API request.
- If set to
true: Chargebee removes existing settings stored in theparent_account_accessandchild_account_accessattributes of the customer. The settings configured in the Chargebee Billing UI apply for the customer. - If set to
false: Chargebee replaces existing settings stored in theparent_account_accessandchild_account_accessparameters with those passed in this API call. If any of those parameters are not passed, they remain unchanged for the customer.
pass parameters as parent_account_access[<param name>]
pass parameters as child_account_access[<param name>]
Returns
Resource object representing customer