Settings
API Version
Library

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

{ "account_credits": 0, "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", "zip": "91789" }, "card_status": "no_card", "created_at": 1517506683, "email": "john@test.com", "excess_payments": 0, "first_name": "John", "id": "__test__5SK0bLNFRFuByp8Bu", "last_name": "Doe", "object": "customer", "refundable_credits": 0, "taxability": "taxable" }

API Index URL GET

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

Model Class

ChargeBee.Models.Customer

Customer attributes

Id
string, max chars=50
Identifier of the customer.
FirstName
optional, string, max chars=150
First name of the customer
LastName
optional, string, max chars=150
Last name of the customer
Email
optional, string, max chars=70
Email of the customer. Configured email notifications will be sent to this email.
Phone
optional, string, max chars=50
Phone number of the customer
Company
optional, string, max chars=250
Company name of the customer.
VatNumber
optional, string, max chars=20
The VAT/tax registration number for the customer. For customers with billing_address country as XI (which is United Kingdom - Northern Ireland), the first two characters of the full VAT number can be overridden by setting vat_number_prefix.
AutoCollection
enumerated string, default=on
Whether payments needs to be collected automatically for this customer
Possible values are
OnWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.OffAutomatic collection of charges will not be made. All payments must be recorded offline.
OnWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.OffAutomatic collection of charges will not be made. All payments must be recorded offline.
Show all values[+]
AllowDirectDebit
boolean, default=false
Whether the customer can pay via Direct Debit
CreatedAt
timestamp(UTC) in seconds
Timestamp indicating when this customer resource is created.
CreatedFromIp
optional, string, max chars=50
The IP address of the customer. Used primarily for referral integrations and EU/UK VAT validation.
Taxability
optional, enumerated string, default=taxable
Specifies if the customer is liable for tax
Possible values are
TaxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.Exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
TaxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.Exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
Show all values[+]
InvoiceNotes
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
AccountCredits
in cents, min=0
Promotional credits balance of this customer
RefundableCredits
in cents, min=0
Refundable credits balance of this customer
ExcessPayments
in cents, min=0
Total unused payments associated with the customer
MetaData
optional, jsonobject
A set of key-value pairs stored as additional information for the customer. Learn more.
BillingAddress
Show attributes [+]
optional, billing_address
Billing address for a customer.
Contacts
Show attributes [+]
optional, list of contact
contacts
PaymentMethod
Show attributes [+]
optional, payment_method
Primary Payment Source of the customer.
Id Id
string, max chars=50
Identifier of the customer.
FirstName FirstName
optional, string, max chars=150
First name of the customer
LastName LastName
optional, string, max chars=150
Last name of the customer
Email Email
optional, string, max chars=70
Email of the customer. Configured email notifications will be sent to this email.
Phone Phone
optional, string, max chars=50
Phone number of the customer
Company Company
optional, string, max chars=250
Company name of the customer.
VatNumber VatNumber
optional, string, max chars=20
The VAT/tax registration number for the customer. For customers with billing_address country as XI (which is United Kingdom - Northern Ireland), the first two characters of the full VAT number can be overridden by setting vat_number_prefix.
AutoCollection AutoCollection
enumerated string, default=on
Whether payments needs to be collected automatically for this customer
Possible values are
OnWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.OffAutomatic collection of charges will not be made. All payments must be recorded offline.
OnWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.OffAutomatic collection of charges will not be made. All payments must be recorded offline.
Show all values[+]
AllowDirectDebit AllowDirectDebit
boolean, default=false
Whether the customer can pay via Direct Debit
CreatedAt CreatedAt
timestamp(UTC) in seconds
Timestamp indicating when this customer resource is created.
CreatedFromIp CreatedFromIp
optional, string, max chars=50
The IP address of the customer. Used primarily for referral integrations and EU/UK VAT validation.
Taxability Taxability
optional, enumerated string, default=taxable
Specifies if the customer is liable for tax
Possible values are
TaxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.Exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
TaxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.Exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
Show all values[+]
InvoiceNotes InvoiceNotes
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
AccountCredits AccountCredits
in cents, min=0
Promotional credits balance of this customer
RefundableCredits RefundableCredits
in cents, min=0
Refundable credits balance of this customer
ExcessPayments ExcessPayments
in cents, min=0
Total unused payments associated with the customer
MetaData
optional, jsonobject
A set of key-value pairs stored as additional information for the customer. Learn more.
BillingAddress
optional, billing_address
Billing address for a customer.
Contacts
optional, list of contact
contacts
PaymentMethod
optional, payment_method
Primary Payment Source of the customer.

Consent Fields for Customer

Custom Fields for Customer

Create a customer

Idempotency Supported
Note: This operation optionally supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.

