Tax Providers

The Tax Provider API allows you to provide business-to-consumer sales tax estimates to shoppers on the storefront and to merchants in the control panel; it can also be used to submit documents for tax reconciliation purposes.

The Tax Provider API works in conjunction with a BigCommerce app, so you will need to build an app that integrates the Tax Provider API.

You can publish your BigCommerce app so that anyone can discover it in the BigCommerce App Marketplace (opens in a new tab) or publish your app as unlisted so merchants must install the app using a URL.

Obtaining an app ID

To get your app ID, start by creating an app in the Developer Portal (opens in a new tab), and fill out the information in the Technical tab. In the URL, you will see your unique app ID.

Learn more about finding your app's ID.

Sharing provider details with BigCommerce

Once you've obtained your app ID, share your app ID and the information below with BigCommerce by emailing taxproviderapi@bigcommerce.com. This information allows us to create your tax provider configuration, which will take approximately five days.

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 with the Tax Provider API.

Tax Provider Details	Required / Optional	Value(s)	Description	Example
App ID	Required	Integer	Tells us which tax provider configuration to use after the app is installed.	`123456`
Tax provider name	Required	String	Displayed in the control panel (e.g., Settings > Setup > Tax > Add tax service).	`Sample Tax`
Transaction type	Required	Production, Test	Whether your tax provider will be handling production traffic or conducting test transactions.	`Production`
Partner support email	Required	Email	Contact email that BigCommerce uses to send merchant support requests or discuss integration improvements with you.	`support@sampletax.example.com`
Coverage
Platform availability	Required	All stores, Limited availability	Whether your tax provider will be available to all stores or a limited number of stores.	`Limited availability`
Supported / unsupported countries	Required	ISO 3166-1 alpha-2	Comma separated ISO 3166-1 alpha-2 country codes for supported countries. You can also select to support to all countries, or all countries except a list of unsupported countries.	`US,CA,GB,FR,AU,NZ`
URLs
⁺Estimate URL	Required	URL	URL BigCommerce should use for Tax Provider API estimate requests.	`https://sampletax.example.com/tax/estimate`
⁺Commit URL	Optional	URL	URL BigCommerce should use for Tax Provider API quote requests.	`https://sampletax.example.com/doc/commit`
⁺Adjust URL	Optional	URL	URL BigCommerce should use for Tax Provider API quote requests.	`https://sampletax.example.com/doc/adjust`
⁺Void URL	Optional	URL	URL BigCommerce should use for Tax Provider API quote requests.	`https://sampletax.example.com/doc/void`
Testing
Partner sandbox store domain	Required	Domain name	Share your partner sandbox store for testing purposes prior to launching your tax provider. Learn how to create a partner sandbox store.	`https://sampletax-test-store.mybigcommerce.com/`

⁺ You have the option of supporting a URL that merchants can customize. See Tax Profile.

Tax profile (optional)

BigCommerce sets the tax provider registry with your URLs for Tax Provider API 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.

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, include the profile base domain along with credentials associated with the merchant's account.

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.

Test tax provider (optional)

You can build a test tax provider instance alongside a primary production tax provider instance. The test tax provider instance can support test transactions, service merchant-facing use cases, or support your development processes.

When you share provider details, specifying the transaction type for your tax provider instance is important. Test tax provider instances have lower expectations than those supporting production traffic like timeouts or error handling.

We recommend only creating one test tax provider instance. When you develop your app, it's best to test your Tax Provider API endpoints outside the BigCommerce platform. This helps avoid unnecessary dependencies.

Building the app

You must build a BigCommerce single-click app 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.

Review our introduction to building 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.

Make sure to also review our app development best practices for some tips.

When you develop your app, you can register your app in the Developer Portal without submitting it. The app will be in a Draft state. This means only stores owned by the same email address as that on the Developer Portal account can install the app.

Installing the app

When the merchant clicks Install on your single-click app, the app must handle the OAuth flow before moving on to the next step of establishing a connection with the Tax Provider API. The Apps Guide provides an overview of the OAuth flow.

When handling the OAuth flow, make sure your app requests read and write permissions on the Information and Settings API scopes. We also recommend storing the client_id and access_token that you receive. Both are required when you establish a connection with the Tax Provider API.

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 have shared your tax provider details 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.
You have built a draft app that handles the OAuth flow during app installation.
During the OAuth flow, the app requests that the merchant authorize read and write permissions on the Information and Settings API scopes.
During the OAuth flow, you received and stored the client_id and access_token.

