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.

The Billing Address is significant especially when EU VAT taxes are involved, for tax calculations will be based on this address. For customers without Billing Address, EU VAT taxes will not be included. Thus ensure to set this properly if you have configured EU VAT Tax.

Note: For the customers who signed up before 1st Mar 2014, Customer's Billing Address and 'vat_number' will be replaced automatically whenever the associated Card gets updated. i.e existing values for Billing Address and 'vat_number' will be cleared and the new values will be set. This behaviour is changed now - The VAT Number should always be passed along Billing Address and not with Card address. Both the addresses have to be dealt separately.

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

Identifier of the customer.
string, max chars=50

first_name

First name of the customer.
optional, string, max chars=150

last_name

Last name of the customer.
optional, string, max chars=150

email

Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70

phone

Phone number of the customer.
optional, string, max chars=50

company

Company name of the customer.
optional, string, max chars=250

vat_number

VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20

auto_collection

Whether payments needs to be collected automatically for this customer.
enumerated string, default=on

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

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

Possible values are

no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.

net_term_days

The number of days within which the customer has to make payment for the invoice.
integer, default=0

vat_number_validated_time

Returns the recent VAT number validation time.
optional, timestamp(UTC) in seconds

vat_number_status

This is only applicable if you have configured EU and Australian taxes and the VAT number validation is enabled.
optional, enumerated string

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

Whether the customer can pay via Direct Debit.
boolean, default=false

is_location_valid

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.
optional, boolean

created_at

Timestamp indicating when this customer resource is created.
timestamp(UTC) in seconds

created_from_ip

The IP address of the customer. Used primarly for referral integration and EU VAT validation.
optional, string, max chars=50

exemption_details

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.
optional, jsonarray

taxability

Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable

Possible values are

taxableCustomer is taxable.exempt

Customer is exempted from tax
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

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

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

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.
optional, string, max chars=100

resource_version

Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long

updated_at

Timestamp indicating when this customer was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, timestamp(UTC) in seconds

locale

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.
optional, string, max chars=50

billing_date

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.
optional, integer, min=1, max=31

billing_date_mode

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

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

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

Possible values are

sundaySunday.mondayMonday.tuesdayTuesday.wednesdayWednesday.thursdayThursday.fridayFriday.saturdaySaturday.

billing_day_of_week_mode

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

Possible values are

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

pii_cleared

Indicates whether this customer's personal information has been cleared .
optional, enumerated string, default=active

Possible values are

activeActive.scheduled_for_clearScheduled For Clear.clearedCleared.

fraud_flag

Indicates whether or not the customer has been identified as fraudulent.
optional, enumerated string

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

Primary payment source for the customer.
optional, string, max chars=40

backup_payment_source_id

Backup payment source for the customer. Used to collect payment if primary payment source fails.
optional, string, max chars=40

invoice_notes

Invoice Notes for this resource. Read More.
optional, string, max chars=2000

preferred_currency_code

TThe currency code of the customer's preferred currency (ISO 4217 format). Applicable if the Multicurrency feature is enabled.
optional, string, max chars=3

promotional_credits

Promotional credits balance of this customer.
in cents, min=0

unbilled_charges

Total unbilled charges for this customer.
in cents, min=0

refundable_credits

Refundable credits balance of this customer.
in cents, min=0

excess_payments

Total unused payments associated with the customer.
in cents, min=0

meta_data

A set of key-value pairs stored as additional information for the subscription.
optional, jsonobject

deleted

Indicates that this resource has been deleted.
boolean

registered_for_gst

Confirms that a customer is registered under GST. This field is available for Australia only.
optional, boolean

consolidated_invoicing

optional, boolean

customer_type

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

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

Confirms that a customer is a valid business without VAT number.
optional, boolean

client_profile_id

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

use_default_hierarchy_settings

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.

.
optional, boolean, default=true

billing_address
Show attributes[+]

Billing address for a customer.
optional, billing_address

Billing addres attributes

first_name

