The Contact Tax Details API lets you manage the tax-related information of a site's contacts. Its main purpose is to associate a contact with a tax exempt group, so that the contact automatically receives that group's tax exemption at checkout.
Each contact's tax details are keyed by the contact ID and map the contact to at most one tax exempt group. During tax calculation, the buyer's contact ID resolves their tax details, and if a tax exempt group is set, the matching exemption is applied and reported as an exempt amount in the tax breakdown.
With the Contact Tax Details API, you can:
- Associate a contact with a tax exempt group, or update that association, individually or in bulk.
- Retrieve, delete, and query a contact's tax details.
- Include a contact's name, email, and VAT ID in responses.
- Count the contacts that match a filter, such as all members of a tax exempt group.
- Organize contact tax details with tags.
To fully exempt a contact, associate them with the predefined global full-exemption group, which requires no setup. To apply reduced or category-specific rates, associate them with a custom tax exempt group that has override rates defined on the relevant manual tax mappings.
It's important to note the following points before starting to code:
- Each contact has a single set of tax details, identified by the contact ID, and can be associated with only one tax exempt group at a time. Creating or updating the association uses Upsert Contact Tax Details.
- To fully exempt a contact, associate them with the predefined global full-exemption group, which requires no setup. For reduced or category-specific rates, use a custom group that has override rates defined on the relevant manual tax mappings.
- A contact's details, such as name, email, and VAT ID, are returned only when you pass
CONTACT_DETAILS in the fields array. This data is read from the contact at request time and isn't stored by this API. The VAT ID specifically is read from the contact's invoices.vatId extended field, so it's empty unless that field is set on the contact.
- The VAT ID checkout flow, where a buyer's VAT ID is validated and used to assign an exempt group, is available when the Exemptify app is installed on the site.
- A resolved exemption is applied by the Wix manual tax calculator, even when the region is otherwise served by a third-party tax calculator.
- Contact tax details: The tax-related record for a single contact, keyed by the contact ID, that associates the contact with a tax exempt group.
- Tax exempt group: A reusable, named set of tax exemption rules applied to many customers.
- VAT ID: A value-added tax identification number a buyer provides to prove eligibility for a tax exemption.
- Exempt amount: The portion of tax reduced by an exemption, reported in the tax breakdown during tax calculation.