POST /customers/{customer-id}/update_billing_info

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

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

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

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 is not configured for your site.
Ensure that registered_for_gst = true is not passed if Australian GST is not configured for your site.

Use Cases

Prevent tax provider errors due to missing billing information

After integrating tax providers, 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 value of item prices is changed from true to false before subscription renewal and reactivation.

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

Choose one of the following solutions:

Option A: Fix IP address mismatch

Use the Update a card payment source API and include the correct IP address in the request header.

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 option or the Self-Serve Portal.

Option C: Disable location validation

In Chargebee Billing, navigate to Settings > Configure Chargebee > Taxes.
Select the country.
In the right pane, clear the Enable location validation checkbox.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`customer-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`vat_number_prefix`	String	No	An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with `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.
`tax_providers_fields`	Object	No	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).
`tax_providers_fields.field_value[]`	Array	No	The value of the related tax field. Note This parameter is supported only when selling to India-SEZ customers or when you're an Indian business that sells to customers outside India.
`tax_providers_fields.field_id[]`	Array	No	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 customers or when you're an Indian business that sells to customers outside India.
`tax_providers_fields.provider_name[]`	Array	No	Name of the tax provider. Note This parameter is supported only when selling to India-SEZ customers or when you're an Indian business that sells to customers outside India.
`entity_identifier_standard`	String	No	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. Default value: "iso6523-actorid-upis"
`entity_identifiers`	Object	No	Parameters for entity_identifiers.
`entity_identifiers.id[]`	Array	No	The unique id for the `entity_identifier[i]` in Chargebee. This is required when `entity_identifier[operation][i]` is `update` or `delete`.
`entity_identifiers.operation[]`	Array	No
`entity_identifiers.value[]`	Array	No	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[]`.
`entity_identifiers.scheme[]`	Array	No	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 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[]` description.
`entity_identifiers.standard[]`	Array	No	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[]`.
`entity_identifier_scheme`	String	No	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.
`vat_number`	String	No	The VAT/tax registration number for the customer. For customers with `billing_address` as `XI` (United Kingdom - Northern Ireland), the first two characters of the full VAT number can be overridden by setting `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.
`is_einvoice_enabled`	Boolean	No	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`	String	No	Determines whether to send einvoice manually or automatic. * 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. Valid values: `"manual"` `"site_default"` `"automatic"`
`registered_for_gst`	Boolean	No	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. 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`	Boolean	No	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.
`billing_address`	Object	No	Parameters for billing_address.
`billing_address.first_name`	String	No	The first name of the billing contact. Warning If you don't pass this parameter, the value will be deleted from the customer object.
`billing_address.state`	String	No	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 and India If `state_code` is provided.
`billing_address.city`	String	No	The name of the city. Warning If you don't pass this parameter, the value will be deleted from the customer object.
`billing_address.validation_status`	String	No	The address verification status. * invalid - Address is invalid. * valid - Address was validated successfully. * partially_valid - The address is valid for taxability but has not been validated for shipping. * not_validated - Address is not yet validated. Valid values: `"partially_valid"` `"valid"` `"not_validated"` `"invalid"` Default value: "not_validated"
`billing_address.line2`	String	No	Address line 2. Warning If you don't pass this parameter, the value will be deleted from the customer object.
`billing_address.line1`	String	No	Address line 1. Warning If you don't pass this parameter, the value will be deleted from the customer object.
`billing_address.email`	String	No	The email address. Warning If you don't pass this parameter, the value will be deleted from the customer object.
`billing_address.last_name`	String	No	The last name of the billing contact. Warning If you don't pass this parameter, the value will be deleted from the customer object.
`billing_address.company`	String	No	The company name.
`billing_address.line3`	String	No	Address line 3. Warning If you don't pass this parameter, the value will be deleted from the customer object.
`billing_address.state_code`	String	No	The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. 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`).
`billing_address.zip`	String	No	Zip or postal code. The number of characters is validated according to the rules specified here. Warning If you don't pass this parameter, the value will be deleted from the customer object.
`billing_address.phone`	String	No	The phone number. Warning If you don't pass this parameter, the value will be deleted from the customer object.
`billing_address.country`	String	No	The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code. Warning If you don't pass this parameter, the value will be deleted from the customer object. Brexit If you have enabled EU VAT in 2021 or later, or have manually enable 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.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.