Introducing the Better Auth Chargebee plugin: Use it to handle subscriptions, billing, and auth seamlessly.
Chargebeechargebee API

Create a customer

Idempotency Supported

Creates a customer resource. Optionally, creates a payment source for the customer.

Prerequisites & Constraints

  • billing_address.country is required when entity_identifiers is provided.
  • Entity identifier collection must be enabled for your site to provide entity_identifiers, unless is_einvoice_enabled is set in the request.

Impacts

Customer

  • If the multi-business entity feature is enabled, the customer is linked to the business entity specified; otherwise, the customer record is linked to the default business entity defined for the site.

Invoices

  • Chargebee uses the billing_address object from the customer to set the values in the billing_address of the invoices generated for the customer.
  • If the billing_address object does not include the first_name, last_name, or company fields, Chargebee automatically uses the values from customer.first_name, customer.last_name, and customer.company (if available) when generating invoices.

Payment source

  • If payment_intent or payment_method parameter is passed, a payment_source resource of the appropriate type is created for the customer.
  • If bank_account parameter is passed, a payment_source resource of type direct_debit is created for the customer.
  • If card parameter is passed, a payment_source resource of type card is created for the customer.
Integrations
  • If CRM systems are connected to Chargebee, a corresponding record is created in the connected CRM (such as Salesforce, and HubSpot).

Use Cases

Create payment source using payment_intent

Use the payment_intent parameter to create a payment source for the customer. Using payment intents is the recommended way to create a payment source in Chargebee for both Strong Customer Authentication (SCA) (i.e. 3D-Secure) and non-SCA flows.

  1. Create a payment_intent resource by calling the Create a payment intent API.
  2. Pass the payment_intent object to your frontend and use Chargebee.js to capture the payment source details from the customer. Use Payment Method Helpers to show payment method UIs and collect payment method details from the customer.
  3. Listen to the payment_intent_updated event. Once the payment_intent.status is authorized, pass the payment_intent.id using the payment_intent[id] parameter in this API call.

Create payment source using payment_method

If you prefer to use the payment gateway's SDKs to capture the payment method details, you can then use the payment_method parameter in this API to pass the payment method token and other details.

  1. Use the JavaScript library of your payment gateway to capture the payment method details. Examples include:
  1. Pass the payment method token using the payment_method[reference_id] or payment_method[tmp_token] parameter along with any additional parameters required by the payment gateway to create the payment source.

Create payment source using bank_account

You can pass raw bank account details via this API. Use the bank_account parameter to pass the bank account details.

Create payment source using card

If you are PCI compliant, you can pass raw card details via this API. Use the card parameter to pass the card details.

Sample Request

creates a customer with billing address.
creates a customer with bank account.
creates a customer with card details.
creates a customer with payment source.

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/customers

Input Parameters

id
optional, string, max chars=50

Id for the new customer. If not given, this will be auto-generated.

first_name
optional, string, max chars=150

First name of the customer.

last_name
optional, string, max chars=150

Last name of the customer.

email
optional, string, max chars=70

Email address of the customer. Configured email notifications are sent to this email address. Invalid email address will result in an error.

preferred_currency_code
optional, string, max chars=3

The currency code (in ISO 4217 format) of the customer.

Prerequisite
  • preferred_currency_code must be an active currency configured for your site.
Constraint
phone
optional, string, max chars=50

Phone number of the customer.

company
optional, string, max chars=250

Company name of the customer.

auto_collection
optional, enumerated string, default=on

Whether payments needs to be collected automatically for this customer.

Constraint
  • offline_payment_method cannot be passed when auto_collection is set to on.
Enum Values
on

Whenever an invoice is created, an automatic attempt to charge the customer's payment method is made.

off

Automatic collection of charges will not be made. All payments must be recorded offline.

net_term_days
optional, integer, default=0

The number of days from invoice.date until payment for the invoice is due.

Prerequisite
  • Payment Terms must be enabled for your site to provide a non-zero net_term_days.
