POST /customers/{customer-id}/update_billing_info

Updates a customer's billing information, including billing_address and tax-related details like vat_number.
Note: To modify other customer attributes, use the Update Customer API.
Note: When an invoice is created for a customer, the billing address specified for the customer is saved with the invoice. If the first_name, last_name, and company fields under customer.billing_address are empty, Chargebee retrieves this information from customer.first_name, customer.last_name, and customer.company respectively, if available.

Implications of the operation {#ImplicationsOfTheOperation}

How this update works
This operation works like an assignment. Chargebee first discards the existing values of the customer object's attributes that correspond to the parameters in this operation. Then, Chargebee assigns the arguments passed in this operation to the corresponding attributes.

Therefore, you must pass all attributes you want to retain, even if their values remain unchanged. If you omit an argument, Chargebee deletes that attribute from the customer object.

Example {#ImplicationDescription}

Assume the customer object has these attributes set:

Set A

vat_number
billing_address.email
billing_address.line1
billing_address.state_code
billing_address.zip
billing_address.city
billing_address.country

Now, you make an API call with only the following parameters:

Set B

billing_address.line1
billing_address.state_code
billing_address.zip
billing_address.city
billing_address.country

Because the vat_number and billing_address.email were not included in the request, those attributes will be removed from the customer object. The object will now only include the parameters in Set B. To preserve vat_number and billing_address.email, include all Set A fields in the request.
entity_identifiers[i] update behavior
If any of entity_identifiers[operation][i] is specified as delete, entity_identifiers[i] remains unchanged for the customer object.

Use Cases {#UseCases}

Prevent subscription cancellations due to missing billing information after tax provider integration
If you're a startup below the tax threshold, you might skip collecting billing addresses during customer signup to reduce friction. However, as you scale and exceed the tax threshold, you'll need to collect taxes and may integrate with a tax provider like Avalara.

After integrating Avalara, you might encounter unintended subscription cancellations 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 {#UseCaseDescription}

Use this operation to update at least the billing_address.zip for all customers to prevent tax calculation failures.

FAQs {#Faqs}

I want to set the VAT number for a customer, but I don't know where it fits into the request. {#FaqTitle}

Use the "Update billing info for a customer" operation including the following arguments:

vat_number
vat_number_prefix
All other arguments that correspond to the existing attributes of the customer.

Troubleshooting {#Troubleshooting}

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

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 Chargebee tries to match the customer's billing country with their IP address or the card issuing country (based on the card BIN).

Resolution {#TroubleshootDescription}

The error occurs because location validation is enabled in the tax settings. Disable it to resolve the issue.

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

If the issue is related to the IP address, use Chargebee's Update a Card Payment Source API and include the correct IP address in the request header.

If the issue is caused by a BIN mismatch, ask the customer to update their payment method with one whose BIN matches their country using the Request Payment Method option or the Self-Serve Portal.

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 Possible 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 Possible 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 Possible 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 `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.
`tax_providers_fields`	Object	No	Parameters for tax_providers_fields
`tax_providers_fields.field_value[]`	Array	No	The value of the related tax field
`tax_providers_fields.field_id[]`	Array	No	Field id of the attribute which tax vendor has provided while getting onboarded with Chargebee.
`tax_providers_fields.provider_name[]`	Array	No	Name of the tax provider.
`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 description for `entity_identifiers[]`.
`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 `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.
`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. Possible 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.
`business_customer_without_vat_number`	Boolean	No	Confirms that a customer is a valid business without an EU/UK VAT number.
`billing_address`	Object	No	Parameters for billing_address
`billing_address.first_name`	String	No	The first name of the billing contact.
`billing_address.state`	String	No	The state/province name. Is set by Chargebee automatically for US, Canada and India If `state_code` is provided.
`billing_address.city`	String	No	The name of the city.
`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. Possible values: `"partially_valid"` `"valid"` `"not_validated"` `"invalid"` Default value: "not_validated"
`billing_address.line2`	String	No	Address line 2
`billing_address.line1`	String	No	Address line 1
`billing_address.email`	String	No	The email address.
`billing_address.last_name`	String	No	The last name of the billing contact.
`billing_address.company`	String	No	The company name.
`billing_address.line3`	String	No	Address line 3
`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 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`).
`billing_address.zip`	String	No	Zip or postal code. The number of characters is validated according to the rules specified here.
`billing_address.phone`	String	No	The phone number.
`billing_address.country`	String	No	The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code. 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.