For context, the Tax Provider API Connection endpoints 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.

We recommend calling the Update 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.

Configure tax provider settings in the control panel

After you install your app and send basic authentication credentials through the Update Connection request, 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.

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.

If you support document submission, the merchant can choose to select the Submit Order Data checkbox. This allows merchants to submit tax documents for supported transactions on their store.

Tax estimation

When tax estimates are requested

After the merchant enables your app in the control panel, your app is ready to respond to tax estimate requests sent by BigCommerce.

Tax estimates will be requested, depending on the BigCommerce store's settings, multiple times during a standard BigCommerce checkout flow.

After selecting a shipping method when using the Estimate Shipping & Tax functionality on the cart page
After specifying a shipping address during a checkout
After specifying a billing address during a checkout

Estimate requests are not expected after the following events.

While browsing a store's home page, product catalog or product pages.
On the cart page prior to a shopper selecting a shipping method using the Estimate Shipping & Tax functionality.
On the checkout page prior to specifying a shipping address.
On the checkout page, when toggling any option related to using the shopper's shipping address as their billing address.

Estimate calls will also be made in the control panel when using flows like the following:

Line-item refund flows
Test connection functionality when merchants navigate to Settings > Setup > Tax > TaxProviderName in the control panel

Tax estimate requests sent by BigCommerce may not always contain complete data as these requests will be fired at different stages of the shopper checkout. For example, the Estimate Shipping & Tax functionality on the cart page does not provide any billing address data, but the tax provider will still be expected to return a valid tax estimate.

Responding to tax estimate requests

BigCommerce sends requests for tax estimates on product item, shipping, and handling prices. The tax estimates that you send back must include total amounts and amounts broken down by tax rates. This is required because merchants can specify whether they want to show taxes in carts, checkouts, orders and invoices as one summarized line item or broken down by tax rate.

View the Estimate Taxes API reference.

Performance

Merchants expect fast tax estimate responses to facilitate a streamlined checkout experience for their shoppers. Hence performance is an essential consideration for a tax provider.

To protect the shopper checkout experience from overly slow tax responses, tax estimate requests will time out after a set period of time. The default timeout threshold of four seconds is intended to support a wide variety of use cases (e.g., large tax estimate requests).

You may request a lower timeout threshold to provide a better service to merchants.

Handling additional inputs

The Tax Provider API's request specification includes all necessary inputs for a standard tax estimation. If your solution needs extra inputs beyond what the request model, ensure this data is readily accessible on your system.

Avoid synchronous calls to external systems when preparing your tax estimate response. We recommend you keep a copy of external data on your system and update it asynchronously through background jobs or queues as required (e.g., subscribing to BigCommerce webhooks (opens in a new tab)).

Using Tax Properties to enhance the initial Tax Provider API request can help you avoid looking up additional tax estimate inputs on external systems.

Document submission

Document submission enables you to persist a tax quote request, replace it with another one, or invalidate it if necessary.

Supporting document submission is optional. If you want to support this functionality, you must share document submission URLs with BigCommerce when sharing provider details.

If your tax provider supports document submission, merchants can enable this feature by navigating to Settings > Setup > Tax > TaxProviderName in the control panel and checking the Submit Order Data checkbox.

View the Commit Tax Quote API reference.

Testing

Before testing your tax provider, your store needs the following configured in the control panel:

The shipping origin address, found by navigating to Settings > Setup > Shipping, is configured. This value is included in tax estimate requests
The tax provider, found by navigating to Settings > Setup > Tax > TaxProviderName, is enabled in the relevant countries or subdivisions
If document submission is supported, navigate to Settings > Setup > Tax > TaxProviderName and ensure the Submit Order Data checkbox is checked

To test the tax provider connection, navigate to Settings > Setup > Tax > TaxProviderName in the control panel and click Test Connection. This function will trigger a request to the tax provider's estimate URL for a sample tax estimate. If the connection or response is unsuccessful, merchants can navigate to Settings > Advanced > Store logs in the control panel to view the error and its description to help triage the issue.

Support

For anything related to the BigCommerce app, please raise a ticket using your BigCommerce dev tools portal (opens in a new tab).

Refer to our Tax Provider API reference here for a complete API description.

For Tax Provider API related questions, or to request set up of a new tax provider configuration, email taxproviderapi@bigcommerce.com.

Related resources

Articles

Building Apps Guide

Endpoints

Did you find what you were looking for?

Shipping providers Overview