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 CustomerJSON
Customers attributes
Email of the customer. Configured email notifications will be sent to this email.
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
.
Whether payments needs to be collected automatically for this customer
Whenever an invoice is created, an automatic attempt to charge the customer's payment method is made.
Automatic collection of charges will not be made. All payments must be recorded offline.
The preferred offline payment method for the customer.
No Preference
Cash
Check
Bank Transfer
ACH Credit
The number of days within which the customer has to make payment for the invoice.
Returns the recent VAT number validation time.
Represents the VAT validation status. This is applicable if you have configured EU, UK or Australian taxes and the VAT number validation is enabled.
If the given VAT number is valid.
If the given VAT number is invalid.
This status is only applicable for countries in European Zone. This is applicable when both the customer's billing address and the organization's address should be of the same European Zone and EU tax should be configured with the "Also validate VAT Number for Country of Business" option in the disabled status.
When Chargebee is not able to validate the VAT number it is stored as 'undetermined'. This can occur due to reasons like service outage etc. VAT numbers with 'undetermined' status will be in queue for validation on daily basis.
Customer location is validated based on IP address and Card issuing country. If the location is valid, it returns True. If not, it returns False. Applicable only for EU, New Zealand and Australia.
Timestamp indicating when this customer resource is created.
The IP address of the customer. Used primarily for referral integrations and EU/UK VAT validation.
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 .
Specifies if the customer is liable for tax
Computes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that's not available either, the tax is taken as zero.
- Customer is exempted from tax. When using Chargebee's native Taxes feature or when using the TaxJar integration, no other action is needed.
- However, when using our Avalara integration, optionally, specify
entity_codeorexempt_numberattributes if you use Chargebee's AvaTax for Sales or specifyexemption_detailsattribute if you use Chargebee's AvaTax for Communications integration. Tax may still be applied by Avalara for certain values ofentity_code/exempt_number/exemption_detailsbased on the state/region/province of the taxable address.
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration .
Federal government
State government
Tribe/Status Indian/Indian Band
Foreign diplomat
Charitable or benevolent organization
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 .
Version number of this resource. The resource_version
is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
Timestamp indicating when this customer was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.
Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication.
Applicable when calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the monthly and yearly subscriptions of this customer will be aligned to this date.
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.
Billing date is set based on defaults configured.
Billing date is specifically set (default configuration is overridden)
Applicable when calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the weekly subscriptions of this customer will be aligned to this week day.
Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
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.
Billing date is set based on defaults configured.
Billing date is specifically set (default configuration is overridden)
Indicates whether this customer's personal information has been cleared
Active
Scheduled For Clear
Cleared
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.
The subscription channel this object originated from and is maintained in.
The object was created (and is maintained) for the web channel directly in Chargebee via API or UI.
The object data is synchronized with data from in-app subscription(s) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.
The object data is synchronized with data from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.
In-App Subscriptions is currently in early access. Contact eap@chargebee.com for more information.
This attribute is only valid for product catalog 2.0 as the Multiple Business Entity features can only be enabled for product catalog 2.0.
Indicates whether or not the customer has been identified as fraudulent.
The customer has been marked as safe
The customer has been identified as potentially fraudulent by the gateway
The customer has been marked as fraudulent
Backup payment source for the customer. Used to collect payment if primary payment source fails.
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.
The ID of the business entity created for the site. For Product Catalog 1.0, all the site data is tied to this business entity.
Note
Multiple Business Entities is a feature available only on Product Catalog 2.0.
The currency code of the customer's preferred currency (ISO 4217 format). Applicable if the Multicurrency feature is enabled.
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.
Determines whether to send einvoice manually or automatic.
Use this value to send e-invoice every time an invoice or credit note is created.
When manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.
The default value of the site which can be overridden at the customer level.
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.
Indicates the type of the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.
When the purchase is made by a customer for home use
When the purchase is made at a place of business
When the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaks
When the purchase is made by an industrial business
Confirms that a customer is a valid business without an EU/UK VAT number.
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.
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.
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.
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.