# Update billing info for a customer

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


[Idempotency Supported](/docs/api/idempotency)

Updates a customer's billing information, including billing address and tax-related details such as VAT number.

**Note**

See **Related APIs** for other customer attributes that can be updated.

### Prerequisites & Constraints

In some cases, passing the following parameters can cause the request to fail: `vat_number`, `business_customer_without_vat_number`, `tax_providers_fields`, and `registered_for_gst`. See **Implementation Notes** for more details.

### Impacts

**

Customer

**

For certain parameters, if you do not include a parameter in the request, Chargebee removes the corresponding attribute from the customer object. To retain an existing attribute, you must explicitly include its parameter in your request.

##### Parameters that are affected by this behavior[](#parameters-that-are-affected-by-this-behavior)

-   `billing_address.first_name`
-   `billing_address.last_name`
-   `billing_address.phone`
-   `billing_address.email`
-   `billing_address.line1`
-   `billing_address.line2`
-   `billing_address.line3`
-   `billing_address.city`
-   `billing_address.state`
-   `billing_address.country`
-   `billing_address.zip`
-   `vat_number`
-   `vat_number_prefix`
-   `business_customer_without_vat_number`
-   `registered_for_gst`

##### Example[](#example)

Assume the customer object has these attributes set:

**Current attributes:**

-   `billing_address.first_name`
-   `billing_address.last_name`
-   `billing_address.phone`
-   `billing_address.email`
-   `vat_number`

You make an API call with only the following parameters:

**Request parameters:**

-   `billing_address.first_name`
-   `billing_address.last_name`
-   `billing_address.phone`

**Result:** The `billing_address.email` and `vat_number` attributes are removed from the customer object because they weren't included in the request. To preserve these attributes, include them in the request.

**

Invoices

**

