Represents a customer. Subscriptions, Card and Billing Address are associated with the customer resource. Customer resource will be created along with subscription via "Create a Subscription" API. The id of the customer will be same as that of associated subscription id if not explictly set.
Legacy behavior:
- For sites created before March 1st, 2014: Whenever the
card
is updated, the billing_address
and vat_number
of the customer are deleted and replaced by the values sent with the request.
- For sites created on or after March 1st, 2014: The
billing_address
and vat_number
are not changed when the associated card is updated.
Sample customer [ JSON ]
{
"allow_direct_debit": false,
"auto_collection": "on",
"billing_address": {
"city": "Walnut",
"country": "US",
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"object": "billing_address",
"state": "California",
"state_code": "CA",
"validation_status": "not_validated",
"zip": "91789"
},
"card_status": "no_card",
"created_at": 1517505731,
"deleted": false,
"email": "john@test.com",
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl7eY2bl",
"last_name": "Doe",
"locale": "fr-CA",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505731000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505731
}
API Index URL GET
https://{site}.chargebee.com/api/v2/customers
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.
The preferred offline payment method for the customer.
optional, enumerated stringPossible values are
no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.
The number of days within which the customer has to make payment for the invoice.
integer, default=0
vat_number_validated_time
Returns the recent VAT number validation time.
optional, timestamp(UTC) in seconds
The VAT validation status. This is only applicable if you have configured EU or Australian taxes and the VAT number validation is enabled. For UK, the value is always
undetermined
.
optional, enumerated stringPossible values are
validIf the given VAT number is valid.invalidIf the given VAT number is invalid.not_validatedThis status is only applicable for countries in European Zone. This is applicable when both the customer’s billing address and the organization’s address should be of the same European Zone and EU tax should be configured with the “‘Also validate VAT Number for Country of Business’” option in the disabled status.undeterminedWhen Chargebee is not able to validate the VAT number it is stored as ‘undetermined’. This can occur due to reasons like service outage etc. VAT numbers with ‘undetermined’ status will be in queue for validation on daily basis.
Whether the customer can pay via Direct Debit.
boolean, default=false
Customer location is validated based on IP address and Card issuing country. If the location is valid, it returns True. If not, it returns False. Applicable only for EU, New Zealand and Australia.
optional, boolean
Timestamp indicating when this customer resource is created.
timestamp(UTC) in seconds
The IP address of the customer. Used primarily for
referral integrations and EU/UK VAT validation.
optional, string, max chars=50
Indicates the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
To know more about what values you need to provide, refer to this
Avalara’s API document.
optional, jsonarray
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxablePossible 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.
.
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's
AvaTax for Sales integration.
optional, enumerated stringPossible values are
aFederal government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.eCharitable or benevolent organization.fReligious organization.gResale.hCommercial agricultural production.iIndustrial production/manufacturer.jDirect pay permit.kDirect mail.lOther or custom.mEducational organization.nLocal government.pCommercial aquaculture.qCommercial Fishery.rNon-resident.med1US Medical Device Excise Tax with exempt sales tax.med2US Medical Device Excise Tax with taxable sales tax.
Show all values[+]
Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's
AvaTax for Sales integration.
optional, string, max chars=100
Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long
Timestamp indicating when this customer was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, timestamp(UTC) in seconds
Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication.
optional, string, max chars=50
Applicable when calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the monthly and yearly subscriptions of this customer will be aligned to this date.
optional, integer, min=1, max=31
Indicates whether this customer's
billing_date value is derived as per configurations or its specifically set (overriden). When specifically set, the
billing_date will not be reset even when all of the monthly/yearly subscriptions are cancelled.
optional, enumerated stringPossible values are
using_defaultsBilling date is set based on defaults configured.manually_setBilling date is specifically set (default configuration is overridden).
Applicable when
calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the weekly subscriptions of this customer will be aligned to this week day.
optional, enumerated stringPossible values are
sundaySunday.mondayMonday.tuesdayTuesday.wednesdayWednesday.thursdayThursday.fridayFriday.saturdaySaturday.
Indicates whether this customer's
billing_day_of_week value is derived as per configurations or its specifically set (overriden). When specifically set, the
billing_day_of_week will not be reset even when all of the weekly subscriptions are cancelled.
optional, enumerated stringPossible values are
using_defaultsBilling date is set based on defaults configured.manually_setBilling date is specifically set (default configuration is overridden).
Indicates whether this customer's personal information has been cleared .
optional, enumerated string, default=activePossible values are
activeActive.scheduled_for_clearScheduled For Clear.clearedCleared.
Override for this customer, the
site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute is also available at the
subscription level which takes precedence.
optional, boolean
Indicates whether or not the customer has been identified as fraudulent.
optional, enumerated stringPossible values are
safeThe customer has been marked as safe.suspiciousThe customer has been identified as potentially fraudulent by the gateway.fraudulentThe customer has been marked as fraudulent.
primary_payment_source_id
Primary payment source for the customer.
optional, string, max chars=40
Backup payment source for the customer. Used to collect payment if primary payment source fails.
optional, string, max chars=40
Invoice Notes for this resource.
optional, string, max chars=2000
TThe currency code of the customer's preferred currency (ISO 4217 format). Applicable if the Multicurrency feature is enabled.
optional, string, max chars=3
Promotional credits balance of this customer.
in cents, min=0
Total unbilled charges for 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
A set of key-value pairs stored as additional information for the subscription.
Learn more.
optional, jsonobject
Indicates that this resource has been deleted.
boolean
Confirms that a customer is registered under GST. If set to
true
then the
Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.
optional, boolean
Indicates the type of the customer. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, enumerated stringPossible values are
residentialWhen the purchase is made by a customer for home use.businessWhen the purchase is made at a place of business.senior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaks.industrialWhen the purchase is made by an industrial business.
business_customer_without_vat_number
Confirms that a customer is a valid business without an EU/UK VAT number.
optional, boolean
use_default_hierarchy_settings
Indicates whether the site-default settings are being used for controlling access to the customer’s information.
The level of access is for data falling into two categories:
- Self-Serve Portal data: subscriptions and invoices of the customer.
- Email Notifications: subscription-, invoice- and payment-related notifications for the customer.
.
optional, boolean, default=true
Billing address for a customer.
optional, billing_address
Billing addres attributes
The first name of the billing contact.
optional, string, max chars=150
The last name of the billing contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
The company name.
optional, string, max chars=250
The 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
The name of the 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
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
State or Province.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
List of referral urls for the customer (if applicable).
optional, list of referral_url
External customer id in the referral system.
optional, string, max chars=100
Referral sharing url for the customer.
string, max chars=50
The referral url creation time.
timestamp(UTC) in seconds
The referral url updation time.
timestamp(UTC) in seconds
Referral campaign id.
string, max chars=50
Referral account id.
string, max chars=50
referral_external_campaign_id
Referral external campaign id.
optional, string, max chars=50
Url for the referral system account.
enumerated stringPossible values are
referral_candyReferral Candy.referral_saasquatchReferral Saasquatch.friendbuyFriendbuy.
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.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.
Show all values[+]
Name of the gateway the payment method is associated with.
enumerated stringPossible values are
chargebeeChargebee test gateway.stripeStripe payment gateway.wepayWePay Gateway.braintreeBraintree payment gateway.authorize_netAuthorize.net payment gateway.paypal_proPaypal Pro Account.pinPin payment gateway.ewayeWAY Account.eway_rapideWAY Rapid gateway.worldpayWorldPay payment gateway.balanced_paymentsBalanced payment gateway.beanstreamBambora (formerly Beanstream).bluepayBluePay payment gateway.elavonElavon Virtual Merchant.first_data_globalFirst Data Global Gateway Virtual Terminal Account.hdfcHDFC Account.migsMasterCard Internet Gateway Service.nmiNMI gateway.ogoneIngenico ePayments (formerly Ogone).paymillPAYMILL payment gateway.paypal_payflow_proPayPal Payflow Pro gateway.sage_paySage Pay gateway.tco2Checkout payment gateway.wirecardWireCard Account.amazon_paymentsThe amazon payments.paypal_express_checkoutThe paypal gateway.gocardlessGoCardless.adyenAdyen.orbitalChase Paymentech(Orbital) Gateway.moneris_usMoneris USA Gateway.monerisMoneris Gateway.bluesnapBlueSnap gateway.cybersourceCyberSource gateway.vantivVantiv gateway.checkout_comCheckout.com Gateway.paypalPaypal Commerce.ingenico_directIngenico ePayments.exactExact Payments gateway.not_applicableIndicates that payment gateway is not applicable for this resource.
Show all values[+]
The gateway account this payment method is stored with.
optional, string, max chars=50
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.pending_verificationThe payment source needs to be verified.
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
The list of balances for this customer.
optional, list of customer_balance
Promotional credits balance of this customer.
in cents, default=0, min=0
Total unused payments associated with the customer.
in cents, default=0, min=0
Refundable credits balance of this customer.
in cents, default=0, min=0
Total unbilled charges for this customer.
in cents, default=0, min=0
The currency code (ISO 4217 format) for balance.
string, max chars=3
The
Account Hierarchy relationship that the customer is part of.
optional, relationship
The id
of the customer who is the immediate parent.
optional, string, max chars=50
The id
of the customer who pays the invoices for this customer. Can be the customer itself or the invoice_owner_id
.
string, max chars=50
The id
of the customer who is invoiced for charges incurred. Can be the customer itself or any parent in its hierarchy.
string, max chars=50
Defines the level of access that the parent account has to the customer's information.
Note: the 'parent' is the customer whose id is
payment_owner_id. However, if the
payment_owner_id
is the customer itself, then the parent is
parent_id.
optional, parent_account_access
Parent account acces attributes
portal_edit_child_subscriptions
Sets parent's level of access to child subscriptions on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe parent account can view and edit the subscriptions of the child account.view_onlyThe parent account can only view the subscriptions of the child account.noThe parent account cannot view or edit the subscriptions of the child account.
portal_download_child_invoices
Sets parent's level of access to child invoices on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe parent account can view and download the invoices of the child account.view_onlyThe parent account can only view the invoices of the child account.noThe parent account can neither view nor download the invoices of the child account.
If true
, the parent account will receive subscription-related emails sent to the child account.
boolean
If true
, the parent account will receive invoice-related emails sent to the child account.
boolean
If true
, the parent account will receive payment-related emails sent to the child account.
boolean
Defines the level of access that the customer has to its own information.
optional, child_account_access
Child account acces attributes
portal_edit_subscriptions
Sets the child's level of access to its own subscriptions on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe child account can view and edit its own subscriptions.view_onlyThe child account can only view its own subscriptions.
Sets the child’s level of access to its own invoices on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe child account can view and download its own invoices.view_onlyThe child account can only view its invoices and not download them.noThe child account can neither view nor download its own invoices.
If true
, the child account will receive subscription-related emails for its own subscriptions.
boolean
If true
, the child account will receive invoice-related emails for its own invoices.
boolean
If true
, the child account will receive payment-related emails for its own invoices.
boolean
This operation supports 3DS verification flow. To achieve the same, create the
Payment Intent and pass it as input parameter to this API.
Creates a customer. You can create a customer and then create subscriptions for the customer when required. When creating a customer, you can pass along the billing address and card details.
Passing raw card data via API involves PCI liability at your end due to the sensitivity of the data. Instead, you can use one of the following integration options as applicable:
Here’s some resources you can use to collect card information within your checkout form based on the payment gateway you use:
- Stripe.js for Stripe users. Here's how you can set it up.
- Braintree.js for Braintree users.
- Accept.js, if you use Authorize.Net.
- If you are using the Adyen gateway, you will have to use the Adyen’s Client Side Encryption to encrypt sensitive cardholder data. Once the cardholder data is encrypted, pass the value in
adyen.encrypted.data
as temp token in this API.
- You can also use our Hosted Pages based integration.
When billing address is not passed (say, for customers making offline payments), you can always provide it later using the Update billing info for a customer API.
Note: When an invoice is generated for a customer, the billing address provided for the customer is stored with the invoice. If the First Name, Last Name, and Company fields of the billing address do not contain any information, they’re picked up from the customer details.
Sample Request
# creates a customer with billing address.
curl https://{site}.chargebee.com/api/v2/customers \
-u {site_api_key}:\
-d first_name="John" \
-d last_name="Doe" \
-d email="john@test.com" \
-d locale="fr-CA" \
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
copy
# creates a customer with billing address.
curl https://{site}.chargebee.com/api/v2/customers \
-u {site_api_key}:\
-d first_name="John" \
-d last_name="Doe" \
-d email="john@test.com" \
-d locale="fr-CA" \
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
# creates a customer with bank account.
curl https://{site}.chargebee.com/api/v2/customers \
-u {site_api_key}:\
-d first_name="John" \
-d last_name="Doe" \
-d allow_direct_debit="true" \
-d email="john@test.com" \
-d bank_account[account_number]="000222222227" \
-d bank_account[routing_number]="110000000" \
-d bank_account[bank_name]="US Bank" \
-d bank_account[account_holder_type]="individual" \
-d bank_account[account_type]="savings" \
-d bank_account[first_name]="Shay" \
-d bank_account[last_name]="Liam" \
-d bank_account[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju"
# creates a customer with card details.
curl https://{site}.chargebee.com/api/v2/customers \
-u {site_api_key}:\
-d first_name="John" \
-d last_name="Doe" \
-d email="john@test.com" \
-d card[first_name]="Richard" \
-d card[last_name]="Fox" \
-d card[number]="4012888888881881" \
-d card[expiry_month]=10 \
-d card[expiry_year]=2022 \
-d card[cvv]="999"
# creates a customer with payment source.
# NOTE : The parameters paymentMethod[tmp_token] and paymentMethod[reference_id] should not be passed together.
curl https://{site}.chargebee.com/api/v2/customers \
-u {site_api_key}:\
-d first_name="John" \
-d last_name="Doe" \
-d payment_method[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju" \
-d payment_method[type]="card" \
-d payment_method[reference_id]="cus_I58PkwpAskxXlJ"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"billing_address": {
"city": "Walnut",
"country": "US",
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"object": "billing_address",
"state": "California",
"state_code": "CA",
"validation_status": "not_validated",
"zip": "91789"
},
"card_status": "no_card",
"created_at": 1517505731,
"deleted": false,
"email": "john@test.com",
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl7eY2bl",
"last_name": "Doe",
"locale": "fr-CA",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505731000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505731
}}
Show more...
{"customer": {
"allow_direct_debit": true,
"auto_collection": "on",
"created_at": 1517505733,
"deleted": false,
"email": "john@test.com",
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl8Ni2bt",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "stripe",
"gateway_account_id": "gw___test__KyVnGlSBWl8M41ju",
"object": "payment_method",
"reference_id": "cus_I58PxQNyWviXnc/ba_1HUy94Jv9j0DyntJTimRcJbw",
"status": "pending_verification",
"type": "direct_debit"
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm___test__KyVnHhSBWl8eE2bu",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505734000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505734
}}
Show more...
{
"card": {
"card_type": "visa",
"created_at": 1517505732,
"customer_id": "__test__KyVnHhSBWl81p2bn",
"expiry_month": 10,
"expiry_year": 2022,
"first_name": "Richard",
"funding_type": "not_known",
"gateway": "chargebee",
"gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
"iin": "401288",
"last4": "1881",
"last_name": "Fox",
"masked_number": "************1881",
"object": "card",
"payment_source_id": "pm___test__KyVnHhSBWl82m2bp",
"resource_version": 1517505732000,
"status": "valid",
"updated_at": 1517505732
},
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1517505732,
"deleted": false,
"email": "john@test.com",
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl81p2bn",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "chargebee",
"gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
"object": "payment_method",
"reference_id": "tok___test__KyVnHhSBWl82h2bo",
"status": "valid",
"type": "card"
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm___test__KyVnHhSBWl82m2bp",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505732000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505732
}
}
Show more...
{
"card": {
"card_type": "visa",
"created_at": 1517505737,
"customer_id": "__test__KyVnHhSBWl9AC2c3",
"expiry_month": 12,
"expiry_year": 2022,
"funding_type": "credit",
"gateway": "stripe",
"gateway_account_id": "gw___test__KyVnGlSBWl8M41ju",
"iin": "******",
"issuing_country": "US",
"last4": "1111",
"masked_number": "************1111",
"object": "card",
"payment_source_id": "pm___test__KyVnHhSBWl9Fw2c4",
"powered_by": "not_applicable",
"resource_version": 1517505737000,
"status": "valid",
"updated_at": 1517505737
},
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1517505736,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl9AC2c3",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "stripe",
"gateway_account_id": "gw___test__KyVnGlSBWl8M41ju",
"object": "payment_method",
"reference_id": "cus_I58PkwpAskxXlJ/card_1HUy96Jv9j0DyntJq6XwrBKd",
"status": "valid",
"type": "card"
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm___test__KyVnHhSBWl9Fw2c4",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505737000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505737
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/customers
Id 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
The currency code (ISO 4217 format) of the customer. Applicable if Multicurrency is enabled.
optional, string, max chars=3
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.
The number of days within which the customer has to make payment for the invoice.
optional, integer, default=0
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
Confirms that a customer is registered under GST. If set to
true
then the
Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.
optional, boolean
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxablePossible 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.
.
Indicates the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
To know more about what values you need to provide, refer to this
Avalara’s API document.
optional, jsonarray
Indicates the type of the customer. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, enumerated stringPossible values are
residentialWhen the purchase is made by a customer for home use.businessWhen the purchase is made at a place of business.senior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaks.industrialWhen the purchase is made by an industrial business.
taxjar_exemption_category
Indicates the exemption type of the customer. This is applicable only if you use Chargebee’s TaxJar integration.
optional, enumerated stringPossible values are
wholesaleWhole-sale.governmentGovernment.otherOther.
business_customer_without_vat_number
Confirms that a customer is a valid business without an EU/UK VAT number.
optional, boolean
Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication.
optional, string, max chars=50
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's
AvaTax for Sales integration.
optional, enumerated stringPossible values are
aFederal government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.eCharitable or benevolent organization.fReligious organization.gResale.hCommercial agricultural production.iIndustrial production/manufacturer.jDirect pay permit.kDirect mail.lOther or custom.mEducational organization.nLocal government.pCommercial aquaculture.qCommercial Fishery.rNon-resident.med1US Medical Device Excise Tax with exempt sales tax.med2US Medical Device Excise Tax with taxable sales tax.
Show all values[+]
Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's
AvaTax for Sales integration.
optional, string, max chars=100
A set of key-value pairs stored as additional information for the subscription.
Learn more.
optional, jsonobject
The preferred offline payment method for the customer.
optional, enumerated stringPossible values are
no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.
Override for this customer, the
site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute is also available at the
subscription level which takes precedence.
optional, boolean
Applicable when consolidated invoicing is enabled. Indicates whether invoice consolidation should happen during subscription renewals. Needs to be set only if this value is different from the defaults configured.
optional, boolean
The Chargebee payment token generated by Chargebee JS.
optional, string, max chars=40
Invoice Notes for this resource.
optional, string, max chars=2000
Parameters for card
pass parameters as card[<param name>]
The gateway account in which this payment source is stored.
optional, string, max chars=50
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 (CVV). 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
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
Parameters for bank_account
pass parameters as bank_account[<param name>]
bank_account[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
Account holder’s International Bank Account Number. For the
GoCardless platform, this can be the
local bank details
.
optional, string, min chars=10, max chars=50
Account holder’s first name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150
Account holder’s last name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150
Account holder’s company name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=250
Account holder’s email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.
optional, string, max chars=70
Name of account holder’s bank.
optional, string, max chars=100
bank_account[account_number]
Account holder’s bank account number.
optional, string, min chars=4, max chars=17
bank_account[routing_number]
Bank account routing number.
optional, string, min chars=3, max chars=9
Indicates the bank code.
optional, string, max chars=20
bank_account[account_type]
For Authorize.net ACH users only. Indicates the type of account.
optional, enumerated stringPossible values are
checkingChecking Account.savingsSavings Account.business_checkingBusiness Checking Account.
bank_account[account_holder_type]
For Stripe ACH users only. Indicates the account holder type.
optional, enumerated stringPossible values are
individualIndividual.companyCompany.
bank_account[echeck_type]
For Authorize.net ACH users only. Indicates the type of eCheck.
optional, enumerated stringPossible values are
webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.
bank_account[issuing_country]
2-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.
optional, string, max chars=50
bank_account[swedish_identity_number]
For GoCardless Autogiro users only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
optional, string, min chars=10, max chars=12
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.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.
Show all values[+]
payment_method[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
payment_method[reference_id]
The reference id. In the case of Amazon and PayPal this will be the
billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer
Update payment method for a customer API under Customer resource.
optional, string, max chars=200
payment_method[tmp_token]
Single-use tokens created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
required if reference_id not provided, string, max chars=65k
payment_method[issuing_country]
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
payment_intent[additional_info]
Applicable only for Braintree gateway. Can be used only for Braintree’s
Advance Fraud Management feature. Pass a stringified JSON containing the
device_session_id
and
fraud_merchant_id
as an input to
fingerprint
. Here’s a
sample to it.
optional, jsonobject
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
The first name of the billing contact.
optional, string, max chars=150
billing_address[last_name]
The last name of the billing contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
The company name.
optional, string, max chars=250
The 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
The name of the 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
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
billing_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Resource object representing customer.
always returned
Resource object representing card.
optional
Retrieves the list of customers.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers \
-G \
-u {site_api_key}:\
--data-urlencode first_name[is]="John" \
--data-urlencode last_name[is]="Doe" \
--data-urlencode email[is]="john@test.com"
copy
curl https://{site}.chargebee.com/api/v2/customers \
-G \
-u {site_api_key}:\
--data-urlencode first_name[is]="John" \
--data-urlencode last_name[is]="Doe" \
--data-urlencode email[is]="john@test.com"
Sample Response [ JSON ]
Show more...
{"list": [
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"created_at": 1517505747,
"deleted": false,
"email": "john@test.com",
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWlC1T2cj",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505747000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505747
}},
{..}
]}
URL Format GET
https://{site}.chargebee.com/api/v2/customers
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset
to the value of next_offset
obtained in the previous iteration of the API call.
optional, string, max chars=1000
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
optional, boolean, default=false
Sorts based on the specified attribute.
Supported attributes : created_at, updated_at
Supported sort-orders : asc, desc
Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.
optional, string filter
Identifier of the customer.
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "9bsvnHgsvmsI"
optional, string filter
First name of the customer.
Supported operators : is, is_not, starts_with, is_present
Example → first_name[is] = "John"
optional, string filter
Last name of the customer.
Supported operators : is, is_not, starts_with, is_present
Example → last_name[is] = "Clint"
optional, string filter
Email of the customer. Configured email notifications will be sent to this email.
Supported operators : is, is_not, starts_with, is_present
Example → email[is] = "john@test.com"
optional, string filter
Company name of the customer.
Supported operators : is, is_not, starts_with, is_present
Example → company[is_not] = "Globex Corp"
optional, string filter
Phone number of the customer.
Supported operators : is, is_not, starts_with, is_present
Example → phone[is_not] = "(541) 754-3010"
optional, string filter
auto_collection[<operator>]
Whether payments needs to be collected automatically for this customer. Possible values are : on, off.
Supported operators : is, is_not, in, not_in
Example → auto_collection[is] = "on"
optional, enumerated string filter
Specifies if the customer is liable for tax. Possible values are : taxable, exempt.
Supported operators : is, is_not, in, not_in
Example → taxability[is] = "taxable"
optional, enumerated string filter
Timestamp indicating when this customer resource is created.
Supported operators : after, before, on, between
Example → created_at[on] = "1435054328"
optional, timestamp(UTC) in seconds filter
To filter based on updated_at
. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by
input parameter as updated_at
for a faster response.
Supported operators : after, before, on, between
Example → updated_at[after] = "1243545465"
optional, timestamp(UTC) in seconds filter
offline_payment_method[<operator>]
The preferred offline payment method for the customer. Possible values are : no_preference, cash, check, bank_transfer, ach_credit, sepa_credit.
Supported operators : is, is_not, in, not_in
Example → offline_payment_method[is_not] = "cash"
optional, enumerated string filter
auto_close_invoices[<operator>]
Override for this customer, the
site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute is also available at the
subscription level which takes precedence. Possible values are :
true, falseSupported operators : is
Example → auto_close_invoices[is] = "true"optional, boolean filter
Parameters for relationship
pass parameters as relationship[<param name>][<operator>]
relationship[parent_id][operator]
Immediate parent with whom we will link our new customer(child).
Supported operators : is, is_not, starts_with
Example → relationship[parent_id][is_not] = "future_billing"
optional, string filter
relationship[payment_owner_id][operator]
Parent who is going to pay.
Supported operators : is, is_not, starts_with
Example → relationship[payment_owner_id][is] = "active1"
optional, string filter
relationship[invoice_owner_id][operator]
Parent who is going to handle invoices.
Supported operators : is, is_not, starts_with
Example → relationship[invoice_owner_id][is_not] = "future_billing"
optional, string filter
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/v2/customers/__test__KyVnHhSBWlF0Q2dg \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlF0Q2dg \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"created_at": 1517505759,
"deleted": false,
"excess_payments": 0,
"first_name": "David",
"id": "__test__KyVnHhSBWlF0Q2dg",
"last_name": "Louis",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505759000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505759
}}
URL Format GET
https://{site}.chargebee.com/api/v2/customers/{customer_id}
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/v2/customers/__test__KyVnHhSBWlFGC2di \
-u {site_api_key}:\
-d first_name="Denise" \
-d last_name="Barone" \
-d locale="fr-CA"
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFGC2di \
-u {site_api_key}:\
-d first_name="Denise" \
-d last_name="Barone" \
-d locale="fr-CA"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"created_at": 1517505760,
"deleted": false,
"excess_payments": 0,
"first_name": "Denise",
"id": "__test__KyVnHhSBWlFGC2di",
"last_name": "Barone",
"locale": "fr-CA",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505760000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505760
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}
First name 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
The currency code (ISO 4217 format) of the customer. Applicable if Multicurrency is enabled.
optional, string, max chars=3
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
The number of days within which the customer has to make payment for the invoice.
optional, integer
Specifies if the customer is liable for tax.
optional, enumerated stringPossible 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.
.
Indicates the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
To know more about what values you need to provide, refer to this
Avalara’s API document.
optional, jsonarray
Indicates the type of the customer. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, enumerated stringPossible values are
residentialWhen the purchase is made by a customer for home use.businessWhen the purchase is made at a place of business.senior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaks.industrialWhen the purchase is made by an industrial business.
taxjar_exemption_category
Indicates the exemption type of the customer. This is applicable only if you use Chargebee’s TaxJar integration.
optional, enumerated stringPossible values are
wholesaleWhole-sale.governmentGovernment.otherOther.
Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication.
optional, string, max chars=50
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's
AvaTax for Sales integration.
optional, enumerated stringPossible values are
aFederal government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.eCharitable or benevolent organization.fReligious organization.gResale.hCommercial agricultural production.iIndustrial production/manufacturer.jDirect pay permit.kDirect mail.lOther or custom.mEducational organization.nLocal government.pCommercial aquaculture.qCommercial Fishery.rNon-resident.med1US Medical Device Excise Tax with exempt sales tax.med2US Medical Device Excise Tax with taxable sales tax.
Show all values[+]
Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's
AvaTax for Sales integration.
optional, string, max chars=100
The preferred offline payment method for the customer.
optional, enumerated stringPossible values are
no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.
Invoice Notes for this resource.
optional, string, max chars=2000
Override for this customer, the
site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute is also available at the
subscription level which takes precedence.
optional, boolean
A set of key-value pairs stored as additional information for the subscription.
Learn more.
optional, jsonobject
Indicates whether or not the customer has been identified as fraudulent.
optional, enumerated stringPossible values are
safeThe customer has been marked as safe.fraudulentThe customer has been marked as fraudulent.
Applicable when consolidated invoicing is enabled. Indicates whether invoice consolidation should happen during subscription renewals. Needs to be set only if this value is different from the defaults configured.
optional, boolean
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, it is provided to help you understand the billing workflow in Chargebee.
PayPal Express Checkout
You can use this API if you are directly integrating PayPal Express Checkout in your website instead of using Chargebee's hosted pages. When your customer updates his payment method using PayPal Express Checkout, you will be provided with the Billing Agreement ID by PayPal. You can update the payment method for that customer in Chargebee by passing type
as paypal_express_checkout
and reference_id
with the Billing Agreement ID.
Login and Pay with Amazon
You can use this API if you are directly integrating Login and Pay with Amazon in your website instead of using Chargebee's hosted pages. When your customer updates Amazon as a payment method, you will be provided with the Billing Agreement ID by Amazon. You can update the payment method for that customer in Chargebee by passing type
as amazon_payments
and reference_id
with the Billing Agreement ID.
Card Payments
When the card details of your customer are stored in the vault of gateways such as Stripe or Braintree, you can use this API to update the reference id provided by them in Chargebee. To use this API, pass
-
type
as card
.
-
gateway
with the gateway associated with the card. If the gateway is not specified, the default gateway will be used.
-
reference_id
with the identifier provided by the gateway/Spreedly to reference that specific card.
Reference id format for Card Payments
The format of reference_id will differ based on where the card is stored.
Stripe: In case of Stripe, the reference_id consists of combination of Stripe Customer ID and Stripe Card ID separated by forward slash (e.g. cus_63MnDn0t6kfDW7/card_6WjCF20vT9WN1G). If you are passing Stripe Customer ID alone, then Chargebee will store the card marked as active for that customer in Stripe.
Braintree: In case of Braintree, the reference_id consists of combination of Braintree Customer ID and Braintree Payment Method Token separated by forward slash
(e.g. cus_63MnDn0t6kfDW7/card_6WjCF20vT9WN1G ). If you are passing Braintree Customer ID alone, then Chargebee will store the card marked as default for that customer in Braintree.
Spreedly Card vault: If the card details are stored in Spreedly vault, then you need to provide the Spreedly token as reference_id
.
Direct Debit Payments
When the bank account details of your customer are stored in the gateway vault, you can use this API to update the reference id provided by them in Chargebee. To use this API, pass
-
type
as direct_debit
.
-
gateway
with the gateway where the bank account details are stored (e.g. authorize_net). If the gateway is not specified, the gateway supporting the direct debit will be used.
-
reference_id
with the identifier provided by the gateway to reference the customer's bank account details.
-
tmp_token
with the single use token provided by the gateway ( Should be passed only if reference_id is not passed ).
Reference id format for Direct Debit Payments
The format of reference_id will differ based on where the bank account is stored.
Stripe: In case of Stripe, the reference_id consists of combination of Stripe Customer ID and Stripe Bank Account ID separated by forward slash
(e.g. cus_8suoHaLQH4G5AW/ba_18b8z2KmcbENlhgU03RznRYW). If you are passing Stripe Customer ID alone, then Chargebee will store the first bank account details present in payment profile list of that customer in Stripe.
Authorize.Net: The reference_id consists of combination of Authorize.Net's Customer Profile ID and Payment Profile ID separated by forward slash (e.g. 2384383/34834382). If you are passing Authorize.Net's Customer Profile ID alone, then Chargebee will store the first bank account details present in payment profile list of that customer in Authorize.Net.
GoCardless: The reference_id is the GoCardless Customer Mandate ID (e.g. MD0077Z99TTQXK).
Note: While using this API to update payment method details, Card Verification will not happen even if it is enabled for that particular gateway.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlHEO2eE/update_payment_method \
-u {site_api_key}:\
-d payment_method[type]="card" \
-d payment_method[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju" \
-d payment_method[reference_id]="cus_I58QViSiwuelqF"
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlHEO2eE/update_payment_method \
-u {site_api_key}:\
-d payment_method[type]="card" \
-d payment_method[gateway_account_id]="gw___test__KyVnGlSBWl8M41ju" \
-d payment_method[reference_id]="cus_I58QViSiwuelqF"
Sample Response [ JSON ]
Show more...
{
"card": {
"card_type": "visa",
"created_at": 1517505769,
"customer_id": "__test__KyVnHhSBWlHEO2eE",
"expiry_month": 12,
"expiry_year": 2022,
"funding_type": "credit",
"gateway": "stripe",
"gateway_account_id": "gw___test__KyVnGlSBWl8M41ju",
"iin": "******",
"issuing_country": "US",
"last4": "1111",
"masked_number": "************1111",
"object": "card",
"payment_source_id": "pm___test__KyVnHhSBWlHbr2eJ",
"powered_by": "not_applicable",
"resource_version": 1517505769000,
"status": "valid",
"updated_at": 1517505769
},
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1517505767,
"deleted": false,
"excess_payments": 0,
"first_name": "David",
"id": "__test__KyVnHhSBWlHEO2eE",
"last_name": "Young",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "stripe",
"gateway_account_id": "gw___test__KyVnGlSBWl8M41ju",
"object": "payment_method",
"reference_id": "cus_I58QViSiwuelqF/card_1HUy9cJv9j0DyntJNR5sLhy1",
"status": "valid",
"type": "card"
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm___test__KyVnHhSBWlHbr2eJ",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505769000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505769
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/update_payment_method
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.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.
Show all values[+]
payment_method[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
payment_method[reference_id]
The reference id. In the case of Amazon and PayPal this will be the
billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer
Update payment method for a customer API under Customer resource.
optional, string, max chars=200
payment_method[tmp_token]
Single-use toke created by payment gateways. In Stripe, a single-use token is created for direct debit. In Braintree, a nonce is created for PayPal.
required if reference_id not provided, string, max chars=65k
payment_method[issuing_country]
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/v2/customers/__test__KyVnHhSBWlFY32dl/update_billing_info \
-u {site_api_key}:\
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFY32dl/update_billing_info \
-u {site_api_key}:\
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"billing_address": {
"city": "Walnut",
"country": "US",
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"object": "billing_address",
"state": "California",
"state_code": "CA",
"validation_status": "not_validated",
"zip": "91789"
},
"card_status": "no_card",
"created_at": 1517505761,
"deleted": false,
"excess_payments": 0,
"first_name": "David",
"id": "__test__KyVnHhSBWlFY32dl",
"last_name": "Lewis",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505761000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505761
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/update_billing_info
VAT/ Tax registration number of the customer.
Learn more.
optional, string, max chars=20
Confirms that a customer is registered under GST. If set to
true
then the
Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.
optional, boolean
business_customer_without_vat_number
Confirms that a customer is a valid business without an EU/UK VAT number.
optional, boolean
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
The first name of the billing contact.
optional, string, max chars=150
billing_address[last_name]
The last name of the billing contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
The company name.
optional, string, max chars=250
The 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
The name of the 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
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
billing_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Resource object representing customer.
always returned
Resource object representing card.
optional
This API retrieves all the contacts for a customer.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlCK52cl/contacts \
-G \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlCK52cl/contacts \
-G \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"list": [
{"contact": {
"email": "jane@test.com",
"enabled": true,
"first_name": "Jane",
"id": "contact___test__KyVnHhSBWlCKq2cn",
"label": "dev",
"last_name": "Doe",
"object": "contact",
"send_account_email": true,
"send_billing_email": true
}},
{..}
]}
URL Format GET
https://{site}.chargebee.com/api/v2/customers/{customer_id}/contacts
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset
to the value of next_offset
obtained in the previous iteration of the API call.
optional, string, max chars=1000
Resource object representing contact.
always returned
next_offset
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000
Assign Primary or Backup payment role or unassign role for the payment source based on the preference for the payment collection.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl4rs2au/assign_payment_role \
-u {site_api_key}:\
-d payment_source_id="pm___test__KyVnHhSBWl4te2ax" \
-d role="primary"
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl4rs2au/assign_payment_role \
-u {site_api_key}:\
-d payment_source_id="pm___test__KyVnHhSBWl4te2ax" \
-d role="primary"
Sample Response [ JSON ]
Show more...
{
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1517505720,
"deleted": false,
"excess_payments": 0,
"first_name": "Mark",
"id": "__test__KyVnHhSBWl4rs2au",
"last_name": "Henry",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "chargebee",
"gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
"object": "payment_method",
"reference_id": "tok___test__KyVnHhSBWl4tX2aw",
"status": "valid",
"type": "card"
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm___test__KyVnHhSBWl4te2ax",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505720000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505720
},
"payment_source": {
"card": {
"brand": "american_express",
"expiry_month": 12,
"expiry_year": 2022,
"funding_type": "not_known",
"iin": "378282",
"last4": "0005",
"masked_number": "***********0005",
"object": "card"
},
"created_at": 1517505720,
"customer_id": "__test__KyVnHhSBWl4rs2au",
"deleted": false,
"gateway": "chargebee",
"gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
"id": "pm___test__KyVnHhSBWl4te2ax",
"object": "payment_source",
"reference_id": "tok___test__KyVnHhSBWl4tX2aw",
"resource_version": 1517505720000,
"status": "valid",
"type": "card",
"updated_at": 1517505720
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/assign_payment_role
Payment source id this role will be assigned to.
required, string, max chars=40
Indicates whether the payment source is Primary, Backup, or neither.
required, enumerated stringPossible values are
primaryPrimary.backupBackup.noneNone.
Resource object representing customer.
always returned
Resource object representing payment_source.
always returned
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5C82b2/add_contact \
-u {site_api_key}:\
-d contact[first_name]="Jane" \
-d contact[last_name]="Doe" \
-d contact[email]="jane@test.com" \
-d contact[label]="dev" \
-d contact[enabled]="true" \
-d contact[send_billing_email]="true" \
-d contact[send_account_email]="true"
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5C82b2/add_contact \
-u {site_api_key}:\
-d contact[first_name]="Jane" \
-d contact[last_name]="Doe" \
-d contact[email]="jane@test.com" \
-d contact[label]="dev" \
-d contact[enabled]="true" \
-d contact[send_billing_email]="true" \
-d contact[send_account_email]="true"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"contacts": [
{
"email": "jane@test.com",
"enabled": true,
"first_name": "Jane",
"id": "contact___test__KyVnHhSBWl5Cy2b4",
"label": "dev",
"last_name": "Doe",
"object": "contact",
"send_account_email": true,
"send_billing_email": true
},
{..}
],
"created_at": 1517505721,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl5C82b2",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505721000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505721
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/add_contact
Parameters for contact
pass parameters as contact[<param name>]
Resource object representing customer.
always returned
Resource object representing card.
optional
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFmo2do/update_contact \
-u {site_api_key}:\
-d contact[id]="contact___test__KyVnHhSBWlFnd2dq" \
-d contact[first_name]="Jane" \
-d contact[last_name]="Doe" \
-d contact[email]="jane@test.com" \
-d contact[label]="dev" \
-d contact[enabled]="true" \
-d contact[send_billing_email]="true" \
-d contact[send_account_email]="true"
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlFmo2do/update_contact \
-u {site_api_key}:\
-d contact[id]="contact___test__KyVnHhSBWlFnd2dq" \
-d contact[first_name]="Jane" \
-d contact[last_name]="Doe" \
-d contact[email]="jane@test.com" \
-d contact[label]="dev" \
-d contact[enabled]="true" \
-d contact[send_billing_email]="true" \
-d contact[send_account_email]="true"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"contacts": [
{
"email": "jane@test.com",
"enabled": true,
"first_name": "Jane",
"id": "contact___test__KyVnHhSBWlFnd2dq",
"label": "dev",
"last_name": "Doe",
"object": "contact",
"send_account_email": true,
"send_billing_email": true
},
{..}
],
"created_at": 1517505762,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWlFmo2do",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505762000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505762
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/update_contact
Parameters for contact
pass parameters as contact[<param name>]
Resource object representing customer.
always returned
Resource object representing card.
optional
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl9ta2cA/delete_contact \
-u {site_api_key}:\
-d contact[id]="contact___test__KyVnHhSBWl9uT2cC"
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl9ta2cA/delete_contact \
-u {site_api_key}:\
-d contact[id]="contact___test__KyVnHhSBWl9uT2cC"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"created_at": 1517505739,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl9ta2cA",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505739000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505739
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/delete_contact
Parameters for contact
pass parameters as contact[<param name>]
Resource object representing customer.
always returned
Resource object representing card.
optional
Use this API to record any excess payments made by the customer, such as advance payments. Such payments will be automatically applied to the future invoices. It can also be manually applied to the existing Not Paid or Payment Due invoices.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDEl2cz/record_excess_payment \
-u {site_api_key}:\
-d comment="Check payment received from John" \
-d transaction[amount]=500 \
-d transaction[date]=1600968152 \
-d transaction[payment_method]="check"
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDEl2cz/record_excess_payment \
-u {site_api_key}:\
-d comment="Check payment received from John" \
-d transaction[amount]=500 \
-d transaction[date]=1600968152 \
-d transaction[payment_method]="check"
Sample Response [ JSON ]
Show more...
{
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"balances": [
{
"balance_currency_code": "USD",
"currency_code": "USD",
"excess_payments": 500,
"object": "customer_balance",
"promotional_credits": 0,
"refundable_credits": 0,
"unbilled_charges": 0
},
{..}
],
"card_status": "no_card",
"created_at": 1517505752,
"deleted": false,
"excess_payments": 500,
"first_name": "John",
"id": "__test__KyVnHhSBWlDEl2cz",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505752000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505752
},
"transaction": {
"amount": 500,
"amount_unused": 500,
"base_currency_code": "USD",
"currency_code": "USD",
"customer_id": "__test__KyVnHhSBWlDEl2cz",
"date": 1600968152,
"deleted": false,
"exchange_rate": 1,
"gateway": "not_applicable",
"id": "txn___test__KyVnHhSBWlDFn2d1",
"linked_invoices": [],
"linked_refunds": [],
"object": "transaction",
"payment_method": "check",
"resource_version": 1517505752000,
"status": "success",
"type": "payment",
"updated_at": 1517505752
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/record_excess_payment
Remarks, if any, on the payment.
optional, string, max chars=300
Parameters for transaction
pass parameters as transaction[<param name>]
The payment transaction amount.
required, in cents, min=1
transaction[currency_code]
The currency code (ISO 4217 format) for the transaction.
required if Multicurrency is enabled, string, max chars=3
Indicates when this transaction occurred.
required, timestamp(UTC) in seconds
transaction[payment_method]
The payment method of this transaction.
required, enumerated string, default=cardPossible values are
cashCash.checkCheck.bank_transferBank Transfer.otherPayment Methods other than the above types.
Show all values[+]
transaction[reference_number]
The reference number for this transaction. e.g check number in case of 'check' payments.
optional, string, max chars=100
Resource object representing customer.
always returned
Resource object representing transaction.
always returned
This operation supports 3DS verification flow. To achieve the same, create the
Payment Intent and pass it as input parameter to this API.
This API can be used to collect the payments for customer’s payment_due and not_paid invoices. You can either choose to collect the payment from an existing payment source or a new payment source. You can choose to either retain or discard the new payment source, which is being used for payment. If the amount collected exceeds the invoice amount, the surplus will be counted in as excess payments.
Sample Request
# collects payment for the customer with the existing payment source.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl6A32bF/collect_payment \
-X POST \
-u {site_api_key}:\
-d amount=100 \
-d payment_source_id="pm___test__KyVnHhSBWl6Q02bG" \
-d invoice_allocations[invoice_id][0]="__demo_inv__1"
copy
# collects payment for the customer with the existing payment source.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl6A32bF/collect_payment \
-X POST \
-u {site_api_key}:\
-d amount=100 \
-d payment_source_id="pm___test__KyVnHhSBWl6Q02bG" \
-d invoice_allocations[invoice_id][0]="__demo_inv__1"
# collects payment for the customer using new payment source.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl78A2bV/collect_payment \
-X POST \
-u {site_api_key}:\
-d card[number]="378282246310005" \
-d card[expiry_month]=10 \
-d card[expiry_year]=2022 \
-d card[cvv]="999" \
-d invoice_allocations[invoice_id][0]="__demo_inv__2"
Sample Response [ JSON ]
Show more...
{
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1517505725,
"deleted": false,
"excess_payments": 0,
"first_name": "Mark",
"id": "__test__KyVnHhSBWl6A32bF",
"last_name": "Henry",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "stripe",
"gateway_account_id": "gw___test__KyVnGlSBWl4aZ1jg",
"object": "payment_method",
"reference_id": "cus_I58Pya87WmQLx0/card_1HUy8vJv9j0DyntJbHs5EYNs",
"status": "valid",
"type": "card"
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm___test__KyVnHhSBWl6Q02bG",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505727000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505727
},
"transaction": {
"amount": 100,
"amount_unused": 0,
"base_currency_code": "USD",
"currency_code": "USD",
"customer_id": "__test__KyVnHhSBWl6A32bF",
"date": 1600968127,
"deleted": false,
"exchange_rate": 1,
"fraud_reason": "Payment complete.",
"gateway": "stripe",
"gateway_account_id": "gw___test__KyVnGlSBWl4aZ1jg",
"id": "txn___test__KyVnHhSBWl6Zg2bR",
"id_at_gateway": "ch_1HUy8xJv9j0DyntJlrFKSALQ",
"linked_invoices": [
{
"applied_amount": 100,
"applied_at": 1517505727,
"invoice_date": 1517505726,
"invoice_id": "__demo_inv__1",
"invoice_status": "payment_due",
"invoice_total": 1095
},
{..}
],
"linked_refunds": [],
"masked_card_number": "************1111",
"object": "transaction",
"payment_method": "card",
"payment_source_id": "pm___test__KyVnHhSBWl6Q02bG",
"resource_version": 1517505727000,
"status": "success",
"subscription_id": "__test__KyVnHhSBWl6RN2bK",
"type": "payment",
"updated_at": 1517505727
}
}
Show more...
{
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"created_at": 1517505729,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl78A2bV",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505729000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505729
},
"transaction": {
"amount": 1095,
"amount_unused": 0,
"base_currency_code": "USD",
"currency_code": "USD",
"customer_id": "__test__KyVnHhSBWl78A2bV",
"date": 1517505729,
"deleted": false,
"exchange_rate": 1,
"gateway": "chargebee",
"gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
"id": "txn___test__KyVnHhSBWl7FU2bg",
"id_at_gateway": "cb___test__KyVnHhSBWl7FZ2bh",
"linked_invoices": [
{
"applied_amount": 1095,
"applied_at": 1517505729,
"invoice_date": 1517505729,
"invoice_id": "__demo_inv__2",
"invoice_status": "paid",
"invoice_total": 1095
},
{..}
],
"linked_refunds": [],
"masked_card_number": "***********0005",
"object": "transaction",
"payment_method": "card",
"resource_version": 1517505729000,
"status": "success",
"subscription_id": "__test__KyVnHhSBWl7AE2bX",
"type": "payment",
"updated_at": 1517505729
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/collect_payment
Amount to be collected. If this parameter is not passed then the invoice(s) amount to collect will be collected.
optional, in cents, min=0
Payment source used for the payment.
optional, string, max chars=40
Token generated by Chargebee JS representing payment method details.
optional, string, max chars=40
replace_primary_payment_source
Indicates whether the primary payment source need to be replaced with the payment source given.
optional, boolean, default=false
Indicates whether the payment source should be retained for the customer.
optional, boolean, default=false
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.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.
Show all values[+]
payment_method[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
payment_method[reference_id]
The reference id. In the case of Amazon and PayPal this will be the
billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer
Update payment method for a customer API under Customer resource.
optional, string, max chars=200
payment_method[tmp_token]
Single-use token created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet or card details. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
required if reference_id not provided, string, max chars=65k
Parameters for card
pass parameters as card[<param name>]
The gateway account in which this payment source is stored.
optional, string, max chars=50
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 (CVV). 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
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
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
payment_intent[additional_info]
Applicable only for Braintree gateway. Can be used only for Braintree’s
Advance Fraud Management feature. Pass a stringified JSON containing the
device_session_id
and
fraud_merchant_id
as an input to
fingerprint
. Here’s a
sample to it.
optional, jsonobject
Parameters for invoice_allocations. Multiple invoice_allocations can be passed by specifying unique indices.
pass parameters as invoice_allocations[<param name>][<idx:0..n>]
invoice_allocations[invoice_id][0..n]
Identifier for the invoice. Multiple invoices can be passed.
required, string, max chars=50
invoice_allocations[allocation_amount][0..n]
Amount that will override the Invoice amount to be collected. If not specified Invoice amount to collect will be taken as default.
optional, in cents, min=0
Resource object representing customer.
always returned
Resource object representing transaction.
always returned
Deletes the customer resource.
Notes
This will delete the Payment Method from the gateway/vault. If you do not want the Payment Method to be deleted from the vault, set the value for the delete_payment_method parameter to false.
This operation is irreversible - all data related to the customer, such as subscriptions, invoices, transactions, and reports, will be deleted.
Note: This operation schedules the customer resource for deletion. It will be deleted in a few minutes.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl9ZA2c8/delete \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl9ZA2c8/delete \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"created_at": 1517505738,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl9ZA2c8",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505738000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505738
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/delete
Deletes the Payment Method from the gateway/vault.
optional, boolean, default=true
Resource object representing customer.
always returned
Resource object representing card.
optional
This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/move \
-u {site_api_key}:\
-d id_at_from_site="__test__KyVnHhSBWlCxa2cx" \
-d from_site="mannar"
copy
curl https://{site}.chargebee.com/api/v2/customers/move \
-u {site_api_key}:\
-d id_at_from_site="__test__KyVnHhSBWlCxa2cx" \
-d from_site="mannar"
Sample Response [ JSON ]
Show more...
{"resource_migration": {
"created_at": 1517505751,
"entity_id": "__test__KyVnHhSBWlCxa2cx",
"entity_type": "customer",
"from_site": "mannar",
"object": "resource_migration",
"status": "scheduled",
"updated_at": 1517505751
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/move
Id of the customer to be copied.
required, string, max chars=100
Name of the site from which this customer need to be copied.
required, string, max chars=50
Resource object representing resource_migration.
always returned
Applicable when calendar billing (with customer specific billing date support) is enabled. Changes the customer's billing_date and/or billing_day_of_week.
Notes
During this operation the upcoming renewal dates are not updated to align immediately with the new date. The alignment will happen during subsequent renewals.
Say a customer's upcoming renewal is scheduled for Jan, 10th. If the customer's billing date is changed to 15th - the next renewal still happens on Jan, 10th. During this renewal alignment with the new date happens therby the subsequent renewal gets scheduled for Feb, 15th.
If you want to align with the new date immediately (in this example: you want the next renewal to be on Jan, 15th and not Jan, 10th) you need to manually change the subscription's term end.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5XP2b6/change_billing_date \
-u {site_api_key}:\
-d billing_date=15 \
-d billing_date_mode="manually_set" \
-d billing_day_of_week="sunday" \
-d billing_day_of_week_mode="manually_set"
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5XP2b6/change_billing_date \
-u {site_api_key}:\
-d billing_date=15 \
-d billing_date_mode="manually_set" \
-d billing_day_of_week="sunday" \
-d billing_day_of_week_mode="manually_set"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"billing_date": 15,
"billing_date_mode": "manually_set",
"billing_day_of_week": "sunday",
"billing_day_of_week_mode": "manually_set",
"card_status": "no_card",
"created_at": 1517505722,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWl5XP2b6",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505723000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505723
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/change_billing_date
Applicable when calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the monthly and yearly subscriptions of this customer will be aligned to this date.
optional, integer, min=1, max=31
Indicates whether this customer's
billing_date value is derived as per configurations or its specifically set (overriden). When specifically set, the
billing_date will not be reset even when all of the monthly/yearly subscriptions are cancelled.
optional, enumerated stringPossible values are
using_defaultsBilling date is set based on defaults configured.manually_setBilling date is specifically set (default configuration is overridden).
Applicable when
calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the weekly subscriptions of this customer will be aligned to this week day.
optional, enumerated stringPossible values are
sundaySunday.mondayMonday.tuesdayTuesday.wednesdayWednesday.thursdayThursday.fridayFriday.saturdaySaturday.
Indicates whether this customer's
billing_day_of_week value is derived as per configurations or its specifically set (overriden). When specifically set, the
billing_day_of_week will not be reset even when all of the weekly subscriptions are cancelled.
optional, enumerated stringPossible values are
using_defaultsBilling date is set based on defaults configured.manually_setBilling date is specifically set (default configuration is overridden).
Resource object representing customer.
always returned
This API moves a customer's payment methods, subscriptions, invoices, credit notes, transactions, unbilled charges,orders to another customer. Events and email logs will not be moved. The API execution is asynchronous. The returned customer object is to customer object.
Note: Moving virtual bank accounts from one customer to another is not supported in this API.
This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/merge \
-u {site_api_key}:\
-d from_customer_id="__test__KyVnHhSBWlCbP2cp" \
-d to_customer_id="__test__KyVnHhSBWlCdz2cv"
copy
curl https://{site}.chargebee.com/api/v2/customers/merge \
-u {site_api_key}:\
-d from_customer_id="__test__KyVnHhSBWlCbP2cp" \
-d to_customer_id="__test__KyVnHhSBWlCdz2cv"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"created_at": 1517505750,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWlCdz2cv",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505750000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505750
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/merge
From customer id.
required, string, max chars=50
To customer id.
required, string, max chars=50
Resource object representing customer.
always returned
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5qO2b9/clear_personal_data \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl5qO2b9/clear_personal_data \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{
"card": {
"card_type": "visa",
"created_at": 1517505724,
"customer_id": "__test__KyVnHhSBWl5qO2b9",
"expiry_month": 12,
"expiry_year": 2022,
"funding_type": "credit",
"gateway": "chargebee",
"gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
"iin": "411111",
"last4": "1111",
"masked_number": "************1111",
"object": "card",
"payment_source_id": "pm___test__KyVnHhSBWl5rL2bB",
"resource_version": 1517505724000,
"status": "valid",
"updated_at": 1517505724
},
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1517505724,
"deleted": false,
"excess_payments": 0,
"first_name": "Mark",
"id": "__test__KyVnHhSBWl5qO2b9",
"last_name": "Henry",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "chargebee",
"gateway_account_id": "gw___test__KyVnGlSBWl4T71j4",
"object": "payment_method",
"reference_id": "tok___test__KyVnHhSBWl5rH2bA",
"status": "valid",
"type": "card"
},
"pii_cleared": "scheduled_for_clear",
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm___test__KyVnHhSBWl5rL2bB",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505724000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505724
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/clear_personal_data
Resource object representing customer.
always returned
Sets a customer into a hierarchical relationship with another. The path parameter customer_id
is the id of the child in the relationship.
Note: For the
use_default_hierarchy_settings
,
parent_account_access
and
child_account_access
parameters, the 'parent' is the customer whose id is
payment_owner_id. However, if the
payment_owner_id
is the child itself, then the parent is
parent_id.
Sample Request
# creates a relationship for reporting purpose
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDY12d5/relationships \
-u {site_api_key}:\
-d parent_id="__test__KyVnHhSBWlDa22d7" \
-d payment_owner_id="__test__KyVnHhSBWlDY12d5" \
-d invoice_owner_id="__test__KyVnHhSBWlDY12d5"
copy
# creates a relationship for reporting purpose
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDY12d5/relationships \
-u {site_api_key}:\
-d parent_id="__test__KyVnHhSBWlDa22d7" \
-d payment_owner_id="__test__KyVnHhSBWlDY12d5" \
-d invoice_owner_id="__test__KyVnHhSBWlDY12d5"
# creates a completely dependent relationship
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlDwm2dJ/relationships \
-u {site_api_key}:\
-d parent_id="__test__KyVnHhSBWlDrp2dC" \
-d payment_owner_id="__test__KyVnHhSBWlDrp2dC" \
-d invoice_owner_id="__test__KyVnHhSBWlDrp2dC"
# creates a relationship and sets custom parent/child access settings
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlEhB2dd/relationships \
-u {site_api_key}:\
-d parent_id="__test__KyVnHhSBWlEc92dW" \
-d payment_owner_id="__test__KyVnHhSBWlEc92dW" \
-d invoice_owner_id="__test__KyVnHhSBWlEhB2dd" \
-d use_default_hierarchy_settings="false" \
-d parent_account_access[portal_edit_child_subscriptions]="yes" \
-d parent_account_access[portal_download_child_invoices]="yes" \
-d parent_account_access[send_subscription_emails]="true" \
-d parent_account_access[send_payment_emails]="false" \
-d parent_account_access[send_invoice_emails]="false" \
-d child_account_access[portal_edit_subscriptions]="view_only" \
-d child_account_access[portal_download_invoices]="view_only" \
-d child_account_access[send_subscription_emails]="true" \
-d child_account_access[send_payment_emails]="true" \
-d child_account_access[send_invoice_emails]="true"
# creates a partially dependent relationship
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlEIc2dT/relationships \
-u {site_api_key}:\
-d parent_id="__test__KyVnHhSBWlEDb2dM" \
-d payment_owner_id="__test__KyVnHhSBWlEDb2dM" \
-d invoice_owner_id="__test__KyVnHhSBWlEIc2dT"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"child_account_access": {
"portal_download_invoices": "view_only",
"portal_edit_subscriptions": "yes",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": true
},
"created_at": 1517505753,
"deleted": false,
"excess_payments": 0,
"first_name": "Bella",
"id": "__test__KyVnHhSBWlDY12d5",
"last_name": "Brown",
"net_term_days": 0,
"object": "customer",
"parent_account_access": {
"portal_download_child_invoices": "yes",
"portal_edit_child_subscriptions": "view_only",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": false
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"relationship": {
"invoice_owner_id": "__test__KyVnHhSBWlDY12d5",
"parent_id": "__test__KyVnHhSBWlDa22d7",
"payment_owner_id": "__test__KyVnHhSBWlDY12d5",
"root_id": "__test__KyVnHhSBWlDa22d7"
},
"resource_version": 1517505753000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505753,
"use_default_hierarchy_settings": true
}}
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"child_account_access": {
"portal_download_invoices": "view_only",
"portal_edit_subscriptions": "yes",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": true
},
"created_at": 1517505755,
"deleted": false,
"excess_payments": 0,
"first_name": "Clara",
"id": "__test__KyVnHhSBWlDwm2dJ",
"last_name": "Cooper",
"net_term_days": 0,
"object": "customer",
"parent_account_access": {
"portal_download_child_invoices": "yes",
"portal_edit_child_subscriptions": "view_only",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": false
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"relationship": {
"invoice_owner_id": "__test__KyVnHhSBWlDrp2dC",
"parent_id": "__test__KyVnHhSBWlDrp2dC",
"payment_owner_id": "__test__KyVnHhSBWlDrp2dC",
"root_id": "__test__KyVnHhSBWlDtT2dE"
},
"resource_version": 1517505755000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505755,
"use_default_hierarchy_settings": true
}}
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"child_account_access": {
"portal_download_invoices": "view_only",
"portal_edit_subscriptions": "view_only",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": true
},
"created_at": 1517505758,
"deleted": false,
"excess_payments": 0,
"first_name": "Clara",
"id": "__test__KyVnHhSBWlEhB2dd",
"last_name": "Cooper",
"net_term_days": 0,
"object": "customer",
"parent_account_access": {
"portal_download_child_invoices": "yes",
"portal_edit_child_subscriptions": "yes",
"send_invoice_emails": false,
"send_payment_emails": false,
"send_subscription_emails": true
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"relationship": {
"invoice_owner_id": "__test__KyVnHhSBWlEhB2dd",
"parent_id": "__test__KyVnHhSBWlEc92dW",
"payment_owner_id": "__test__KyVnHhSBWlEc92dW",
"root_id": "__test__KyVnHhSBWlEdx2dY"
},
"resource_version": 1517505758000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505758,
"use_default_hierarchy_settings": false
}}
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"child_account_access": {
"portal_download_invoices": "view_only",
"portal_edit_subscriptions": "yes",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": true
},
"created_at": 1517505756,
"deleted": false,
"excess_payments": 0,
"first_name": "Clara",
"id": "__test__KyVnHhSBWlEIc2dT",
"last_name": "Cooper",
"net_term_days": 0,
"object": "customer",
"parent_account_access": {
"portal_download_child_invoices": "yes",
"portal_edit_child_subscriptions": "view_only",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": false
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"relationship": {
"invoice_owner_id": "__test__KyVnHhSBWlEIc2dT",
"parent_id": "__test__KyVnHhSBWlEDb2dM",
"payment_owner_id": "__test__KyVnHhSBWlEDb2dM",
"root_id": "__test__KyVnHhSBWlEFE2dO"
},
"resource_version": 1517505756000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505756,
"use_default_hierarchy_settings": true
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/relationships
The id
of the customer which is to be set as the immediate parent.
optional, string, max chars=50
The id
of the customer who will pay the invoices for this customer. Can be the child itself or the invoice_owner_id
.
optional, string, max chars=50
The id
of the customer who will be invoiced for charges incurred. Can be the child itself or any parent in its hierarchy.
optional, string, max chars=50
use_default_hierarchy_settings
The level of access that the parent and the child itself have to the child's information can be set here. This data falls into two categories:
- Self-Serve Portal data: subscriptions and invoices of the child.
- Email Notifications: subscription-, invoice- and payment-related notifications for the child.
Usage:
- Value set to
true
: Applies the global access levels defined in the Account Hierarchy settings to this child. These global settings are configured in the admin console - Value set to
false
: Customizes the access levels for this customer. Pass the parent_account_access
and child_account_access
parameters to specify the settings. If you skip passing any parameters, the global settings are applied for them.
.
optional, boolean, default=true
Parameters for parent_account_access
pass parameters as parent_account_access[<param name>]
parent_account_access[portal_edit_child_subscriptions]
Sets parent's level of access to child subscriptions on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe parent account can view and edit the subscriptions of the child account.view_onlyThe parent account can only view the subscriptions of the child account.noThe parent account cannot view or edit the subscriptions of the child account.
parent_account_access[portal_download_child_invoices]
Sets parent's level of access to child invoices on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe parent account can view and download the invoices of the child account.view_onlyThe parent account can only view the invoices of the child account.noThe parent account can neither view nor download the invoices of the child account.
parent_account_access[send_subscription_emails]
If true
, the parent account will receive subscription-related emails sent to the child account.
optional, boolean
parent_account_access[send_payment_emails]
If true
, the parent account will receive payment-related emails sent to the child account.
optional, boolean
parent_account_access[send_invoice_emails]
If true
, the parent account will receive invoice-related emails sent to the child account.
optional, boolean
Parameters for child_account_access
pass parameters as child_account_access[<param name>]
child_account_access[portal_edit_subscriptions]
Sets the child's level of access to its own subscriptions on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe child account can view and edit its own subscriptions.view_onlyThe child account can only view its own subscriptions.
child_account_access[portal_download_invoices]
Sets the child’s level of access to its own invoices on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe child account can view and download its own invoices.view_onlyThe child account can only view its invoices and not download them.noThe child account can neither view nor download its own invoices.
child_account_access[send_subscription_emails]
If true
, the child account will receive subscription-related emails for its own subscriptions.
optional, boolean
child_account_access[send_payment_emails]
If true
, the child account will receive payment-related emails for its own invoices.
optional, boolean
child_account_access[send_invoice_emails]
If true
, the child account will receive invoice-related emails for its own invoices.
optional, boolean
Resource object representing customer.
always returned
Disconnects a child customer from its parent.
customer_id
is the
id of the child.
Sample Request
# deletes a customer from hierarchy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlAG12cF/delete_relationship \
-X POST \
-u {site_api_key}:
copy
# deletes a customer from hierarchy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlAG12cF/delete_relationship \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"created_at": 1517505741,
"deleted": false,
"excess_payments": 0,
"first_name": "Bella",
"id": "__test__KyVnHhSBWlAG12cF",
"last_name": "Brown",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505741000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505741
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/delete_relationship
Resource object representing customer.
always returned
Retrieves the
account hierarchy tree for the customer.
Sample Request
# retrieves all the customers in a hierarchy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlAkY2cO/hierarchy \
-u {site_api_key}:\
-d hierarchy_operation_type="complete_hierarchy"
copy
# retrieves all the customers in a hierarchy
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlAkY2cO/hierarchy \
-u {site_api_key}:\
-d hierarchy_operation_type="complete_hierarchy"
# retrieves customers in same chain from root to node
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlBci2cc/hierarchy \
-u {site_api_key}:\
-d hierarchy_operation_type="path_to_root"
# retrieves customers which are the subordinates
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlBEG2cV/hierarchy \
-u {site_api_key}:\
-d hierarchy_operation_type="subordinates"
Sample Response [ JSON ]
Show more...
{"hierarchies": [
{
"children_ids": [
"__test__KyVnHhSBWlAkY2cO",
{..}
],
"customer_id": "__test__KyVnHhSBWlAmZ2cQ",
"invoice_owner_id": "__test__KyVnHhSBWlAmZ2cQ",
"object": "hierarchy",
"payment_owner_id": "__test__KyVnHhSBWlAmZ2cQ"
},
{..}
]}
Show more...
{"hierarchies": [
{
"children_ids": [
"__test__KyVnHhSBWlBci2cc",
{..}
],
"customer_id": "__test__KyVnHhSBWlBfT2ce",
"invoice_owner_id": "__test__KyVnHhSBWlBfT2ce",
"object": "hierarchy",
"payment_owner_id": "__test__KyVnHhSBWlBfT2ce"
},
{..}
]}
Show more...
{"hierarchies": [
{
"children_ids": [],
"customer_id": "__test__KyVnHhSBWlBEG2cV",
"invoice_owner_id": "__test__KyVnHhSBWlBEG2cV",
"object": "hierarchy",
"parent_id": "__test__KyVnHhSBWlBGy2cX",
"payment_owner_id": "__test__KyVnHhSBWlBEG2cV"
},
{..}
]}
URL Format GET
https://{site}.chargebee.com/api/v2/customers/{customer_id}/hierarchy
Selects the specific part of the hierarchy to be fetched.
optional, enumerated stringPossible values are
complete_hierarchyList the nodes of the full hierarchy to which the customer belongs.subordinatesList all the nodes of the hierarchy formed by the customer and its subordinates. In other words, fetch the nodes of the tree whose root node is the customer.path_to_rootList the nodes along the path from the customer to the root of the full hierarchy.
Resource object representing hierarchy.
always returned
Changes the level of access that the parent or the child itself has to the child's information.
This data falls into two categories:
- Self-Serve Portal data: subscriptions and invoices of the child.
- Email Notifications: subscription-, invoice- and payment-related notifications for the child.
The 'parent' is the customer whose id is
payment_owner_id. However, if the
payment_owner_id
is the child itself, then the parent is
parent_id. The path parameter
customer_id
is the
id of the child in the relationship.
Note: This endpoint cannot be used to change the
parent_id
,
invoice_owner_id
or
payment_owner_id
for the customer. To change them,
delink the customer and then call
Link a customer again.
Sample Request
# Deletes any custom parent/child access settings defined and applies the
# site defaults
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlG3y2dt/update_hierarchy_settings \
-X POST \
-u {site_api_key}:\
-d use_default_hierarchy_settings="true"
copy
# Deletes any custom parent/child access settings defined and applies the
# site defaults
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlG3y2dt/update_hierarchy_settings \
-X POST \
-u {site_api_key}:\
-d use_default_hierarchy_settings="true"
# Updates all of the "parent_account_access" and "child_account_access" settings for a
# customer.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlGoZ2e7/update_hierarchy_settings \
-X POST \
-u {site_api_key}:\
-d use_default_hierarchy_settings="false" \
-d child_account_access[portal_edit_subscriptions]="yes" \
-d child_account_access[portal_download_invoices]="yes" \
-d child_account_access[send_subscription_emails]="true" \
-d child_account_access[send_payment_emails]="true" \
-d child_account_access[send_invoice_emails]="true" \
-d parent_account_access[portal_edit_child_subscriptions]="view_only" \
-d parent_account_access[portal_download_child_invoices]="yes" \
-d parent_account_access[send_subscription_emails]="false" \
-d parent_account_access[send_payment_emails]="false" \
-d parent_account_access[send_invoice_emails]="false"
# Updates only some of the "parent_account_access" and "child_account_access" settings for
# a customer
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlGQc2e0/update_hierarchy_settings \
-X POST \
-u {site_api_key}:\
-d use_default_hierarchy_settings="false" \
-d parent_account_access[portal_edit_child_subscriptions]="yes" \
-d parent_account_access[portal_download_child_invoices]="yes" \
-d parent_account_access[send_invoice_emails]="false" \
-d child_account_access[portal_download_invoices]="yes" \
-d child_account_access[send_invoice_emails]="true"
Sample Response [ JSON ]
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"child_account_access": {
"portal_download_invoices": "view_only",
"portal_edit_subscriptions": "yes",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": true
},
"created_at": 1517505763,
"deleted": false,
"excess_payments": 0,
"first_name": "Bella",
"id": "__test__KyVnHhSBWlG3y2dt",
"last_name": "Brown",
"net_term_days": 0,
"object": "customer",
"parent_account_access": {
"portal_download_child_invoices": "yes",
"portal_edit_child_subscriptions": "view_only",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": false
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"relationship": {
"invoice_owner_id": "__test__KyVnHhSBWlG3y2dt",
"parent_id": "__test__KyVnHhSBWlG5Z2dv",
"payment_owner_id": "__test__KyVnHhSBWlG3y2dt",
"root_id": "__test__KyVnHhSBWlG5Z2dv"
},
"resource_version": 1517505763000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505763,
"use_default_hierarchy_settings": true
}}
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"child_account_access": {
"portal_download_invoices": "yes",
"portal_edit_subscriptions": "yes",
"send_invoice_emails": true,
"send_payment_emails": true,
"send_subscription_emails": true
},
"created_at": 1517505766,
"deleted": false,
"excess_payments": 0,
"first_name": "Bella",
"id": "__test__KyVnHhSBWlGoZ2e7",
"last_name": "Brown",
"net_term_days": 0,
"object": "customer",
"parent_account_access": {
"portal_download_child_invoices": "yes",
"portal_edit_child_subscriptions": "view_only",
"send_invoice_emails": false,
"send_payment_emails": false,
"send_subscription_emails": false
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"relationship": {
"invoice_owner_id": "__test__KyVnHhSBWlGoZ2e7",
"parent_id": "__test__KyVnHhSBWlGqO2e9",
"payment_owner_id": "__test__KyVnHhSBWlGoZ2e7",
"root_id": "__test__KyVnHhSBWlGqO2e9"
},
"resource_version": 1517505766000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505766,
"use_default_hierarchy_settings": false
}}
Show more...
{"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"child_account_access": {
"portal_download_invoices": "yes",
"portal_edit_subscriptions": "view_only",
"send_invoice_emails": true,
"send_payment_emails": false,
"send_subscription_emails": true
},
"created_at": 1517505764,
"deleted": false,
"excess_payments": 0,
"first_name": "Bella",
"id": "__test__KyVnHhSBWlGQc2e0",
"last_name": "Brown",
"net_term_days": 0,
"object": "customer",
"parent_account_access": {
"portal_download_child_invoices": "yes",
"portal_edit_child_subscriptions": "yes",
"send_invoice_emails": false,
"send_payment_emails": true,
"send_subscription_emails": false
},
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"relationship": {
"invoice_owner_id": "__test__KyVnHhSBWlGQc2e0",
"parent_id": "__test__KyVnHhSBWlGSS2e2",
"payment_owner_id": "__test__KyVnHhSBWlGQc2e0",
"root_id": "__test__KyVnHhSBWlGSS2e2"
},
"resource_version": 1517505764000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505764,
"use_default_hierarchy_settings": false
}}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/update_hierarchy_settings
use_default_hierarchy_settings
Determines whether the site default settings are applied for the access levels.
- Value set to
true
: Removes any customized access levels for the customer. The global settings configured in the admin console now apply. - Value set to
false
: Changes the access levels for this customer. Pass the parent_account_access
and child_account_access
parameters to specify the new settings. If you skip passing any parameters, they will remain unchanged.
.
optional, boolean, default=true
Parameters for parent_account_access
pass parameters as parent_account_access[<param name>]
parent_account_access[portal_edit_child_subscriptions]
Sets parent's level of access to child subscriptions on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe parent account can view and edit the subscriptions of the child account.view_onlyThe parent account can only view the subscriptions of the child account.noThe parent account cannot view or edit the subscriptions of the child account.
parent_account_access[portal_download_child_invoices]
Sets parent's level of access to child invoices on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe parent account can view and download the invoices of the child account.view_onlyThe parent account can only view the invoices of the child account.noThe parent account can neither view nor download the invoices of the child account.
parent_account_access[send_subscription_emails]
If true
, the parent account will receive subscription-related emails sent to the child account.
optional, boolean
parent_account_access[send_payment_emails]
If true
, the parent account will receive payment-related emails sent to the child account.
optional, boolean
parent_account_access[send_invoice_emails]
If true
, the parent account will receive invoice-related emails sent to the child account.
optional, boolean
Parameters for child_account_access
pass parameters as child_account_access[<param name>]
child_account_access[portal_edit_subscriptions]
Sets the child's level of access to its own subscriptions on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe child account can view and edit its own subscriptions.view_onlyThe child account can only view its own subscriptions.
child_account_access[portal_download_invoices]
Sets the child’s level of access to its own invoices on the Self-Serve Portal.
optional, enumerated stringPossible values are
yesThe child account can view and download its own invoices.view_onlyThe child account can only view its invoices and not download them.noThe child account can neither view nor download its own invoices.
child_account_access[send_subscription_emails]
If true
, the child account will receive subscription-related emails for its own subscriptions.
optional, boolean
child_account_access[send_payment_emails]
If true
, the child account will receive payment-related emails for its own invoices.
optional, boolean
child_account_access[send_invoice_emails]
If true
, the child account will receive invoice-related emails for its own invoices.
optional, boolean
Resource object representing customer.
always returned