Creates a customer resource. Optionally, creates a payment source for the customer.
Creating payment source
Although this operation supports creation of a customer with a payment source, it is recommended to use one of the Payment Source APIs to capture payment source details instead of using this operation. This way, even if payment source creation fails due to errors at the payment gateway, the customer resource can still be created successfully.
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_addressobject from the customer to set the values in thebilling_addressof the invoices generated for the customer. - If the
billing_addressobject does not include thefirst_name,last_name, orcompanyfields, Chargebee automatically uses the values fromcustomer.first_name,customer.last_name, andcustomer.company(if available) when generating invoices.
Payment source
- If
payment_intentorpayment_methodparameter is passed, apayment_sourceresource of the appropriate type is created for the customer. - If
bank_accountparameter is passed, apayment_sourceresource oftypedirect_debitis created for the customer. - If
cardparameter is passed, apayment_sourceresource oftypecardis created for the customer.
Use Cases
Use the payment_intent parameter to create a payment source for the customer.
Note
This works for both Strong Customer Authentication (SCA) (i.e. 3D-Secure) and non-SCA flows.
- Create a
payment_intentresource by calling the Create a payment intent API. - Pass the
payment_intentobject to your frontend and use Chargebee.js to capture the payment source details from the customer. You can use Payment Components to capture the payment source details. - Listen to the
payment_intent_updatedevent. Once thepayment_intent.statusisauthorized, pass thepayment_intent.idusing thepayment_intent[id]parameter in this API call.
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.
- Use the JavaScript library of your payment gateway to capture the payment method details. Examples include:
- Stripe.js
- Braintree.js
- Accept.js (if you use Authorize.Net)
- Adyen's Client-Side Encryption (if you use Adyen)
- Pass the payment method token using the
payment_method[reference_id]orpayment_method[tmp_token]parameter along with any additional parameters required by the payment gateway to create the payment source.
You can pass raw bank account details via this API. Use the bank_account parameter to pass the bank account details.
Sample Request
URL Format
Input Parameters
Email address of the customer. Configured email notifications are sent to this email address. Invalid email address will result in an error.
The currency code (in ISO 4217 format) of the customer.
Prerequisites
- Applicable only when Multi-currency pricing is enabled.
- The currency must be enabled in Chargebee Billing before passing this parameter.
Whether payments needs to be collected automatically for this customer.
Constraints
offline_payment_methodcannot be passed whenauto_collectionis set toon.
Whenever an invoice is created, an automatic attempt to charge the customer's payment method is made.
Automatic 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.
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
.
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.
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.
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.
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.
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.
Determines whether to send an e-invoice manually or automatic.
Use this value to send e-invoice every time an invoice or credit note is created.
When manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.
The default value of the site which can be overridden at the customer level.
Specifies if the customer is liable for tax.
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.
- 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_codeorexempt_numberattributes if you use Chargebee's AvaTax for Sales or specifyexemption_detailsattribute if you use Chargebee's AvaTax for Communications integration. Tax may still be applied by Avalara for certain values ofentity_code/exempt_number/exemption_detailsbased 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 .
Indicates the type of the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.
When the purchase is made by a customer for home use
When the purchase is made at a place of business
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
When the purchase is made by an industrial business
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.
Indicates the exemption type of the customer. This is applicable only if you use Chargebee's TaxJar integration.
Whole-sale
Government
Other
Confirms that a customer is a valid business without an EU/UK VAT number.
Determines which region-specific language Chargebee uses to communicate with the customer. Use the language pack to customize the translations for each locale.
Constraints
- The value must be one from the supported locale list.
Prerequisite
- Add and activate the locale in Chargebee.
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.
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration .
Federal government
State government
Tribe/Status Indian/Indian Band
Foreign diplomat
Charitable or benevolent organization
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 .
A collection of key-value pairs that provides extra information about the customer.
Note: There's a character limit of 65,535.
The preferred offline payment method for the customer.
Constraints
- auto_collection must be set to
offwhen passing this parameter.
Prerequisites
- Offline payment methods are enabled.
No Preference
Cash
Check
Bank Transfer
ACH 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.
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.
.
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.
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.
Prerequisites
- Multiple business entities have been created for the site.
Default behavior
- When not provided, the customer is linked to the default business entity defined for the site.
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.
Parameters for card. Use this parameter to pass raw card details.
Passing raw card data via API involves PCI liability at your end due to the sensitivity of the data.