Customers

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_month

optional, integer, min=1, max=12

billing_month, together with billing_date, specify, for this customer, the day of the year when the renewals of all the year-based subscriptions take place.

For example, the renewals happen on 15th July when billing_month is 7 and billing_date is 15.

Note

Applicable when Calendar Billing (with customer-specific billing date support) is enabled and billing_date_mode is manually_set.

billing_date_mode

optional, enumerated string
Indicates whether this customer's billing_date value is derived as per configurations or its specifically set (overriden). When specifically set, the billing_date will not be reset even when all of the monthly/yearly subscriptions are cancelled.

Possible values are

using_defaultsBilling date is set based on defaults configured.manually_setBilling date is specifically set (default configuration is overridden).

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
The 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_validThe address is valid for taxability but has not been validated for shipping.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 Candyreferral_saasquatchReferral SaasquatchfriendbuyFriendbuy

contacts
Show attributes[+]

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.chargebee_paymentsChargebee Payments gatewaystripeStripe is a payment gateway.wepayWePay is a payment gateway.

braintreeBraintree is a payment gateway.authorize_netAuthorize.net is a payment gatewaypaypal_proPayPal Pro Account is a payment gateway.pinPin is a payment gatewayewayeWAY Account is a payment gateway.eway_rapideWAY Rapid is a payment gateway.worldpayWorldPay is a payment gatewaybalanced_paymentsBalanced is a payment gatewaybeanstreamBambora(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 AccounthdfcHDFC 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 gatewayrazorpayRazorpay 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.global_paymentsGlobal Payments is a payment service provider.bank_of_americaBank of America Gatewaynot_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 expiredinvalidThe 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.

balances
Show attributes[+]

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:

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:

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

# creates a customer with billing address.
curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d email="john@test.com" \
     -d locale="fr-CA" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

# creates a customer with bank account.
curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d allow_direct_debit="true" \
     -d email="john@test.com" \
     -d bank_account[account_number]="000222222227" \
     -d bank_account[routing_number]="110000000" \
     -d bank_account[bank_name]="US Bank" \
     -d bank_account[account_holder_type]="individual" \
     -d bank_account[account_type]="savings" \
     -d bank_account[first_name]="Shay" \
     -d bank_account[last_name]="Liam" \
     -d bank_account[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju"

# creates a customer with card details.
curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d email="john@test.com" \
     -d card[first_name]="Richard" \
     -d card[last_name]="Fox" \
     -d card[number]="4012888888881881" \
     -d card[expiry_month]=10 \
     -d card[expiry_year]=2022 \
     -d card[cvv]="999"

# creates a customer with payment source.
# NOTE :  The parameters paymentMethod[tmp_token] and paymentMethod[reference_id] should not be passed together.
curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d payment_method[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju" \
     -d payment_method[type]="card" \
     -d payment_method[reference_id]="cus_I58PkwpAskxXlJ"

Sample Response [ JSON ]

{"customer": {
    "allow_direct_debit": false,
    "auto_collection": "on",
    "billing_address": {
        "city": "Walnut",
        "country": "US",
        "first_name": "John",
        "last_name": "Doe",
        "line1": "PO Box 9999",
        "object": "billing_address",
        "state": "California",
        "state_code": "CA",
        "validation_status": "not_validated",
        "zip": "91789"
    },
    "card_status": "no_card",
    "created_at": 1517505731,
    "deleted": false,
    "email": "john@test.com",
    "excess_payments": 0,
    "first_name": "John",
    "id": "__test__KyVnHhSBWl7eY2bl",
    "last_name": "Doe",
    "locale": "fr-CA",
    "net_term_days": 0,
    "object": "customer",
    "pii_cleared": "active",
    "preferred_currency_code": "USD",
    "promotional_credits": 0,
    "refundable_credits": 0,
    "resource_version": 1517505731000,
    "taxability": "taxable",
    "unbilled_charges": 0,
    "updated_at": 1517505731
}}

{"customer": {
    "allow_direct_debit": true,
    "auto_collection": "on",
    "created_at": 1517505733,
    "deleted": false,
    "email": "john@test.com",
    "excess_payments": 0,
    "first_name": "John",
    "id": "__test__KyVnHhSBWl8Ni2bt",
    "last_name": "Doe",
    "net_term_days": 0,
    "object": "customer",
    "payment_method": {
        "gateway": "stripe",
        "gateway_account_id": "gw___test__KyVnGlSBWl8M41ju",
        "object": "payment_method",
        "reference_id": "cus_I58PxQNyWviXnc/ba_1HUy94Jv9j0DyntJTimRcJbw",
        "status": "pending_verification",
        "type": "direct_debit"
    },
    "pii_cleared": "active",
    "preferred_currency_code": "USD",
    "primary_payment_source_id": "pm___test__KyVnHhSBWl8eE2bu",
    "promotional_credits": 0,
    "refundable_credits": 0,
    "resource_version": 1517505734000,
    "taxability": "taxable",
    "unbilled_charges": 0,
    "updated_at": 1517505734
}}

{
    "card": {
        "card_type": "visa",
        "created_at": 1517505732,
        "customer_id": "__test__KyVnHhSBWl81p2bn",
        "expiry_month": 10,
        "expiry_year": 2022,
        "first_name": "Richard",
        "funding_type": "not_known",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
        "iin": "401288",
        "last4": "1881",
        "last_name": "Fox",
        "masked_number": "************1881",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWl82m2bp",
        "resource_version": 1517505732000,
        "status": "valid",
        "updated_at": 1517505732
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505732,
        "deleted": false,
        "email": "john@test.com",
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWl81p2bn",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWl82h2bo",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWl82m2bp",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505732000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505732
    }
}

{
    "card": {
        "card_type": "visa",
        "created_at": 1517505737,
        "customer_id": "__test__KyVnHhSBWl9AC2c3",
        "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__KyVnHhSBWl9Fw2c4",
        "powered_by": "not_applicable",
        "resource_version": 1517505737000,
        "status": "valid",
        "updated_at": 1517505737
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505736,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWl9AC2c3",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__KyVnGlSBWl8M41ju",
            "object": "payment_method",
            "reference_id": "cus_I58PkwpAskxXlJ/card_1HUy96Jv9j0DyntJq6XwrBKd",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWl9Fw2c4",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505737000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505737
    }
}

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

vat_number_prefix

entity_identifier_scheme

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

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

is_einvoice_enabled

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

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

customer_type

optional, enumerated string
Indicates the type of the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.

Possible values are

residentialWhen the purchase is made by a customer for home usebusinessWhen the purchase is made at a place of businesssenior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaksindustrialWhen the purchase is made by an industrial business

client_profile_id

optional, string, max chars=50
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.

taxjar_exemption_category

optional, enumerated string
Indicates the exemption type of the customer. This is applicable only if you use Chargebee’s TaxJar integration.

Possible values are

wholesaleWhole-salegovernmentGovernmentotherOther

business_customer_without_vat_number

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

locale

entity_code

optional, enumerated string
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration.

Possible values are

aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat

eCharitable or benevolent organizationfReligious organizationgResalehCommercial agricultural productioniIndustrial production/manufacturerjDirect pay permitkDirect maillOther or custommEducational organizationnLocal governmentpCommercial aquacultureqCommercial FisheryrNon-residentmed1US Medical Device Excise Tax with exempt sales taxmed2US Medical Device Excise Tax with taxable sales tax

Show all values[+]

exempt_number

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 PreferencecashCashcheckCheckbank_transferBank Transferach_creditACH Creditsepa_creditSEPA Credit

auto_close_invoices

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]

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]

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.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
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.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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 AccountsavingsSavings Accountbusiness_checkingBusiness Checking AccountcurrentCurrent 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

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.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
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.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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

cardcardidealidealsofortsofortbancontactbancontact

google_paygoogle_paydotpaydotpaygiropaygiropayapple_payapple_payupiupinetbanking_emandatesnetbanking_emandatespaypal_express_checkoutpaypal_express_checkoutdirect_debitdirect_debit

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.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
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.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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]

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

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]

