Sample Use Cases and Flows

This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful jumping off point as you plan your implementation.

Set up custom tax rates for a new region

You need to configure tax rates for a business expanding into a new geographical region.

To set up custom tax rates for a new region:

1. Identify the tax groups that need custom rates in the new region. Call Query Tax Groups to get the tax group IDs for products or services requiring different tax treatment.

2. Identify the tax region representing the new geographical area. Call Query Tax Regions to get the tax region ID.

3. Create the manual tax mapping with the custom rate.

4. Verify the mapping was created successfully by calling Get Manual Tax Mapping with the returned ID.

Import tax mappings from an external system

You need to migrate existing tax configuration from a legacy tax system or import rates from a spreadsheet.

To import multiple tax mappings:

1. Structure your data as an array of manual tax mapping objects. Ensure each mapping has valid tax group and region IDs.

2. Group the mappings into batches of up to 100 items to comply with bulk operation limits.

3. For each batch, call Bulk Create Manual Tax Mappings.

4. Process any failed mappings from the results array and retry them in a separate request if needed.

Update tax rates after regulatory changes

Local tax authorities have announced rate changes that affect your existing manual tax mappings.

To update existing tax rates:

1. Query existing mappings that need updates. For example, to find all mappings for a specific region.

2. For each mapping that needs updating, call Update Manual Tax Mapping with the new rate.

3. Verify the updates by querying the updated mappings to confirm the new rates are in effect.