The first name of the billing contact.
optional, string, max chars=150

last_name

The last name of the billing contact.
optional, string, max chars=150

email

The email address.
optional, string, max chars=70

company

The company name.
optional, string, max chars=250

phone

The phone number.
optional, string, max chars=50

line1

Address line 1.
optional, string, max chars=150

line2

Address line 2.
optional, string, max chars=150

line3

Address line 3.
optional, string, max chars=150

city

The name of the city.
optional, string, max chars=50

state_code

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50

state

State or Province.
optional, string, max chars=50

country

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

zip

Zip or Postal code.
optional, string, max chars=20

validation_status

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

referral_urls
Show attributes[+]

List of referral urls for the customer (if applicable).
optional, list of referral_url

Referral url attributes

external_customer_id

External customer id in the referral system.
optional, string, max chars=100

referral_sharing_url

Referral sharing url for the customer.
string, max chars=50

created_at

The referral url creation time.
timestamp(UTC) in seconds

updated_at

The referral url updation time.
timestamp(UTC) in seconds

referral_campaign_id

Referral campaign id.
string, max chars=50

referral_account_id

Referral account id.
string, max chars=50

referral_external_campaign_id

Referral external campaign id.
optional, string, max chars=50

referral_system

Url for the referral system account.
enumerated string

Possible values are

referral_candyReferral Candy.referral_saasquatchReferral Saasquatch.friendbuyFriendbuy.

contacts
Show attributes[+]

contacts.
optional, list of contact

Contact attributes

id

Unique reference ID provided for the contact.
string, max chars=150

first_name

First name of the contact.
optional, string, max chars=150

last_name

Last name of the contact.
optional, string, max chars=150

email

Email of the contact.
string, max chars=70

phone

Phone number of the contact.
optional, string, max chars=50

label

Label/Tag provided for contact.
optional, string, max chars=50

enabled

Contact enabled / disabled.
boolean, default=false

send_account_email

Whether Account Emails option is enabled for the contact.
boolean, default=false

send_billing_email

Whether Billing Emails option is enabled for the contact.
boolean, default=false

payment_method
Show attributes[+]

Primary Payment Source of the customer.
optional, payment_method

Payment method attributes

type

Type of payment source.
enumerated string

Possible values are

cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.

genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.

Show all values[+]

gateway

Name of the gateway the payment method is associated with.
enumerated string

Possible values are

chargebeeChargebee test gateway.stripeStripe payment gateway.wepayWePay Gateway.braintreeBraintree payment gateway.

authorize_netAuthorize.net payment gateway.paypal_proPaypal Pro Account.pinPin payment gateway.ewayeWAY Account.eway_rapideWAY Rapid gateway.worldpayWorldPay payment gateway.balanced_paymentsBalanced payment gateway.beanstreamBambora (formerly Beanstream).bluepayBluePay payment gateway.elavonElavon Virtual Merchant.first_data_globalFirst Data Global Gateway Virtual Terminal Account.hdfcHDFC Account.migsMasterCard Internet Gateway Service.nmiNMI gateway.ogoneIngenico ePayments (formerly Ogone).paymillPAYMILL payment gateway.paypal_payflow_proPayPal Payflow Pro gateway.sage_paySage Pay gateway.tco2Checkout payment gateway.wirecardWireCard Account.amazon_paymentsThe amazon payments.paypal_express_checkoutThe paypal gateway.gocardlessGoCardless.adyenAdyen.orbitalChase Paymentech(Orbital) Gateway.moneris_usMoneris USA Gateway.monerisMoneris Gateway.bluesnapBlueSnap gateway.cybersourceCyberSource gateway.vantivVantiv gateway.checkout_comCheckout.com Gateway.paypalPaypal Commerce.not_applicableIndicates that payment gateway is not applicable for this resource.

Show all values[+]

gateway_account_id

The gateway account this payment method is stored with.
optional, string, max chars=50

status

Current status of the payment source.
enumerated string, default=valid