Tip:

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:

entity_identifiers[standard][0..n]

Tip:

customer

always returned
Resource object representing customer

card

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 ]

{"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_not] = "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_not] = "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] = "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[on] = "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[on] = "1243545465"

business_entity_id[<operator>]

optional, string filter
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.

Supported operators : is, is_not, starts_with

Example → business_entity_id[is] = "business_entity_id"

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

customer

always returned
Resource object representing customer

card

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 ]

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

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

Sample admin console URL

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

Updates the customer resource. However, this method cannot be used for updating the 'Billing Info' - the Billing Address and 'vat_number' attributes - of the customer. To update the same, use our Update Billing Info API.

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 ]

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

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

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

client_profile_id

optional, string, max chars=50
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.

taxjar_exemption_category

optional, enumerated string
Indicates the exemption type of the customer. This is applicable only if you use Chargebee’s TaxJar integration.

Possible values are

wholesaleWhole-salegovernmentGovernmentotherOther

locale

entity_code

optional, enumerated string
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration.

Possible values are

aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat

Show all values[+]

exempt_number

offline_payment_method

optional, enumerated string
The preferred offline payment method for the customer.

Possible values are

no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transferach_creditACH Creditsepa_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

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 safefraudulentThe customer has been marked as fraudulent

consolidated_invoicing

