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_address and vat_number and replaces them with values from the request.
Sites created on or after March 1, 2014: updating the card doesn't change the billing_address and vat_number.

Sample CustomerJSON

Customers attributes

required, string, max chars=50

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.)

first_name

optional, string, max chars=150

First name of the customer

last_name

optional, string, max chars=150

Last name of the customer

optional, string, max chars=70

Email of the customer. Configured email notifications will be sent to this email.

phone

optional, string, max chars=50

Phone number of the customer

company

optional, string, max chars=250

Company name of the customer.

vat_number

optional, string, max chars=20

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 .

auto_collection

required, enumerated string, default=on

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.

Chargebee automatically charges the card for invoices that enter payment_due status .

off

Automatic charging is disabled; manual payment is required for due invoices.

offline_payment_method

optional, enumerated string

The preferred offline payment method for the customer.

no_preference

No Preference

cash

Cash

check

Check

bank_transfer

Bank Transfer

ach_credit

ACH Credit

net_term_days

required, integer, default=0

The number of days within which the customer has to make payment for the invoice.

vat_number_validated_time

optional, timestamp(UTC) in seconds

Returns the recent VAT number validation time.

vat_number_status

optional, enumerated string

Represents the VAT validation status. This is applicable if you have configured EU, UK or Australian taxes and the VAT number validation is enabled.

valid

If the given VAT number is valid.

invalid

If the given VAT number is invalid.

not_validated

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.

undetermined

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.

allow_direct_debit

required, boolean, default=false

Whether the customer can pay via Direct Debit

is_location_valid

optional, boolean

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_ip belongs.
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 to false.

created_at

required, timestamp(UTC) in seconds

Timestamp indicating when this customer resource is created.

created_from_ip

optional, string, max chars=50

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 customer resource through the API, you must include the customer's IP address in a custom HTTP request header (chargebee-request-origin-ip) for Chargebee to capture it.
Checkout: For customer resources created through Chargebee Checkout, Chargebee automatically captures the IP address of the customer.
UI: When creating a customer resource via the Chargebee Billing UI, this field is not relevant and the value must be ignored.

exemption_details

optional, jsonarray

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 .

taxability

optional, enumerated string, default=taxable

Specifies if the customer is liable for tax

taxable

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.

exempt

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_code or exempt_number attributes if you use Chargebee's AvaTax for Sales or specify exemption_details attribute if you use Chargebee's AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.

entity_code

optional, enumerated string

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

exempt_number

optional, string, max chars=100

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 .

resource_version

optional, long

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.

updated_at

optional, timestamp(UTC) in seconds

Timestamp indicating when this customer was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.

locale

optional, string, max chars=50

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.

billing_date

optional, integer, min=1, max=31

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_date is set to 15, month-based renewals occur on the 15th of the month. It's important to note that if the value is set to 31, renewals align with the last day of the month. Additionally, in February, a billing_date of 29, 30, or 31 aligns renewals for the last day of February.
Year-based subscriptions: A billing_date of 15 and a billing_month of 7 schedules the renewal on the 15th of July.

billing_month

optional, integer, min=1, max=12

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.

billing_date_mode

optional, enumerated string

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 .

using_defaults

billing_date and billing_month are fixed as per Chargebee site settings and not modifiable via API.

manually_set

billing_date and billing_month can be adjusted via API.

billing_day_of_week

optional, enumerated string

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

Sunday

monday

Monday

tuesday

Tuesday

wednesday

Wednesday

thursday

Thursday

friday

Friday

saturday

Saturday

billing_day_of_week_mode

optional, enumerated string

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.

using_defaults

Billing date is set based on defaults configured.

manually_set

Billing date is specifically set (default configuration is overridden)

pii_cleared

optional, enumerated string, default=active

Indicates whether this customer's personal information has been cleared

active

Active

scheduled_for_clear

Scheduled For Clear

cleared

Cleared

auto_close_invoices

optional, boolean

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.

