Skip to content

Modified section about configuring tax provider settings to streamline it for integrators #1143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 3, 2025
Merged

Modified section about configuring tax provider settings to streamline it for integrators #1143

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions docs/integrations/tax.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,10 @@ You must build a BigCommerce [single-click app](/docs/integrations/apps/guide/ty

Review our [introduction to building apps](/docs/integrations/apps) guide and use the sidebar to explore topics including: types of apps, managing apps in the dev portal, implementing OAuth, and designing the UI.

We recommend that you provide a login flow within your app iFrame so that you can choose your own authentication method. You can also provide an account registration flow in your iFrame to help merchants create a new tax provider account. Learn more about [designing the app UI](/docs/integrations/apps/guide/ui). An account login flow lets you capture basic authentication credentials from merchants.

We also recommend that you [establish a connection](#establishing-a-connection) immediately after the merchant installs your app, and you authenticate the merchant's account credentials. Otherwise, your tax provider will not be displayed when merchants navigate to the **Settings > Setup > Tax** page in the control panel.

Make sure to also review our [app development best practices](/docs/integrations/apps/guide/best-practices) for some tips.

<Callout type="info">
Expand All @@ -98,25 +102,27 @@ When handling the OAuth flow, make sure your app requests read and write permiss

## Establishing a connection

You will be ready to set up a connection with the Tax Provider API when all of the following are true:
You will be ready to set up a connection with the Tax Provider API when all the following are true:

* You have [shared your tax provider details](#sharing-provider-details-with-bigcommerce) with BigCommerce through email, and we've replied confirming the tax provider configuration is now ready on all supplied merchant and/or partner test stores.
* BigCommerce has shared the `provider_id` of the tax provider configuration with you through email after you [shared your tax provider details](#sharing-provider-details-with-bigcommerce).
* You have [built a draft app](#building-the-app) that handles the OAuth flow during app installation.
* During the [OAuth flow](#installing-the-app), the app requests that the merchant authorize read and write permissions on the Information and Settings API scopes.
* During the [OAuth flow](#installing-the-app), you received and stored the `client_id` and `access_token`.

For context, the [Tax Provider API Connection endpoints](/docs/rest-contracts/tax-app-connection) add a layer of security for your app. You can use these basic credentials to authenticate API requests that you receive from stores so that you can reject unauthorized requests.

An account login flow lets you capture basic authentication credentials from merchants. We recommend that you provide a login flow within your app iFrame so that you can choose your own authentication method. You can also provide an account registration flow in your iFrame to help merchants create a new tax provider account. Learn more about [designing the app UI](/docs/integrations/apps/guide/ui).
To establish a connection, you **must** call the [Update Connection](/docs/rest-contracts/tax-app-connection#update-a-connection) Tax Connection endpoint to establish a connection.

We recommend calling the [Update Connection](/docs/rest-contracts/tax-app-connection#update-a-connection) endpoint immediately after the merchant installs your app and you authenticate the merchant's account credentials. Otherwise, your tax provider will not be displayed when merchants navigate to the **Settings > Setup > Tax** page in the control panel. You will need to include `store_hash`, `provider_id`, and `X-Auth-Token`(`access_token`) values.
The [Tax Provider API Connection endpoints](/docs/rest-contracts/tax-app-connection) add a layer of security for your app. You can use these basic credentials to authenticate API requests that you receive from stores so that you can reject unauthorized requests.

## Configure tax provider settings in the control panel

After you install your app and send basic authentication credentials through the [Update Connection](/docs/rest-contracts/tax-app-connection#update-a-connection) request, merchants can adjust their tax provider settings to activate supported functions on their store.
After you've established a connection, merchants can adjust their tax provider settings to activate supported functions on their store.

Merchants can adjust these settings by navigating to **Settings > Setup > Tax > _TaxProviderName_** in the control panel.
Merchants can adjust these settings by navigating to **Settings > Setup > Tax > _TaxProviderName_** in the control panel.

<Callout type="info">
Is your tax provider not visible in the control panel? Ensure that you have sent the update connection request as described in the [establishing a connection](#establishing-a-connection) section.
</Callout>

Before you can provide tax estimates, the merchant must choose which regions they want you to service. The control panel displays a list of countries and subdivisions that you support.

Expand Down