optional, boolean

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

always returned
Resource object representing customer

card

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 ]

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

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]

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]

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.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
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.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

customer

always returned
Resource object representing customer

card

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 ]

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

vat_number_prefix

entity_identifier_scheme

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

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

business_customer_without_vat_number

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

is_einvoice_enabled

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]

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

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]

Tip:

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:

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]

Tip:

customer

always returned
Resource object representing customer

card

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 ]

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

contact

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 ]

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

primaryPrimarybackupBackupnoneNone

customer

always returned
Resource object representing customer

payment_source

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 ]

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

customer

always returned
Resource object representing customer

card

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 ]

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

customer

always returned
Resource object representing customer

card

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 ]

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

customer

always returned
Resource object representing customer

card

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 ]

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

cashCashcheckCheck

bank_transferBank TransferotherPayment Methods other than the above typescustomCustom

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.

customer

always returned
Resource object representing customer

transaction

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

# collects payment for the customer with the existing payment source.
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl6A32bF/collect_payment \
     -X POST  \
     -u {site_api_key}:\
     -d amount=100 \
     -d payment_source_id="pm___test__KyVnHhSBWl6Q02bG" \
     -d invoice_allocations[invoice_id][0]="__demo_inv__1"

# collects payment for the customer using new payment source.
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl78A2bV/collect_payment \
     -X POST  \
     -u {site_api_key}:\
     -d card[number]="378282246310005" \
     -d card[expiry_month]=10 \
     -d card[expiry_year]=2022 \
     -d card[cvv]="999" \
     -d invoice_allocations[invoice_id][0]="__demo_inv__2"

Sample Response [ JSON ]

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

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505729,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWl78A2bV",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505729000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505729
    },
    "transaction": {
        "amount": 1095,
        "amount_unused": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWl78A2bV",
        "date": 1517505729,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
        "id": "txn___test__KyVnHhSBWl7FU2bg",
        "id_at_gateway": "cb___test__KyVnHhSBWl7FZ2bh",
        "linked_invoices": [
            {
                "applied_amount": 1095,
                "applied_at": 1517505729,
                "invoice_date": 1517505729,
                "invoice_id": "__demo_inv__2",
                "invoice_status": "paid",
                "invoice_total": 1095
            },
            {..}
        ],
        "linked_refunds": [],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "resource_version": 1517505729000,
        "status": "success",
        "subscription_id": "__test__KyVnHhSBWl7AE2bX",
        "type": "payment",
        "updated_at": 1517505729
    }
}

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

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]

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.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
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.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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]

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]

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.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
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.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

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]

payment_intent[payment_method_type]

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

google_paygoogle_paydotpaydotpaygiropaygiropayapple_payapple_payupiupinetbanking_emandatesnetbanking_emandatespaypal_express_checkoutpaypal_express_checkoutdirect_debitdirect_debit

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.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
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.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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.