channel

optional, enumerated string

The subscription channel this object originated from and is maintained in.

web

The object was created (and is maintained) for the web channel directly in Chargebee via API or UI.

app_store

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.

play_store

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.

active_id

optional, string, max chars=50

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.

fraud_flag

optional, enumerated string

Indicates whether or not the customer has been identified as fraudulent.

safe

The customer has been marked as safe

suspicious

The customer has been identified as potentially fraudulent by the gateway

fraudulent

The customer has been marked as fraudulent

primary_payment_source_id

optional, string, max chars=40

The identifier of the customer's primary payment source

backup_payment_source_id

optional, string, max chars=40

The identifier of the customer's backup payment source .

invoice_notes

optional, string, max chars=2000

A note for the customer that appears on all their invoice PDFs. This is one of several notes displayed on the invoice PDF.

business_entity_id

optional, string, max chars=50

The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.

preferred_currency_code

optional, string, max chars=3

Note Applicable only when the Multi-Currency feature is enabled.

Specifies the customer's preferred currency in ISO 4217 format.

promotional_credits

required, in cents, min=0

The balance of promotional credits available to the customer.

unbilled_charges

required, in cents, min=0

Total unbilled charges for this customer

refundable_credits

required, in cents, min=0

Refundable credits balance of this customer

excess_payments

required, in cents, min=0

Total unused payments associated with the customer. These are automatically applied to new invoices subject to limits set at the site level which can be overridden for subscriptions via subscription.billing_override.

Constraints

When multiple currencies are enabled, this value is the excess payments balance for the customer's preferred currency. In other words, this value is the same as balances[i].excess_payments where balances[i].currency_code is the same as the preferred_currency_code.

is_einvoice_enabled

optional, boolean

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.

einvoicing_method

optional, enumerated string

Determines whether to send e-invoice manually or automatic.

automatic

Use this value to send e-invoice every time an invoice or credit note is created.

manual

When manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.

site_default

The default value of the site which can be overridden at the customer level.

meta_data

optional, jsonobject

A collection of key-value pairs that provides extra information about the customer.

Note: There's a character limit of 65,535.

Learn more .

deleted

required, boolean

Indicates that this resource has been deleted when the value is true .

registered_for_gst

optional, boolean

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.

consolidated_invoicing

optional, boolean

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.

customer_type

optional, enumerated string

Note Applicable only when the Chargebee's AvaTax for Communications integration is enabled.

Indicates the Avalara customer type .

residential

The customer is an individual user.

business

The customer represents a business.

senior_citizen

The customer is an individual that meets the jurisdiction requirements to be considered a senior citizen and qualifies for tax breaks.

industrial

The customer is an industrial business.

business_customer_without_vat_number

optional, boolean

Confirms that a customer is a valid business without an EU/UK VAT number.

client_profile_id

optional, string, max chars=50

Note Applicable only when the Chargebee's AvaTax for Communications integration is enabled.

The Avalara client profile ID assigned to the customer.

use_default_hierarchy_settings

optional, boolean, default=true

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.

vat_number_prefix

optional, string, max chars=10

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.

entity_identifier_scheme

optional, string, max chars=50

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.

entity_identifier_standard

optional, string, default=iso6523-actorid-upis, max chars=50

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

optional, billing_address

Billing address for a customer.

referral_urls

optional, list of referral_url

List of referral urls for the customer (if applicable)

contacts

optional, list of contact

contacts

payment_method

optional, payment_method

Primary Payment Source of the customer.

balances

optional, list of customer_balance

The list of balances for this customer.

entity_identifiers

optional, list of entity_identifier

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.

tax_providers_fields

optional, list of tax_providers_field

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.

relationship

optional, relationship

The account hierarchy relationship that the customer is part of.

parent_account_access

optional, parent_account_access

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 .

child_account_access

optional, child_account_access

When the customer is part of an account hierarchy , this attribute defines the level of access that the customer has to its own information.