Creates a customer. You can create a customer and then create subscriptions for the customer when required. When creating a customer, you can pass along the billing address and card details.

Passing credit card details to through the API involves PCI liability at your end as sensitive card information passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable:

  • If you use Stripe, you can also use Stripe.js with your checkout form, to collect card information.
  • If you are using Braintree gateway, you can use Braintree.js with your checkout form.
  • You can also use our Hosted Pages based integration.

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

Billing Address attributes shall be explicitly passed for customers paying offline(Cash, Check, Bank Transfer etc).

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.

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.Create()
		.FirstName("John")
		.LastName("Doe")
		.Email("john@test.com")
		.BillingAddressFirstName("John")
		.BillingAddressLastName("Doe")
		.BillingAddressLine1("PO Box 9999")
		.BillingAddressCity("Walnut")
		.BillingAddressState("California")
		.BillingAddressZip("91789")
		.BillingAddressCountry("US")
		.Request();

Customer customer = result.Customer;
Card card = result.Card;
copy
Click to Copy
Creates a customer with billing address.
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.Create()
		.FirstName("John")
		.LastName("Doe")
		.Email("john@test.com")
		.BillingAddressFirstName("John")
		.BillingAddressLastName("Doe")
		.BillingAddressLine1("PO Box 9999")
		.BillingAddressCity("Walnut")
		.BillingAddressState("California")
		.BillingAddressZip("91789")
		.BillingAddressCountry("US")
		.Request();

Customer customer = result.Customer;
Card card = result.Card;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 0,
        "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",
            "zip": "91789"
        },
        "card_status": "no_card",
        "created_at": 1517506683,
        "email": "john@test.com",
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__5SK0bLNFRFuByp8Bu",
        "last_name": "Doe",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.Create()

Input Parameters

Id[(val)](val)
optional, string, max chars=50
Id for the new customer. If not given, this will be auto-generated.
FirstName[(val)](val)
optional, string, max chars=150
First name of the customer.
LastName[(val)](val)
optional, string, max chars=150
Last name of the customer.
Email[(val)](val)
optional, string, max chars=70
Email of the customer. Configured email notifications will be sent to this email.
Phone[(val)](val)
optional, string, max chars=50
Phone number of the customer.
Company[(val)](val)
optional, string, max chars=250
Company name of the customer.
AutoCollection[(val)](val)
optional, enumerated string, default=on
Whether payments needs to be collected automatically for this customer.
Possible values are
OnWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.OffAutomatic collection of charges will not be made. All payments must be recorded offline.
OnWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.OffAutomatic collection of charges will not be made. All payments must be recorded offline.
Show all values[+]
AllowDirectDebit[(val)](val)
optional, boolean, default=false
Whether the customer can pay via Direct Debit.
VatNumber[(val)](val)
optional, string, max chars=20
The VAT/tax registration number for the customer. For customers with billing_address country as XI (which is United Kingdom - Northern Ireland), the first two characters of the full VAT number can be overridden by setting vat_number_prefix.
Taxability[(val)](val)
optional, enumerated string, default=taxable
Specifies if the customer is liable for tax.
Possible values are
TaxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.Exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
TaxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.Exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
Show all values[+]
MetaData[(val)](val)
optional, jsonobject
A set of key-value pairs stored as additional information for the customer. Learn more.
CreatedFromIp[(val)](val)
optional, string, max chars=50
The IP address of the customer. Used primarily for referral integrations and EU/UK VAT validation.
InvoiceNotes[(val)](val)
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
CardGateway(val)
optional, enumerated string
Name of the gateway this payment source is stored with.
Possible values are
ChargebeeChargebee test gateway.StripeStripe is a payment gateway.BraintreeBraintree is a payment gateway.AuthorizeNetAuthorize.net is a payment gatewayPaypalProPayPal Pro Account is a payment gateway.PinPin is a payment gatewayEwayeWAY Account is a payment gateway.EwayRapideWAY Rapid is a payment gateway.WorldpayWorldPay is a payment gatewayBalancedPaymentsBalanced is a payment gatewayBeanstreamBambora(formerly known as Beanstream) is a payment gateway.BluepayBluePay is a payment gateway.ElavonElavon Virtual Merchant is a payment solution.FirstDataGlobalFirst Data Global Gateway Virtual Terminal AccountHdfcHDFC Account is a payment gateway.MigsMasterCard Internet Gateway Service payment gateway.NmiNMI is a payment gateway.OgoneIngenico ePayments (formerly known as Ogone) is a payment gateway.PaymillPAYMILL is a payment gateway.PaypalPayflowProPayPal Payflow Pro is a payment gateway.SagePaySage Pay is a payment gateway.Tco2Checkout is a payment gateway.WirecardWireCard Account is a payment service provider.
ChargebeeChargebee test gateway.StripeStripe is a payment gateway.BraintreeBraintree is a payment gateway.AuthorizeNetAuthorize.net is a payment gateway
PaypalProPayPal Pro Account is a payment gateway.PinPin is a payment gatewayEwayeWAY Account is a payment gateway.EwayRapideWAY Rapid is a payment gateway.WorldpayWorldPay is a payment gatewayBalancedPaymentsBalanced is a payment gatewayBeanstreamBambora(formerly known as Beanstream) is a payment gateway.BluepayBluePay is a payment gateway.ElavonElavon Virtual Merchant is a payment solution.FirstDataGlobalFirst Data Global Gateway Virtual Terminal AccountHdfcHDFC Account is a payment gateway.MigsMasterCard Internet Gateway Service payment gateway.NmiNMI is a payment gateway.OgoneIngenico ePayments (formerly known as Ogone) is a payment gateway.PaymillPAYMILL is a payment gateway.PaypalPayflowProPayPal Payflow Pro is a payment gateway.SagePaySage Pay is a payment gateway.Tco2Checkout is a payment gateway.WirecardWireCard Account is a payment service provider.
Show all values[+]
CardTmpToken(val)
optional, string, max chars=300
The single-use card token returned by vaults like Stripe/Braintree which act as a substitute for your card details. Before calling this API, you should have submitted your card details to the gateway and gotten this token in return.
Note: Supported only for Stripe, Braintree and Authorize.Net. If this value is specified, there is no need to specify other card details (like number, cvv, etc).
CardFirstName(val)
optional, string, max chars=50
Cardholder's first name
CardLastName(val)
optional, string, max chars=50
Cardholder's last name
CardNumber(val)
required if card provided, string, max chars=1500
The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
CardExpiryMonth(val)
required if card provided, integer, min=1, max=12
Card expiry month.
CardExpiryYear(val)
required if card provided, integer
Card expiry year.
CardCvv(val)
optional, string, max chars=520
The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
CardBillingAddr1(val)
optional, string, max chars=150
Address line 1, as available in card billing address.
CardBillingAddr2(val)
optional, string, max chars=150
Address line 2, as available in card billing address.
CardBillingCity(val)
optional, string, max chars=50
City, as available in card billing address.
CardBillingStateCode(val)
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
CardBillingState(val)
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
CardBillingZip(val)
optional, string, max chars=20
Postal or Zip code, as available in card billing address.
CardBillingCountry(val)
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

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