customer

always returned
Resource object representing customer

transaction

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 ]

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

customer

always returned
Resource object representing customer

card

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

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

resource_migration

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 ]

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

billing_month

optional, integer, min=1, max=12

billing_month, together with billing_date, specify, for this customer, the day of the year when the renewals of all the year-based subscriptions take place.

For example, the renewals happen on 15th July when billing_month is 7 and billing_date is 15.

Note

Applicable when Calendar Billing (with customer-specific billing date support) is enabled and billing_date_mode is manually_set.

billing_date_mode

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

Possible values are

sundaySundaymondayMondaytuesdayTuesdaywednesdayWednesdaythursdayThursdayfridayFridaysaturdaySaturday

billing_day_of_week_mode

Possible values are

using_defaultsBilling date is set based on defaults configured.manually_setBilling date is specifically set (default configuration is overridden)

customer

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

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

customer

always returned
Resource object representing customer

Clear personal details of a customer using this API.

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 ]

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

customer

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

In the descriptions for 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 set as the ID of the child itself ({customer_id}), then the "parent" is parent_id.
The parent and the child customers must belong to the same business entity.

Sample Request

# creates a relationship for reporting purpose
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDY12d5/relationships \
     -u {site_api_key}:\
     -d parent_id="__test__KyVnHhSBWlDa22d7" \
     -d payment_owner_id="__test__KyVnHhSBWlDY12d5" \
     -d invoice_owner_id="__test__KyVnHhSBWlDY12d5"

copy

# creates a relationship for reporting purpose
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDY12d5/relationships \
     -u {site_api_key}:\
     -d parent_id="__test__KyVnHhSBWlDa22d7" \
     -d payment_owner_id="__test__KyVnHhSBWlDY12d5" \
     -d invoice_owner_id="__test__KyVnHhSBWlDY12d5"

# creates a completely dependent relationship
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDwm2dJ/relationships \
     -u {site_api_key}:\
     -d parent_id="__test__KyVnHhSBWlDrp2dC" \
     -d payment_owner_id="__test__KyVnHhSBWlDrp2dC" \
     -d invoice_owner_id="__test__KyVnHhSBWlDrp2dC"

# creates a relationship and sets custom parent/child access settings
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlEhB2dd/relationships \
     -u {site_api_key}:\
     -d parent_id="__test__KyVnHhSBWlEc92dW" \
     -d payment_owner_id="__test__KyVnHhSBWlEc92dW" \
     -d invoice_owner_id="__test__KyVnHhSBWlEhB2dd" \
     -d use_default_hierarchy_settings="false" \
     -d parent_account_access[portal_edit_child_subscriptions]="yes" \
     -d parent_account_access[portal_download_child_invoices]="yes" \
     -d parent_account_access[send_subscription_emails]="true" \
     -d parent_account_access[send_payment_emails]="false" \
     -d parent_account_access[send_invoice_emails]="false" \
     -d child_account_access[portal_edit_subscriptions]="view_only" \
     -d child_account_access[portal_download_invoices]="view_only" \
     -d child_account_access[send_subscription_emails]="true" \
     -d child_account_access[send_payment_emails]="true" \
     -d child_account_access[send_invoice_emails]="true"

# creates a partially dependent relationship
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlEIc2dT/relationships \
     -u {site_api_key}:\
     -d parent_id="__test__KyVnHhSBWlEDb2dM" \
     -d payment_owner_id="__test__KyVnHhSBWlEDb2dM" \
     -d invoice_owner_id="__test__KyVnHhSBWlEIc2dT"

Sample Response [ JSON ]

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