-   Chargebee uses the `billing_address` object from the customer to set the values in the [`billing_address`](/docs/api/invoices/invoice-object#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`](/docs/api/customers/customer-object#first_name), [`customer.last_name`](/docs/api/customers/customer-object#last_name), and [`customer.company`](/docs/api/customers/customer-object#company) (if available) when generating invoices.

### Implementation Notes

-   Ensure that `vat_number` and `business_customer_without_vat_number` = `true` are not passed together in the same request.
-   Ensure that `tax_providers_fields` is not passed if [Indian GST](https://www.chargebee.com/docs/billing/2.0/taxes/indian-gst) is not configured for your site.
-   Ensure that `registered_for_gst` = `true` is not passed if [Australian GST](https://www.chargebee.com/docs/australian-gst.html) is not configured for your site.

### Use Cases

Prevent tax provider errors due to missing billing information

After integrating [tax providers](https://www.chargebee.com/docs/billing/2.0/integrations/tax-integration-index), you might encounter unintended tax calculation failures during renewals. The error message typically states:

> Unable to calculate the tax rate as the shipping/billing address is either invalid or incomplete. Please verify and try again.

This error can occur even if the [`is_taxable`](/docs/api/item_prices/update-an-item-price#is_taxable) value of item prices is changed from `true` to `false` before subscription renewal and reactivation.

##### Solution[](#solution)

Use this operation to update the billing address attributes to ensure they are accurate and complete.

### Troubleshooting

Here are some commonly encountered errors when using this API, along with their resolutions

  

Error: `400`: "Operation failed as the country entered in the billing address by the customer cannot be verified against IP address or card BIN number."

This error occurs when location validation is enabled in the tax settings and there's a mismatch between the customer's billing country and their IP address or the card issuing country.

##### Resolution[](#resolution)

Choose one of the following solutions:

**Option A: Fix IP address mismatch**

Use the [Update a card payment source API](/docs/api/payment_sources/update-a-card-payment-source) and include the correct IP address in the [request header](/docs/api/advanced-features).

**Option B: Fix BIN mismatch**

Ask the customer to update their payment method with one whose BIN matches their country. You can do this using the [Request Payment Method](https://www.chargebee.com/docs/billing/2.0/hosted-capabilities/manage-payment-sources) option or the [Self-Serve Portal](/docs/api/customers/update-billing-info-for-a-customer).

**Option C: Disable location validation**

1.  In [Chargebee Billing](https://app.chargebee.com), navigate to **Settings > Configure Chargebee > Taxes**.
2.  Select the country.
3.  In the right pane, clear the **Enable location validation** checkbox.

#### Related APIs

Update a customer

Link a customer to an account

Unlink a customer from its parent account

## Sample Request

#### cURL

```bash
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"
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Customer.UpdateBillingInfo("__test__KyVnHhSBWlFY32dl")
		.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.UpdateBillingInfo("__test__KyVnHhSBWlFY32dl", &customer.UpdateBillingInfoRequestParams{
        BillingAddress : &customer.UpdateBillingInfoBillingAddressParams{
            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.CustomerUpdateBillingInfoRequest{
    BillingAddress : &chargebee.CustomerUpdateBillingInfoBillingAddress{
        FirstName : "John",
        LastName : "Doe",
        Line1 : "PO Box 9999",
        City : "Walnut",
        State : "California",
        Zip : "91789",
        Country : "US",
    },
}
  res, err := client.Customer.UpdateBillingInfo("__test__KyVnHhSBWlFY32dl", 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.updateBillingInfo("__test__KyVnHhSBWlFY32dl")
            .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.CustomerUpdateBillingInfoParams;
import com.chargebee.v4.models.customer.responses.CustomerUpdateBillingInfoResponse;

public class CustomerUpdateBillingInfo {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        CustomerUpdateBillingInfoParams.BillingAddressParams billingAddressParams =
            CustomerUpdateBillingInfoParams.BillingAddressParams.builder()
                .firstName("John")
                .lastName("Doe")
                .line1("PO Box 9999")
                .city("Walnut")
                .state("California")
                .zip("91789")
                .country("US")
                .build();

        CustomerUpdateBillingInfoParams params = CustomerUpdateBillingInfoParams.builder()
            .billingAddress(billingAddressParams)
            .build();

        CustomerUpdateBillingInfoResponse response = client
            .customers()
            .updateBillingInfo("__test__KyVnHhSBWlFY32dl", 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.updateBillingInfo("__test__KyVnHhSBWlFY32dl", {
        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
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->customer()->updateBillingInfo("__test__KyVnHhSBWlFY32dl", [
    "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.update_billing_info("__test__KyVnHhSBWlFY32dl",
    cb_client.Customer.UpdateBillingInfoParams(
        billing_address=cb_client.Customer.UpdateBillingInfoBillingAddressParams(
            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.update_billing_info("__test__KyVnHhSBWlFY32dl",{
  :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": {
    "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

## Input Parameters

- `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) as `XI` (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).
  
  **Warning**
  
  -   If you don't pass this parameter, the value will be **deleted** from the customer object.
  -   If you pass this parameter and also pass `business_customer_without_vat_number` = `true`, the request will fail.

- `vat_number_prefix` (optional, string, max chars=10)
  An overridden value for the first two characters of the [full VAT number](https://en.wikipedia.org/wiki/VAT_identification_number). Only applicable specifically for customers with [`billing_address`](/docs/api/customers/customer-object#billing_address) as `XI` (United Kingdom - Northern Ireland).
  
  **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.

- `entity_identifier_scheme` (optional, string, max chars=50)
  The Peppol BIS scheme associated with the `[vat_number](/docs/api/customers/customer-object#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](https://www.chargebee.com/docs/e-invoicing.html#supported-countries) .
  
  **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](https://www.chargebee.com/docs/australian-gst.html#reverse-charge-mechanism) is applicable. This field is applicable only when Australian GST is configured for your site.
  
  **Warning**
  
  -   If you don't pass this parameter, the value will be **deleted** from the customer object.
  -   If you pass this parameter as `true` and Australian GST is not configured for your site, the request will fail.

- `business_customer_without_vat_number` (optional, boolean)
  Confirms that a customer is a valid business without an EU/UK VAT number.
  
  **Warning**
  
  -   If you don't pass this parameter, the value will be **deleted** from the customer object.
  -   If you pass this parameter as `true` and also pass `vat_number`, the request will fail.

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

- `einvoicing_method` (optional, enumerated string)
  Determines whether to send einvoice manually or automatic.
  Possible 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.

- `billing_address` (optional, string)
  Parameters for billing\_address.
  - `first_name` (optional, string, max chars=150)
    The first name of the billing contact.
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
  - `last_name` (optional, string, max chars=150)
    The last name of the billing contact.
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
  - `email` (optional, string, max chars=70)
    The email address.
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
  - `company` (optional, string, max chars=250)
    The company name.
  - `phone` (optional, string, max chars=50)
    The phone number.
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
  - `line1` (optional, string, max chars=150)
    Address line 1.
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
  - `line2` (optional, string, max chars=150)
    Address line 2.
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
  - `line3` (optional, string, max chars=150)
    Address line 3.
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
  - `city` (optional, string, max chars=50)
    The name of the city.
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
  - `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 example:
    
    -   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.
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
    
    **Note** If you don't pass this parameter, the value will be 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).
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
  - `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).
    
    **Warning** If you don't pass this parameter, the value will be **deleted** from the customer object.
    
    **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.
    
    **E-Invoicing** If `country` is provided as different from the existing value and if `entity_identifier_scheme`, `entity_identifier_standard`, and `entity_identifier` already exist and are not provided for this operation, they're cleared.
  - `validation_status` (optional, enumerated string, default=not_validated)
    The address verification status.
    Possible enum values:
      - `not_validated`
        Address is not yet validated.
      - `valid`
        Address was validated successfully.
      - `partially_valid`
        The address is valid for taxability but has not been validated for shipping.
      - `invalid`
        Address is invalid.

- `entity_identifiers` (optional, array)
  Parameters for entity\_identifiers.
  - `id` (optional, string, max chars=40)
    The unique id for the `entity_identifier[i]` in Chargebee. This is required when `entity_identifier[operation][i]` is `update` or `delete`.
  - `scheme` (optional, string, max chars=50)
    The Peppol BIS scheme associated with the [`vat_number`](/docs/api/customers/customer-object#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](https://www.chargebee.com/docs/e-invoicing.html#supported-countries).
    
    **Tip** If there is only one entity identifier for the customer and the value is the same as `vat_number`, then there is no need to provide the `entity_identifiers[]` array. See [`entity_identifiers[]`](customers#customer_entity_identifiers) description.
  - `value` (optional, string, max chars=50)
    The value of the `entity_identifier`. This identifies the customer entity on the Peppol network. For example: `10101010-STO-10` .
    
    **Tip:**
    
    If there is only one entity identifier for the customer and the value is the same as `vat_number`, then there is no need to provide the `entity_identifiers[]` array. See [description for `entity_identifiers[]`](/docs/api/customers/customer-object#entity_identifiers).
  - `operation` (optional, enumerated string)
    The operation to be performed for the `entity_identifier`.
    Possible enum values:
      - `create`
        Creates a new `entity_identifier` for the customer.
      - `update`
        Updates an existing `entity_identifier` for the customer. `entity_identifier[id]` must be provided in this case.
      - `delete`
        Deletes an existing `entity_identifier` for the customer. `entity_identifier[id]` must be provided in this case.
  - `standard` (optional, string, 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 is only one entity identifier for the customer and the value is the same as `vat_number`, then there is no need to provide the `entity_identifiers[]` array. See [description for `entity_identifiers[]`](/docs/api/customers/customer-object#entity_identifiers).

- `tax_providers_fields` (optional, array)
  Parameters for tax\_providers\_fields.
  
  **Note** This parameter is supported only when selling to [India-SEZ](https://www.chargebee.com/docs/billing/2.0/taxes/indian-gst#configuring-taxes-for-special-economic-zones-sezs) customers or when you're an [Indian business that sells to customers outside India](https://www.chargebee.com/docs/billing/2.0/taxes/indian-gst#configuring-taxes-for-exports).
  - `provider_name` (optional, string, max chars=50)
    Name of the tax provider.
    
    **Note** This parameter is supported only when selling to [India-SEZ](https://www.chargebee.com/docs/billing/2.0/taxes/indian-gst#configuring-taxes-for-special-economic-zones-sezs) customers or when you're an [Indian business that sells to customers outside India](https://www.chargebee.com/docs/billing/2.0/taxes/indian-gst#configuring-taxes-for-exports).
  - `field_id` (optional, string, max chars=50)
    Field id of the attribute which tax vendor has provided while getting onboarded with Chargebee.
    
    **Note** This parameter is supported only when selling to [India-SEZ](https://www.chargebee.com/docs/billing/2.0/taxes/indian-gst#configuring-taxes-for-special-economic-zones-sezs) customers or when you're an [Indian business that sells to customers outside India](https://www.chargebee.com/docs/billing/2.0/taxes/indian-gst#configuring-taxes-for-exports).
  - `field_value` (optional, string, max chars=50)
    The value of the related tax field.
    
    **Note** This parameter is supported only when selling to [India-SEZ](https://www.chargebee.com/docs/billing/2.0/taxes/indian-gst#configuring-taxes-for-special-economic-zones-sezs) customers or when you're an [Indian business that sells to customers outside India](https://www.chargebee.com/docs/billing/2.0/taxes/indian-gst#configuring-taxes-for-exports).

## Returns

- `customer` (Customer object)
  Resource object representing customer

- `card` (Card object)
  Resource object representing card