Skip to content

Adjust dynamic URL section, Tax provider visibility section #1272

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
theromulans merged 1 commit into from
Mar 2, 2026
Merged

Adjust dynamic URL section, Tax provider visibility section #1272

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
27 changes: 14 additions & 13 deletions docs/integrations/tax.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,17 +23,24 @@ Once you've obtained your app ID, fill out [this form](https://docs.google.com/f

Once your tax provider configuration is ready, we'll let you know through email. The email will also include your `provider_id`, which is required when [establishing a connection](#establishing-a-connection) with the [Tax Provider API](/docs/rest-contracts/tax).

### Tax profile (optional)
### Tax provider visibility

BigCommerce sets the tax provider registry with your URLs for [Tax Provider API](/docs/rest-contracts/tax) requests. BigCommerce sends requests to these URLs, for example, when a shopper requests tax estimates.
If you would like to support multiple connections for a merchant, BigCommerce can set the registry with flexible URLs that use our new profile option.
These URLs would include a reserved string, for example, `https://{profile}/estimate`, allowing merchants to customize the base domain.
By default, tax providers can be installed on any number of stores. Your tax provider will only be visible on these stores after [establishing a connection](#establishing-a-connection).

When connecting or installing your app, you must allow merchants to enter the URL's base domain in the control panel. Merchants need to be able to self-serve updates to the URL through your app.
When you [Establish a Tax Provider connection](#establishing-a-connection), include the `profile` base domain along with credentials associated with the merchant's account.
Tax providers can optionally be made visible on all stores on the BigCommerce platform. If you are interested in exploring this topic, please discuss the available options with your [BigCommerce tech partner contact](https://www.bigcommerce.com/partners).

Once an arrangement has been confirmed, you can make a request to enable platform-wide availability for your tax provider by emailing [taxproviderapi@bigcommerce.com](mailto:taxproviderapi@bigcommerce.com) with the relevant details.

### Dynamic tax URLs (optional)

BigCommerce sets the tax provider registry with your URLs for [Tax Provider API](/docs/rest-contracts/tax) requests. BigCommerce sends requests to these URLs, for example, when a shopper requests a tax estimate. These URLs can optionally include a reserved string to generate a dynamic URL.

BigCommerce offers the `{profile}` reserved string. When you [Establish a Tax Provider connection](#establishing-a-connection), include a `profile` value along with credentials associated with the merchant's account. This `profile` value will then be applied to any future requests made by this merchant.

For example, the tax URL `https://{profile}/estimate` allows merchants to customize the base domain. This can be especially useful when using tunnelling software during development of your sandbox tax provider (e.g. ngrok).

<Callout type="info">
You must liaise with the merchant to provide them with customized URLs. BigCommerce merely consumes the URL values the merchant enters and uses the provided string value for Tax Provider API requests.
It is the tax provider's responsibility to enforce the profile value being populated by merchants. Blank values cannot be processed as valid URLs.
</Callout>

### Test tax provider (optional)
Expand All @@ -46,12 +53,6 @@ When you [share provider details](#sharing-provider-details-with-bigcommerce), s
We recommend only creating one test tax provider instance. When you develop your app, it's best to test your [Tax Provider API](/docs/rest-contracts/tax) endpoints outside the BigCommerce platform. This helps avoid unnecessary dependencies.
</Callout>

### Platform-wide availability (optional)

Tax providers can be made available to all stores on the BigCommerce platform. If you are interested in exploring this topic, please discuss the available options with your [BigCommerce tech partner contact](https://www.bigcommerce.com/partners).

Once an arrangement has been confirmed, you can make a request to enable platform-wide availability for your tax provider by emailing [taxproviderapi@bigcommerce.com](mailto:taxproviderapi@bigcommerce.com) with the relevant details.

## Building the app

You must build a BigCommerce [single-click app](/docs/integrations/apps/guide/types#single-click) to use the Tax Provider API for tax estimates and document submissions. Using a BigCommerce single-click app lets you promote your solution in the BigCommerce App Marketplace and ask merchants to authorize your app during install. Single-click apps also allow merchants to configure tax provider settings through an iFrame in the control panel.
Expand Down