Customers - Chargebee Data Catalog

The customer table represents an individual or organization that subscribes to your products or services. It includes key details such as the customer's ID, name, contact information, and any custom fields you want to associate with them. The customer table is linked to subscriptions, payment methods, and billing addresses.

Related Tables

Tables referencing customers.id

invoices quotes subscription_mrr_changes credit_notes quote_line_items customer_custom_fields subscription_mrr_daily_summary payment_sources invoice_line_items orders subscription_mrr_monthly_summary credit_note_line_items transactions subscriptions

Columns

id string, not null

Primary Key

The unique identifier of the customer table. You have the option to specify this value when creating a customer. If not specified, Chargebee automatically generates a unique identifier.

business_entity_id string, null

Foreign Key business_entities.id

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

active_id string, null

allow_direct_debit boolean, not null, default=false

Whether the customer can pay via Direct Debit

auto_close_invoices boolean, null

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 field is also available at the subscription level which takes precedence.

auto_collection string, not null, default=on

When the customer has a payment_method of type card, this field determines whether to automatically charge the card whenever an invoice status is payment_due.

backup_payment_source_id string, null

The identifier of the customer's backup payment source.

billing_address_city string, null

The name of the city.

billing_address_company string, null

The company name.

billing_address_country string, null

The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

billing_address_email string, null

The email address.

billing_address_first_name string, null

The first name of the billing contact.

billing_address_last_name string, null

The last name of the billing contact.

billing_address_line1 string, null

Address line 1

billing_address_line2 string, null

Address line 2

billing_address_line3 string, null

Address line 3

billing_address_phone string, null

The phone number.

billing_address_state string, null

State or Province

billing_address_state_code string, null

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).

billing_address_validation_status string, null, default=not_validated

The address verification status.

billing_address_zip string, null

Zip or postal code. The number of characters is validated according to the rules specified here.

billing_date null

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 tables where the item_type is set to plan and period_unit is set to month and year respectively.

billing_date_mode string, null

Indicates whether this customer's billing_date and billing_month values were changed via the Change billing date table.

billing_day_of_week string, null

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.

billing_day_of_week_mode string, null

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_month null

Specifies the renewal month for subscriptions on year-based plans. Year-based plans are item_price tables where item_type is set to plan and period_unit is set to year.

business_customer_without_vat_number boolean, null

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

channel string, null

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

child_account_access_portal_download_invoices string, null

Determines the child’s access to its own invoices in the Self-Serve Portal.

child_account_access_portal_edit_subscriptions string, null

Determines the child’s access to its own subscriptions in the Self-Serve Portal.

child_account_access_send_invoice_emails boolean, null

Determines whether the child account receives email notifications for its invoices.

child_account_access_send_payment_emails boolean, null

Determines whether the child account receives email notifications for payment-related activities for its invoices.

child_account_access_send_subscription_emails boolean, null

Determines whether the child account receives email notifications for its subscriptions.

client_profile_id string, null

The Avalara client profile ID assigned to the customer.

company string, null

Company name of the customer.

consolidated_invoicing boolean, null

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 field is applicable only when Consolidated Invoicing is enabled.

created_at timestamp, not null

Timestamp indicating when this customer table is created.

created_from_ip string, null

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:

Data Import: When importing customer records into the table, include the customer’s IP address in a specified column for Chargebee to capture it.
Checkout: For customer records created through Chargebee Checkout, Chargebee automatically captures the IP address of the customer.
UI: When creating a customer record via the Chargebee Billing UI, this field is not relevant and the value must be ignored.

customer_type string, null

Indicates the Avalara customer type.

einvoicing_method string, null

Determines whether to send e-invoice manually or automatic.

email string, null

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

entity_code string, null

The customer's exemption category for USA and Canada. This field is applicable if you use Chargebee's AvaTax for Sales integration.

entity_identifier_scheme string, null

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.

entity_identifier_standard string, null, default=iso6523-actorid-upis

The standard used for specifying the entity_identifier_scheme. Currently only iso6523-actorid-upis is supported and is used by default when not provided.

exempt_number string, null

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.

exemption_details string, null

first_name string, null

First name of the customer

fraud_flag string, null

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

invoice_notes string, null

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

is_einvoice_enabled boolean, null

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.