Brexit

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

CardIpAddress(val)
optional, string, max chars=50
The IP address of the customer. Used primarily for referral integration and EU VAT validation.
PaymentMethodType(val)
optional, enumerated string
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
Possible values are
CardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.PaypalExpressCheckoutPayments made via PayPal Express Checkout.AmazonPaymentsPayments made via Amazon Payments.DirectDebitRepresents bank account for which the direct debit or ACH agreement/mandate is created.AutomatedBankTransferRepresents virtual bank account using which the payment will be done.
CardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.PaypalExpressCheckoutPayments made via PayPal Express Checkout.AmazonPaymentsPayments made via Amazon Payments.DirectDebitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
AutomatedBankTransferRepresents virtual bank account using which the payment will be done.
Show all values[+]
PaymentMethodGateway(val)
optional, enumerated string
Name of the gateway the payment method is associated with.
Possible values are
StripeStripe is a payment gateway.BraintreeBraintree is a payment gateway.AuthorizeNetAuthorize.net is a payment gatewayPaypalProPayPal Pro Account is a payment gateway.PinPin is a payment gatewayEwayeWAY Account is a payment gateway.EwayRapideWAY Rapid is a payment gateway.WorldpayWorldPay is a payment gatewayBalancedPaymentsBalanced is a payment gatewayBeanstreamBambora(formerly known as Beanstream) is a payment gateway.BluepayBluePay is a payment gateway.ElavonElavon Virtual Merchant is a payment solution.FirstDataGlobalFirst Data Global Gateway Virtual Terminal AccountHdfcHDFC Account is a payment gateway.MigsMasterCard Internet Gateway Service payment gateway.NmiNMI is a payment gateway.OgoneIngenico ePayments (formerly known as Ogone) is a payment gateway.PaymillPAYMILL is a payment gateway.PaypalPayflowProPayPal Payflow Pro is a payment gateway.SagePaySage Pay is a payment gateway.Tco2Checkout is a payment gateway.WirecardWireCard Account is a payment service provider.
StripeStripe is a payment gateway.BraintreeBraintree is a payment gateway.AuthorizeNetAuthorize.net is a payment gatewayPaypalProPayPal Pro Account is a payment gateway.
PinPin is a payment gatewayEwayeWAY Account is a payment gateway.EwayRapideWAY Rapid is a payment gateway.WorldpayWorldPay is a payment gatewayBalancedPaymentsBalanced is a payment gatewayBeanstreamBambora(formerly known as Beanstream) is a payment gateway.BluepayBluePay is a payment gateway.ElavonElavon Virtual Merchant is a payment solution.FirstDataGlobalFirst Data Global Gateway Virtual Terminal AccountHdfcHDFC Account is a payment gateway.MigsMasterCard Internet Gateway Service payment gateway.NmiNMI is a payment gateway.OgoneIngenico ePayments (formerly known as Ogone) is a payment gateway.PaymillPAYMILL is a payment gateway.PaypalPayflowProPayPal Payflow Pro is a payment gateway.SagePaySage Pay is a payment gateway.Tco2Checkout is a payment gateway.WirecardWireCard Account is a payment service provider.
Show all values[+]
PaymentMethodReferenceId(val)
optional, string, max chars=200
The reference id. In the case of Amazon and Paypal this will be the billing agreement 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.
PaymentIntentId(val)
optional, string, max chars=150
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
PaymentIntentGatewayAccountId(val)
required if payment intent token provided, string, max chars=50
The gateway account used for performing the 3DS flow.
PaymentIntentGwToken(val)
optional, string, max chars=65k
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
PaymentIntentReferenceId(val)
optional, string, max chars=65k
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
BillingAddressFirstName(val)
optional, string, max chars=150
The first name of the billing contact.
BillingAddressLastName(val)
optional, string, max chars=150
The last name of the billing contact.
BillingAddressEmail(val)
optional, string, max chars=70
The email address.
BillingAddressCompany(val)
optional, string, max chars=250
The company name.
BillingAddressPhone(val)
optional, string, max chars=50
The phone number.
BillingAddressLine1(val)
optional, string, max chars=150
Address line 1
BillingAddressLine2(val)
optional, string, max chars=150
Address line 2
BillingAddressLine3(val)
optional, string, max chars=150
Address line 3
BillingAddressCity(val)
optional, string, max chars=50
The name of the city.
BillingAddressStateCode(val)
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
BillingAddressState(val)
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
BillingAddressZip(val)
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
BillingAddressCountry(val)
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Brexit

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