Constraints
  • net_term_days must be 0 or omitted when auto_collection is on, unless Net D is enabled for online payment methods on your site.
  • net_term_days must be 0 or omitted when auto_collection is not on, unless Net D is enabled for offline payment methods on your site.
allow_direct_debit
optional, boolean, default=false

Whether the customer can pay via Direct Debit.

Constraint
  • allow_direct_debit must be true when payment_method.type is direct_debit.
vat_number
optional, string, max chars=20

The VAT/tax registration number for the customer. For customers with billing_address

country as XI (which is United Kingdom - Northern Ireland ), the first two characters of the full VAT number can be overridden by setting vat_number_prefix .

Constraints
  • billing_address.country is required to validate the vat_number.
  • vat_number is applicable only when the billing country collects VAT/tax registration numbers.
vat_number_prefix
optional, string, max chars=10

An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address

country as XI (which is United Kingdom - Northern Ireland ).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address

country as XI. That's the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.

Constraints
  • vat_number is required when vat_number_prefix is provided.
  • vat_number_prefix must be valid for the billing country.
entity_identifier_scheme
optional, string, max chars=50

The Peppol BIS scheme associated with the vat_number of the customer. This helps identify the specific type of customer entity. For example, DE:VAT is used for a German business entity while DE:LWID45 is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country. See list of possible values .

Tip:

If there are additional entity identifiers for the customer not associated with the vat_number, they can be provided as the entity_identifiers[] array.

entity_identifier_standard
optional, string, default=iso6523-actorid-upis, max chars=50

The standard used for specifying the entity_identifier_scheme. Currently only iso6523-actorid-upis is supported and is used by default when not provided.

Tip:

If there are additional entity identifiers for the customer not associated with the vat_number, they can be provided as the entity_identifiers[] array.

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

Prerequisite
  • Australian GST must be enabled for your site to provide registered_for_gst.
Constraints
  • billing_address.country is required to provide registered_for_gst.
  • registered_for_gst can be true only when billing_address.country is AU.
is_einvoice_enabled
optional, boolean

Determines whether the customer is e-invoiced. When set to true or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country ). When set to false , the customer is not e-invoiced even if e-invoicing is enabled for their country.

Tip:

It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.

Prerequisite
  • E-Invoicing must be enabled for your site to provide is_einvoice_enabled.
einvoicing_method
optional, enumerated string

Determines whether to send an e-invoice manually or automatic.

Constraint
  • einvoicing_method can be provided only when E-Invoicing is enabled for your site and the billing country is allowed for e-invoicing.
Enum Values
automatic

Use this value to send e-invoice every time an invoice or credit note is created.

manual

When manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.

site_default

The default value of the site which can be overridden at the customer level.

taxability
optional, enumerated string, default=taxable

Specifies if the customer is liable for tax.

Prerequisite
  • The default value taxable for taxability should be sent only when tax is not configured or the TCO gateway is enabled
Enum Values
taxable

Computes 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.
exemption_details
optional

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 .

Prerequisite
  • Avalara Communication Tax must be configured for your site to provide exemption_details.
Constraint
  • exemption_details is applicable only when taxability is exempt.
customer_type
optional, enumerated string

Indicates the type of the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.

Prerequisite
  • Avalara Communication Tax must be configured for your site to provide customer_type.
Enum Values
residential

When the purchase is made by a customer for home use

business

When the purchase is made at a place of business

senior_citizen

When 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

industrial

When the purchase is made by an industrial business

client_profile_id
optional, string, max chars=50

Indicates the Client profile id for the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.

Prerequisite
  • Avalara Communication Tax must be configured for your site to provide client_profile_id.
taxjar_exemption_category
optional, enumerated string

Indicates the exemption type of the customer. This is applicable only if you use Chargebee's TaxJar integration.

Prerequisite
  • TaxJar must be configured for your site to provide taxjar_exemption_category.
Constraint
  • taxjar_exemption_category is applicable only when taxability is exempt.
Enum Values
wholesale

