API Version
Product Catalog
Library

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 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 GET

https://{site}.chargebee.com/api/v2/customers

Model Class

id
string, max chars=50
Identifier of the customer.
first_name
optional, string, max chars=150
First name of the customer
last_name
optional, string, max chars=150
Last name of the customer
email
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
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.


Possible values are
onChargebee automatically charges the card for invoices that enter payment_due status.offAutomatic charging is disabled; manual payment is required for due invoices.
Show all values[+]
offline_payment_method
optional, enumerated string
The preferred offline payment method for the customer.
Possible values are
no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transfer
Show all values[+]
net_term_days
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.
Possible values are
validIf the given VAT number is valid.invalidIf the given VAT number is invalid.not_validatedThis 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.undeterminedWhen 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.
Show all values[+]
allow_direct_debit
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
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
Possible values are
taxableComputes 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.
Show all values[+]
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.
Possible values are
aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat
Show all values[+]
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.

Possible values are
using_defaultsbilling_date and billing_month are fixed as per Chargebee site settings and not modifiable via API.manually_setbilling_date and billing_month can be adjusted via API.
Show all values[+]
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.
Possible values are
sundaySundaymondayMondaytuesdayTuesdaywednesdayWednesday
Show all values[+]
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.
Possible values are
using_defaultsBilling date is set based on defaults configured.manually_setBilling date is specifically set (default configuration is overridden)
Show all values[+]
pii_cleared
optional, enumerated string, default=active
Indicates whether this customer's personal information has been cleared
Possible values are
activeActivescheduled_for_clearScheduled For ClearclearedCleared
Show all values[+]
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.
Possible values are
webThe object was created (and is maintained) for the web channel directly in Chargebee via API or UI.app_storeThe 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_storeThe 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.
Show all values[+]
active_id
optional, string, max chars=50
This attribute represents the identifier of the most recent version of the customers resource. When interacting with our API, the active_id ensures you're always referencing the current and most up-to-date version of the customers resource. This mechanism is in place to maintain consistent external references and data integrity across business entity changes and updates. active_id is present on the resource after the resource is transferred to the destination business entity and it will refer to the most recent version of the resource. Learn more about the customer transfer feature and setup.

Note:

  • If active_id and id of the customer are the same, then it is the most recent version of the resource.
  • If active_id and id of the customer are different, then it is a transferred resource.
  • If active_id is not present, then the resource is not transferred and there are no business entity-related changes.

fraud_flag
optional, enumerated string
Indicates whether or not the customer has been identified as fraudulent.
Possible values are
safeThe customer has been marked as safesuspiciousThe customer has been identified as potentially fraudulent by the gatewayfraudulentThe customer has been marked as fraudulent
Show all values[+]
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
in cents, min=0
The balance of promotional credits available to the customer.
unbilled_charges
in cents, min=0
Total unbilled charges for this customer
refundable_credits
in cents, min=0
Refundable credits balance of this customer
excess_payments
in cents, min=0
Total unused payments associated with the customer
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.
Possible values are
automaticUse this value to send e-invoice every time an invoice or credit note is created.manualWhen manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.site_defaultThe default value of the site which can be overridden at the customer level.
Show all values[+]
deleted
boolean
Indicates that this resource has been deleted.
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.

Possible values are
residentialThe customer is an individual user.businessThe customer represents a business.senior_citizenThe customer is an individual that meets the jurisdiction requirements to be considered a senior citizen and qualifies for tax breaks.industrialThe customer is an industrial business.
Show all values[+]
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
Show attributes [+]
optional, billing_address
Billing address for a customer.
referral_urls
Show attributes [+]
optional, list of referral_url
List of referral urls for the customer (if applicable)
optional, list of contact
contacts
payment_method
Show attributes [+]
optional, payment_method
Primary Payment Source of the customer.
optional, list of customer_balance
The list of balances for this customer
entity_identifiers
Show attributes [+]
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.
relationship
Show attributes [+]
optional, relationship
The account hierarchy relationship that the customer is part of.
parent_account_access
Show attributes [+]
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
Show attributes [+]
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.
id id
string, max chars=50
Identifier of the customer.
first_name first_name
optional, string, max chars=150
First name of the customer
last_name last_name
optional, string, max chars=150
Last name of the customer
email email
optional, string, max chars=70
Email of the customer. Configured email notifications will be sent to this email.
phone phone
optional, string, max chars=50
Phone number of the customer
company company
optional, string, max chars=250
Company name of the customer.
vat_number 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 auto_collection
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.


offline_payment_method offline_payment_method
optional, enumerated string
The preferred offline payment method for the customer.
net_term_days net_term_days
integer, default=0
The number of days within which the customer has to make payment for the invoice.
vat_number_validated_time vat_number_validated_time
optional, timestamp(UTC) in seconds
Returns the recent VAT number validation time.
vat_number_status 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.
allow_direct_debit allow_direct_debit
boolean, default=false
Whether the customer can pay via Direct Debit
is_location_valid 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 created_at
timestamp(UTC) in seconds
Timestamp indicating when this customer resource is created.
created_from_ip 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 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 taxability
optional, enumerated string, default=taxable
Specifies if the customer is liable for tax
entity_code 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.
exempt_number 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 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 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 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 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 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 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.

billing_day_of_week 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.
billing_day_of_week_mode 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.
pii_cleared pii_cleared
optional, enumerated string, default=active
Indicates whether this customer's personal information has been cleared
auto_close_invoices 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 channel
optional, enumerated string
The subscription channel this object originated from and is maintained in.
active_id active_id
optional, string, max chars=50
This attribute represents the identifier of the most recent version of the customers resource. When interacting with our API, the active_id ensures you're always referencing the current and most up-to-date version of the customers resource. This mechanism is in place to maintain consistent external references and data integrity across business entity changes and updates. active_id is present on the resource after the resource is transferred to the destination business entity and it will refer to the most recent version of the resource. Learn more about the customer transfer feature and setup.

Note:

  • If active_id and id of the customer are the same, then it is the most recent version of the resource.
  • If active_id and id of the customer are different, then it is a transferred resource.
  • If active_id is not present, then the resource is not transferred and there are no business entity-related changes.