Returns

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

Sample admin console URL

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

List customers

Retrieves a list of customers added to your Chargebee site. The list contains the necessary customer details such as First Name, Last Name and the Customer ID.

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
ListResult result = Customer.List().Request();

foreach (var item in result.List){
  Customer customer = item.Customer;
  Card card = item.Card;
}
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
ListResult result = Customer.List().Request();

foreach (var item in result.List){
  Customer customer = item.Customer;
  Card card = item.Card;
}

Sample Result [ JSON ]

Show more...
{
    "list": [
        {
            "customer": {
                "account_credits": 0,
                "allow_direct_debit": false,
                "auto_collection": "on",
                "card_status": "no_card",
                "created_at": 1517506685,
                "email": "john@test.com",
                "excess_payments": 0,
                "first_name": "John",
                "id": "__test__5SK0bLNFRFuBzHXC8",
                "last_name": "Doe",
                "object": "customer",
                "refundable_credits": 0,
                "taxability": "taxable"
            }
        },
        {..}
    ],
    "next_offset": "[\"1517506680000\",\"154000000144\"]"
}

URL Format GET

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

Method

Customer.List()

Input Parameters

Limit[(val)](val)
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
Offset[(val)](val)
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

Returns

customer customer
always returned
Resource object representing customer
card card
optional
Resource object representing card
next_offset next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

Sample admin console URL

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

Retrieve a customer

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

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.Retrieve("__test__5SK0bLNFRFuBzQTCQ").Request();

Customer customer = result.Customer;
Card card = result.Card;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.Retrieve("__test__5SK0bLNFRFuBzQTCQ").Request();

Customer customer = result.Customer;
Card card = result.Card;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517506685,
        "excess_payments": 0,
        "first_name": "David",
        "id": "__test__5SK0bLNFRFuBzQTCQ",
        "last_name": "Louis",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format GET

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

Method

Customer.Retrieve(<customer_id>)

Returns

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

Sample admin console URL

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

Update a customer

Idempotency Supported

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

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.Update("__test__5SK0bLNFRFuBzRjCS")
		.FirstName("Denise")
		.LastName("Barone")
		.Request();

Customer customer = result.Customer;
Card card = result.Card;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.Update("__test__5SK0bLNFRFuBzRjCS")
		.FirstName("Denise")
		.LastName("Barone")
		.Request();

