You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

Represents a customer. Subscriptions, Card and Billing Address are associated with the customer resource. Customer resource will be created along with subscription via "Create a Subscription" API. The id of the customer will be same as that of associated subscription id if not explictly set.

Legacy behavior:
  • For sites created before March 1st, 2014: Whenever the card is updated, the billing_address and vat_number of the customer are deleted and replaced by the values sent with the request.
  • For sites created on or after March 1st, 2014: The billing_address and vat_number are not changed when the associated card is updated.

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
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
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.
offline_payment_method
optional, enumerated string
The preferred offline payment method for the customer.
Possible values are
no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.
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.
allow_direct_debit
boolean, default=false
Whether the customer can pay via Direct Debit.
is_location_valid
optional, boolean
Customer location is validated based on IP address and Card issuing country. If the location is valid, it returns True. If not, it returns False. Applicable only for EU, New Zealand and Australia.
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. Used primarily for referral integrations and EU/UK VAT validation.
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.
.
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 government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.
eCharitable or benevolent organization.fReligious organization.gResale.hCommercial agricultural production.iIndustrial production/manufacturer.jDirect pay permit.kDirect mail.lOther or custom.mEducational organization.nLocal government.pCommercial aquaculture.qCommercial Fishery.rNon-resident.med1US Medical Device Excise Tax with exempt sales tax.med2US Medical Device Excise Tax with taxable sales tax.
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
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_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).
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
sundaySunday.mondayMonday.tuesdayTuesday.wednesdayWednesday.thursdayThursday.fridayFriday.saturdaySaturday.
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).
pii_cleared
optional, enumerated string, default=active
Indicates whether this customer's personal information has been cleared .
Possible values are
activeActive.scheduled_for_clearScheduled For Clear.clearedCleared.
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.
.
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 safe.suspiciousThe customer has been identified as potentially fraudulent by the gateway.fraudulentThe customer has been marked as fraudulent.
primary_payment_source_id
optional, string, max chars=40
Primary payment source for the customer.
backup_payment_source_id
optional, string, max chars=40
Backup payment source for the customer. Used to collect payment if primary payment source fails.
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.
business_entity_id
optional, string, max chars=50
The ID of the business entity created for the site. For Product Catalog 1.0, all the site data is tied to this business entity.
Note

Multiple Business Entities is a feature available only on Product Catalog 2.0.


preferred_currency_code
optional, string, max chars=3
TThe currency code of the customer's preferred currency (ISO 4217 format). Applicable if the Multicurrency feature is enabled.
promotional_credits
in cents, min=0
Promotional credits balance of this 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.

.
meta_data
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.
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
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 use.businessWhen the purchase is made at a place of business.senior_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 breaks.industrialWhen the purchase is made by an industrial business.
business_customer_without_vat_number
optional, boolean
Confirms that a customer is a valid business without an EU/UK VAT number.
client_profile_id
optional, string, max chars=50
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
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.
Billing address attributes
first_name
optional, string, max chars=150
The first name of the billing contact.
last_name
optional, string, max chars=150
The last name of the billing contact.
email
optional, string, max chars=70
The email address.
company
optional, string, max chars=250
The company name.
phone
optional, string, max chars=50
The phone number.
line1
optional, string, max chars=150
Address line 1.
line2
optional, string, max chars=150
Address line 2.
line3
optional, string, max chars=150
Address line 3.
city
optional, string, max chars=50
The name of the city.
state_code
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
state
optional, string, max chars=50
State or Province.
country
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

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

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