{"customer": {
    "allow_direct_debit": false,
    "auto_collection": "on",
    "card_status": "no_card",
    "child_account_access": {
        "portal_download_invoices": "view_only",
        "portal_edit_subscriptions": "yes",
        "send_invoice_emails": true,
        "send_payment_emails": true,
        "send_subscription_emails": true
    },
    "created_at": 1517505755,
    "deleted": false,
    "excess_payments": 0,
    "first_name": "Clara",
    "id": "__test__KyVnHhSBWlDwm2dJ",
    "last_name": "Cooper",
    "net_term_days": 0,
    "object": "customer",
    "parent_account_access": {
        "portal_download_child_invoices": "yes",
        "portal_edit_child_subscriptions": "view_only",
        "send_invoice_emails": true,
        "send_payment_emails": true,
        "send_subscription_emails": false
    },
    "pii_cleared": "active",
    "preferred_currency_code": "USD",
    "promotional_credits": 0,
    "refundable_credits": 0,
    "relationship": {
        "invoice_owner_id": "__test__KyVnHhSBWlDrp2dC",
        "parent_id": "__test__KyVnHhSBWlDrp2dC",
        "payment_owner_id": "__test__KyVnHhSBWlDrp2dC",
        "root_id": "__test__KyVnHhSBWlDtT2dE"
    },
    "resource_version": 1517505755000,
    "taxability": "taxable",
    "unbilled_charges": 0,
    "updated_at": 1517505755,
    "use_default_hierarchy_settings": true
}}

{"customer": {
    "allow_direct_debit": false,
    "auto_collection": "on",
    "card_status": "no_card",
    "child_account_access": {
        "portal_download_invoices": "view_only",
        "portal_edit_subscriptions": "view_only",
        "send_invoice_emails": true,
        "send_payment_emails": true,
        "send_subscription_emails": true
    },
    "created_at": 1517505758,
    "deleted": false,
    "excess_payments": 0,
    "first_name": "Clara",
    "id": "__test__KyVnHhSBWlEhB2dd",
    "last_name": "Cooper",
    "net_term_days": 0,
    "object": "customer",
    "parent_account_access": {
        "portal_download_child_invoices": "yes",
        "portal_edit_child_subscriptions": "yes",
        "send_invoice_emails": false,
        "send_payment_emails": false,
        "send_subscription_emails": true
    },
    "pii_cleared": "active",
    "preferred_currency_code": "USD",
    "promotional_credits": 0,
    "refundable_credits": 0,
    "relationship": {
        "invoice_owner_id": "__test__KyVnHhSBWlEhB2dd",
        "parent_id": "__test__KyVnHhSBWlEc92dW",
        "payment_owner_id": "__test__KyVnHhSBWlEc92dW",
        "root_id": "__test__KyVnHhSBWlEdx2dY"
    },
    "resource_version": 1517505758000,
    "taxability": "taxable",
    "unbilled_charges": 0,
    "updated_at": 1517505758,
    "use_default_hierarchy_settings": false
}}

{"customer": {
    "allow_direct_debit": false,
    "auto_collection": "on",
    "card_status": "no_card",
    "child_account_access": {
        "portal_download_invoices": "view_only",
        "portal_edit_subscriptions": "yes",
        "send_invoice_emails": true,
        "send_payment_emails": true,
        "send_subscription_emails": true
    },
    "created_at": 1517505756,
    "deleted": false,
    "excess_payments": 0,
    "first_name": "Clara",
    "id": "__test__KyVnHhSBWlEIc2dT",
    "last_name": "Cooper",
    "net_term_days": 0,
    "object": "customer",
    "parent_account_access": {
        "portal_download_child_invoices": "yes",
        "portal_edit_child_subscriptions": "view_only",
        "send_invoice_emails": true,
        "send_payment_emails": true,
        "send_subscription_emails": false
    },
    "pii_cleared": "active",
    "preferred_currency_code": "USD",
    "promotional_credits": 0,
    "refundable_credits": 0,
    "relationship": {
        "invoice_owner_id": "__test__KyVnHhSBWlEIc2dT",
        "parent_id": "__test__KyVnHhSBWlEDb2dM",
        "payment_owner_id": "__test__KyVnHhSBWlEDb2dM",
        "root_id": "__test__KyVnHhSBWlEFE2dO"
    },
    "resource_version": 1517505756000,
    "taxability": "taxable",
    "unbilled_charges": 0,
    "updated_at": 1517505756,
    "use_default_hierarchy_settings": true
}}

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

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

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

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.