fraud_flag fraud_flag
optional, enumerated string
Indicates whether or not the customer has been identified as fraudulent.
primary_payment_source_id primary_payment_source_id
optional, string, max chars=40
The identifier of the customer's primary payment source
backup_payment_source_id backup_payment_source_id
optional, string, max chars=40
The identifier of the customer's backup payment source.
invoice_notes 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 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 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 promotional_credits
in cents, min=0
The balance of promotional credits available to the customer.
unbilled_charges unbilled_charges
in cents, min=0
Total unbilled charges for this customer
refundable_credits refundable_credits
in cents, min=0
Refundable credits balance of this customer
excess_payments excess_payments
in cents, min=0
Total unused payments associated with the customer
is_einvoice_enabled 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 einvoicing_method
optional, enumerated string
Determines whether to send e-invoice manually or automatic.
deleted deleted
boolean
Indicates that this resource has been deleted.
registered_for_gst 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 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 customer_type
optional, enumerated string
Note

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

Indicates the Avalara customer type.

business_customer_without_vat_number business_customer_without_vat_number
optional, boolean
Confirms that a customer is a valid business without an EU/UK VAT number.
client_profile_id 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 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 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 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 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.
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.
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 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:

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

Notes

Sample Request
# creates a customer with billing address.
curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d email="john@test.com" \
     -d locale="fr-CA" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"