.
zip
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
validation_status
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
referral_urls
Show attributes[+]
optional, list of referral_url
List of referral urls for the customer (if applicable).
Referral url attributes
external_customer_id
optional, string, max chars=100
External customer id in the referral system.
referral_sharing_url
string, max chars=50
Referral sharing url for the customer.
created_at
timestamp(UTC) in seconds
The referral url creation time.
updated_at
timestamp(UTC) in seconds
The referral url updation time.
referral_campaign_id
string, max chars=50
Referral campaign id.
referral_account_id
string, max chars=50
Referral account id.
referral_external_campaign_id
optional, string, max chars=50
Referral external campaign id.
referral_system
enumerated string
Url for the referral system account.
Possible values are
referral_candyReferral Candy.referral_saasquatchReferral Saasquatch.friendbuyFriendbuy.
optional, list of contact
contacts.
Contact attributes
id
string, max chars=150
Unique reference ID provided for the contact.
first_name
optional, string, max chars=150
First name of the contact.
last_name
optional, string, max chars=150
Last name of the contact.
email
string, max chars=70
Email of the contact.
phone
optional, string, max chars=50
Phone number of the contact.
label
optional, string, max chars=50
Label/Tag provided for contact.
enabled
boolean, default=false
Contact enabled / disabled.
send_account_email
boolean, default=false
Whether Account Emails option is enabled for the contact.
send_billing_email
boolean, default=false
Whether Billing Emails option is enabled for the contact.
payment_method
Show attributes[+]
optional, payment_method
Primary Payment Source of the customer.
Payment method attributes
type
enumerated string
Type of payment source.
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.
genericPayments made via Generic Payment Method.alipayPayments made via Alipay.unionpayPayments made via UnionPay.apple_payPayments made via Apple Pay.wechat_payPayments made via WeChat Pay.idealPayments made via iDEAL.google_payPayments made via Google Pay.sofortPayments made via Sofort.bancontactPayments made via Bancontact Card.giropayPayments made via giropay.dotpayPayments made via Dotpay.upiUPI Payments.netbanking_emandatesNetbanking (eMandates) Payments.
Show all values[+]
gateway
enumerated string
Name of the gateway the payment method is associated with.
Possible values are
chargebeeChargebee test gateway.stripeStripe is a payment gateway.wepayWePay is a payment gateway.braintreeBraintree is a payment gateway.
authorize_netAuthorize.net is a payment gateway.paypal_proPayPal Pro Account is a payment gateway.pinPin is a payment gateway.ewayeWAY Account is a payment gateway.eway_rapideWAY Rapid is a payment gateway.worldpayWorldPay is a payment gateway.balanced_paymentsBalanced is a payment gateway.beanstreamBambora(formerly known as Beanstream) is a payment gateway.bluepayBluePay is a payment gateway.elavonElavon Virtual Merchant is a payment solution.first_data_globalFirst Data Global Gateway Virtual Terminal Account.hdfcHDFC Account is a payment gateway.migsMasterCard Internet Gateway Service payment gateway.nmiNMI is a payment gateway.ogoneIngenico ePayments (formerly known as Ogone) is a payment gateway.paymillPAYMILL is a payment gateway.paypal_payflow_proPayPal Payflow Pro is a payment gateway.sage_paySage Pay is a payment gateway.tco2Checkout is a payment gateway.wirecardWireCard Account is a payment service provider.amazon_paymentsAmazon Payments is a payment service provider.paypal_express_checkoutPayPal Express Checkout is a payment gateway.gocardlessGoCardless is a payment service provider.adyenAdyen is a payment gateway.orbitalChase Paymentech(Orbital) is a payment gateway.moneris_usMoneris USA is a payment gateway.monerisMoneris is a payment gateway.bluesnapBlueSnap is a payment gateway.cybersourceCyberSource is a payment gateway.vantivVantiv is a payment gateway.checkout_comCheckout.com is a payment gateway.paypalPayPal Commerce is a payment gateway.ingenico_directWorldline Online Payments is a payment gateway.exactExact Payments is a payment gateway.mollieMollie is a payment gateway.quickbooksIntuit QuickBooks Payments gateway.razorpayRazorpay is a fast growing payment service provider in India working with all leading banks and support for major local payment methods including Netbanking, UPI etc.not_applicableIndicates that payment gateway is not applicable for this resource.
Show all values[+]
gateway_account_id
optional, string, max chars=50
The gateway account this payment method is stored with.
status
enumerated string, default=valid
Current status of the payment source.
Possible values are
validA payment source that is valid and active.expiringA payment source that is expiring (like card's status based on its expiry date).expiredA payment source that has expired.invalidThe billing agreement cannot be used. It might become valid again either automatically or due to customer action.pending_verificationThe payment source needs to be verified.
reference_id
string, max chars=200
The reference id. In the case of Amazon and PayPal this will be the 'billing agreement id'. For GoCardless direct debit this will be 'mandate id'. In the case of card payments this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one time temporary token provided by gateways like Stripe.
optional, list of customer_balance
The list of balances for this customer.
Balance attributes
promotional_credits
in cents, default=0, min=0
Promotional credits balance of this customer.
excess_payments
in cents, default=0, min=0
Total unused payments associated with the customer.
refundable_credits
in cents, default=0, min=0
Refundable credits balance of this customer.
unbilled_charges
in cents, default=0, min=0
Total unbilled charges for this customer.
currency_code
string, max chars=3
The currency code (ISO 4217 format) for balance.
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. .
Entity identifier attributes
id
string, max chars=40
The unique id for the entity_identifier in Chargebee. When not provided, it is autogenerated.
value
optional, string, max chars=50
The value of the entity_identifier. This identifies the customer entity on the Peppol network. For example: 10101010-STO-10.

Tip:

If there is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

.
scheme
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 is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

.
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 is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

.
relationship
Show attributes[+]
optional, relationship
The Account Hierarchy relationship that the customer is part of.
Relationship attributes
parent_id
optional, string, max chars=50
The id of the customer who is the immediate parent.
payment_owner_id
string, max chars=50
The id of the customer who pays the invoices for this customer. Can be the customer itself or the invoice_owner_id.
invoice_owner_id
string, max chars=50
The id of the customer who is invoiced for charges incurred. Can be the customer itself or any parent in its hierarchy.
parent_account_access
Show attributes[+]
optional, parent_account_access

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.
Parent account access attributes
portal_edit_child_subscriptions
optional, enumerated string
Sets parent's level of access to child subscriptions on the Self-Serve Portal.
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.
portal_download_child_invoices
optional, enumerated string
Sets parent's level of access to child invoices on the Self-Serve Portal.
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.
send_subscription_emails
boolean
If true, the parent account will receive subscription-related emails sent to the child account.
send_invoice_emails
boolean
If true, the parent account will receive invoice-related emails sent to the child account.
send_payment_emails
boolean
If true, the parent account will receive payment-related emails sent to the child account.
child_account_access
Show attributes[+]
optional, child_account_access
Defines the level of access that the customer has to its own information.
Child account access attributes
portal_edit_subscriptions
optional, enumerated string
Sets the child's level of access to its own subscriptions on the Self-Serve Portal.
Possible values are
yesThe child account can view and edit its own subscriptions.view_onlyThe child account can only view its own subscriptions.
portal_download_invoices
optional, enumerated string
Sets the child’s level of access to its own invoices on the Self-Serve Portal.
Possible values are
yesThe child account can view and download its own invoices.view_onlyThe child account can only view its invoices and not download them.noThe child account can neither view nor download its own invoices.
send_subscription_emails
boolean
If true, the child account will receive subscription-related emails for its own subscriptions.
send_invoice_emails
boolean
If true, the child account will receive invoice-related emails for its own invoices.
send_payment_emails
boolean
If true, the child account will receive payment-related emails for its own invoices.
This operation 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.

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"
copy

Sample Response [ JSON ]

URL Format POST

https://{site}.chargebee.com/api/v2/customers
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.
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.

.
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.
.
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 use.businessWhen the purchase is made at a place of business.senior_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 breaks.industrialWhen the purchase is made by an industrial business.
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-sale.governmentGovernment.otherOther.
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 government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.
eCharitable or benevolent organization.fReligious organization.gResale.hCommercial agricultural production.iIndustrial production/manufacturer.jDirect pay permit.kDirect mail.lOther or custom.mEducational organization.nLocal government.pCommercial aquaculture.qCommercial Fishery.rNon-resident.med1US Medical Device Excise Tax with exempt sales tax.med2US Medical Device Excise Tax with taxable sales tax.
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 set of key-value pairs stored as additional information for the subscription. Learn more.
offline_payment_method
optional, enumerated string
The preferred offline payment method for the customer.
Possible values are
no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.
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.
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
Parameters for card
pass parameters as card[<param name>]
card[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
card[first_name]
optional, string, max chars=50
Cardholder's first name.
card[last_name]
optional, string, max chars=50
Cardholder's last name.
card[number]
required if card provided, string, max chars=1500
The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
card[expiry_month]
required if card provided, integer, min=1, max=12
Card expiry month.
card[expiry_year]
required if card provided, integer
Card expiry year.
card[cvv]
optional, string, max chars=520
The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
card[billing_addr1]
optional, string, max chars=150
Address line 1, as available in card billing address.
card[billing_addr2]
optional, string, max chars=150
Address line 2, as available in card billing address.
card[billing_city]
optional, string, max chars=50
City, as available in card billing address.
card[billing_state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
card[billing_state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
card[billing_zip]
optional, string, max chars=20
Postal or Zip code, as available in card billing address.
card[billing_country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

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

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

.
card[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
.
+
bank_account
Parameters for bank_account
pass parameters as bank_account[<param name>]
bank_account[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
bank_account[iban]
optional, string, min chars=10, max chars=50
Account holder’s International Bank Account Number. For the GoCardless platform, this can be the local bank details .
bank_account[first_name]
optional, string, max chars=150
Account holder’s first name as per bank account. If not passed, details from customer details will be considered.
bank_account[last_name]
optional, string, max chars=150
Account holder’s last name as per bank account. If not passed, details from customer details will be considered.
bank_account[company]
optional, string, max chars=250
Account holder’s company name as per bank account. If not passed, details from customer details will be considered.
bank_account[email]
optional, string, max chars=70
Account holder’s email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.
bank_account[phone]
optional, string, max chars=50
Phone number of the account holder that is linked to the bank account.
bank_account[bank_name]
optional, string, max chars=100
Name of account holder’s bank.
bank_account[account_number]
optional, string, min chars=4, max chars=17
Account holder’s bank account number.
bank_account[routing_number]
optional, string, min chars=3, max chars=9
Bank account routing number.
bank_account[bank_code]
optional, string, max chars=20
Indicates the bank code.
bank_account[account_type]
optional, enumerated string
Represents the account type used to create a payment source. Available for Authorize.net ACH and Razorpay NetBanking users only. If not passed, account type is taken as null.
Possible values are
checkingChecking Account.savingsSavings Account.business_checkingBusiness Checking Account.currentCurrent Account.
bank_account[account_holder_type]
optional, enumerated string
For Stripe ACH users only. Indicates the account holder type.
Possible values are
individualIndividual Account.companyCompany Account.
bank_account[echeck_type]
optional, enumerated string
For Authorize.net ACH users only. Indicates the type of eCheck.
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.
bank_account[issuing_country]
optional, string, max chars=50
two-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.
bank_account[swedish_identity_number]
optional, string, min chars=10, max chars=12
For GoCardless Autogiro users only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
bank_account[billing_address]
optional, jsonobject
The billing address associated with the bank account. The value is a JSON object with the following keys and their values:
  • first_name:(string, max chars=150) The first name of the contact.
  • last_name:(string, max chars=150) The last name of the contact.
  • company_name:(string, max chars=250) The company name for the address.
  • line1:(string, max chars=180) The first line of the address.
  • line2:(string, max chars=180) The second line of the address.
  • country:(string) The name of the country for the address.
  • country_code:(string, max chars=50) The two-letter, ISO 3166 alpha-2 country code for the address.
  • state:(string, max chars=50) The name of the state or province for the address. When not provided, this is set automatically for US, Canada, and India.
  • state_code:(string, max chars=50) The ISO 3166-2 state/province code without the country prefix. This is supported for USA, Canada, and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
  • city:(string, max chars=50) The city name for the address.
  • postal_code:(string, max chars=20) The postal or ZIP code for the address.
  • phone:(string, max chars=50) The contact phone number for the address.
  • email:(string, max chars=70) The contact email address for the address.
+
payment_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
payment_method[type]
optional, enumerated string
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
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.
genericPayments made via Generic Payment Method.alipayPayments made via Alipay.unionpayPayments made via UnionPay.apple_payPayments made via Apple Pay.wechat_payPayments made via WeChat Pay.idealPayments made via iDEAL.google_payPayments made via Google Pay.sofortPayments made via Sofort.bancontactPayments made via Bancontact Card.giropayPayments made via giropay.dotpayPayments made via Dotpay.upiUPI Payments.netbanking_emandatesNetbanking (eMandates) Payments.
Show all values[+]
payment_method[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
payment_method[reference_id]
optional, string, max chars=200
The reference id. In the case of Amazon and PayPal this will be the billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
payment_method[tmp_token]
required if reference_id not provided, string, max chars=65k
Single-use tokens created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
payment_method[issuing_country]
optional, string, max chars=50
ISO 3166 alpha-2 country code.

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

If you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.
payment_method[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
.
+
payment_intent
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
payment_intent[id]
optional, string, max chars=150
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
payment_intent[gateway_account_id]
required if payment intent token provided, string, max chars=50
The gateway account used for performing the 3DS flow.
payment_intent[gw_token]
optional, string, max chars=65k
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
payment_intent[payment_method_type]
optional, enumerated string
The list of payment method types (For example, card, ideal, sofort, bancontact, etc.) this Payment Intent is allowed to use. If payment method type is empty, Card is taken as the default type for all gateways except Razorpay.
Possible values are
cardcard.idealideal.sofortsofort.bancontactbancontact.
google_paygoogle_pay.dotpaydotpay.giropaygiropay.apple_payapple_pay.upiupi.netbanking_emandatesnetbanking_emandates.paypal_express_checkoutpaypal_express_checkout.
Show all values[+]
payment_intent[reference_id]
optional, string, max chars=65k
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
payment_intent[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
.
+
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
optional, string, max chars=150
The first name of the billing contact.
billing_address[last_name]
optional, string, max chars=150
The last name of the billing contact.
billing_address[email]
optional, string, max chars=70
The email address.
billing_address[company]
optional, string, max chars=250
The company name.
billing_address[phone]
optional, string, max chars=50
The phone number.
billing_address[line1]
optional, string, max chars=150
Address line 1.
billing_address[line2]
optional, string, max chars=150
Address line 2.
billing_address[line3]
optional, string, max chars=150
Address line 3.
billing_address[city]
optional, string, max chars=50
The name of the city.
billing_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
billing_address[state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
billing_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
billing_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

.
billing_address[validation_status]
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
+
entity_identifiers
Parameters for entity_identifiers. Multiple entity_identifiers can be passed by specifying unique indices.
pass parameters as entity_identifiers[<param name>][<idx:0..n>]
entity_identifiers[id][0..n]
optional, string, max chars=40
The unique id for the entity_identifier in Chargebee. When not provided, it is autogenerated. .
entity_identifiers[scheme][0..n]
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 is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

.
entity_identifiers[value][0..n]
optional, string, max chars=50
The value of the entity_identifier. This identifies the customer entity on the Peppol network. For example: 10101010-STO-10.

Tip:

If there is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

.
entity_identifiers[standard][0..n]
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 is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

.
always returned
Resource object representing customer.
optional
Resource object representing card.
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.
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
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"

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
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.
Supported operators : is, is_not, starts_with, in, not_in

Example id[is] = "9bsvnHgsvmsI"
first_name[<operator>]
optional, string filter
First name of the customer.
Supported operators : is, is_not, starts_with, is_present

Example first_name[is] = "John"
last_name[<operator>]
optional, string filter
Last name of the customer.
Supported operators : is, is_not, starts_with, is_present

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

Example email[is] = "john@test.com"
company[<operator>]
optional, string filter
Company name of the customer.
Supported operators : is, is_not, starts_with, is_present

Example company[is] = "Globex Corp"
phone[<operator>]
optional, string filter
Phone number of the customer.
Supported operators : is, is_not, starts_with, is_present

Example phone[is] = "(541) 754-3010"
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_not] = "on"
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_not] = "taxable"
created_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating when this customer resource is created.
Supported operators : after, before, on, between

Example created_at[after] = "1435054328"
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.
Supported operators : after, before, on, between

Example updated_at[after] = "1243545465"
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.
Supported operators : is, is_not, in, not_in

Example offline_payment_method[is_not] = "cash"
auto_close_invoices[<operator>]
optional, boolean 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"
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"
+
relationship
Parameters for relationship
pass parameters as relationship[<param name>][<operator>]
relationship[parent_id][operator]
optional, string filter
Immediate parent with whom we will link our new customer(child).
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.
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.
Supported operators : is, is_not, starts_with

Example relationship[invoice_owner_id][is] = "future_billing"
always returned
Resource object representing customer.
optional
Resource object representing card.
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”.
Retrieves the details of the desired customer. You can use the unique identifier for a particular customer to retrieve the desired details.
Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlF0Q2dg \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlF0Q2dg \
     -u {site_api_key}:

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}
always returned
Resource object representing customer.
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.

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

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}
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
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.
allow_direct_debit
optional, boolean
Whether the customer can pay via Direct Debit.
net_term_days
optional, integer
The number of days within which the customer has to make payment for the invoice. .
taxability
optional, enumerated string
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.
.
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 use.businessWhen the purchase is made at a place of business.senior_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 breaks.industrialWhen the purchase is made by an industrial business.
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-sale.governmentGovernment.otherOther.
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 government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.
eCharitable or benevolent organization.fReligious organization.gResale.hCommercial agricultural production.iIndustrial production/manufacturer.jDirect pay permit.kDirect mail.lOther or custom.mEducational organization.nLocal government.pCommercial aquaculture.qCommercial Fishery.rNon-resident.med1US Medical Device Excise Tax with exempt sales tax.med2US Medical Device Excise Tax with taxable sales tax.
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 Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.
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 set of key-value pairs stored as additional information for the subscription. 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 safe.fraudulentThe customer has been marked as fraudulent.
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.

.
always returned
Resource object representing customer.
optional
Resource object representing card.
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.

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

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
+
payment_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
payment_method[type]
required, enumerated string
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
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.
genericPayments made via Generic Payment Method.alipayPayments made via Alipay.unionpayPayments made via UnionPay.wechat_payPayments made via WeChat Pay.idealPayments made via iDEAL.google_payPayments made via Google Pay.sofortPayments made via Sofort.bancontactPayments made via Bancontact Card.giropayPayments made via giropay.dotpayPayments made via Dotpay.upiUPI Payments.netbanking_emandatesNetbanking (eMandates) Payments.
Show all values[+]
payment_method[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
payment_method[reference_id]
optional, string, max chars=200
The reference id. In the case of Amazon and PayPal this will be the billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
payment_method[tmp_token]
required if reference_id not provided, string, max chars=65k
Single-use toke created by payment gateways. In Stripe, a single-use token is created for direct debit. In Braintree, a nonce is created for PayPal.
payment_method[issuing_country]
optional, string, max chars=50
ISO 3166 alpha-2 country code.

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

If you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.
payment_method[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
.
always returned
Resource object representing customer.
optional
Resource object representing card.

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.

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

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

.
+
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
optional, string, max chars=150
The first name of the billing contact.
billing_address[last_name]
optional, string, max chars=150
The last name of the billing contact.
billing_address[email]
optional, string, max chars=70
The email address.
billing_address[company]
optional, string, max chars=250
The company name.
billing_address[phone]
optional, string, max chars=50
The phone number.
billing_address[line1]
optional, string, max chars=150
Address line 1.
billing_address[line2]
optional, string, max chars=150
Address line 2.
billing_address[line3]
optional, string, max chars=150
Address line 3.
billing_address[city]
optional, string, max chars=50
The name of the city.
billing_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
billing_address[state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
billing_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
billing_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

E-Invoicing

If country is provided as different from the existing value and if entity_identifier_scheme, entity_identifier_standard, and entity_identifier already exist and are not provided for this operation, they’re cleared.

.
billing_address[validation_status]
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
+
entity_identifiers
Parameters for entity_identifiers. Multiple entity_identifiers can be passed by specifying unique indices.
pass parameters as entity_identifiers[<param name>][<idx:0..n>]
entity_identifiers[id][0..n]
optional, string, max chars=40
The unique id for the entity_identifier[i] in Chargebee. This is required when entity_identifier[operation][i] is update or delete. .
entity_identifiers[scheme][0..n]
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 is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

.
entity_identifiers[value][0..n]
optional, string, max chars=50
The value of the entity_identifier. This identifies the customer entity on the Peppol network. For example: 10101010-STO-10.

Tip:

If there is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

.
entity_identifiers[operation][0..n]
optional, enumerated string
The operation to be performed for the entity_identifier. .
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.
entity_identifiers[standard][0..n]
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 is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

.
always returned
Resource object representing customer.
optional
Resource object representing card.
This API retrieves all the contacts for a customer.
Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlCK52cl/contacts \
     -G  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlCK52cl/contacts \
     -G  \
     -u {site_api_key}:

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
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.
always returned
Resource object representing contact.
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”.

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

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

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
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
primaryPrimary.backupBackup.noneNone.
always returned
Resource object representing customer.
always returned
Resource object representing payment_source.

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.

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

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
+
contact
Parameters for contact
pass parameters as contact[<param name>]
contact[id]
optional, string, max chars=150
Unique reference ID provided for the contact.
contact[first_name]
optional, string, max chars=150
First name of the contact.
contact[last_name]
optional, string, max chars=150
Last name of the contact.
contact[email]
required, string, max chars=70
Email of the contact.
contact[phone]
optional, string, max chars=50
Phone number of the contact.
contact[label]
optional, string, max chars=50
Label/Tag provided for contact.
contact[enabled]
optional, boolean, default=false
Contact enabled / disabled.
contact[send_billing_email]
optional, boolean, default=false
Whether Billing Emails option is enabled for the contact.
contact[send_account_email]
optional, boolean, default=false
Whether Account Emails option is enabled for the contact.
always returned
Resource object representing customer.
optional
Resource object representing card.

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.

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

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
+
contact
Parameters for contact
pass parameters as contact[<param name>]
contact[id]
required, string, max chars=150
Unique reference ID provided for the contact.
contact[first_name]
optional, string, max chars=150
First name of the contact.
contact[last_name]
optional, string, max chars=150
Last name of the contact.
contact[email]
optional, string, max chars=70
Email of the contact.
contact[phone]
optional, string, max chars=50
Phone number of the contact.
contact[label]
optional, string, max chars=50
Label/Tag provided for contact.
contact[enabled]
optional, boolean
Contact enabled / disabled.
contact[send_billing_email]
optional, boolean
Whether Billing Emails option is enabled for the contact.
contact[send_account_email]
optional, boolean
Whether Account Emails option is enabled for the contact.
always returned
Resource object representing customer.
optional
Resource object representing card.

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

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
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl9ta2cA/delete_contact \
     -u {site_api_key}:\
     -d contact[id]="contact___test__KyVnHhSBWl9uT2cC"

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
+
contact
Parameters for contact
pass parameters as contact[<param name>]
contact[id]
required, string, max chars=150
Unique reference ID provided for the contact.
always returned
Resource object representing customer.
optional
Resource object representing card.

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.

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

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
comment
optional, string, max chars=300
Remarks, if any, on the payment.
+
transaction
Parameters for transaction
pass parameters as transaction[<param name>]
transaction[amount]
required, in cents, min=1
The payment transaction amount.
transaction[currency_code]
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) for the transaction.
transaction[date]
required, timestamp(UTC) in seconds
Indicates when this transaction occurred.
transaction[payment_method]
required, enumerated string, default=card
The payment method of this transaction.
Possible values are
cashCash.checkCheck.
bank_transferBank Transfer.otherPayment Methods other than the above types.upiupi.netbanking_emandatesnetbanking_emandates.
Show all values[+]
transaction[reference_number]
optional, string, max chars=100
The reference number for this transaction. e.g check number in case of 'check' payments.
always returned
Resource object representing customer.
always returned
Resource object representing transaction.
This operation 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.

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"
copy

Sample Response [ JSON ]

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/collect_payment
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_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
payment_method[type]
optional, enumerated string
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
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.
genericPayments made via Generic Payment Method.alipayPayments made via Alipay.unionpayPayments made via UnionPay.apple_payPayments made via Apple Pay.wechat_payPayments made via WeChat Pay.idealPayments made via iDEAL.google_payPayments made via Google Pay.sofortPayments made via Sofort.bancontactPayments made via Bancontact Card.giropayPayments made via giropay.dotpayPayments made via Dotpay.upiUPI Payments.netbanking_emandatesNetbanking (eMandates) Payments.
Show all values[+]
payment_method[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
payment_method[reference_id]
optional, string, max chars=200
The reference id. In the case of Amazon and PayPal this will be the billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
payment_method[tmp_token]
required if reference_id not provided, string, max chars=65k
Single-use token created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet or card details. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
payment_method[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
.
+
card
Parameters for card
pass parameters as card[<param name>]
card[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
card[first_name]
optional, string, max chars=50
Cardholder's first name.
card[last_name]
optional, string, max chars=50
Cardholder's last name.
card[number]
required if card provided, string, max chars=1500
The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
card[expiry_month]
required if card provided, integer, min=1, max=12
Card expiry month.
card[expiry_year]
required if card provided, integer
Card expiry year.
card[cvv]
optional, string, max chars=520
The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
card[billing_addr1]
optional, string, max chars=150
Address line 1, as available in card billing address.
card[billing_addr2]
optional, string, max chars=150
Address line 2, as available in card billing address.
card[billing_city]
optional, string, max chars=50
City, as available in card billing address.
card[billing_state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
card[billing_state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
card[billing_zip]
optional, string, max chars=20
Postal or Zip code, as available in card billing address.
card[billing_country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

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

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

.
card[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
.
+
payment_intent
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
payment_intent[id]
optional, string, max chars=150
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
payment_intent[gateway_account_id]
required if payment intent token provided, string, max chars=50
The gateway account used for performing the 3DS flow.
payment_intent[gw_token]
optional, string, max chars=65k
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
payment_intent[payment_method_type]
optional, enumerated string
The list of payment method types (For example, card, ideal, sofort, bancontact, etc.) this Payment Intent is allowed to use. If payment method type is empty, Card is taken as the default type for all gateways except Razorpay.
Possible values are
cardcard.idealideal.sofortsofort.bancontactbancontact.
google_paygoogle_pay.dotpaydotpay.giropaygiropay.apple_payapple_pay.upiupi.netbanking_emandatesnetbanking_emandates.paypal_express_checkoutpaypal_express_checkout.
Show all values[+]
payment_intent[reference_id]
optional, string, max chars=65k
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
payment_intent[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
.
+
invoice_allocations
Parameters for invoice_allocations. Multiple invoice_allocations can be passed by specifying unique indices.
pass parameters as invoice_allocations[<param name>][<idx:0..n>]
invoice_allocations[invoice_id][0..n]
required, string, max chars=50
Identifier for the invoice. Multiple invoices can be passed.
invoice_allocations[allocation_amount][0..n]
optional, in cents, min=0
Amount that will override the Invoice amount to be collected. If not specified Invoice amount to collect will be taken as default. The unit depends on the type of currency.
always returned
Resource object representing customer.
always returned
Resource object representing transaction.

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

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
delete_payment_method
optional, boolean, default=true
Deletes the Payment Method from the gateway/vault.
always returned
Resource object representing customer.
optional
Resource object representing card.

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@chargebee.com 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
curl  https://{site}.chargebee.com/api/v2/customers/move \
     -u {site_api_key}:\
     -d id_at_from_site="__test__KyVnHhSBWlCxa2cx" \
     -d from_site="mannar"

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
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.
always returned
Resource object representing resource_migration.

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

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
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_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).
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
sundaySunday.mondayMonday.tuesdayTuesday.wednesdayWednesday.thursdayThursday.fridayFriday.saturdaySaturday.
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).
always returned
Resource object representing customer.

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@chargebee.com to get this enabled.
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
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"

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
from_customer_id
required, string, max chars=50
From customer id.
to_customer_id
required, string, max chars=50
To customer id.
always returned
Resource object representing customer.
Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5qO2b9/clear_personal_data \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5qO2b9/clear_personal_data \
     -X POST  \
     -u {site_api_key}:

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
always returned
Resource object representing customer.

Sets a customer into a hierarchical relationship with another. The path parameter customer_id is the id of the child in the relationship.

Note: For the use_default_hierarchy_settings, parent_account_access and child_account_access parameters, the 'parent' is the customer whose id is payment_owner_id. However, if the payment_owner_id is the child itself, then the parent is parent_id.
Sample Request
copy

Sample Response [ JSON ]

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/relationships
parent_id
optional, string, max chars=50
The id of the customer which is to be set as the immediate parent.
payment_owner_id
optional, string, max chars=50
The id of the customer who will pay the invoices for this customer. Can be the child itself or the invoice_owner_id.
invoice_owner_id
optional, string, max chars=50
The id of the customer who will be invoiced for charges incurred. Can be the child itself or any parent in its hierarchy.
use_default_hierarchy_settings
optional, boolean, default=true

The level of access that the parent and the child itself have to the child's information can be set here. This data falls into two categories:

  • Self-Serve Portal data: subscriptions and invoices of the child.
  • Email Notifications: subscription-, invoice- and payment-related notifications for the child.

Usage:

  • Value set to true: Applies the global access levels defined in the Account Hierarchy settings to this child. These global settings are configured in the admin console
  • Value set to false: Customizes the access levels for this customer. Pass the parent_account_access and child_account_access parameters to specify the settings. If you skip passing any parameters, the global settings are applied for them.
.
+
parent_account_access
Parameters for parent_account_access
pass parameters as parent_account_access[<param name>]
parent_account_access[portal_edit_child_subscriptions]
optional, enumerated string
Sets parent's level of access to child subscriptions on the Self-Serve Portal.
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.
parent_account_access[portal_download_child_invoices]
optional, enumerated string
Sets parent's level of access to child invoices on the Self-Serve Portal.
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.
parent_account_access[send_subscription_emails]
optional, boolean
If true, the parent account will receive subscription-related emails sent to the child account.
parent_account_access[send_payment_emails]
optional, boolean
If true, the parent account will receive payment-related emails sent to the child account.
parent_account_access[send_invoice_emails]
optional, boolean
If true, the parent account will receive invoice-related emails sent to the child account.
+
child_account_access
Parameters for child_account_access
pass parameters as child_account_access[<param name>]
child_account_access[portal_edit_subscriptions]
optional, enumerated string
Sets the child's level of access to its own subscriptions on the Self-Serve Portal.
Possible values are
yesThe child account can view and edit its own subscriptions.view_onlyThe child account can only view its own subscriptions.
child_account_access[portal_download_invoices]
optional, enumerated string
Sets the child’s level of access to its own invoices on the Self-Serve Portal.
Possible values are
yesThe child account can view and download its own invoices.view_onlyThe child account can only view its invoices and not download them.noThe child account can neither view nor download its own invoices.
child_account_access[send_subscription_emails]
optional, boolean
If true, the child account will receive subscription-related emails for its own subscriptions.
child_account_access[send_payment_emails]
optional, boolean
If true, the child account will receive payment-related emails for its own invoices.
child_account_access[send_invoice_emails]
optional, boolean
If true, the child account will receive invoice-related emails for its own invoices.
always returned
Resource object representing customer.
Disconnects a child customer from its parent. customer_id is the id of the child.
Sample Request
copy
# deletes a customer from hierarchy
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlAG12cF/delete_relationship \
     -X POST  \
     -u {site_api_key}:

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
always returned
Resource object representing customer.
Retrieves the account hierarchy tree for the customer.
Sample Request
# retrieves all the customers in a hierarchy
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlAkY2cO/hierarchy \
     -u {site_api_key}:\
     -d hierarchy_operation_type="complete_hierarchy"
copy

Sample Response [ JSON ]

URL Format GET

https://{site}.chargebee.com/api/v2/customers/{customer_id}/hierarchy
hierarchy_operation_type
required, enumerated string
Selects the specific part of the hierarchy to be fetched.
Possible values are
complete_hierarchyList the nodes of the full hierarchy to which the customer belongs.subordinatesList all the nodes of the hierarchy formed by the customer and its subordinates. In other words, fetch the nodes of the tree whose root node is the customer.path_to_rootList the nodes along the path from the customer to the root of the full hierarchy.
always returned
Resource object representing hierarchy.

Changes the level of access that the parent or the child itself has to the child's information.

This data falls into two categories:

  • Self-Serve Portal data: subscriptions and invoices of the child.
  • Email Notifications: subscription-, invoice- and payment-related notifications for the child.
The 'parent' is the customer whose id is payment_owner_id. However, if the payment_owner_id is the child itself, then the parent is parent_id. The path parameter customer_id is the id of the child in the relationship.

Note: This endpoint cannot be used to change the parent_id, invoice_owner_id or payment_owner_id for the customer. To change them, delink the customer and then call Link a customer again.
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 \
     -X POST  \
     -u {site_api_key}:\
     -d use_default_hierarchy_settings="true"
copy

Sample Response [ JSON ]

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/update_hierarchy_settings
use_default_hierarchy_settings
optional, boolean, default=true

Determines whether the site default settings are applied for the access levels.

  • Value set to true: Removes any customized access levels for the customer. The global settings configured in the admin console now apply.
  • Value set to false: Changes the access levels for this customer. Pass the parent_account_access and child_account_access parameters to specify the new settings. If you skip passing any parameters, they will remain unchanged.
.
+
parent_account_access
Parameters for parent_account_access
pass parameters as parent_account_access[<param name>]
parent_account_access[portal_edit_child_subscriptions]
optional, enumerated string
Sets parent's level of access to child subscriptions on the Self-Serve Portal.
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.
parent_account_access[portal_download_child_invoices]
optional, enumerated string
Sets parent's level of access to child invoices on the Self-Serve Portal.
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.
parent_account_access[send_subscription_emails]
optional, boolean
If true, the parent account will receive subscription-related emails sent to the child account.
parent_account_access[send_payment_emails]
optional, boolean
If true, the parent account will receive payment-related emails sent to the child account.
parent_account_access[send_invoice_emails]
optional, boolean
If true, the parent account will receive invoice-related emails sent to the child account.
+
child_account_access
Parameters for child_account_access
pass parameters as child_account_access[<param name>]
child_account_access[portal_edit_subscriptions]
optional, enumerated string
Sets the child's level of access to its own subscriptions on the Self-Serve Portal.
Possible values are
yesThe child account can view and edit its own subscriptions.view_onlyThe child account can only view its own subscriptions.
child_account_access[portal_download_invoices]
optional, enumerated string
Sets the child’s level of access to its own invoices on the Self-Serve Portal.
Possible values are
yesThe child account can view and download its own invoices.view_onlyThe child account can only view its invoices and not download them.noThe child account can neither view nor download its own invoices.
child_account_access[send_subscription_emails]
optional, boolean
If true, the child account will receive subscription-related emails for its own subscriptions.
child_account_access[send_payment_emails]
optional, boolean
If true, the child account will receive payment-related emails for its own invoices.
child_account_access[send_invoice_emails]
optional, boolean
If true, the child account will receive invoice-related emails for its own invoices.
always returned
Resource object representing customer.