Contact Tax Details: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Mark a customer as tax-exempt

A site owner wants to exempt a specific customer from tax. You associate the customer's contact with a tax exempt group.

To mark a customer as tax-exempt:

1. Choose a group. To fully exempt the customer, call List Default Tax Exempt Groups and use the global full-exemption group's id. For a reduced rate, use a custom tax exempt group that has override rates defined.
2. Associate the customer with the group by calling Upsert Contact Tax Details with the customer's contact ID as id and the group's ID as taxExemptGroupId.
3. On the customer's next checkout, tax calculation applies the group's exemption and reports the reduced tax as the exempt amount in the tax breakdown.

Exempt a customer after validating their VAT ID at checkout

The Exemptify app collects and validates a buyer's VAT ID at checkout, then associates the contact with an exempt group.

To exempt a customer after validating their VAT ID:

1. At checkout, the buyer provides a VAT ID, and Exemptify validates it and determines the appropriate tax exempt group.
2. Associate the buyer's contact with the group by calling Upsert Contact Tax Details with the contact ID and the chosen taxExemptGroupId.
3. On this and later checkouts, the buyer's cart is calculated with the exemption applied, without the buyer re-entering their VAT ID.
4. If the buyer later becomes ineligible, call Delete Contact Tax Details to remove the association.

List all customers in a tax exempt group

A site owner wants a dashboard of the customers in a tax exempt group, enriched with each contact's details.

To list all customers in a tax exempt group:

1. Call Query Contact Tax Details with a filter on taxExemptGroupId, and include CONTACT_DETAILS in the fields array to enrich each result with the contact's name, email, and VAT ID.
2. Page through the results using the returned cursor paging metadata.
3. Call Count Contact Tax Details with the same filter to display the total number of customers in the group.