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.
{
"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"
}
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
. 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:
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.
# 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"
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
. curl https://{site}.chargebee.com/api/v1/customers \ -G \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzQTCQ \ -u {site_api_key}:
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.
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzRjCS \ -u {site_api_key}:\ -d first_name="Denise" \ -d last_name="Barone"
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.
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"
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.
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"
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
. Creates an additional contact for the customer. You can add up to a maximum of 6 contacts. Learn more about Contacts.
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
Updates the contact information. Learn more about Contacts.
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
Deletes the contact information. Learn more about Contacts.
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzFdC3/delete_contact \ -u {site_api_key}:\ -d contact[id]="contact___test__5SK0bLNFRFuBzG9C5"
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.
curl https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPq8ZI3q/add_account_credits \ -u {site_api_key}:\ -d amount=500 \ -d description="Loyalty credits"
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.
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"
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.
curl https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPqBqT5I/set_account_credits \ -u {site_api_key}:\ -d amount=500 \ -d description="Loyalty credits"
Deletes the customer resource.
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.
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBzESC1/delete \ -X POST \ -u {site_api_key}: