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 ]
{
"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
Identifier of the customer.
string, max chars=50
First name of the customer.
optional, string, max chars=150
Last name of the customer.
optional, string, max chars=150
Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70
Phone number of the customer.
optional, string, max chars=50
Company name of the customer.
optional, string, max chars=250
VAT/ Tax registration number of the customer.
Learn more.
optional, string, max chars=20
Whether payments needs to be collected automatically for this customer.
enumerated string, default=onPossible 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.
Whether the customer can pay via Direct Debit.
boolean, default=false
Timestamp indicating when this customer resource is created.
timestamp(UTC) in seconds
The IP address of the customer. Used primarly for referral integration and EU VAT validation.
optional, string, max chars=50
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxablePossible 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.
.
Invoice Notes for this resource.
Read More.
optional, string, max chars=2000
Promotional credits balance of this customer.
in cents, min=0
Refundable credits balance of this customer.
in cents, min=0
Total unused payments associated with the customer.
in cents, min=0
Additional data about this resource can be stored here in the JSON Format.
Learn more.
optional, jsonobject
Billing address for a customer.
optional, billing_address
Billing addres attributes
First name.
optional, string, max chars=150
Last name.
optional, string, max chars=150
Email.
optional, string, max chars=70
Company name.
optional, string, max chars=250
Phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=150
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
City.
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 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 or Province.
optional, string, max chars=50
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
contacts.
optional, list of contact
Unique reference ID provided for the contact.
string, max chars=150
First name of the contact.
optional, string, max chars=150
Last name of the contact.
optional, string, max chars=150
Email of the contact.
string, max chars=70
Phone number of the contact.
optional, string, max chars=50
Label/Tag provided for contact.
optional, string, max chars=50
Contact enabled / disabled.
boolean, default=false
Whether Account Emails option is enabled for the contact.
boolean, default=false
Whether Billing Emails option is enabled for the contact.
boolean, default=false
Primary Payment Source of the customer.
optional, payment_method
Payment method attributes
Type of payment source.
enumerated stringPossible 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.
Name of the gateway the payment method is associated with.
enumerated stringPossible values are
chargebeeChargebee test gateway.stripeStripe payment 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.not_applicableIndicates that payment gateway is not applicable for this resource.
Show all values[+]
Current status of the payment source.
enumerated string, default=validPossible 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.
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
This operation supports 3DS verification flow. To acheive 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. Here's how to set this up.
- 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.
Sample Request
# creates a customer with billing address.
curl https://{site}.chargebee.com/api/v1/customers \
-u {site_api_key}:\
-d first_name="John" \
-d last_name="Doe" \
-d email="john@test.com" \
-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/v1/customers \
-u {site_api_key}:\
-d first_name="John" \
-d last_name="Doe" \
-d email="john@test.com" \
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
Sample Response [ JSON ]
Show more...
{"customer": {
"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
Id for the new customer. If not given, this will be auto-generated.
optional, string, max chars=50
First name of the customer.
optional, string, max chars=150
Last name of the customer.
optional, string, max chars=150
Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70
Phone number of the customer.
optional, string, max chars=50
Company name of the customer.
optional, string, max chars=250
Whether payments needs to be collected automatically for this customer.
optional, enumerated string, default=onPossible 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.
Whether the customer can pay via Direct Debit.
optional, boolean, default=false
VAT/ Tax registration number of the customer.
Learn more.
optional, string, max chars=20
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxablePossible 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.
.
Additional data about this resource can be stored here in the JSON Format.
Learn more.
optional, jsonobject
The IP address of the customer. Used primarly for referral integration and EU VAT validation.
optional, string, max chars=50
Invoice Notes for this resource.
Read More.
optional, string, max chars=2000
Parameters for card
pass parameters as card[<param name>]
Name of the gateway this payment source is stored with.
optional, enumerated stringPossible values are
chargebeeChargebee test gateway.stripeStripe payment 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.
Show all values[+]
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).
optional, string, max chars=300
Cardholder's first name.
optional, string, max chars=50
Cardholder's last name.
optional, string, max chars=50
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.
required if card provided, integer, min=1, max=12
Card expiry year.
required if card provided, integer
The card verification value. If you are using
Braintree.js, you can specify the Braintree encrypted cvv here.
optional, string, max chars=520
Address line 1, as available in card billing address.
optional, string, max chars=150
Address line 2, as available in card billing address.
optional, string, max chars=150
City, as available in card billing address.
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 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
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
The IP address from where the payment source is created or updated. Used primarily for EU VAT validation.
optional, string, max chars=50
Parameters for payment_method
pass parameters as payment_method[<param name>]
The type of payment method. For more details refer
Update payment method for a customer API under Customer resource.
optional, enumerated stringPossible 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.
Name of the gateway the payment method is associated with.
optional, enumerated stringPossible values are
stripeStripe payment 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.
Show all values[+]
payment_method[reference_id]
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.
optional, string, max chars=200
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
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
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
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
First name.
optional, string, max chars=150
billing_address[last_name]
Last name.
optional, string, max chars=150
Email.
optional, string, max chars=70
Company name.
optional, string, max chars=250
Phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=150
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
City.
optional, string, max chars=50
billing_address[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
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
Resource object representing customer.
always returned
Resource object representing card.
optional
Retrieves the list of customers.
Sample Request
curl https://{site}.chargebee.com/api/v1/customers \
-G \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v1/customers \
-G \
-u {site_api_key}:
Sample Response [ 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
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
Resource object representing customer.
always returned
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/v1/customers/__test__5SK0bLNFRFuBzQTCQ \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzQTCQ \
-u {site_api_key}:
Sample Response [ 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}
Resource object representing customer.
always returned
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/v1/customers/__test__5SK0bLNFRFuBzRjCS \
-u {site_api_key}:\
-d first_name="Denise" \
-d last_name="Barone"
copy
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzRjCS \
-u {site_api_key}:\
-d first_name="Denise" \
-d last_name="Barone"
Sample Response [ 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}
First name of the customer.
optional, string, max chars=150
Last name of the customer.
optional, string, max chars=150
Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70
Phone number of the customer.
optional, string, max chars=50
Company name of the customer.
optional, string, max chars=250
Whether payments needs to be collected automatically for this customer.
optional, enumerated stringPossible 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.
Whether the customer can pay via Direct Debit.
optional, boolean
Specifies if the customer is liable for tax.
optional, enumerated stringPossible 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.
.
Invoice Notes for this resource.
Read More.
optional, string, max chars=2000
Additional data about this resource can be stored here in the JSON Format.
Learn more.
optional, jsonobject
Resource object representing customer.
always returned
Resource object representing card.
optional
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 Request
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzXuCd/update_payment_method \
-u {site_api_key}:\
-d payment_method[type]="card" \
-d payment_method[reference_id]="cus_EOFhU9kPO6xU5G" \
-d payment_method[gateway]="stripe"
copy
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzXuCd/update_payment_method \
-u {site_api_key}:\
-d payment_method[type]="card" \
-d payment_method[reference_id]="cus_EOFhU9kPO6xU5G" \
-d payment_method[gateway]="stripe"
Sample Response [ 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
Parameters for payment_method
pass parameters as payment_method[<param name>]
The type of payment method. For more details refer
Update payment method for a customer API under Customer resource.
required, enumerated stringPossible 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.
Name of the gateway the payment method is associated with.
optional, enumerated stringPossible values are
stripeStripe payment 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.
Show all values[+]
payment_method[reference_id]
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.
required, string, max chars=200
Resource object representing customer.
always returned
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/v1/customers/__test__5SK0bLNFRFuBzTbCV/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/v1/customers/__test__5SK0bLNFRFuBzTbCV/update_billing_info \
-u {site_api_key}:\
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
Sample Response [ JSON ]
Show more...
{"customer": {
"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
VAT/ Tax registration number of the customer.
Learn more.
optional, string, max chars=20
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
First name.
optional, string, max chars=150
billing_address[last_name]
Last name.
optional, string, max chars=150
Email.
optional, string, max chars=70
Company name.
optional, string, max chars=250
Phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=150
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
City.
optional, string, max chars=50
billing_address[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
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
Resource object representing customer.
always returned
Resource object representing card.
optional
Creates an additional contact for the customer. You can add up to a maximum of 6 contacts. Learn more about Contacts.
Sample Request
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBy8HBN/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/v1/customers/__test__5SK0bLNFRFuBy8HBN/add_contact \
-u {site_api_key}:\
-d contact[first_name]="Jane" \
-d contact[last_name]="Doe" \
-d contact[email]="jane@test.com" \
-d contact[label]="dev" \
-d contact[enabled]="true" \
-d contact[send_billing_email]="true" \
-d contact[send_account_email]="true"
Sample Response [ JSON ]
Show more...
{"customer": {
"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
Parameters for contact
pass parameters as contact[<param name>]
Resource object representing customer.
always returned
Resource object representing card.
optional
Updates the contact information. Learn more about Contacts.
Sample Request
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzV0CY/update_contact \
-u {site_api_key}:\
-d contact[id]="contact___test__5SK0bLNFRFuBzVVCa" \
-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/v1/customers/__test__5SK0bLNFRFuBzV0CY/update_contact \
-u {site_api_key}:\
-d contact[id]="contact___test__5SK0bLNFRFuBzVVCa" \
-d contact[first_name]="Jane" \
-d contact[last_name]="Doe" \
-d contact[email]="jane@test.com" \
-d contact[label]="dev" \
-d contact[enabled]="true" \
-d contact[send_billing_email]="true" \
-d contact[send_account_email]="true"
Sample Response [ JSON ]
Show more...
{"customer": {
"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
Parameters for contact
pass parameters as contact[<param name>]
Resource object representing customer.
always returned
Resource object representing card.
optional
Deletes the contact information. Learn more about Contacts.
Sample Request
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzFdC3/delete_contact \
-u {site_api_key}:\
-d contact[id]="contact___test__5SK0bLNFRFuBzG9C5"
copy
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzFdC3/delete_contact \
-u {site_api_key}:\
-d contact[id]="contact___test__5SK0bLNFRFuBzG9C5"
Sample Response [ 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
Parameters for contact
pass parameters as contact[<param name>]
Resource object representing customer.
always returned
Resource object representing card.
optional
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.
Sample Request
curl https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPq8ZI3q/add_account_credits \
-u {site_api_key}:\
-d amount=500 \
-d description="Loyalty credits"
copy
curl https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPq8ZI3q/add_account_credits \
-u {site_api_key}:\
-d amount=500 \
-d description="Loyalty credits"
Sample Response [ 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
Credit amount to be added.
required, in cents, min=1
Description for this credit.
required, string, max chars=250
Resource object representing customer.
always returned
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.
Sample Request
curl https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPqBDO4m/deduct_account_credits \
-u {site_api_key}:\
-d amount=200 \
-d description="Correcting credits given by mistake"
copy
curl https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPqBDO4m/deduct_account_credits \
-u {site_api_key}:\
-d amount=200 \
-d description="Correcting credits given by mistake"
Sample Response [ 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
Credit amount to be deducted.
required, in cents, min=1
Description for this credit.
required, string, max chars=250
Resource object representing customer.
always returned
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.
Sample Request
curl https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPqBqT5I/set_account_credits \
-u {site_api_key}:\
-d amount=500 \
-d description="Loyalty credits"
copy
curl https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPqBqT5I/set_account_credits \
-u {site_api_key}:\
-d amount=500 \
-d description="Loyalty credits"
Sample Response [ 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
Credit amount to be set.
required, in cents, min=0
Description for this credit.
required, string, max chars=250
Resource object representing customer.
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/v1/customers/__test__5SK0bLNFRFuBzESC1/delete \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzESC1/delete \
-X POST \
-u {site_api_key}:
Sample Response [ 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
Deletes the Payment Method from the gateway/vault.
optional, boolean, default=true
Resource object representing customer.
always returned
Resource object representing card.
optional