Customer customer = result.Customer;
Card card = result.Card;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517506685,
        "excess_payments": 0,
        "first_name": "Denise",
        "id": "__test__5SK0bLNFRFuBzRjCS",
        "last_name": "Barone",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.Update(<customer_id>)

Input Parameters

FirstName[(val)](val)
optional, string, max chars=150
First name of the customer.
LastName[(val)](val)
optional, string, max chars=150
Last name of the customer.
Email[(val)](val)
optional, string, max chars=70
Email of the customer. Configured email notifications will be sent to this email.
Phone[(val)](val)
optional, string, max chars=50
Phone number of the customer.
Company[(val)](val)
optional, string, max chars=250
Company name of the customer.
AutoCollection[(val)](val)
optional, enumerated string, default=on
Whether payments needs to be collected automatically for this customer.
Possible values are
OnWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.OffAutomatic collection of charges will not be made. All payments must be recorded offline.
OnWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.OffAutomatic collection of charges will not be made. All payments must be recorded offline.
Show all values[+]
AllowDirectDebit[(val)](val)
optional, boolean, default=false
Whether the customer can pay via Direct Debit.
Taxability[(val)](val)
optional, enumerated string, default=taxable
Specifies if the customer is liable for tax.
Possible values are
TaxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.Exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
TaxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.Exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
Show all values[+]
InvoiceNotes[(val)](val)
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
MetaData[(val)](val)
optional, jsonobject
A set of key-value pairs stored as additional information for the customer. Learn more.

Returns

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

Sample admin console URL

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

Update payment method for a customer

Idempotency Supported

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, which 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 is stored in the vault of Authorize.Net, 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.

Reference id format for Direct Debit Payments
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.

Note: While using this API to update payment method details, Card Verification will not happen even if it is enabled for that particular gateway.

Notes

Storing card after successful 3DS flow not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.
Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
using ChargeBee.Models.Enums;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.UpdatePaymentMethod("__test__5SK0bLNFRFuBzXuCd")
		.PaymentMethodType(TypeEnum.Card)
		.PaymentMethodReferenceId("cus_EOFhU9kPO6xU5G")
		.PaymentMethodGateway(GatewayEnum.Stripe)
		.Request();

Customer customer = result.Customer;
Card card = result.Card;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
using ChargeBee.Models.Enums;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.UpdatePaymentMethod("__test__5SK0bLNFRFuBzXuCd")
		.PaymentMethodType(TypeEnum.Card)
		.PaymentMethodReferenceId("cus_EOFhU9kPO6xU5G")
		.PaymentMethodGateway(GatewayEnum.Stripe)
		.Request();

Customer customer = result.Customer;
Card card = result.Card;

Sample Result [ JSON ]