# creates a customer with bank account.
curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d allow_direct_debit=true \
     -d email="john@test.com" \
     -d bank_account[account_number]="000222222227" \
     -d bank_account[routing_number]="110000000" \
     -d bank_account[bank_name]="US Bank" \
     -d bank_account[account_holder_type]="INDIVIDUAL" \
     -d bank_account[account_type]="SAVINGS" \
     -d bank_account[first_name]="Shay" \
     -d bank_account[last_name]="Liam" \
     -d bank_account[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju"
# creates a customer with card details.
curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d email="john@test.com" \
     -d card[first_name]="Richard" \
     -d card[last_name]="Fox" \
     -d card[number]="4012888888881881" \
     -d card[expiry_month]=10 \
     -d card[expiry_year]=2022 \
     -d card[cvv]="999"
# creates a customer with payment source.
# NOTE :  The parameters paymentMethod[tmp_token] and paymentMethod[reference_id] should not be passed together.
curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d payment_method[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju" \
     -d payment_method[type]="CARD" \
     -d payment_method[reference_id]="cus_I58PkwpAskxXlJ"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "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
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers

Method

id[]
optional, string, max chars=50
Id for the new customer. If not given, this will be auto-generated.
first_name[]
optional, string, max chars=150
First name of the customer.
last_name[]
optional, string, max chars=150
Last name of the customer.
email[]
optional, string, max chars=70
Email of the customer. Configured email notifications will be sent to this email.
preferred_currency_code[]
optional, string, max chars=3
The currency code (ISO 4217 format) of the customer. Applicable if Multicurrency is enabled.
phone[]
optional, string, max chars=50
Phone number of the customer.
company[]
optional, string, max chars=250
Company name of the customer.
auto_collection[]
optional, enumerated string, default=on
Whether payments needs to be collected automatically for this customer.
Possible values are
onWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.offAutomatic collection of charges will not be made. All payments must be recorded offline.
Show all values[+]
net_term_days[]
optional, integer, default=0
The number of days within which the customer has to make payment for the invoice. .
allow_direct_debit[]
optional, boolean, default=false
Whether the customer can pay via Direct Debit.
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.
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.

.
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.
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 an e-invoice manually or automatic.
Possible values are
automaticUse this value to send e-invoice every time an invoice or credit note is created.manualWhen manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.site_defaultThe default value of the site which can be overridden at the customer level.
Show all values[+]
taxability[]
optional, enumerated string, default=taxable
Specifies if the customer is liable for tax.
Possible values are
taxableComputes 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.
Show all values[+]
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.
customer_type[]
optional, enumerated string
Indicates the type of the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Possible values are
residentialWhen the purchase is made by a customer for home usebusinessWhen the purchase is made at a place of businesssenior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaksindustrialWhen the purchase is made by an industrial business
Show all values[+]
client_profile_id[]
optional, string, max chars=50
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
taxjar_exemption_category[]
optional, enumerated string
Indicates the exemption type of the customer. This is applicable only if you use Chargebee’s TaxJar integration.
Possible values are
wholesaleWhole-salegovernmentGovernmentotherOther
Show all values[+]
business_customer_without_vat_number[]
optional, boolean
Confirms that a customer is a valid business without an EU/UK VAT number.
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.
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.
Possible values are
aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat
Show all values[+]
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.
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.
offline_payment_method[]
optional, enumerated string
The preferred offline payment method for the customer.
Possible values are
no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transfer
Show all values[+]
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.
consolidated_invoicing[]
optional, boolean

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.

.
token_id[]
optional, string, max chars=40
The Chargebee payment token generated by Chargebee JS.
business_entity_id[]
optional, string, max chars=50
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.

.
invoice_notes[]
optional, string, max chars=2000
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.
card[gateway_account_id]
optional, string, max chars=50
card[first_name]
optional, string, max chars=50
card[last_name]
optional, string, max chars=50
card[number]
required if card provided, string, max chars=1500
card[expiry_month]
required if card provided, integer, min=1, max=12
card[expiry_year]
required if card provided, integer
card[cvv]
optional, string, max chars=520
card[billing_addr1]
optional, string, max chars=150
card[billing_addr2]
optional, string, max chars=150
card[billing_city]
optional, string, max chars=50
card[billing_state_code]
optional, string, max chars=50
card[billing_state]
optional, string, max chars=50
card[billing_zip]
optional, string, max chars=20
card[billing_country]
optional, string, max chars=50
card[additional_information]
optional, jsonobject
bank_account[gateway_account_id]
optional, string, max chars=50
bank_account[iban]
optional, string, min chars=10, max chars=50
bank_account[first_name]
optional, string, max chars=150
bank_account[last_name]
optional, string, max chars=150
bank_account[company]
optional, string, max chars=250
bank_account[email]
optional, string, max chars=70
bank_account[phone]
optional, string, max chars=50
bank_account[bank_name]
optional, string, max chars=100
bank_account[account_number]
optional, string, min chars=4, max chars=17
bank_account[routing_number]
optional, string, min chars=3, max chars=9
bank_account[bank_code]
optional, string, max chars=20
bank_account[account_type]
optional, enumerated string
Possible values are
checkingChecking AccountsavingsSavings Accountbusiness_checkingBusiness Checking AccountcurrentCurrent Account
Show all values[+]
bank_account[account_holder_type]
optional, enumerated string
Possible values are
individualIndividual Account.companyCompany Account.
Show all values[+]
bank_account[echeck_type]
optional, enumerated string
Possible values are
webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.
Show all values[+]
bank_account[issuing_country]
optional, string, max chars=50
bank_account[swedish_identity_number]
optional, string, min chars=10, max chars=12
bank_account[billing_address]
optional, jsonobject
payment_method[type]
optional, enumerated string
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
Show all values[+]
payment_method[gateway_account_id]
optional, string, max chars=50
payment_method[reference_id]
optional, string, max chars=200
payment_method[tmp_token]
required if reference_id not provided, string, max chars=65k
payment_method[issuing_country]
optional, string, max chars=50
payment_method[additional_information]
optional, jsonobject
payment_intent[id]
optional, string, max chars=150
payment_intent[gateway_account_id]
required if payment intent token provided, string, max chars=50
payment_intent[gw_token]
optional, string, max chars=65k
payment_intent[payment_method_type]
optional, enumerated string
Possible values are
cardcardidealidealsofortsofortbancontactbancontact
Show all values[+]
payment_intent[reference_id]
optional, string, max chars=65k
payment_intent[additional_information]
optional, jsonobject
billing_address[first_name]
optional, string, max chars=150
billing_address[last_name]
optional, string, max chars=150
billing_address[email]
optional, string, max chars=70
billing_address[company]
optional, string, max chars=250
billing_address[phone]
optional, string, max chars=50
billing_address[line1]
optional, string, max chars=150
billing_address[line2]
optional, string, max chars=150
billing_address[line3]
optional, string, max chars=150
billing_address[city]
optional, string, max chars=50
billing_address[state_code]
optional, string, max chars=50
billing_address[state]
optional, string, max chars=50
billing_address[zip]
optional, string, max chars=20
billing_address[country]
optional, string, max chars=50
billing_address[validation_status]
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
Show all values[+]
entity_identifiers[id][0..n]
optional, string, max chars=40
entity_identifiers[scheme][0..n]
optional, string, max chars=50
entity_identifiers[value][0..n]
optional, string, max chars=50
entity_identifiers[standard][0..n]
optional, string, default=iso6523-actorid-upis, max chars=50
customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

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.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode first_name[is]="John" \
     --data-urlencode last_name[is]="Doe" \
     --data-urlencode email[is]="john@test.com"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "customer": {
                "allow_direct_debit": false,
                "auto_collection": "on",
                "card_status": "no_card",
                "created_at": 1517505747,
                "deleted": false,
                "email": "john@test.com",
                "excess_payments": 0,
                "first_name": "John",
                "id": "__test__KyVnHhSBWlC1T2cj",
                "last_name": "Doe",
                "net_term_days": 0,
                "object": "customer",
                "pii_cleared": "active",
                "preferred_currency_code": "USD",
                "promotional_credits": 0,
                "refundable_credits": 0,
                "resource_version": 1517505747000,
                "taxability": "taxable",
                "unbilled_charges": 0,
                "updated_at": 1517505747
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/customers

Method

limit[]
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset[]
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
include_deleted[]
optional, boolean, default=false
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
sort_by[<sort-order>]
optional, string filter
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.
id[<operator>]
optional, string filter
Identifier of the customer. Possible values are :
Supported operators : is, is_not, starts_with, in, not_in

Example id[is] = "9bsvnHgsvmsI"
id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
id[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
first_name[<operator>]
optional, string filter
First name of the customer. Possible values are :
Supported operators : is, is_not, starts_with, is_present

Example first_name[is] = "John"
first_name[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
first_name[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
first_name[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
first_name[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
last_name[<operator>]
optional, string filter
Last name of the customer. Possible values are :
Supported operators : is, is_not, starts_with, is_present

Example last_name[is] = "Clint"
last_name[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
last_name[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
last_name[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
last_name[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
email[<operator>]
optional, string filter
Email of the customer. Configured email notifications will be sent to this email. Possible values are :
Supported operators : is, is_not, starts_with, is_present

Example email[is] = "john@test.com"
email[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
email[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
email[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
email[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
company[<operator>]
optional, string filter
Company name of the customer. Possible values are :
Supported operators : is, is_not, starts_with, is_present

Example company[is] = "Globex Corp"
company[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
company[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
company[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
company[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
phone[<operator>]
optional, string filter
Phone number of the customer. Possible values are :
Supported operators : is, is_not, starts_with, is_present

Example phone[is] = "(541) 754-3010"
phone[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
phone[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
phone[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
phone[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
auto_collection[<operator>]
optional, enumerated string filter
Whether payments needs to be collected automatically for this customer. Possible values are : on, off
Supported operators : is, is_not, in, not_in

Example auto_collection[is] = "on"
auto_collection[is][operator]
optional, enumerated string filter
Possible values are : on, off
Supported operators :

Example
auto_collection[is_not][operator]
optional, enumerated string filter
Possible values are : on, off
Supported operators :

Example
auto_collection[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
auto_collection[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
taxability[<operator>]
optional, enumerated string filter
Specifies if the customer is liable for tax. Possible values are : taxable, exempt
Supported operators : is, is_not, in, not_in

Example taxability[is] = "taxable"
taxability[is][operator]
optional, enumerated string filter
Possible values are : taxable, exempt
Supported operators :

Example
taxability[is_not][operator]
optional, enumerated string filter
Possible values are : taxable, exempt
Supported operators :

Example
taxability[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
taxability[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
created_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating when this customer resource is created. Possible values are :
Supported operators : after, before, on, between

Example created_at[after] = "1435054328"
created_at[after][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
created_at[before][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
created_at[on][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
created_at[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
updated_at[<operator>]
optional, timestamp(UTC) in seconds filter
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. Possible values are :
Supported operators : after, before, on, between

Example updated_at[after] = "1243545465"
updated_at[after][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
updated_at[before][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
updated_at[on][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
updated_at[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
business_entity_id[<operator>]
optional, string filter
The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer. Possible values are :
Supported operators : is, is_not, starts_with

Example business_entity_id[is] = "business_entity_id"
business_entity_id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
business_entity_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
business_entity_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
offline_payment_method[<operator>]
optional, enumerated string filter
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, custom
Supported operators : is, is_not, in, not_in

Example offline_payment_method[is] = "cash"
offline_payment_method[is][operator]
optional, enumerated string filter
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, custom
Supported operators :

Example
offline_payment_method[is_not][operator]
optional, enumerated string filter
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, custom
Supported operators :

Example
offline_payment_method[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
offline_payment_method[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
auto_close_invoices[<operator>]
optional, enumerated string filter
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, false
Supported operators : is

Example auto_close_invoices[is] = "true"
auto_close_invoices[is][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
channel[<operator>]
optional, enumerated string filter
The subscription channel this object originated from and is maintained in. Possible values are : web, app_store, play_store
Supported operators : is, is_not, in, not_in

Example channel[is] = "APP STORE"
channel[is][operator]
optional, enumerated string filter
Possible values are : web, app_store, play_store
Supported operators :

Example
channel[is_not][operator]
optional, enumerated string filter
Possible values are : web, app_store, play_store
Supported operators :

Example
channel[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
channel[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
relationship[<operator>]
optional, string filter
Parameters for relationship Possible values are :
Supported operators : parent_id, payment_owner_id, invoice_owner_id

Example relationship[parent_id] = "undefined"
relationship[parent_id][operator]
optional, string filter
Immediate parent with whom we will link our new customer(child) Possible values are :
Supported operators : is, is_not, starts_with

Example relationship[parent_id][is] = "future_billing"
relationship[payment_owner_id][operator]
optional, string filter
Parent who is going to pay Possible values are :
Supported operators : is, is_not, starts_with

Example relationship[payment_owner_id][is] = "active1"
relationship[invoice_owner_id][operator]
optional, string filter
Parent who is going to handle invoices Possible values are :
Supported operators : is, is_not, starts_with

Example relationship[invoice_owner_id][is] = "future_billing"
customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card
next_offset next_offset
optional, string, max chars=1000
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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

Retrieves the details of the desired customer. You can use the unique identifier for a particular customer to retrieve the desired details.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlF0Q2dg \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505759,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "David",
        "id": "__test__KyVnHhSBWlF0Q2dg",
        "last_name": "Louis",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505759000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505759
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/customers/{customer-id}

Method

customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

Updates the customer resource. 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.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFGC2di \
     -u {site_api_key}:\
     -d first_name="Denise" \
     -d last_name="Barone" \
     -d locale="fr-CA"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505760,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Denise",
        "id": "__test__KyVnHhSBWlFGC2di",
        "last_name": "Barone",
        "locale": "fr-CA",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505760000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505760
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}

Method

first_name[]
optional, string, max chars=150
First name of the customer.
last_name[]
optional, string, max chars=150
Last name of the customer.
email[]
optional, string, max chars=70
Email of the customer. Configured email notifications will be sent to this email.
preferred_currency_code[]
optional, string, max chars=3
The currency code (ISO 4217 format) of the customer. Applicable if Multicurrency is enabled.
phone[]
optional, string, max chars=50
Phone number of the customer.
company[]
optional, string, max chars=250
Company name of the customer.
auto_collection[]
optional, enumerated string, default=on
Whether payments needs to be collected automatically for this customer.
Possible values are
onWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.offAutomatic collection of charges will not be made. All payments must be recorded offline.
Show all values[+]
allow_direct_debit[]
optional, boolean, default=false
Whether the customer can pay via Direct Debit.
net_term_days[]
optional, integer, default=0
The number of days within which the customer has to make payment for the invoice. .
taxability[]
optional, enumerated string, default=taxable
Specifies if the customer is liable for tax.
Possible values are
taxableComputes 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.
Show all values[+]
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.
customer_type[]
optional, enumerated string
Indicates the type of the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Possible values are
residentialWhen the purchase is made by a customer for home usebusinessWhen the purchase is made at a place of businesssenior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaksindustrialWhen the purchase is made by an industrial business
Show all values[+]
client_profile_id[]
optional, string, max chars=50
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
taxjar_exemption_category[]
optional, enumerated string
Indicates the exemption type of the customer. This is applicable only if you use Chargebee’s TaxJar integration.
Possible values are
wholesaleWhole-salegovernmentGovernmentotherOther
Show all values[+]
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.
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.
Possible values are
aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat
Show all values[+]
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.
offline_payment_method[]
optional, enumerated string
The preferred offline payment method for the customer.
Possible values are
no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transfer
Show all values[+]
invoice_notes[]
optional, string, max chars=2000
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.
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.
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.
fraud_flag[]
optional, enumerated string
Indicates whether or not the customer has been identified as fraudulent.
Possible values are
safeThe customer has been marked as safefraudulentThe customer has been marked as fraudulent
Show all values[+]
consolidated_invoicing[]
optional, boolean

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.

.
customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x
We recently released Payment Sources, which 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

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

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlHEO2eE/update_payment_method \
     -u {site_api_key}:\
     -d payment_method[type]="CARD" \
     -d payment_method[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju" \
     -d payment_method[reference_id]="cus_I58QViSiwuelqF"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "card": {
        "card_type": "visa",
        "created_at": 1517505769,
        "customer_id": "__test__KyVnHhSBWlHEO2eE",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "credit",
        "gateway": "stripe",
        "gateway_account_id": "gw___test__KyVnGlSBWl8M41ju",
        "iin": "******",
        "issuing_country": "US",
        "last4": "1111",
        "masked_number": "************1111",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWlHbr2eJ",
        "powered_by": "not_applicable",
        "resource_version": 1517505769000,
        "status": "valid",
        "updated_at": 1517505769
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505767,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "David",
        "id": "__test__KyVnHhSBWlHEO2eE",
        "last_name": "Young",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__KyVnGlSBWl8M41ju",
            "object": "payment_method",
            "reference_id": "cus_I58QViSiwuelqF/card_1HUy9cJv9j0DyntJNR5sLhy1",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWlHbr2eJ",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505769000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505769
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/update_payment_method

Method

payment_method[type]
required, enumerated string
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
Show all values[+]
payment_method[gateway_account_id]
optional, string, max chars=50
payment_method[reference_id]
optional, string, max chars=200
payment_method[tmp_token]
required if reference_id not provided, string, max chars=65k
payment_method[issuing_country]
optional, string, max chars=50
payment_method[additional_information]
optional, jsonobject
customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

This method is used for updating the billing_address and vat_number attributes of the customer. For updating the other customer attributes use Update Customer API.

During this operation, if billing_address and vat_number are not already present, they’re added. Whereas if present, the existing values are replaced with the new values passed. The only exception here is for entity_identifiers[i] when entity_identifiers[operation][i] is passed as delete.

Note: When an invoice is generated for a customer, the billing address provided for the customer will be stored with the invoice. If the First Name, Last Name, and Company fields do not contain any information under Billing Info, the same will be picked from Customer Details if the same is available there.Please ensure that the VAT number is provided whenever the billing address is updated, as failing to do so will override any existing VAT numbers if new values are not provided.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFY32dl/update_billing_info \
     -u {site_api_key}:\
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "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": 1517505761,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "David",
        "id": "__test__KyVnHhSBWlFY32dl",
        "last_name": "Lewis",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505761000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505761
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/update_billing_info

Method

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

.
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.
business_customer_without_vat_number[]
optional, boolean
Confirms that a customer is a valid business without an EU/UK VAT number.
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 einvoice manually or automatic.
Possible values are
automaticUse this value to send e-invoice every time an invoice or credit note is created.manualWhen manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.site_defaultThe default value of the site which can be overridden at the customer level.
Show all values[+]
billing_address[first_name]
optional, string, max chars=150
billing_address[last_name]
optional, string, max chars=150
billing_address[email]
optional, string, max chars=70
billing_address[company]
optional, string, max chars=250
billing_address[phone]
optional, string, max chars=50
billing_address[line1]
optional, string, max chars=150
billing_address[line2]
optional, string, max chars=150
billing_address[line3]
optional, string, max chars=150
billing_address[city]
optional, string, max chars=50
billing_address[state_code]
optional, string, max chars=50
billing_address[state]
optional, string, max chars=50
billing_address[zip]
optional, string, max chars=20
billing_address[country]
optional, string, max chars=50
billing_address[validation_status]
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
Show all values[+]
entity_identifiers[id][0..n]
optional, string, max chars=40
entity_identifiers[scheme][0..n]
optional, string, max chars=50
entity_identifiers[value][0..n]
optional, string, max chars=50
entity_identifiers[operation][0..n]
optional, enumerated string
Possible values are
createCreates a new entity_identifier for the customer.updateUpdates an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.deleteDeletes an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.
Show all values[+]
entity_identifiers[standard][0..n]
optional, string, default=iso6523-actorid-upis, max chars=50
customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x
This API retrieves all the contacts for a customer.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlCK52cl/contacts \
     -G  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "contact": {
                "email": "jane@test.com",
                "enabled": true,
                "first_name": "Jane",
                "id": "contact___test__KyVnHhSBWlCKq2cn",
                "label": "dev",
                "last_name": "Doe",
                "object": "contact",
                "send_account_email": true,
                "send_billing_email": true
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/customers/{customer-id}/contacts

Method

limit[]
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset[]
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
contact contact
always returned
Resource object representing contact
next_offset next_offset
optional, string, max chars=1000
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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

Assign Primary or Backup payment role or unassign role for the payment source based on the preference for the payment collection.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl4rs2au/assign_payment_role \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__KyVnHhSBWl4te2ax" \
     -d role="PRIMARY"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505720,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__KyVnHhSBWl4rs2au",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWl4tX2aw",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWl4te2ax",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505720000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505720
    },
    "payment_source": {
        "card": {
            "brand": "american_express",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "not_known",
            "iin": "378282",
            "last4": "0005",
            "masked_number": "***********0005",
            "object": "card"
        },
        "created_at": 1517505720,
        "customer_id": "__test__KyVnHhSBWl4rs2au",
        "deleted": false,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
        "id": "pm___test__KyVnHhSBWl4te2ax",
        "object": "payment_source",
        "reference_id": "tok___test__KyVnHhSBWl4tX2aw",
        "resource_version": 1517505720000,
        "status": "valid",
        "type": "card",
        "updated_at": 1517505720
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/assign_payment_role

Method

payment_source_id[]
required, string, max chars=40
Payment source id this role will be assigned to.
role[]
required, enumerated string
Indicates whether the payment source is Primary, Backup, or neither.
Possible values are
primaryPrimarybackupBackupnoneNone
Show all values[+]
customer customer
always returned
Resource object representing customer
payment_source payment_source
always returned
Resource object representing payment_source

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

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.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5C82b2/add_contact \
     -u {site_api_key}:\
     -d contact[first_name]="Jane" \
     -d contact[last_name]="Doe" \
     -d contact[email]="jane@test.com" \
     -d contact[label]="dev" \
     -d contact[enabled]=true \
     -d contact[send_billing_email]=true \
     -d contact[send_account_email]=true
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "contacts": [
            {
                "email": "jane@test.com",
                "enabled": true,
                "first_name": "Jane",
                "id": "contact___test__KyVnHhSBWl5Cy2b4",
                "label": "dev",
                "last_name": "Doe",
                "object": "contact",
                "send_account_email": true,
                "send_billing_email": true
            },
            {..}
        ],
        "created_at": 1517505721,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWl5C82b2",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505721000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505721
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/add_contact

Method

contact[id]
optional, string, max chars=150
contact[first_name]
optional, string, max chars=150
contact[last_name]
optional, string, max chars=150
contact[email]
required, string, max chars=70
contact[phone]
optional, string, max chars=50
contact[label]
optional, string, max chars=50
contact[enabled]
optional, boolean, default=false
contact[send_billing_email]
optional, boolean, default=false
contact[send_account_email]
optional, boolean, default=false
customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

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.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFmo2do/update_contact \
     -u {site_api_key}:\
     -d contact[id]="contact___test__KyVnHhSBWlFnd2dq" \
     -d contact[first_name]="Jane" \
     -d contact[last_name]="Doe" \
     -d contact[email]="jane@test.com" \
     -d contact[label]="dev" \
     -d contact[enabled]=true \
     -d contact[send_billing_email]=true \
     -d contact[send_account_email]=true
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "contacts": [
            {
                "email": "jane@test.com",
                "enabled": true,
                "first_name": "Jane",
                "id": "contact___test__KyVnHhSBWlFnd2dq",
                "label": "dev",
                "last_name": "Doe",
                "object": "contact",
                "send_account_email": true,
                "send_billing_email": true
            },
            {..}
        ],
        "created_at": 1517505762,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWlFmo2do",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505762000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505762
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/update_contact

Method

contact[id]
required, string, max chars=150
contact[first_name]
optional, string, max chars=150
contact[last_name]
optional, string, max chars=150
contact[email]
optional, string, max chars=70
contact[phone]
optional, string, max chars=50
contact[label]
optional, string, max chars=50
contact[enabled]
optional, boolean, default=false
contact[send_billing_email]
optional, boolean, default=false
contact[send_account_email]
optional, boolean, default=false
customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

Deletes a particular contact for a customer. You can delete a contact by giving the Contact ID as the input parameter.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl9ta2cA/delete_contact \
     -u {site_api_key}:\
     -d contact[id]="contact___test__KyVnHhSBWl9uT2cC"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505739,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWl9ta2cA",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505739000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505739
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/delete_contact

Method

contact[id]
required, string, max chars=150
customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

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.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDEl2cz/record_excess_payment \
     -u {site_api_key}:\
     -d comment="Check payment received from John" \
     -d transaction[amount]=500 \
     -d transaction[date]=1600968152 \
     -d transaction[payment_method]="CHECK"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "balances": [
            {
                "balance_currency_code": "USD",
                "currency_code": "USD",
                "excess_payments": 500,
                "object": "customer_balance",
                "promotional_credits": 0,
                "refundable_credits": 0,
                "unbilled_charges": 0
            },
            {..}
        ],
        "card_status": "no_card",
        "created_at": 1517505752,
        "deleted": false,
        "excess_payments": 500,
        "first_name": "John",
        "id": "__test__KyVnHhSBWlDEl2cz",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505752000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505752
    },
    "transaction": {
        "amount": 500,
        "amount_unused": 500,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWlDEl2cz",
        "date": 1600968152,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "not_applicable",
        "id": "txn___test__KyVnHhSBWlDFn2d1",
        "linked_invoices": [],
        "linked_refunds": [],
        "object": "transaction",
        "payment_method": "check",
        "resource_version": 1517505752000,
        "status": "success",
        "type": "payment",
        "updated_at": 1517505752
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/record_excess_payment

Method

comment[]
optional, string, max chars=300
Remarks, if any, on the payment.
transaction[amount]
required, in cents, min=1
transaction[currency_code]
required if Multicurrency is enabled, string, max chars=3
transaction[date]
required, timestamp(UTC) in seconds
transaction[payment_method]
required, enumerated string
Possible values are
cashCashcheckCheckbank_transferBank TransferotherPayment Methods other than the above types
Show all values[+]
transaction[reference_number]
optional, string, max chars=100
transaction[custom_payment_method_id]
optional, string, max chars=50
customer customer
always returned
Resource object representing customer
transaction transaction
always returned
Resource object representing transaction

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x
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.

Notes

Sample Request
# collects payment for the customer with the existing payment source.
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl6A32bF/collect_payment \
     -X POST  \
     -u {site_api_key}:\
     -d amount=100 \
     -d payment_source_id="pm___test__KyVnHhSBWl6Q02bG" \
     -d invoice_allocations[invoice_id][0]="__demo_inv__1" 
# collects payment for the customer using new payment source.
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl78A2bV/collect_payment \
     -X POST  \
     -u {site_api_key}:\
     -d card[number]="378282246310005" \
     -d card[expiry_month]=10 \
     -d card[expiry_year]=2022 \
     -d card[cvv]="999" 
     -d invoice_allocations[invoice_id][0]="__demo_inv__2" 
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505725,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__KyVnHhSBWl6A32bF",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__KyVnGlSBWl4aZ1jg",
            "object": "payment_method",
            "reference_id": "cus_I58Pya87WmQLx0/card_1HUy8vJv9j0DyntJbHs5EYNs",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWl6Q02bG",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505727000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505727
    },
    "transaction": {
        "amount": 100,
        "amount_unused": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWl6A32bF",
        "date": 1600968127,
        "deleted": false,
        "exchange_rate": 1,
        "fraud_reason": "Payment complete.",
        "gateway": "stripe",
        "gateway_account_id": "gw___test__KyVnGlSBWl4aZ1jg",
        "id": "txn___test__KyVnHhSBWl6Zg2bR",
        "id_at_gateway": "ch_1HUy8xJv9j0DyntJlrFKSALQ",
        "linked_invoices": [
            {
                "applied_amount": 100,
                "applied_at": 1517505727,
                "invoice_date": 1517505726,
                "invoice_id": "__demo_inv__1",
                "invoice_status": "payment_due",
                "invoice_total": 1095
            },
            {..}
        ],
        "linked_refunds": [],
        "masked_card_number": "************1111",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__KyVnHhSBWl6Q02bG",
        "resource_version": 1517505727000,
        "status": "success",
        "subscription_id": "__test__KyVnHhSBWl6RN2bK",
        "type": "payment",
        "updated_at": 1517505727
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/collect_payment

Method

amount[]
optional, in cents, min=0
Amount to be collected. If this parameter is not passed then the invoice(s) amount to collect will be collected.
payment_source_id[]
optional, string, max chars=40
Payment source used for the payment.
token_id[]
optional, string, max chars=40
Token generated by Chargebee JS representing payment method details.
replace_primary_payment_source[]
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
retain_payment_source[]
optional, boolean, default=false
Indicates whether the payment source should be retained for the customer.
payment_initiator[]
optional, enumerated string
The type of initiator to be used for the payment request triggered by this operation.
Possible values are
customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant
Show all values[+]
payment_method[type]
optional, enumerated string
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
Show all values[+]
payment_method[gateway_account_id]
optional, string, max chars=50
payment_method[reference_id]
optional, string, max chars=200
payment_method[tmp_token]
required if reference_id not provided, string, max chars=65k
payment_method[additional_information]
optional, jsonobject
card[gateway_account_id]
optional, string, max chars=50
card[first_name]
optional, string, max chars=50
card[last_name]
optional, string, max chars=50
card[number]
required if card provided, string, max chars=1500
card[expiry_month]
required if card provided, integer, min=1, max=12
card[expiry_year]
required if card provided, integer
card[cvv]
optional, string, max chars=520
card[billing_addr1]
optional, string, max chars=150
card[billing_addr2]
optional, string, max chars=150
card[billing_city]
optional, string, max chars=50
card[billing_state_code]
optional, string, max chars=50
card[billing_state]
optional, string, max chars=50
card[billing_zip]
optional, string, max chars=20
card[billing_country]
optional, string, max chars=50
card[additional_information]
optional, jsonobject
payment_intent[id]
optional, string, max chars=150
payment_intent[gateway_account_id]
required if payment intent token provided, string, max chars=50
payment_intent[gw_token]
optional, string, max chars=65k
payment_intent[payment_method_type]
optional, enumerated string
Possible values are
cardcardidealidealsofortsofortbancontactbancontact
Show all values[+]
payment_intent[reference_id]
optional, string, max chars=65k
payment_intent[additional_information]
optional, jsonobject
invoice_allocations[invoice_id][0..n]
required, string, max chars=50
invoice_allocations[allocation_amount][0..n]
optional, in cents, min=0
customer customer
always returned
Resource object representing customer
transaction transaction
always returned
Resource object representing transaction

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

Deletes a particular customer identified by the a unique identifier.

Notes

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 Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl9ZA2c8/delete \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505738,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWl9ZA2c8",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505738000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505738
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/delete

Method

delete_payment_method[]
optional, boolean, default=true
Deletes the Payment Method from the gateway/vault.
customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

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.

This API is not enabled for live sites by default. Please contact support to get this enabled.

Notes

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_code must be enabled in the destination site.

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/move \
     -u {site_api_key}:\
     -d id_at_from_site="__test__KyVnHhSBWlCxa2cx" \
     -d from_site="mannar"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "resource_migration": {
        "created_at": 1517505751,
        "entity_id": "__test__KyVnHhSBWlCxa2cx",
        "entity_type": "customer",
        "from_site": "mannar",
        "object": "resource_migration",
        "status": "scheduled",
        "updated_at": 1517505751
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/move

Method

id_at_from_site[]
required, string, max chars=100
Id of the customer to be copied.
from_site[]
required, string, max chars=50
Name of the site from which this customer need to be copied.
resource_migration resource_migration
always returned
Resource object representing resource_migration

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

Applicable when calendar billing (with customer specific billing date support) is enabled. Changes the customer's billing_date and/or billing_day_of_week.

Notes

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 Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5XP2b6/change_billing_date \
     -u {site_api_key}:\
     -d billing_date=15 \
     -d billing_date_mode="MANUALLY_SET" \
     -d billing_day_of_week="SUNDAY" \
     -d billing_day_of_week_mode="MANUALLY_SET"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "billing_date": 15,
        "billing_date_mode": "manually_set",
        "billing_day_of_week": "sunday",
        "billing_day_of_week_mode": "manually_set",
        "card_status": "no_card",
        "created_at": 1517505722,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWl5XP2b6",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505723000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505723
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/change_billing_date

Method

billing_date[]
optional, integer, min=1, max=31
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[]
optional, integer, min=1, max=12

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.

billing_date_mode[]
optional, enumerated string
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.
Possible values are
using_defaultsBilling date is set based on defaults configured.manually_setBilling date is specifically set (default configuration is overridden)
Show all values[+]
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.
Possible values are
sundaySundaymondayMondaytuesdayTuesdaywednesdayWednesday
Show all values[+]
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.
Possible values are
using_defaultsBilling date is set based on defaults configured.manually_setBilling date is specifically set (default configuration is overridden)
Show all values[+]
customer customer
always returned
Resource object representing customer

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

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.
This API is not enabled for live sites by default. Please contact support to get this enabled.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/merge \
     -u {site_api_key}:\
     -d from_customer_id="__test__KyVnHhSBWlCbP2cp" \
     -d to_customer_id="__test__KyVnHhSBWlCdz2cv"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505750,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWlCdz2cv",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505750000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505750
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/merge

Method

from_customer_id[]
required, string, max chars=50
From customer id.
to_customer_id[]
required, string, max chars=50
To customer id.
customer customer
always returned
Resource object representing customer

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x
Clear personal details of a customer using this API.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5qO2b9/clear_personal_data \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "card": {
        "card_type": "visa",
        "created_at": 1517505724,
        "customer_id": "__test__KyVnHhSBWl5qO2b9",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "credit",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
        "iin": "411111",
        "last4": "1111",
        "masked_number": "************1111",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWl5rL2bB",
        "resource_version": 1517505724000,
        "status": "valid",
        "updated_at": 1517505724
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505724,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__KyVnHhSBWl5qO2b9",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWl5rH2bA",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "scheduled_for_clear",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWl5rL2bB",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505724000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505724
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/clear_personal_data

Method

customer customer
always returned
Resource object representing customer

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

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.

Notes

Sample Request
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "child_account_access": {
            "portal_download_invoices": "view_only",
            "portal_edit_subscriptions": "yes",
            "send_invoice_emails": true,
            "send_payment_emails": true,
            "send_subscription_emails": true
        },
        "created_at": 1517505753,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Bella",
        "id": "__test__KyVnHhSBWlDY12d5",
        "last_name": "Brown",
        "net_term_days": 0,
        "object": "customer",
        "parent_account_access": {
            "portal_download_child_invoices": "yes",
            "portal_edit_child_subscriptions": "view_only",
            "send_invoice_emails": true,
            "send_payment_emails": true,
            "send_subscription_emails": false
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "relationship": {
            "invoice_owner_id": "__test__KyVnHhSBWlDY12d5",
            "parent_id": "__test__KyVnHhSBWlDa22d7",
            "payment_owner_id": "__test__KyVnHhSBWlDY12d5",
            "root_id": "__test__KyVnHhSBWlDa22d7"
        },
        "resource_version": 1517505753000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505753,
        "use_default_hierarchy_settings": true
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/relationships

Method

parent_id[]
optional, string, max chars=50
ID of the customer intended to be set as the immediate parent of the customer identified by customer_id.
payment_owner_id[]
optional, string, max chars=50
The id of the customer responsible for paying the invoices for the customer identified by customer_id. This ID must match either customer_id or invoice_owner_id.
invoice_owner_id[]
optional, string, max chars=50
The id of the customer who receives the invoice for charges incurred by the customer identified by customer_id. This ID must match either customer_id or one of its ancestors.
use_default_hierarchy_settings[]
optional, boolean, default=true

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 the parent_account_access and child_account_access parameters are applied.
parent_account_access[portal_edit_child_subscriptions]
optional, enumerated string
Possible values are
yesThe parent can view and edit the child's subscriptions.view_onlyThe parent can only view the child's subscriptions.noThe parent can't view or edit the child's subscriptions.
Show all values[+]
parent_account_access[portal_download_child_invoices]
optional, enumerated string
Possible values are
yesThe parent can both view and download the child's invoices.view_onlyThe parent can view but not download the child's invoices.noThe parent can't view or download the child's invoices.
Show all values[+]
parent_account_access[send_subscription_emails]
optional, boolean
parent_account_access[send_payment_emails]
optional, boolean
parent_account_access[send_invoice_emails]
optional, boolean
child_account_access[portal_edit_subscriptions]
optional, enumerated string
Possible values are
yesThe child account can view and edit its subscriptions.view_onlyThe child account can only view its subscriptions.
Show all values[+]
child_account_access[portal_download_invoices]
optional, enumerated string
Possible values are
yesThe child account can both view and download its invoices.view_onlyThe child account can view but not download its invoices.noThe child account cannot view or download its own invoices.
Show all values[+]
child_account_access[send_subscription_emails]
optional, boolean
child_account_access[send_payment_emails]
optional, boolean
child_account_access[send_invoice_emails]
optional, boolean
customer customer
always returned
Resource object representing customer

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x
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.

Notes

Sample Request
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505741,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Bella",
        "id": "__test__KyVnHhSBWlAG12cF",
        "last_name": "Brown",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505741000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505741
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/delete_relationship

Method

customer customer
always returned
Resource object representing customer

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x
Retrieves the full or partial account hierarchy for a customer.

Notes

Sample Request
# List the nodes of the full hierarchy to which the customer belongs.
curl  https://{site}.chargebee.com/api/v2/customers/foo/hierarchy \
     -u {site_api_key}:\
     -d hierarchy_operation_type="COMPLETE_HIERARCHY"
# List the nodes along the path from the customer to the root of the full hierarchy.
curl  https://{site}.chargebee.com/api/v2/customers/foo/hierarchy \
     -u {site_api_key}:\
     -d hierarchy_operation_type="PATH_TO_ROOT"
# List all the nodes of the hierarchy formed by the customer and its subordinates.
curl  https://{site}.chargebee.com/api/v2/customers/foo/hierarchy \
     -u {site_api_key}:\
     -d hierarchy_operation_type="SUBORDINATES"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "hierarchies": [
        {
            "children_ids": [
                "foo",
                {..}
            ],
            "payment_owner_id": "bar",
            "customer_id": "bar",
            "invoice_owner_id": "bar",
            "object": "hierarchy"
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/customers/{customer-id}/hierarchy

Method

hierarchy_operation_type[]
required, enumerated string
Specifies which part of the account hierarchy to retrieve for the customer identified by {customer_id}.
Possible values are
complete_hierarchyRetrieve all nodes in the account hierarchy.subordinatesRetrieve all nodes in the account hierarchy that start from the specified customer (identified by {customer_id}) and include its subordinates. In other words, get nodes in the account hierarchy tree where the root node is the specified customer.path_to_rootRetrieve nodes from the specified customer (identified by {customer_id}) to the root of its account hierarchy.
Show all values[+]
hierarchies hierarchies
always returned
Resource object representing hierarchies

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x

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.

Notes

Sample Request
# Deletes any custom parent/child access settings defined and applies the site defaults
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlG3y2dt/update_hierarchy_settings \
     -u {site_api_key}:\
     -d use_default_hierarchy_settings=true
# Updates all of the &quot;parent_account_access&quot; and &quot;child_account_access&quot; settings for a customer.
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlGoZ2e7/update_hierarchy_settings \
     -u {site_api_key}:\
     -d use_default_hierarchy_settings=false \
     -d child_account_access[portal_edit_subscriptions]="YES" \
     -d child_account_access[portal_download_invoices]="YES" \
     -d child_account_access[send_subscription_emails]=true \
     -d child_account_access[send_payment_emails]=true \
     -d child_account_access[send_invoice_emails]=true 
     -d parent_account_access[portal_edit_child_subscriptions]="VIEW_ONLY" \
     -d parent_account_access[portal_download_child_invoices]="YES" \
     -d parent_account_access[send_subscription_emails]=false \
     -d parent_account_access[send_payment_emails]=false \
     -d parent_account_access[send_invoice_emails]=false
# Updates only some of the &quot;parent_account_access&quot; and &quot;child_account_access&quot; settings for a customer
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlGQc2e0/update_hierarchy_settings \
     -u {site_api_key}:\
     -d use_default_hierarchy_settings=false \
     -d parent_account_access[portal_edit_child_subscriptions]="YES" \
     -d parent_account_access[portal_download_child_invoices]="YES" \
     -d parent_account_access[send_invoice_emails]=false 
     -d child_account_access[portal_download_invoices]="YES" \
     -d child_account_access[send_invoice_emails]=true
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "id": "__test__KyVnHhSBWlG3y2dt",
        "relationship": {
            "invoice_owner_id": "__test__KyVnHhSBWlG3y2dt",
            "parent_id": "__test__KyVnHhSBWlG5Z2dv",
            "payment_owner_id": "__test__KyVnHhSBWlG3y2dt",
            "root_id": "__test__KyVnHhSBWlG5Z2dv"
        },
        "use_default_hierarchy_settings": true,
        "parent_account_access": {
            "portal_download_child_invoices": "yes",
            "portal_edit_child_subscriptions": "view_only",
            "send_invoice_emails": true,
            "send_payment_emails": true,
            "send_subscription_emails": false
        },
        "child_account_access": {
            "portal_download_invoices": "view_only",
            "portal_edit_subscriptions": "yes",
            "send_invoice_emails": true,
            "send_payment_emails": true,
            "send_subscription_emails": true
        },
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505763,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Bella",
        "last_name": "Brown",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505763000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505763
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/update_hierarchy_settings

Method

use_default_hierarchy_settings[]
optional, boolean, default=true

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 the parent_account_access and child_account_access attributes 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 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.
parent_account_access[portal_edit_child_subscriptions]
optional, enumerated string
Possible values are
yesThe parent account can view and edit the subscriptions of the child account.view_onlyThe parent account can only view the subscriptions of the child account.noThe parent account cannot view or edit the subscriptions of the child account.
Show all values[+]
parent_account_access[portal_download_child_invoices]
optional, enumerated string
Possible values are
yesThe parent account can view and download the invoices of the child account.view_onlyThe parent account can only view the invoices of the child account.noThe parent account can neither view nor download the invoices of the child account.
Show all values[+]
parent_account_access[send_subscription_emails]
optional, boolean
parent_account_access[send_payment_emails]
optional, boolean
parent_account_access[send_invoice_emails]
optional, boolean
child_account_access[portal_edit_subscriptions]
optional, enumerated string
Possible values are
yesThe child account can view and edit its subscriptions.view_onlyThe child account can only view its subscriptions.
Show all values[+]
child_account_access[portal_download_invoices]
optional, enumerated string
Possible values are
yesThe child account can both view and download its invoices.view_onlyThe child account can view but not download its invoices.noThe child account cannot view or download its own invoices.
Show all values[+]
child_account_access[send_subscription_emails]
optional, boolean
child_account_access[send_payment_emails]
optional, boolean
child_account_access[send_invoice_emails]
optional, boolean
customer customer
always returned
Resource object representing customer

Sample admin console URL

https://{site}.chargebee.com/admin-console/customers/123x