customer

always returned
Resource object representing customer

Disconnects a child customer from its parent. customer_id is the id of the child.

Sample Request

# deletes a customer from hierarchy
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlAG12cF/delete_relationship \
     -X POST  \
     -u {site_api_key}:

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 ]

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

customer

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

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

# retrieves customers in same chain from root to node
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlBci2cc/hierarchy \
     -u {site_api_key}:\
     -d hierarchy_operation_type="path_to_root"

# retrieves customers which are the subordinates
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlBEG2cV/hierarchy \
     -u {site_api_key}:\
     -d hierarchy_operation_type="subordinates"

Sample Response [ JSON ]

{"hierarchies": [
    {
        "children_ids": [
            "__test__KyVnHhSBWlAkY2cO",
            {..}
        ],
        "customer_id": "__test__KyVnHhSBWlAmZ2cQ",
        "invoice_owner_id": "__test__KyVnHhSBWlAmZ2cQ",
        "object": "hierarchy",
        "payment_owner_id": "__test__KyVnHhSBWlAmZ2cQ"
    },
    {..}
]}

{"hierarchies": [
    {
        "children_ids": [
            "__test__KyVnHhSBWlBci2cc",
            {..}
        ],
        "customer_id": "__test__KyVnHhSBWlBfT2ce",
        "invoice_owner_id": "__test__KyVnHhSBWlBfT2ce",
        "object": "hierarchy",
        "payment_owner_id": "__test__KyVnHhSBWlBfT2ce"
    },
    {..}
]}

{"hierarchies": [
    {
        "children_ids": [],
        "customer_id": "__test__KyVnHhSBWlBEG2cV",
        "invoice_owner_id": "__test__KyVnHhSBWlBEG2cV",
        "object": "hierarchy",
        "parent_id": "__test__KyVnHhSBWlBGy2cX",
        "payment_owner_id": "__test__KyVnHhSBWlBEG2cV"
    },
    {..}
]}

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.

hierarchies

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

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

# Updates all of the "parent_account_access" and "child_account_access" settings for a
# customer.
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlGoZ2e7/update_hierarchy_settings \
     -X POST  \
     -u {site_api_key}:\
     -d use_default_hierarchy_settings="false" \
     -d child_account_access[portal_edit_subscriptions]="yes" \
     -d child_account_access[portal_download_invoices]="yes" \
     -d child_account_access[send_subscription_emails]="true" \
     -d child_account_access[send_payment_emails]="true" \
     -d child_account_access[send_invoice_emails]="true" \
     -d parent_account_access[portal_edit_child_subscriptions]="view_only" \
     -d parent_account_access[portal_download_child_invoices]="yes" \
     -d parent_account_access[send_subscription_emails]="false" \
     -d parent_account_access[send_payment_emails]="false" \
     -d parent_account_access[send_invoice_emails]="false"

# Updates only some of the "parent_account_access" and "child_account_access" settings for
# a customer
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlGQc2e0/update_hierarchy_settings \
     -X POST  \
     -u {site_api_key}:\
     -d use_default_hierarchy_settings="false" \
     -d parent_account_access[portal_edit_child_subscriptions]="yes" \
     -d parent_account_access[portal_download_child_invoices]="yes" \
     -d parent_account_access[send_invoice_emails]="false" \
     -d child_account_access[portal_download_invoices]="yes" \
     -d child_account_access[send_invoice_emails]="true"

Sample Response [ JSON ]

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

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

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

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

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

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

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.

customer

always returned
Resource object representing customer

Sample customer [ JSON ]

API Index URL GET

Customer attributes

Create a customer¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List customers¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Retrieve a customer¶

Sample Response [ JSON ]

URL Format GET

Returns

Sample admin console URL

Update a customer¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Update payment method for a customer¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Update billing info for a customer¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List of contacts for a customer¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

Assign payment role¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Add contacts to a customer¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Update contacts for a customer¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Delete contacts for a customer¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Record an excess payment for a customer¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Collect payment for customer¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Delete a customer¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Move a customer¶

Notes

Sample Response [ JSON ]