Show more...
{
    "card": {
        "card_type": "visa",
        "customer_id": "__test__5SK0bLNFRFuBzXuCd",
        "expiry_month": 12,
        "expiry_year": 2019,
        "gateway": "stripe",
        "iin": "******",
        "last4": "1111",
        "masked_number": "************1111",
        "object": "card",
        "status": "valid"
    },
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517506686,
        "excess_payments": 0,
        "first_name": "David",
        "id": "__test__5SK0bLNFRFuBzXuCd",
        "last_name": "Young",
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "object": "payment_method",
            "reference_id": "cus_EOFhU9kPO6xU5G/card_1DvTCMJv9j0DyntJmVTtsFci",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.UpdatePaymentMethod(<customer_id>)

Input Parameters

PaymentMethodType(val)
required, enumerated string
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
Possible values are
CardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.PaypalExpressCheckoutPayments made via PayPal Express Checkout.AmazonPaymentsPayments made via Amazon Payments.DirectDebitRepresents bank account for which the direct debit or ACH agreement/mandate is created.AutomatedBankTransferRepresents virtual bank account using which the payment will be done.
CardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.PaypalExpressCheckoutPayments made via PayPal Express Checkout.AmazonPaymentsPayments made via Amazon Payments.DirectDebitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
AutomatedBankTransferRepresents virtual bank account using which the payment will be done.
Show all values[+]
PaymentMethodGateway(val)
optional, enumerated string
Name of the gateway the payment method is associated with.
Possible values are
StripeStripe is a payment gateway.BraintreeBraintree is a payment gateway.AuthorizeNetAuthorize.net is a payment gatewayPaypalProPayPal Pro Account is a payment gateway.PinPin is a payment gatewayEwayeWAY Account is a payment gateway.EwayRapideWAY Rapid is a payment gateway.WorldpayWorldPay is a payment gatewayBalancedPaymentsBalanced is a payment gatewayBeanstreamBambora(formerly known as Beanstream) is a payment gateway.BluepayBluePay is a payment gateway.ElavonElavon Virtual Merchant is a payment solution.FirstDataGlobalFirst Data Global Gateway Virtual Terminal AccountHdfcHDFC Account is a payment gateway.MigsMasterCard Internet Gateway Service payment gateway.NmiNMI is a payment gateway.OgoneIngenico ePayments (formerly known as Ogone) is a payment gateway.PaymillPAYMILL is a payment gateway.PaypalPayflowProPayPal Payflow Pro is a payment gateway.SagePaySage Pay is a payment gateway.Tco2Checkout is a payment gateway.WirecardWireCard Account is a payment service provider.
StripeStripe is a payment gateway.BraintreeBraintree is a payment gateway.AuthorizeNetAuthorize.net is a payment gatewayPaypalProPayPal Pro Account is a payment gateway.
PinPin is a payment gatewayEwayeWAY Account is a payment gateway.EwayRapideWAY Rapid is a payment gateway.WorldpayWorldPay is a payment gatewayBalancedPaymentsBalanced is a payment gatewayBeanstreamBambora(formerly known as Beanstream) is a payment gateway.BluepayBluePay is a payment gateway.ElavonElavon Virtual Merchant is a payment solution.FirstDataGlobalFirst Data Global Gateway Virtual Terminal AccountHdfcHDFC Account is a payment gateway.MigsMasterCard Internet Gateway Service payment gateway.NmiNMI is a payment gateway.OgoneIngenico ePayments (formerly known as Ogone) is a payment gateway.PaymillPAYMILL is a payment gateway.PaypalPayflowProPayPal Payflow Pro is a payment gateway.SagePaySage Pay is a payment gateway.Tco2Checkout is a payment gateway.WirecardWireCard Account is a payment service provider.
Show all values[+]
PaymentMethodReferenceId(val)
required, string, max chars=200
The reference id. In the case of Amazon and Paypal this will be the billing agreement 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.

Returns

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

Sample admin console URL

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

Update billing info for a customer

Idempotency Supported

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.

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.UpdateBillingInfo("__test__5SK0bLNFRFuBzTbCV")
		.BillingAddressFirstName("John")
		.BillingAddressLastName("Doe")
		.BillingAddressLine1("PO Box 9999")
		.BillingAddressCity("Walnut")
		.BillingAddressState("California")
		.BillingAddressZip("91789")
		.BillingAddressCountry("US")
		.Request();

Customer customer = result.Customer;
Card card = result.Card;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.UpdateBillingInfo("__test__5SK0bLNFRFuBzTbCV")
		.BillingAddressFirstName("John")
		.BillingAddressLastName("Doe")
		.BillingAddressLine1("PO Box 9999")
		.BillingAddressCity("Walnut")
		.BillingAddressState("California")
		.BillingAddressZip("91789")
		.BillingAddressCountry("US")
		.Request();

Customer customer = result.Customer;
Card card = result.Card;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 0,
        "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",
            "zip": "91789"
        },
        "card_status": "no_card",
        "created_at": 1517506685,
        "excess_payments": 0,
        "first_name": "David",
        "id": "__test__5SK0bLNFRFuBzTbCV",
        "last_name": "Lewis",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.UpdateBillingInfo(<customer_id>)

Input Parameters

VatNumber[(val)](val)
optional, string, max chars=20
The VAT/tax registration number for the customer. For customers with billing_address country as XI (which is United Kingdom - Northern Ireland), the first two characters of the full VAT number can be overridden by setting vat_number_prefix.
BillingAddressFirstName(val)
optional, string, max chars=150
The first name of the billing contact.
BillingAddressLastName(val)
optional, string, max chars=150
The last name of the billing contact.
BillingAddressEmail(val)
optional, string, max chars=70
The email address.
BillingAddressCompany(val)
optional, string, max chars=250
The company name.
BillingAddressPhone(val)
optional, string, max chars=50
The phone number.
BillingAddressLine1(val)
optional, string, max chars=150
Address line 1
BillingAddressLine2(val)
optional, string, max chars=150
Address line 2
BillingAddressLine3(val)
optional, string, max chars=150
Address line 3
BillingAddressCity(val)
optional, string, max chars=50
The name of the city.
BillingAddressStateCode(val)
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
BillingAddressState(val)
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
BillingAddressZip(val)
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
BillingAddressCountry(val)
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Brexit

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

E-Invoicing

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

Returns

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

Sample admin console URL

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

Add contacts to a customer

Idempotency Supported

Creates an additional contact for the customer. You can add up to a maximum of 6 contacts. Learn more about Contacts.

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.AddContact("__test__5SK0bLNFRFuBy8HBN")
		.ContactFirstName("Jane")
		.ContactLastName("Doe")
		.ContactEmail("jane@test.com")
		.ContactLabel("dev")
		.ContactEnabled(true)
		.ContactSendBillingEmail(true)
		.ContactSendAccountEmail(true)
		.Request();

