# Customers

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


Represents a customer. [Subscriptions](/docs/api/v1/subscriptions/subscription-object), [Card](/docs/api/v1/cards/card-object) and Billing Address are associated with the customer resource. Customer resource will be created along with subscription via "[Create a Subscription](/docs/api/v1/subscriptions/create-a-subscription)" API. The **id** of the customer will be same as that of associated subscription id if not explicitly set.

The Billing Address is significant especially when [EU VAT taxes](https://www.chargebee.com/docs/tax.html#european-union-vat) are involved, for tax calculations will be based on this address. For customers without Billing Address, EU VAT taxes will **not** be included. Thus ensure to set this properly if you have configured EU VAT Tax.

**Note:** For the customers who signed up before 1st Mar 2014, Customer's Billing Address and 'vat\_number' will be replaced automatically whenever the associated Card gets updated. i.e existing values for Billing Address and 'vat\_number' will be cleared and the new values will be set. This behaviour is changed now - The VAT Number should always be passed along Billing Address and not with Card address. Both the addresses have to be dealt separately.

## Sample Customer

```json
{
  "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"
}
```

## Customers attributes

## Input Parameters

- `id` (required, string, max chars=50)
  Identifier of the customer.

- `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.

- `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)` .

- `auto_collection` (required, 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` (required, boolean, default=false)
  Whether the customer can pay via Direct Debit

- `created_at` (required, timestamp(UTC) in seconds)
  Timestamp indicating when this customer resource is created.

- `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.

- `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.

- `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.

- `account_credits` (required, in cents, min=0)
  Promotional credits balance of this customer

- `refundable_credits` (required, in cents, min=0)
  Refundable credits balance of this customer

- `excess_payments` (required, in cents, min=0)
  Total unused payments associated with the customer

- `meta_data` (optional, jsonobject)
  A set of key-value pairs stored as additional information for the customer. [Learn more](/docs/api/v1/customers) .

- `billing_address` (optional, billing_address)
  Billing address for a customer.
  - `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) 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)
    State or Province
  - `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.
  - `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) .

- `contacts` (optional, list of contact)
  contacts
  - `id` (required, string, max chars=150)
    Unique reference ID provided for the contact.
  - `first_name` (optional, string, max chars=150)
    First name of the contact.
  - `last_name` (optional, string, max chars=150)
    Last name of the contact.
  - `email` (required, string, max chars=70)
    Email of the contact.
  - `phone` (optional, string, max chars=50)
    Phone number of the contact.
  - `label` (optional, string, max chars=50)
    Label/Tag provided for contact.
  - `enabled` (required, boolean, default=false)
    Contact enabled / disabled
  - `send_account_email` (required, boolean, default=false)
    Whether Account Emails option is enabled for the contact.
  - `send_billing_email` (required, boolean, default=false)
    Whether Billing Emails option is enabled for the contact.

- `payment_method` (optional, payment_method)
  Primary Payment Source of the customer.
  - `type` (required, enumerated string)
    Type of payment source
    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` (required, enumerated string)
    Name of the gateway the payment method is associated 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.
      - `not_applicable`
        Indicates that payment gateway is not applicable for this resource.
  - `status` (required, enumerated string, default=valid)
    Current status of the payment source.
    Possible enum values:
      - `valid`
        A payment source that is valid and active.
      - `expiring`
        A payment source that is expiring (like card's status based on its expiry date).
      - `expired`
        A payment source that has expired
      - `invalid`
        The billing agreement cannot be used. It might become valid again either automatically or due to customer action.
  - `reference_id` (required, string, max chars=200)
    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.