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 customer resource. You may also update any of its custom attributes. 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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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 like vat_number.
Note: To modify other customer attributes, use the Update Customer API.
Note: When an invoice is created for a customer, the billing address specified for the customer is saved with the invoice. If the first_name, last_name, and company fields under customer.billing_address are empty, Chargebee retrieves this information from customer.first_name, customer.last_name, and customer.company respectively, if available.
Note: The tax_providers_fields parameter is supported only for sharing India-SEZ and Export details.
Implications of the operation
How this update works
This operation works like an assignment. Chargebee first discards the existing values of the customer object's attributes that correspond to the parameters in this operation. Then, Chargebee assigns the arguments passed in this operation to the corresponding attributes.
Therefore, you must pass all attributes you want to retain, even if their values remain unchanged. If you omit an argument, Chargebee deletes that attribute from the customer object.
Example
Assume the customer object has these attributes set:
Set A
vat_numberbilling_address.emailbilling_address.line1billing_address.state_codebilling_address.zipbilling_address.citybilling_address.country
Now, you make an API call with only the following parameters:
Set B
billing_address.line1billing_address.state_codebilling_address.zipbilling_address.citybilling_address.country
Because the vat_number and billing_address.email were not included in the request, those attributes will be removed from the customer object. The object will now only include the parameters in Set B. To preserve vat_number and billing_address.email, include all Set A fields in the request.
entity_identifiers[i] update behavior
If any of entity_identifiers[operation][i] is specified as delete, entity_identifiers[i] remains unchanged for the customer object.
Use Cases
Prevent subscription cancellations due to missing billing information after tax provider integration
If you're a startup below the tax threshold, you might skip collecting billing addresses during customer signup to reduce friction. However, as you scale and exceed the tax threshold, you'll need to collect taxes and may integrate with a tax provider like Avalara.
After integrating Avalara, you might encounter unintended subscription cancellations 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 at least the billing_address.zip for all customers to prevent tax calculation failures.
FAQs
I want to set the VAT number for a customer, but I don't know where it fits into the request.
Use the "Update billing info for a customer" operation including the following arguments:
vat_numbervat_number_prefix- All other arguments that correspond to the existing attributes of the customer.
Troubleshooting
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 Chargebee tries to match the customer's billing country with their IP address or the card issuing country (based on the card BIN).
Resolution
The error occurs because location validation is enabled in the tax settings. Disable it to resolve the issue.
- In Chargebee Billing, navigate to Settings > Configure Chargebee > Taxes.
- Select the country.
- In the right pane, clear the Enable location validation checkbox.
If the issue is related to the IP address, use Chargebee's Update a Card Payment Source API and include the correct IP address in the request header.
If the issue is caused by a BIN mismatch, ask the customer to update their payment method with one whose BIN matches their country using the Request Payment Method option or the Self-Serve Portal.
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.
.
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 Primary or Backup payment role or unassign role for the payment source based on the preference for the payment collection.
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 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.
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