Customer customer = result.Customer;
Card card = result.Card;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.AddContact("__test__5SK0bLNFRFuBy8HBN")
		.ContactFirstName("Jane")
		.ContactLastName("Doe")
		.ContactEmail("jane@test.com")
		.ContactLabel("dev")
		.ContactEnabled(true)
		.ContactSendBillingEmail(true)
		.ContactSendAccountEmail(true)
		.Request();

Customer customer = result.Customer;
Card card = result.Card;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "contacts": [
            {
                "email": "jane@test.com",
                "enabled": true,
                "first_name": "Jane",
                "id": "contact___test__5SK0bLNFRFuBy8kBP",
                "label": "dev",
                "last_name": "Doe",
                "object": "contact",
                "send_account_email": true,
                "send_billing_email": true
            },
            {..}
        ],
        "created_at": 1517506680,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__5SK0bLNFRFuBy8HBN",
        "last_name": "Doe",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.AddContact(<customer_id>)

Input Parameters

ContactId(val)
optional, string, max chars=150
Unique reference ID provided for the contact.
ContactFirstName(val)
optional, string, max chars=150
First name of the contact.
ContactLastName(val)
optional, string, max chars=150
Last name of the contact.
ContactEmail(val)
required, string, max chars=70
Email of the contact.
ContactPhone(val)
optional, string, max chars=50
Phone number of the contact.
ContactLabel(val)
optional, string, max chars=50
Label/Tag provided for contact.
ContactEnabled(val)
optional, boolean, default=false
Contact enabled / disabled
ContactSendBillingEmail(val)
optional, boolean, default=false
Whether Billing Emails option is enabled for the contact.
ContactSendAccountEmail(val)
optional, boolean, default=false
Whether Account Emails option is enabled for the contact.

Returns

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

Sample admin console URL

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

Update contacts for a customer

Idempotency Supported

Updates the contact information. Learn more about Contacts.

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.UpdateContact("__test__5SK0bLNFRFuBzV0CY")
		.ContactId("contact___test__5SK0bLNFRFuBzVVCa")
		.ContactFirstName("Jane")
		.ContactLastName("Doe")
		.ContactEmail("jane@test.com")
		.ContactLabel("dev")
		.ContactEnabled(true)
		.ContactSendBillingEmail(true)
		.ContactSendAccountEmail(true)
		.Request();

Customer customer = result.Customer;
Card card = result.Card;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.UpdateContact("__test__5SK0bLNFRFuBzV0CY")
		.ContactId("contact___test__5SK0bLNFRFuBzVVCa")
		.ContactFirstName("Jane")
		.ContactLastName("Doe")
		.ContactEmail("jane@test.com")
		.ContactLabel("dev")
		.ContactEnabled(true)
		.ContactSendBillingEmail(true)
		.ContactSendAccountEmail(true)
		.Request();

Customer customer = result.Customer;
Card card = result.Card;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "contacts": [
            {
                "email": "jane@test.com",
                "enabled": true,
                "first_name": "Jane",
                "id": "contact___test__5SK0bLNFRFuBzVVCa",
                "label": "dev",
                "last_name": "Doe",
                "object": "contact",
                "send_account_email": true,
                "send_billing_email": true
            },
            {..}
        ],
        "created_at": 1517506686,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__5SK0bLNFRFuBzV0CY",
        "last_name": "Doe",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.UpdateContact(<customer_id>)

Input Parameters

ContactId(val)
required, string, max chars=150
Unique reference ID provided for the contact.
ContactFirstName(val)
optional, string, max chars=150
First name of the contact.
ContactLastName(val)
optional, string, max chars=150
Last name of the contact.
ContactEmail(val)
optional, string, max chars=70
Email of the contact.
ContactPhone(val)
optional, string, max chars=50
Phone number of the contact.
ContactLabel(val)
optional, string, max chars=50
Label/Tag provided for contact.
ContactEnabled(val)
optional, boolean, default=false
Contact enabled / disabled
ContactSendBillingEmail(val)
optional, boolean, default=false
Whether Billing Emails option is enabled for the contact.
ContactSendAccountEmail(val)
optional, boolean, default=false
Whether Account Emails option is enabled for the contact.

Returns

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

Sample admin console URL

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

Delete contacts for a customer

Idempotency Supported

Deletes the contact information. Learn more about Contacts.

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.DeleteContact("__test__5SK0bLNFRFuBzFdC3")
		.ContactId("contact___test__5SK0bLNFRFuBzG9C5")
		.Request();