is_location_valid boolean, null

When the customer uses a card payment source, this field specifies whether the country of the customer and the card issuer are the same.

The table compares the following three location indicators:

The card issuer’s country.
The billing_address.country.
The country to which created_from_ip belongs.

When all three are the same, this field is set to true; otherwise, it is set to false.

last_name string, null

Last name of the customer

locale string, null

Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale field, Chargebee will use your site's default language for customer communication.

meta_data string, null

net_term_days not null, default=0

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

offline_payment_method string, null

The preferred offline payment method for the customer.

parent_account_access_portal_download_child_invoices string, null

Determines the parent's access to the child's invoices in the Self-Serve Portal.

parent_account_access_portal_edit_child_subscriptions string, null

Determines the parent's access to the child's subscriptions in the Self-Serve Portal.

parent_account_access_send_invoice_emails boolean, null

Determines whether the parent receives email notifications for the child's invoices.

parent_account_access_send_payment_emails boolean, null

Determines whether, the parent receives email notifications for payment-related activities on the child's invoices.

parent_account_access_send_subscription_emails boolean, null

Determines whether the parent receives email notifications for the child's subscriptions.

payment_method_gateway string, null

Name of the gateway the payment method is associated with.

payment_method_gateway_account_id string, null

The gateway account this payment method is stored with.

payment_method_reference_id string, null

The reference id. In the case of Amazon and PayPal this will be the 'billing agreement id'. For GoCardless direct debit this will be 'mandate id'. In the case of card payments this will be the identifier provided by the gateway/card vault for the specific payment method table.
Note: This is not the one time temporary token provided by gateways like Stripe.

payment_method_status string, null, default=valid

Current status of the payment source.

payment_method_type string, null

Type of payment source

phone string, null

Phone number of the customer

pii_cleared string, null, default=active

Indicates whether this customer's personal information has been cleared

preferred_currency_code string, null

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

primary_payment_source_id string, null

The identifier of the customer's primary payment source

registered_for_gst boolean, null

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.

relationship_invoice_owner_id string, null

The id of the customer who receives the invoice for charges incurred by the customer. This ID must match either this customer or one of its ancestors.

relationship_parent_id string, null

The id of the immediate parent of this customer under account hierarchy. If the customer is the root of the hierarchy, this field isn't returned.

relationship_payment_owner_id string, null

The id of the customer responsible for paying the invoices for this customer. This ID must match either this customer's ID or the invoice_owner_id.

resource_version long, null

Version number of this table. The resource_version is updated with a new timestamp in milliseconds for every change made to the table. This field is present only if the table was updated after 2016-09-28.

taxability string, null, default=taxable

Specifies if the customer is liable for tax

updated_at timestamp, null

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

use_default_hierarchy_settings boolean, null, 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 string, null

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.

vat_number_prefix string, null

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.

vat_number_status string, null

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

vat_number_validated_time timestamp, null

Returns the recent VAT number validation time.

Sample Queries

List Transactions Needing Attention

This query retrieves all transactions with a status of needs_attention along with relevant details from the customers and subscriptions tables.

copy

Click to Copy

      SELECT
  t.id AS transaction_id,
  t.currency_code,
  t.amount,
  t.id_at_gateway,
  t.status AS transaction_status,
  c.id AS customer_id,
  c.name AS customer_name,
  c.email AS customer_email,
  s.id AS subscription_id,
  s.status AS subscription_status
FROM
  transactions t
  LEFT JOIN customers c ON t.customer_id = c.id
  LEFT JOIN subscriptions s ON t.subscription_id = s.id
WHERE
  t.status = 'needs_attention';

Paused Subscriptions

Retrieves a list of paused subscriptions along with customer info. pause_date is the date/time when the subscription was paused. resume_date is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.

copy

Click to Copy

      SELECT
  s.id AS subscription_id,
  s.status AS subscription_status,
  s.pause_date AS subscription_pause_date,
  s.resume_date AS subscription_pause_date,
  c.first_name AS customer_first_name,
  c.last_name AS customer_last_name,
  c.email AS customer_email,
  c.phone AS customer_phone
FROM
  subscriptions s
  JOIN customers c ON s.customer_id = c.id
WHERE
  s.status = 'paused';