# Create a customer > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). [Idempotency Supported](/docs/api/v1/idempotency) **Note:** This operation optionally supports 3DS verification flow. To achieve the same, create the [Payment Intent](/docs/api/getting-started) and pass it as input parameter to this API. Creates a customer. You can create a customer and then create subscriptions for the customer when required. When creating a customer, you can pass along the billing address and card details. Passing credit card details to through the API involves PCI liability at your end as sensitive card information passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable: - If you use Stripe, you can also use [Stripe.js](https://stripe.com/docs/js) with your checkout form, to collect card information. - If you are using Braintree gateway, you can use [Braintree.js](https://developer.paypal.com/braintree/docs/guides/client-sdk/setup/javascript/v2) with your checkout form. - You can also use our [Hosted Pages](https://www.chargebee.com/docs/billing/2.0/hosted-capabilities/hosted-capabilities) based integration. The Billing Address is significant especially when [EU VAT taxes](https://www.chargebee.com/docs/tax.html#european-union-vat) are involved, for tax calculations will be based on this address. For customers without a billing address, EU VAT taxes will not be included. Thus ensure to set this properly if you have configured EU VAT Tax. Billing Address attributes shall be explicitly passed for customers paying offline(Cash, Check, Bank Transfer etc). **Note:** When an invoice is generated for a customer, the billing address provided for the customer will be stored with the invoice. If the First Name, Last Name, and Company fields do not contain any information under Billing Info, the same will be picked from Customer Details if the same is available there. ## Sample Request #### cURL ```bash curl https://{site}.chargebee.com/api/v1/customers \ -u {site_api_key}:\ -d first_name="John" \ -d last_name="Doe" \ -d email="john@test.com" \ -d "billing_address[first_name]"="John" \ -d "billing_address[last_name]"="Doe" \ -d "billing_address[line1]"="PO Box 9999" \ -d "billing_address[city]"="Walnut" \ -d "billing_address[state]"="California" \ -d "billing_address[zip]"="91789" \ -d "billing_address[country]"="US" ``` #### .NET ```dotnet using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = Customer.Create() .FirstName("John") .LastName("Doe") .Email("john@test.com") .BillingAddressFirstName("John") .BillingAddressLastName("Doe") .BillingAddressLine1("PO Box 9999") .BillingAddressCity("Walnut") .BillingAddressState("California") .BillingAddressZip("91789") .BillingAddressCountry("US") .Request(); Customer customer = result.Customer; Card card = result.Card; ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v3" customerAction "github.com/chargebee/chargebee-go/v3/actions/customer" "github.com/chargebee/chargebee-go/v3/models/customer" ) func main() { chargebee.Configure("{site_api_key}","{site}"); res,err := customerAction.Create(&customer.CreateRequestParams{ FirstName : "John", LastName : "Doe", Email : "john@test.com", BillingAddress : &customer.CreateBillingAddressParams{ FirstName : "John", LastName : "Doe", Line1 : "PO Box 9999", City : "Walnut", State : "California", Zip : "91789", Country : "US", }, }).Request() if err != nil { fmt.Println(err) } else { Customer := res.Customer Card := res.Card } } ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v4" ) func main() { config := &chargebee.ClientConfig{ SiteName: "{site}", ApiKey: "{site_api_key}", } client := chargebee.NewClient(config) req := &chargebee.CustomerCreateRequest{ FirstName : "John", LastName : "Doe", Email : "john@test.com", BillingAddress : &chargebee.CustomerCreateBillingAddress{ FirstName : "John", LastName : "Doe", Line1 : "PO Box 9999", City : "Walnut", State : "California", Zip : "91789", Country : "US", }, } res, err := client.Customer.Create(req) if err != nil { fmt.Println(err) } else { Customer := res.Customer Card := res.Card } } ``` #### Java ```java import com.chargebee.*; import com.chargebee.ListResult; import com.chargebee.models.*; import com.chargebee.models.enums.*; import java.io.IOException; public class Sample { public static void main(String args[]) throws IOException, Exception { Environment.configure("{site}", "{site_api_key}"); Result result = Customer.create() .firstName("John") .lastName("Doe") .email("john@test.com") .billingAddressFirstName("John") .billingAddressLastName("Doe") .billingAddressLine1("PO Box 9999") .billingAddressCity("Walnut") .billingAddressState("California") .billingAddressZip("91789") .billingAddressCountry("US") .request(); Customer customer = result.customer(); Card card = result.card(); } } ``` #### Java ```java import com.chargebee.v4.client.ChargebeeClient; import com.chargebee.v4.models.card.Card; import com.chargebee.v4.models.customer.Customer; import com.chargebee.v4.models.customer.params.CustomerCreateParams; import com.chargebee.v4.models.customer.responses.CustomerCreateResponse; public class CustomerCreate { public static void main(String[] args) { ChargebeeClient client = ChargebeeClient.builder() .apiKey("{site_api_key}") .siteName("{site}") .build(); CustomerCreateParams.BillingAddressParams billingAddressParams = CustomerCreateParams.BillingAddressParams.builder() .firstName("John") .lastName("Doe") .line1("PO Box 9999") .city("Walnut") .state("California") .zip("91789") .country("US") .build(); CustomerCreateParams params = CustomerCreateParams.builder() .firstName("John") .lastName("Doe") .email("john@test.com") .billingAddress(billingAddressParams) .build(); CustomerCreateResponse response = client.customers().create(params); Customer customer = response.getCustomer(); Card card = response.getCard(); } } ``` #### Node.js ```node import Chargebee from "chargebee"; const chargebee = new Chargebee({ site: "{site}", apiKey: "{site_api_key}", }); try { const result = await chargebee.customer.create({ first_name: "John", last_name: "Doe", email: "john@test.com", billing_address: { first_name: "John", last_name: "Doe", line1: "PO Box 9999", city: "Walnut", state: "California", zip: 91789, country: "US" } }); console.log(result); const customer = result.customer; const card = result.card; } catch (err) { console.log(err); } ``` #### PHP ```php "{site}", "apiKey" => "{site_api_key}", ]); $result = $chargebee->customer()->create([ "first_name" => "John", "last_name" => "Doe", "email" => "john@test.com", "billing_address" => [ "first_name" => "John", "last_name" => "Doe", "line1" => "PO Box 9999", "city" => "Walnut", "state" => "California", "zip" => "91789", "country" => "US" ] ]); $customer = $result->customer; $card = $result->card; ``` #### Python ```python from chargebee import Chargebee cb_client = Chargebee(api_key="{site_api_key}", site="{site}") response = cb_client.Customer.create( cb_client.Customer.CreateParams( first_name="John", last_name="Doe", email="john@test.com", billing_address=cb_client.Customer.CreateBillingAddressParams( first_name="John", last_name="Doe", line1="PO Box 9999", city="Walnut", state="California", zip="91789", country="US" ) ) ) customer = response.customer card = response.card ``` #### Ruby ```ruby require 'chargebee' ChargeBee.configure(:site => "{site}", :api_key => "{site_api_key}") result = ChargeBee::Customer.create({ :first_name => "John", :last_name => "Doe", :email => "john@test.com", :billing_address => { :first_name => "John", :last_name => "Doe", :line1 => "PO Box 9999", :city => "Walnut", :state => "California", :zip => "91789", :country => "US" } }) customer = result.customer card = result.card ``` ## Sample Response ```json { "customer": { "account_credits": 0, "allow_direct_debit": false, "auto_collection": "on", "billing_address": { "city": "Walnut", "country": "US", "first_name": "John", "last_name": "Doe", "line1": "PO Box 9999", "object": "billing_address", "state": "California", "state_code": "CA", "zip": "91789" }, "card_status": "no_card", "created_at": 1517506683, "email": "john@test.com", "excess_payments": 0, "first_name": "John", "id": "__test__5SK0bLNFRFuByp8Bu", "last_name": "Doe", "object": "customer", "refundable_credits": 0, "taxability": "taxable" } } ``` ## URL Format **POST** https://[site].chargebee.com/api/v1/customers ## 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 of the customer. Configured email notifications will be sent to this email. - `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. Possible 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. - `allow_direct_debit` (optional, boolean, default=false) Whether the customer can pay via Direct Debit. - `vat_number` (optional, string, max chars=20) The VAT/tax registration number for the customer. For customers with `[billing_address](/docs/api/customers/customer-object#billing_address)` `country` as `XI` (which is **United Kingdom - Northern Ireland** ), the first two characters of the [full VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) can be overridden by setting `[vat_number_prefix](/docs/api/customers/customer-object#vat_number_prefix)` . - `taxability` (optional, enumerated string, default=taxable) Specifies if the customer is liable for tax. Possible enum values: - `taxable` Computes tax for the customer based on the [site configuration](https://www.chargebee.com/docs/tax.html). 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](https://www.chargebee.com/docs/tax.html) feature or when using the [TaxJar integration](https://www.chargebee.com/docs/taxjar.html), no other action is needed. - However, when using our [Avalara integration](https://www.chargebee.com/docs/avalara.html), optionally, specify `entity_code` or `exempt_number` attributes if you use Chargebee's [AvaTax for Sales](https://www.chargebee.com/docs/avalara.html#configuring-tax-exemption) or specify `exemption_details` attribute if you use [Chargebee's AvaTax for Communications](https://www.chargebee.com/docs/avatax-for-communication.html) 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. - `meta_data` (optional, jsonobject) A set of key-value pairs stored as additional information for the customer. [Learn more](/docs/api/v1/customers) . - `created_from_ip` (optional, string, max chars=50) The IP address of the customer. Used primarily for [referral integrations](https://www.chargebee.com/docs/marketing-integration-index.html) and EU/UK VAT validation. - `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](/docs/api/invoices/invoice-object#notes) displayed on the invoice PDF. - `card` (optional, enumerated string) Parameters for card - `gateway` (optional, enumerated string) Name of the gateway this payment source is stored with. Possible enum values: - `chargebee` Chargebee test gateway. - `stripe` Stripe is a payment gateway. - `braintree` Braintree is a payment gateway. - `authorize_net` Authorize.net is a payment gateway - `paypal_pro` PayPal Pro Account is a payment gateway. - `pin` Pin is a payment gateway - `eway` eWAY Account is a payment gateway. - `eway_rapid` eWAY Rapid is a payment gateway. - `worldpay` WorldPay is a payment gateway - `balanced_payments` Balanced is a payment gateway - `beanstream` Bambora(formerly known as Beanstream) is a payment gateway. - `bluepay` BluePay is a payment gateway. - `elavon` Elavon Virtual Merchant is a payment solution. - `first_data_global` First Data Global Gateway Virtual Terminal Account - `hdfc` HDFC Account is a payment gateway. - `migs` MasterCard Internet Gateway Service payment gateway. - `nmi` NMI is a payment gateway. - `ogone` Ingenico ePayments (formerly known as Ogone) is a payment gateway. - `paymill` PAYMILL is a payment gateway. - `paypal_payflow_pro` PayPal Payflow Pro is a payment gateway. - `sage_pay` Sage Pay is a payment gateway. - `tco` 2Checkout is a payment gateway. - `wirecard` WireCard Account is a payment service provider. - `tmp_token` (optional, string, max chars=300) The single-use card token returned by vaults like Stripe/Braintree which act as a substitute for your card details. Before calling this API, you should have submitted your card details to the gateway and gotten this token in return. **Note:** Supported only for Stripe, Braintree and Authorize.Net. If this value is specified, there is no need to specify other card details (like number, cvv, etc). - `first_name` (optional, string, max chars=50) Cardholder's first name - `last_name` (optional, string, max chars=50) Cardholder's last name - `number` (required if card provided, string, max chars=1500) The credit card number without any format. If you are using [Braintree.js](https://developer.paypal.com/braintree/docs/guides/client-sdk/setup/javascript/v2#getting-braintree.js) , you can specify the Braintree encrypted card number here. - `expiry_month` (required if card provided, integer, min=1, max=12) Card expiry month. - `expiry_year` (required if card provided, integer) Card expiry year. - `cvv` (optional, string, max chars=520) The card verification value (CVV). If you are using [Braintree.js](https://developer.paypal.com/braintree/docs/guides/client-sdk/setup/javascript/v2#getting-braintree.js) , you can specify the Braintree encrypted CVV here. - `billing_addr1` (optional, string, max chars=150) Address line 1, as available in card billing address. - `billing_addr2` (optional, string, max chars=150) Address line 2, as available in card billing address. - `billing_city` (optional, string, max chars=50) City, as available in card billing address. - `billing_state_code` (optional, string, max chars=50) The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search/code) without the country prefix. Currently supported for USA, Canada, India and UAE. For instance, for Arizona (USA), set `billing_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` ). For Dubai (UAE), set as `DU` (not `AE-DU` ). - `billing_state` (optional, string, max chars=50) The state/province name. Is set by Chargebee automatically for US, Canada, India and UAE, if `billing_state_code` is provided. - `billing_zip` (optional, string, max chars=20) Postal or Zip code, as available in card billing address. - `billing_country` (optional, string, max chars=50) The billing address country of the customer. Must be one of [ISO 3166 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html) . **Note**: If you enter an invalid country code, the system will return an error. **Brexit** If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, then `XI` (the code for **United Kingdom - Northern Ireland**) is available as an option. - `ip_address` (optional, string, max chars=50) The IP address of the customer. Used primarily for referral integration and EU VAT validation. - `payment_method` (optional, enumerated string) Parameters for payment\_method - `type` (optional, enumerated string) The type of payment method. For more details refer [Update payment method for a customer](/docs/api/customers/update-payment-method-for-a-customer) API under Customer resource. Possible enum values: - `card` Card based payment including credit cards and debit cards. Details about the card can be obtained from the card resource. - `paypal_express_checkout` Payments made via PayPal Express Checkout. - `amazon_payments` Payments made via Amazon Payments. - `direct_debit` Represents bank account for which the direct debit or ACH agreement/mandate is created. - `automated_bank_transfer` Represents virtual bank account using which the payment will be done. - `gateway` (optional, enumerated string) Name of the gateway the payment method is associated with. Possible enum values: - `stripe` Stripe is a payment gateway. - `braintree` Braintree is a payment gateway. - `authorize_net` Authorize.net is a payment gateway - `paypal_pro` PayPal Pro Account is a payment gateway. - `pin` Pin is a payment gateway - `eway` eWAY Account is a payment gateway. - `eway_rapid` eWAY Rapid is a payment gateway. - `worldpay` WorldPay is a payment gateway - `balanced_payments` Balanced is a payment gateway - `beanstream` Bambora(formerly known as Beanstream) is a payment gateway. - `bluepay` BluePay is a payment gateway. - `elavon` Elavon Virtual Merchant is a payment solution. - `first_data_global` First Data Global Gateway Virtual Terminal Account - `hdfc` HDFC Account is a payment gateway. - `migs` MasterCard Internet Gateway Service payment gateway. - `nmi` NMI is a payment gateway. - `ogone` Ingenico ePayments (formerly known as Ogone) is a payment gateway. - `paymill` PAYMILL is a payment gateway. - `paypal_payflow_pro` PayPal Payflow Pro is a payment gateway. - `sage_pay` Sage Pay is a payment gateway. - `tco` 2Checkout is a payment gateway. - `wirecard` WireCard Account is a payment service provider. - `reference_id` (optional, string, max chars=200) The reference id. In the case of Amazon and Paypal this will be the _billing agreement id_. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. **Note:** This is not the one time temporary token provided by gateways like Stripe. For more details refer [Update payment method for a customer](/docs/api/customers/update-payment-method-for-a-customer) API under Customer resource. - `payment_intent` (optional, string) Parameters for payment\_intent - `id` (optional, string, max chars=150) 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. - `gateway_account_id` (required if payment intent token provided, string, max chars=50) The gateway account used for performing the 3DS flow. - `gw_token` (optional, string, max chars=65k) Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer [3DS implementation in Chargebee](/docs/api/3ds_card_payments) to find out the gateway-specific gw\_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow. - `reference_id` (optional, string, max chars=65k) Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow. - `billing_address` (optional, string) Parameters for billing\_address - `first_name` (optional, string, max chars=150) The first name of the billing contact. - `last_name` (optional, string, max chars=150) The last name of the billing contact. - `email` (optional, string, max chars=70) The email address. - `company` (optional, string, max chars=250) The company name. - `phone` (optional, string, max chars=50) The phone number. - `line1` (optional, string, max chars=150) Address line 1 - `line2` (optional, string, max chars=150) Address line 2 - `line3` (optional, string, max chars=150) Address line 3 - `city` (optional, string, max chars=50) The name of the city. - `state_code` (optional, string, max chars=50) The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search/code) without the country prefix. Currently supported for USA, Canada, India and UAE. 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` ). For Dubai (UAE), set as `DU` (not `AE-DU` ). - `state` (optional, string, max chars=50) The state/province name. Is set by Chargebee automatically for US, Canada, India and UAE, if `state_code` is provided. - `zip` (optional, string, max chars=20) Zip or postal code. The number of characters is validated according to the rules [specified here](https://chromium-i18n.appspot.com/ssl-address) . - `country` (optional, string, max chars=50) The billing address country of the customer. Must be one of [ISO 3166 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) . **Brexit** If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, then `XI` (the code for **United Kingdom - Northern Ireland**) is available as an option. ## Returns - `customer` (Customer object) Resource object representing customer - `card` (Card object) Resource object representing card