Customer customer = result.Customer;
Card card = result.Card;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.DeleteContact("__test__5SK0bLNFRFuBzFdC3")
		.ContactId("contact___test__5SK0bLNFRFuBzG9C5")
		.Request();

Customer customer = result.Customer;
Card card = result.Card;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517506685,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__5SK0bLNFRFuBzFdC3",
        "last_name": "Doe",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.DeleteContact(<customer_id>)

Input Parameters

ContactId(val)
required, string, max chars=150
Unique reference ID provided for the contact.

Returns

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

Sample admin console URL

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

Add account credits to a customer

Idempotency Supported

This API call can be used to add credits to a customer. Learn more about Promotional Credits.

For example, if a customer has credits of $10, if you pass the amount as $10, then the customer’s credit balance would become $20.

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.AddAccountCredits("__test__3Nl9RLTRcPq8ZI3q")
		.Amount(500)
		.Description("Loyalty credits")
		.Request();

Customer customer = result.Customer;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.AddAccountCredits("__test__3Nl9RLTRcPq8ZI3q")
		.Amount(500)
		.Description("Loyalty credits")
		.Request();

Customer customer = result.Customer;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 500,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517479642,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__3Nl9RLTRcPq8ZI3q",
        "last_name": "Henry",
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "object": "payment_method",
            "reference_id": "tok___test__3Nl9RLTRcPq8a13r",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.AddAccountCredits(<customer_id>)

Input Parameters

Amount[(val)](val)
required, in cents, min=1
Credit amount to be added.
Description[(val)](val)
required, string, max chars=250
Description for this credit.

Returns

customer customer
always returned
Resource object representing customer

Sample admin console URL

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

Deduct account credits for a customer

Idempotency Supported

This API call can be used to deduct credits for a customer. Learn more about Promotional Credits.

For example, if a customer has a credit balance of $20, if you pass the amount as $5, then the customer’s credit balance would become $15.

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.DeductAccountCredits("__test__3Nl9RLTRcPqBDO4m")
		.Amount(200)
		.Description("Correcting credits given by mistake")
		.Request();

Customer customer = result.Customer;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.DeductAccountCredits("__test__3Nl9RLTRcPqBDO4m")
		.Amount(200)
		.Description("Correcting credits given by mistake")
		.Request();

Customer customer = result.Customer;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 300,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517479652,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__3Nl9RLTRcPqBDO4m",
        "last_name": "Henry",
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "object": "payment_method",
            "reference_id": "tok___test__3Nl9RLTRcPqBDa4n",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.DeductAccountCredits(<customer_id>)

Input Parameters

Amount[(val)](val)
required, in cents, min=1
Credit amount to be deducted.
Description[(val)](val)
required, string, max chars=250
Description for this credit.

Returns

customer customer
always returned
Resource object representing customer

Sample admin console URL

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

Set account credits for a customer

Idempotency Supported

This API call can be used to set credits for a customer. Learn more about Promotional Credits.

For example, if a customer has a credit balance of $10 and if you would like to set the balance to $100, you could pass the amount as $100.

Notes

Sample Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.SetAccountCredits("__test__3Nl9RLTRcPqBqT5I")
		.Amount(500)
		.Description("Loyalty credits")
		.Request();

Customer customer = result.Customer;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.SetAccountCredits("__test__3Nl9RLTRcPqBqT5I")
		.Amount(500)
		.Description("Loyalty credits")
		.Request();

Customer customer = result.Customer;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 500,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517479655,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__3Nl9RLTRcPqBqT5I",
        "last_name": "Henry",
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "object": "payment_method",
            "reference_id": "tok___test__3Nl9RLTRcPqBqi5J",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.SetAccountCredits(<customer_id>)

Input Parameters

Amount[(val)](val)
required, in cents, min=0
Credit amount to be set.
Description[(val)](val)
required, string, max chars=250
Description for this credit.

Returns

customer customer
always returned
Resource object representing customer

Sample admin console URL

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

Delete a customer

Idempotency Supported

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 Codes 
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.Delete("__test__5SK0bLNFRFuBzESC1").Request();

Customer customer = result.Customer;
Card card = result.Card;
copy
Click to Copy
 
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.Delete("__test__5SK0bLNFRFuBzESC1").Request();

Customer customer = result.Customer;
Card card = result.Card;

Sample Result [ JSON ]

Show more...
{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517506685,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__5SK0bLNFRFuBzESC1",
        "last_name": "Doe",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}

URL Format POST

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

Method

Customer.Delete(<customer_id>)

Input Parameters

DeletePaymentMethod[(val)](val)
optional, boolean, default=true
Deletes the Payment Method from the gateway/vault.

Returns

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

Sample admin console URL

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