Possible values are

validA payment source that is valid and active.expiringA payment source that is expiring (like card's status based on its expiry date).expiredA payment source that has expired.invalidThe billing agreement cannot be used. It might become valid again either automatically or due to customer action.pending_verificationThe payment source needs to be verified.

reference_id

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.
string, max chars=200

balances
Show attributes[+]

The list of balances for this customer.
optional, list of customer_balance

Balance attributes

promotional_credits

Promotional credits balance of this customer.
in cents, default=0, min=0

excess_payments

Total unused payments associated with the customer.
in cents, default=0, min=0

refundable_credits

Refundable credits balance of this customer.
in cents, default=0, min=0

unbilled_charges

Total unbilled charges for this customer.
in cents, default=0, min=0

currency_code

The currency code (ISO 4217 format) for balance.
string, max chars=3

relationship
Show attributes[+]

The Account Hierarchy relationship that the customer is part of.
optional, relationship

Relationship attributes

parent_id

The id of the customer who is the immediate parent.
optional, string, max chars=50

payment_owner_id

The id of the customer who pays the invoices for this customer. Can be the customer itself or the invoice_owner_id.
string, max chars=50

invoice_owner_id

The id of the customer who is invoiced for charges incurred. Can be the customer itself or any parent in its hierarchy.
string, max chars=50

parent_account_access
Show attributes[+]

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.
optional, parent_account_access

Parent account acces attributes

portal_edit_child_subscriptions

Sets parent's level of access to child subscriptions on the Self-Serve Portal.
optional, enumerated string

Possible values are

yesThe parent account can view and edit the subscriptions of the child account.view_onlyThe parent account can only view the subscriptions of the child account.noThe parent account cannot view or edit the subscriptions of the child account.

portal_download_child_invoices

Sets parent's level of access to child invoices on the Self-Serve Portal.
optional, enumerated string

Possible values are

yesThe parent account can view and download the invoices of the child account.view_onlyThe parent account can only view the invoices of the child account.noThe parent account can neither view nor download the invoices of the child account.

send_subscription_emails

If true, the parent account will receive subscription-related emails sent to the child account.
boolean

send_invoice_emails

If true, the parent account will receive invoice-related emails sent to the child account.
boolean

send_payment_emails

If true, the parent account will receive payment-related emails sent to the child account.
boolean

child_account_access
Show attributes[+]

Defines the level of access that the customer has to its own information.
optional, child_account_access

Child account acces attributes

portal_edit_subscriptions

Sets the child's level of access to its own subscriptions on the Self-Serve Portal.
optional, enumerated string

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

Sets the child’s level of access to its own invoices on the Self-Serve Portal.
optional, enumerated string

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

If true, the child account will receive subscription-related emails for its own subscriptions.
boolean

send_invoice_emails

If true, the child account will receive invoice-related emails for its own invoices.
boolean

send_payment_emails

If true, the child account will receive payment-related emails for its own invoices.
boolean

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. Here's how you can set it up.
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.data as temp token in this API.
You can also use our Hosted Pages based integration.

billing_address is significant especially when EU VAT is involved since the VAT calculations are based on it. EU VAT is exempted for customers without a billing address.

Though you may choose not to pass the billing address (eg. for customers who would make offline payments), you can still use the Update billing info for a customer endpoint to do this later, as needed.

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

Id for the new customer. If not given, this will be auto-generated.
optional, string, max chars=50

first_name

First name of the customer.
optional, string, max chars=150

last_name

Last name of the customer.
optional, string, max chars=150

email

Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70

preferred_currency_code

The currency code (ISO 4217 format) of the customer. Applicable if Multicurrency is enabled.
optional, string, max chars=3

phone

Phone number of the customer.
optional, string, max chars=50

company

Company name of the customer.
optional, string, max chars=250

auto_collection

Whether payments needs to be collected automatically for this customer.
optional, enumerated string, default=on

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

The number of days within which the customer has to make payment for the invoice.
optional, integer, default=0

allow_direct_debit

Whether the customer can pay via Direct Debit.
optional, boolean, default=false

vat_number

VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20

registered_for_gst

Confirms that a customer is registered under GST. This field is available for Australia only.
optional, boolean

taxability

Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable

Possible values are

taxableCustomer is taxable.exempt

Customer is exempted from tax
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

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

Possible values are

client_profile_id

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

taxjar_exemption_category

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

Possible values are

wholesaleWhole-sale.governmentGovernment.otherOther.

business_customer_without_vat_number

Confirms that a customer is a valid business without VAT number.
optional, boolean

locale

entity_code

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

Possible values are

aFederal government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.

Show all values[+]

exempt_number

meta_data

A set of key-value pairs stored as additional information for the subscription.
optional, jsonobject

offline_payment_method

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

Possible values are

no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.

consolidated_invoicing

Applicable when consolidated invoicing is enabled. Indicates whether invoice consolidation should happen during subscription renewals. Needs to be set only if this value is different from the defaults configured.
optional, boolean

token_id

The Chargebee payment token generated by Chargebee JS.
optional, string, max chars=40

invoice_notes

Invoice Notes for this resource. Read More.
optional, string, max chars=2000

card

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

card[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

card[first_name]

Cardholder's first name.
optional, string, max chars=50

card[last_name]

Cardholder's last name.
optional, string, max chars=50

card[number]

The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500

card[expiry_month]

Card expiry month.
required if card provided, integer, min=1, max=12

card[expiry_year]

Card expiry year.
required if card provided, integer

card[cvv]

The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520

card[billing_addr1]

Address line 1, as available in card billing address.
optional, string, max chars=150

card[billing_addr2]

Address line 2, as available in card billing address.
optional, string, max chars=150

card[billing_city]

City, as available in card billing address.
optional, string, max chars=50

card[billing_state_code]

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).
optional, string, max chars=50

card[billing_state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

card[billing_zip]

Postal or Zip code, as available in card billing address.
optional, string, max chars=20

card[billing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

bank_account

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

bank_account[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

bank_account[iban]

Account holder’s International Bank Account Number.
optional, string, min chars=10, max chars=50

bank_account[first_name]

Account holder’s first name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150

bank_account[last_name]

Account holder’s last name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150

bank_account[company]

Account holder’s company name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=250

bank_account[email]

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.
optional, string, max chars=70

bank_account[bank_name]

Name of account holder’s bank.
optional, string, max chars=100

bank_account[account_number]

Account holder’s bank account number.
optional, string, min chars=4, max chars=17

bank_account[routing_number]

Bank account routing number.
optional, string, min chars=3, max chars=9

bank_account[bank_code]

Indicates the bank code.
optional, string, max chars=20

bank_account[account_type]

For Authorize.net ACH users only. Indicates the type of account.
optional, enumerated string

Possible values are

checkingChecking Account.savingsSavings Account.business_checkingBusiness Checking Account.

bank_account[account_holder_type]

For Stripe ACH users only. Indicates the account holder type.
optional, enumerated string

Possible values are

individualIndividual.companyCompany.

bank_account[echeck_type]

For Authorize.net ACH users only. Indicates the type of eCheck.
optional, enumerated string

Possible values are

webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.

bank_account[issuing_country]

2-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.
optional, string, max chars=50

bank_account[swedish_identity_number]

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.
optional, string, min chars=10, max chars=12

payment_method

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

payment_method[type]

The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
optional, enumerated string

Possible values are

Show all values[+]

payment_method[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

payment_method[reference_id]

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.
optional, string, max chars=200

payment_method[tmp_token]

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.
required if reference_id not provided, string, max chars=65k

payment_method[issuing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

payment_intent

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

payment_intent[id]

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.
optional, string, max chars=150

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

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.
optional, string, max chars=65k

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_info]

Applicable only for Braintree gateway. Can be used only for Braintree’s Advance Fraud Management feature. Pass a stringified JSON containing the device_session_id and fraud_merchant_id as an input to fingerprint. Here’s a sample to it.
optional, jsonobject

billing_address

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

billing_address[first_name]

The first name of the billing contact.
optional, string, max chars=150

billing_address[last_name]

The last name of the billing contact.
optional, string, max chars=150

billing_address[email]

The email address.
optional, string, max chars=70

billing_address[company]

The company name.
optional, string, max chars=250

billing_address[phone]

The phone number.
optional, string, max chars=50

billing_address[line1]

Address line 1.
optional, string, max chars=150

billing_address[line2]

Address line 2.
optional, string, max chars=150

billing_address[line3]

Address line 3.
optional, string, max chars=150

billing_address[city]

The name of the city.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

billing_address[zip]

Zip or Postal code.
optional, string, max chars=20

billing_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

billing_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

Retrieves the list of customers.

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

The number of resources to be returned.
optional, integer, default=10, min=1, max=100

offset

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.
optional, string, max chars=1000

include_deleted

If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
optional, boolean, default=false

sort_by[<sort-order>]

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

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

Identifier of the customer.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "9bsvnHgsvmsI"
optional, string filter

first_name[<operator>]

First name of the customer.
Supported operators : is, is_not, starts_with, is_present

Example → first_name[is] = "John"
optional, string filter

last_name[<operator>]

Last name of the customer.
Supported operators : is, is_not, starts_with, is_present

Example → last_name[is_not] = "Clint"
optional, string filter

email[<operator>]

Email of the customer. Configured email notifications will be sent to this email.
Supported operators : is, is_not, starts_with, is_present

Example → email[is] = "john@test.com"
optional, string filter

company[<operator>]

Company name of the customer.
Supported operators : is, is_not, starts_with, is_present

Example → company[is_not] = "Globex Corp"
optional, string filter

phone[<operator>]

Phone number of the customer.
Supported operators : is, is_not, starts_with, is_present

Example → phone[is] = "(541) 754-3010"
optional, string filter

auto_collection[<operator>]

Whether payments needs to be collected automatically for this customer. Possible values are : on, off.
Supported operators : is, is_not, in, not_in

Example → auto_collection[is] = "on"
optional, enumerated string filter

taxability[<operator>]

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

created_at[<operator>]

Timestamp indicating when this customer resource is created.
Supported operators : after, before, on, between

Example → created_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter

updated_at[<operator>]

To filter based on updated_at. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by input parameter as updated_at for a faster response.
Supported operators : after, before, on, between

Example → updated_at[after] = "1243545465"
optional, timestamp(UTC) in seconds filter

offline_payment_method[<operator>]

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

relationship

Parameters for relationship
pass parameters as relationship[<param name>][<operator>]

relationship[parent_id][operator]

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

relationship[payment_owner_id][operator]

Parent who is going to pay.
Supported operators : is, is_not, starts_with

Example → relationship[payment_owner_id][is_not] = "active1"
optional, string filter

relationship[invoice_owner_id][operator]

Parent who is going to handle invoices.
Supported operators : is, is_not, starts_with

Example → relationship[invoice_owner_id][is_not] = "future_billing"
optional, string filter

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

next_offset

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”.
optional, string, max chars=1000

Retrieves the customer identified by the unique identifier.

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

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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

First name of the customer.
optional, string, max chars=150

last_name

Last name of the customer.
optional, string, max chars=150

email

Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70

preferred_currency_code

The currency code (ISO 4217 format) of the customer. Applicable if Multicurrency is enabled.
optional, string, max chars=3

phone

Phone number of the customer.
optional, string, max chars=50

company

Company name of the customer.
optional, string, max chars=250

auto_collection

Whether payments needs to be collected automatically for this customer.
optional, enumerated string

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

Whether the customer can pay via Direct Debit.
optional, boolean

net_term_days

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

taxability

Specifies if the customer is liable for tax.
optional, enumerated string

Possible values are

taxableCustomer is taxable.exempt

Customer is exempted from tax
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

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

Possible values are

client_profile_id

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

taxjar_exemption_category

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

Possible values are

wholesaleWhole-sale.governmentGovernment.otherOther.

locale

entity_code

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

Possible values are

aFederal government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.

Show all values[+]

exempt_number

offline_payment_method

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

Possible values are

no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.

invoice_notes

Invoice Notes for this resource. Read More.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription.
optional, jsonobject

fraud_flag

Indicates whether or not the customer has been identified as fraudulent.
optional, enumerated string

Possible values are

safeThe customer has been marked as safe.fraudulentThe customer has been marked as fraudulent.

consolidated_invoicing

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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]

The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
required, enumerated string

Possible values are

genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.

Show all values[+]

payment_method[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

payment_method[reference_id]

payment_method[tmp_token]

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.
required if reference_id not provided, string, max chars=65k

payment_method[issuing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

This method is used for updating the 'Billing Info' - the Billing Address and 'vat_number' attributes - of the customer. For updating the other customer attributes use our Update Customer API.

During this operation if Billing Info(Billing Address and vat_number) is not already present it will get added. Whereas if it is present already, the existing values will be replaced. i.e existing values for Billing Address and vat_number will be cleared and the new values will be set.

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/ Tax registration number of the customer. Learn more.
optional, string, max chars=20

registered_for_gst

Confirms that a customer is registered under GST. This field is available for Australia only.
optional, boolean

business_customer_without_vat_number

Confirms that a customer is a valid business without VAT number.
optional, boolean

billing_address

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

billing_address[first_name]

The first name of the billing contact.
optional, string, max chars=150

billing_address[last_name]

The last name of the billing contact.
optional, string, max chars=150

billing_address[email]

The email address.
optional, string, max chars=70

billing_address[company]

The company name.
optional, string, max chars=250

billing_address[phone]

The phone number.
optional, string, max chars=50

billing_address[line1]

Address line 1.
optional, string, max chars=150

billing_address[line2]

Address line 2.
optional, string, max chars=150

billing_address[line3]

Address line 3.
optional, string, max chars=150

billing_address[city]

The name of the city.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

billing_address[zip]

Zip or Postal code.
optional, string, max chars=20

billing_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

billing_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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

The number of resources to be returned.
optional, integer, default=10, min=1, max=100

offset

contact

Resource object representing contact.
always returned

next_offset

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”.
optional, string, max chars=1000

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

Payment source id this role will be assigned to.
required, string, max chars=40

role

Indicates whether the payment source is Primary, Backup, or neither.
required, enumerated string

Possible values are

primaryPrimary.backupBackup.noneNone.

customer

Resource object representing customer.
always returned

payment_source

Resource object representing payment_source.
always returned

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]

Unique reference ID provided for the contact.
optional, string, max chars=150

contact[first_name]

First name of the contact.
optional, string, max chars=150

contact[last_name]

Last name of the contact.
optional, string, max chars=150

contact[email]

Email of the contact.
required, string, max chars=70

contact[phone]

Phone number of the contact.
optional, string, max chars=50

contact[label]

Label/Tag provided for contact.
optional, string, max chars=50

contact[enabled]

Contact enabled / disabled.
optional, boolean, default=false

contact[send_billing_email]

Whether Billing Emails option is enabled for the contact.
optional, boolean, default=false

contact[send_account_email]

Whether Account Emails option is enabled for the contact.
optional, boolean, default=false

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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]

Unique reference ID provided for the contact.
required, string, max chars=150

contact[first_name]

First name of the contact.
optional, string, max chars=150

contact[last_name]

Last name of the contact.
optional, string, max chars=150

contact[email]

Email of the contact.
optional, string, max chars=70

contact[phone]

Phone number of the contact.
optional, string, max chars=50

contact[label]

Label/Tag provided for contact.
optional, string, max chars=50

contact[enabled]

Contact enabled / disabled.
optional, boolean

contact[send_billing_email]

Whether Billing Emails option is enabled for the contact.
optional, boolean

contact[send_account_email]

Whether Account Emails option is enabled for the contact.
optional, boolean

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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]

Unique reference ID provided for the contact.
required, string, max chars=150

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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

Remarks, if any, on the payment.
optional, string, max chars=300

transaction

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

transaction[amount]

The payment transaction amount.
required, in cents, min=1

transaction[currency_code]

The currency code (ISO 4217 format) for the transaction.
required if Multicurrency is enabled, string, max chars=3

transaction[date]

Indicates when this transaction occurred.
required, timestamp(UTC) in seconds

transaction[payment_method]

The Payment Method of this transaction.
required, enumerated string, default=card

Possible values are

cashCash.checkCheck.

bank_transferBank Transfer.otherPayment Methods other than the above types.

Show all values[+]

transaction[reference_number]

The reference number for this transaction. e.g check number in case of 'check' payments.
optional, string, max chars=100

customer

Resource object representing customer.
always returned

transaction

Resource object representing transaction.
always returned

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

Amount to be collected. If this parameter is not passed then the invoice(s) amount to collect will be collected.
optional, in cents, min=0

payment_source_id

Payment source used for the payment.
optional, string, max chars=40

token_id

Token generated by Chargebee JS representing payment method details.
optional, string, max chars=40

replace_primary_payment_source

Indicates whether the primary payment source need to be replaced with the payment source given.
optional, boolean, default=false

retain_payment_source

Indicates whether the payment source should be retained for the customer.
optional, boolean, default=false

payment_method

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

payment_method[type]

The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
optional, enumerated string

Possible values are

Show all values[+]

payment_method[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

payment_method[reference_id]

payment_method[tmp_token]

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.
required if reference_id not provided, string, max chars=65k

card

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

card[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

card[first_name]

Cardholder's first name.
optional, string, max chars=50

card[last_name]

Cardholder's last name.
optional, string, max chars=50

card[number]

The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500

card[expiry_month]

Card expiry month.
required if card provided, integer, min=1, max=12

card[expiry_year]

Card expiry year.
required if card provided, integer

card[cvv]

The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520

card[billing_addr1]

Address line 1, as available in card billing address.
optional, string, max chars=150

card[billing_addr2]

Address line 2, as available in card billing address.
optional, string, max chars=150

card[billing_city]

City, as available in card billing address.
optional, string, max chars=50

card[billing_state_code]

card[billing_state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

card[billing_zip]

Postal or Zip code, as available in card billing address.
optional, string, max chars=20

card[billing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

payment_intent

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

payment_intent[id]

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_info]

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]

Identifier for the invoice. Multiple invoices can be passed.
optional, string, max chars=50

invoice_allocations[allocation_amount][0..n]

Amount that will override the Invoice amount to be collected. If not specified Invoice amount to collect will be taken as default.
optional, in cents, min=0

customer

Resource object representing customer.
always returned

transaction

Resource object representing transaction.
always returned

Deletes the customer resource.

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

Deletes the Payment Method from the gateway/vault.
optional, boolean, default=true

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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

Sample Request

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

Id of the customer to be copied.
required, string, max chars=100

from_site

Name of the site from which this customer need to be copied.
required, string, max chars=50

resource_migration

Resource object representing resource_migration.
always returned

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.

Say a customer's upcoming renewal is scheduled for Jan, 10th. If the customer's billing date is changed to 15th - the next renewal still happens on Jan, 10th. During this renewal alignment with the new date happens therby the subsequent renewal gets scheduled for Feb, 15th.

If you want to align with the new date immediately (in this example: you want the next renewal to be on Jan, 15th and not Jan, 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_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

sundaySunday.mondayMonday.tuesdayTuesday.wednesdayWednesday.thursdayThursday.fridayFriday.saturdaySaturday.

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

Resource object representing customer.
always returned

This API moves a customer's payment methods, subscriptions, invoices, credit notes, transactions, unbilled charges,orders to another customer. Events and email logs will not be moved. The API execution is asynchronous. The returned customer object is to customer object.

Note: Moving virtual bank accounts from one customer to another is not supported in this API.

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

From customer id.
required, string, max chars=50

to_customer_id

To customer id.
required, string, max chars=50

customer

Resource object representing customer.
always returned

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

Resource object representing customer.
always returned

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

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

Sample Request

# 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

The id of the customer which is to be set as the immediate parent.
optional, string, max chars=50

payment_owner_id

The id of the customer who will pay the invoices for this customer. Can be the child itself or the invoice_owner_id.
optional, string, max chars=50

invoice_owner_id

The id of the customer who will be invoiced for charges incurred. Can be the child itself or any parent in its hierarchy.
optional, string, max chars=50

use_default_hierarchy_settings

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.

.
optional, boolean, default=true

parent_account_access

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

parent_account_access[portal_edit_child_subscriptions]

Sets parent's level of access to child subscriptions on the Self-Serve Portal.
optional, enumerated string

Possible values are

parent_account_access[portal_download_child_invoices]

Sets parent's level of access to child invoices on the Self-Serve Portal.
optional, enumerated string

Possible values are

parent_account_access[send_subscription_emails]

If true, the parent account will receive subscription-related emails sent to the child account.
optional, boolean

parent_account_access[send_payment_emails]

If true, the parent account will receive payment-related emails sent to the child account.
optional, boolean

parent_account_access[send_invoice_emails]

If true, the parent account will receive invoice-related emails sent to the child account.
optional, boolean

child_account_access

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

child_account_access[portal_edit_subscriptions]

Sets the child's level of access to its own subscriptions on the Self-Serve Portal.
optional, enumerated string

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]

Sets the child’s level of access to its own invoices on the Self-Serve Portal.
optional, enumerated string

Possible values are

child_account_access[send_subscription_emails]

If true, the child account will receive subscription-related emails for its own subscriptions.
optional, boolean

child_account_access[send_payment_emails]

If true, the child account will receive payment-related emails for its own invoices.
optional, boolean

child_account_access[send_invoice_emails]

If true, the child account will receive invoice-related emails for its own invoices.
optional, boolean

customer

Resource object representing customer.
always returned

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

Resource object representing customer.
always returned

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

Selects the specific part of the hierarchy to be fetched.
optional, enumerated string

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

Resource object representing hierarchy.
always returned

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

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.

.
optional, boolean, default=true

parent_account_access

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

parent_account_access[portal_edit_child_subscriptions]

Sets parent's level of access to child subscriptions on the Self-Serve Portal.
optional, enumerated string

Possible values are

parent_account_access[portal_download_child_invoices]

Sets parent's level of access to child invoices on the Self-Serve Portal.
optional, enumerated string

Possible values are

parent_account_access[send_subscription_emails]

If true, the parent account will receive subscription-related emails sent to the child account.
optional, boolean

parent_account_access[send_payment_emails]

If true, the parent account will receive payment-related emails sent to the child account.
optional, boolean

parent_account_access[send_invoice_emails]

If true, the parent account will receive invoice-related emails sent to the child account.
optional, boolean

child_account_access

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

child_account_access[portal_edit_subscriptions]

Sets the child's level of access to its own subscriptions on the Self-Serve Portal.
optional, enumerated string

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]

Sets the child’s level of access to its own invoices on the Self-Serve Portal.
optional, enumerated string

Possible values are

child_account_access[send_subscription_emails]

If true, the child account will receive subscription-related emails for its own subscriptions.
optional, boolean

child_account_access[send_payment_emails]

If true, the child account will receive payment-related emails for its own invoices.
optional, boolean

child_account_access[send_invoice_emails]

If true, the child account will receive invoice-related emails for its own invoices.
optional, boolean

customer

Resource object representing customer.
always returned

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¶

Sample Response [ JSON ]

URL Format POST