Represents a customer, which can be an individual or organization that subscribes to your products or services. The customer resource associates with subscriptions, card information, and billing addresses. The customer details include their ID, name, contact information, and any custom attributes you'd like to associate with them.
Breaking Change:
billing_address
and vat_number
and replaces them with values from the request.billing_address
and vat_number
.{
"allow_direct_debit": false,
"auto_collection": "on",
"billing_address": {
"city": "Walnut",
"country": "US",
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"object": "billing_address",
"state": "California",
"state_code": "CA",
"validation_status": "not_validated",
"zip": "91789"
},
"card_status": "no_card",
"created_at": 1517505731,
"deleted": false,
"email": "john@test.com",
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl7eY2bl",
"last_name": "Doe",
"locale": "fr-CA",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505731000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505731
}
<chargebee>.Customer
billing_address
country
as
XI
(which is United Kingdom - Northern Ireland), the first two characters of the full VAT
number can be overridden by setting
vat_number_prefix
. billing_month
, together with billing_date
, specify, for this customer, the day of the year when the renewals of all the year-based subscriptions take place.
For example, the renewals happen on 15th July when billing_month
is 7
and billing_date
is 15
.
Applicable when Calendar Billing (with customer-specific billing date support) is enabled and billing_date_mode
is manually_set
.
Multiple Business Entities is a feature available only on Product Catalog 2.0.
true
or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country
). When set to false
, the customer is not e-invoiced even if e-invoicing is enabled for their country.
Tip:
It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.
true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site. Indicates whether invoices raised on the same day for the customer
are consolidated. When present, this value overrides the default configuration at the site-level. This attribute is applicable only when Consolidated Invoicing is enabled.
Note:
Any invoices raised when a subscription activates from in_trial
or future
status
, are not consolidated by default. Contact Support to enable consolidation for such invoices.
Indicates whether the site-default settings are being used for controlling access to the customer’s information.
The level of access is for data falling into two categories:billing_address
country
as XI
(which is United Kingdom - Northern Ireland).billing_address
country
as XI
. That’s the code for United Kingdom - Northern
Ireland. The first two characters of the VAT number in such a case is
XI
by default. However, if the VAT number was registered in UK, the value should be GB
. Set
vat_number_prefix
to GB
for such cases. vat_number
of the customer. This helps identify the specific type of customer entity. For example, DE:VAT
is used for a German business entity while DE:LWID45
is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country
. See list of possible values.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
entity_identifier_scheme
. Currently only iso6523-actorid-upis
is supported and is used by default when not provided.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
entity_identifiers[]
array identifies a specific customer entity with the e-invoicing system. If the customer has only one entity identifier whose value
is the vat_number
, then this array is not needed as the scheme
can be provided via entity_identifier_scheme
. This array holds any additional entity identifiers that the customer may have.
When the customer is part of an account hierarchy, this attribute defines the level of access that the parent account has to the customer's information.
Note: the 'parent' is the customer whose id is payment_owner_id. However, if thepayment_owner_id
is the customer itself, then the parent is parent_id.Creates a customer. You can create a customer and then create subscriptions for the customer when required. When creating a customer, you can pass along the billing address and card details.
Passing raw card data via API involves PCI liability at your end due to the sensitivity of the data. Instead, you can use one of the following integration options as applicable:
Here’s some resources you can use to collect card information within your checkout form based on the payment gateway you use:
adyen.encrypted.data
as temp token in this API.When billing address is not passed (say, for customers making offline payments), you can always provide it later using the Update billing info for a customer API.
Note: When an invoice is generated for a customer, the billing address provided for the customer is stored with the invoice. If the First Name, Last Name, and Company fields of the billing address do not contain any information, they’re picked up from the customer details.
<chargebee>.customer.create({<param name> : <value>,<param name> : <value> ...})
billing_address
country
as
XI
(which is United Kingdom - Northern Ireland), the first two characters of the full VAT
number can be overridden by setting
vat_number_prefix
. billing_address
country
as XI
(which is United Kingdom - Northern Ireland).billing_address
country
as XI
. That’s the code for United Kingdom - Northern
Ireland. The first two characters of the VAT number in such a case is
XI
by default. However, if the VAT number was registered in UK, the value should be GB
. Set
vat_number_prefix
to GB
for such cases. vat_number
of the customer. This helps identify the specific type of customer entity. For example, DE:VAT
is used for a German business entity while DE:LWID45
is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country
. See list of possible values.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
entity_identifier_scheme
. Currently only iso6523-actorid-upis
is supported and is used by default when not provided.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site. true
or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country
). When set to false
, the customer is not e-invoiced even if e-invoicing is enabled for their country.
Tip:
It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.
Indicates whether invoices raised on the same day for the customer
are consolidated. When provided, this overrides the default configuration at the site-level. This parameter can be provided only when Consolidated Invoicing is enabled.
Note:
Any invoices raised when a subscription activates from in_trial
or future
status
, are not consolidated by default. Contact Support to enable consolidation for such invoices.
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.
updated_at
. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by
input parameter as updated_at
for a faster response. Retrieves the details of the desired customer. You can use the unique identifier for a particular customer to retrieve the desired details.
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.
Indicates whether invoices raised on the same day for the customer
are consolidated. When provided, this overrides the default configuration at the site-level. This parameter can be provided only when Consolidated Invoicing is enabled.
Note:
Any invoices raised when a subscription activates from in_trial
or future
status
, are not consolidated by default. Contact Support to enable consolidation for such invoices.
Updates payment method details for a customer.
Note: If you wish to pass the card number, CVV, or the single-use card tokens provided by gateways like Stripe, then use the Update card for a customer API under Cards resource. This API is not supported for Chargebee Test Gateway, it is provided to help you understand the billing workflow in Chargebee.
PayPal Express Checkout
You can use this API if you are directly integrating PayPal Express Checkout in your website instead of using Chargebee's hosted pages. When your customer updates his payment method using PayPal Express Checkout, you will be provided with the Billing Agreement ID by PayPal. You can update the payment method for that customer in Chargebee by passing type
as paypal_express_checkout
and reference_id
with the Billing Agreement ID.
Login and Pay with Amazon
You can use this API if you are directly integrating Login and Pay with Amazon in your website instead of using Chargebee's hosted pages. When your customer updates Amazon as a payment method, you will be provided with the Billing Agreement ID by Amazon. You can update the payment method for that customer in Chargebee by passing type
as amazon_payments
and reference_id
with the Billing Agreement ID.
Card Payments
When the card details of your customer are stored in the vault of gateways such as Stripe or Braintree, you can use this API to update the reference id provided by them in Chargebee. To use this API, pass
type
as card
. gateway
with the gateway associated with the card. If the gateway is not specified, the default gateway will be used. reference_id
with the identifier provided by the gateway/Spreedly to reference that specific card. Reference id format for Card Payments
The format of reference_id will differ based on where the card is stored.
Stripe: In case of Stripe, the reference_id consists of combination of Stripe Customer ID and Stripe Card ID separated by forward slash (e.g. cus_63MnDn0t6kfDW7/card_6WjCF20vT9WN1G). If you are passing Stripe Customer ID alone, then Chargebee will store the card marked as active for that customer in Stripe.
Braintree: In case of Braintree, the reference_id consists of combination of Braintree Customer ID and Braintree Payment Method Token separated by forward slash
(e.g. cus_63MnDn0t6kfDW7/card_6WjCF20vT9WN1G ). If you are passing Braintree Customer ID alone, then Chargebee will store the card marked as default for that customer in Braintree.
Spreedly Card vault: If the card details are stored in Spreedly vault, then you need to provide the Spreedly token as reference_id
.
Direct Debit Payments
When the bank account details of your customer are stored in the gateway vault, you can use this API to update the reference id provided by them in Chargebee. To use this API, pass
type
as direct_debit
. gateway
with the gateway where the bank account details are stored (e.g. authorize_net). If the gateway is not specified, the gateway supporting the direct debit will be used. reference_id
with the identifier provided by the gateway to reference the customer's bank account details. tmp_token
with the single use token provided by the gateway ( Should be passed only if reference_id is not passed ). Reference id format for Direct Debit Payments
The format of reference_id will differ based on where the bank account is stored.
Stripe: In case of Stripe, the reference_id consists of combination of Stripe Customer ID and Stripe Bank Account ID separated by forward slash
(e.g. cus_8suoHaLQH4G5AW/ba_18b8z2KmcbENlhgU03RznRYW). If you are passing Stripe Customer ID alone, then Chargebee will store the first bank account details present in payment profile list of that customer in Stripe.
Authorize.Net: The reference_id consists of combination of Authorize.Net's Customer Profile ID and Payment Profile ID separated by forward slash (e.g. 2384383/34834382). If you are passing Authorize.Net's Customer Profile ID alone, then Chargebee will store the first bank account details present in payment profile list of that customer in Authorize.Net.
GoCardless: The reference_id is the GoCardless Customer Mandate ID (e.g. MD0077Z99TTQXK).
Note: While using this API to update payment method details, Card Verification will not happen even if it is enabled for that particular gateway.
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.
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.
Assume the customer object has these attributes set:
Set A
vat_number
billing_address.email
billing_address.line1
billing_address.state_code
billing_address.zip
billing_address.city
billing_address.country
Now, you make an API call with only the following parameters:
Set B
billing_address.line1
billing_address.state_code
billing_address.zip
billing_address.city
billing_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.
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.
Use this operation to update at least the billing_address.zip
for all customers to prevent tax calculation failures.
Use the “Update billing info for a customer” operation including the following arguments:
vat_number
vat_number_prefix
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).
The error occurs because location validation is enabled in the tax settings. Disable it to resolve the issue.
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.
billing_address
country
as
XI
(which is United Kingdom - Northern Ireland), the first two characters of the full VAT
number can be overridden by setting
vat_number_prefix
. billing_address
country
as XI
(which is United Kingdom - Northern Ireland).billing_address
country
as XI
. That’s the code for United Kingdom - Northern
Ireland. The first two characters of the VAT number in such a case is
XI
by default. However, if the VAT number was registered in UK, the value should be GB
. Set
vat_number_prefix
to GB
for such cases. vat_number
of the customer. This helps identify the specific type of customer entity. For example, DE:VAT
is used for a German business entity while DE:LWID45
is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country
. See list of possible values.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
entity_identifier_scheme
. Currently only iso6523-actorid-upis
is supported and is used by default when not provided.
Tip:
If there are additional entity identifiers for the customer not associated with the vat_number
, they can be provided as the entity_identifiers[]
array.
true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site. true
or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country
). When set to false
, the customer is not e-invoiced even if e-invoicing is enabled for their country.
Tip:
It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.
Assign Primary or Backup payment role or unassign role for the payment source based on the preference for the payment collection.
Adds the required contact to a customer. You can give the First Name, Last Name, Email ID and more details as input parameters to add them under the desired customer.
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.
Deletes a particular contact for a customer. You can delete a contact by giving the Contact ID as the input parameter.
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.
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.
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.
This API copies a customer object from one site to another. The destination site (the site to which the customer is copied) is specified by the path parameter {site}
; whereas, the source site (the site from which the customer is copied) is specified by the query parameter from_site
.
Prerequisites
preferred_currency_code
must be enabled in the destination site. 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.
billing_month
, together with billing_date
, specify, for this customer, the day of the year when the renewals of all the year-based subscriptions take place.
For example, the renewals happen on 15th July when billing_month
is 7
and billing_date
is 15
.
Applicable when Calendar Billing (with customer-specific billing date support) is enabled and billing_date_mode
is manually_set
.
This API moves a customer's payment methods, subscriptions, invoices, credit notes, transactions, unbilled charges, and orders to another customer. Events and email logs will not be moved. The API execution is asynchronous.
Establish a hierarchical relationship between customers. The path parameter customer_id
identifies the child in this relationship.
Both parent and child customers must be part of the same business entity.
For the use_default_hierarchy_settings
, parent_account_access
, and child_account_access
parameters below, the term "parent" usually refers to the customer with the ID payment_owner_id
. However, if the payment_owner_id
is the same as the child's ID ({customer_id}
), the "parent" is identified by parent_id
.
Decides if Chargebee should apply settings from the Chargebee Billing UI or from this API request.
true
: Chargebee uses settings configured in the Chargebee Billing UI.false
: Settings provided in the parent_account_access
and child_account_access
parameters are applied.When the customer is part of an account hierarchy, this operation updates the access privileges that both the customer and its parent have to the customer's data.
The term "parent" usually refers to the customer with the ID payment_owner_id
. However, if the payment_owner_id
is the same as the child's ID (given by the path parameter), the "parent" is identified by parent_id
.
You cannot use this endpoint to change the parent_id
, invoice_owner_id
or payment_owner_id
for the customer. To change them, unlink the customer and then call Link a customer with the updated values.
Decides if Chargebee should apply settings from the Chargebee Billing UI or from this API request.
true
: Chargebee removes existing settings stored in the parent_account_access
and child_account_access
attributes of the customer. The settings configured in the Chargebee Billing UI apply for the customer.false
: Chargebee replaces existing settings stored in the parent_account_access
and child_account_access
parameters with those passed in this API call. If any of those parameters are not passed, they remain unchanged for the customer.