Whole-sale

government

Government

other

Other

business_customer_without_vat_number
optional, boolean

Confirms that a customer is a valid business without an EU/UK VAT number.

Prerequisite
  • business_customer_without_vat_number is applicable only when EU VAT settings are enabled for your site and the billing country requires a VAT number.
Constraints
  • billing_address.country is required to validate the VAT number.
  • business_customer_without_vat_number cannot be true when vat_number is provided.
locale
optional, string, max chars=50

Determines which region-specific language Chargebee uses to communicate with the customer. Use the language pack to customize the translations for each locale.

Default behavior

  • If you don't pass locale, or if you pass it but it is not added and activated in Chargebee, then the primary language for customers would be used.
Prerequisite
entity_code
optional, enumerated string

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

Prerequisite
  • Avalara Sales Tax must be configured for your site to provide entity_code.
Constraints
  • entity_code and exempt_number are mutually exclusive; provide only one.
  • entity_code is applicable only when taxability is exempt.
Enum Values
a

Federal government

b

State government

c

Tribe/Status Indian/Indian Band

d

Foreign diplomat

e

Charitable or benevolent organization

exempt_number
optional, string, max chars=100

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 .

Prerequisite
  • Avalara Sales Tax must be configured for your site to provide exempt_number.
Constraint
  • exempt_number is applicable only when taxability is exempt.
meta_data
optional, jsonobject

A collection of key-value pairs that provides extra information about the customer.

Note: There's a character limit of 65,535.

Learn more .

offline_payment_method
optional, enumerated string

The preferred offline payment method for the customer.

Prerequisite
  • Offline Payment Methods must be enabled for your site to provide offline_payment_method.
Constraints
  • offline_payment_method cannot be configured when customer sharing is enabled for your site.
  • auto_collection must be set to off to provide offline_payment_method.
Enum Values
no_preference

No Preference

cash

Cash

check

Check

bank_transfer

Bank Transfer

ach_credit

ACH Credit

auto_close_invoices
optional, boolean

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.

Prerequisites
  • Metered Billing must be enabled for your site to provide auto_close_invoices.
  • Automatically Close Invoices must be enabled for your site to provide auto_close_invoices.
consolidated_invoicing
optional, boolean

Indicates whether invoices raised on the same day for the customer are consolidated. When provided, this overrides the default configuration at the site-level. This parameter can be provided only when Consolidated Invoicing is enabled.

Note:

Any invoices raised when a subscription activates from in_trial or future status, are not consolidated by default. Contact Support to enable consolidation for such invoices.

.

Prerequisites
  • Consolidated Invoicing must be enabled for your site to provide consolidated_invoicing.
  • Overriding the Consolidated Invoicing setting must be allowed for your site to provide consolidated_invoicing.
token_id
optional, string, max chars=40

The Chargebee payment token generated by Chargebee JS.

Note: The payment token created via Chargebee JS uses the gateway selected through Smart Routing. Explicitly passing a gateway_id in this API call will not override the gateway associated with the token.

business_entity_id
optional, string, max chars=50

The unique ID of the business entity this customer should be linked to. An alternative way of passing this parameter is by means of a custom HTTP header.

Default behavior

Prerequisite
  • Multiple business entities have been created for the site.
invoice_notes
optional, string, max chars=2000

A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.

card
Parameters for card
pass parameters as card[<param name>]
bank_account
Parameters for bank_account
pass parameters as bank_account[<param name>]
payment_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
payment_intent
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
entity_identifiers[0..n]
Parameters for entity_identifiers. Multiple entity_identifiers can be passed by specifying unique indices.
pass parameters as entity_identifiers[<param name>][<idx:0..n>]
tax_providers_fields[0..n]
Parameters for tax_providers_fields. Multiple tax_providers_fields can be passed by specifying unique indices.
pass parameters as tax_providers_fields[<param name>][<idx:0..n>]

Returns

customer
Customer object
Resource object representing customer
card
Card object
Resource object representing card