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 | Contact email that BigCommerce uses to send merchant support requests or discuss integration improvements with you. | support@sampletax.example.com | |
| 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 1 | Required | URL | URL BigCommerce should use for Tax Provider API estimate requests. | https://sampletax.example.com/tax/estimate |
| Commit URL 1,2 | Optional | URL | URL BigCommerce should use for Tax Provider API quote requests. | https://sampletax.example.com/doc/commit |
| Adjust URL 1,2 | Optional | URL | URL BigCommerce should use for Tax Provider API quote requests. | https://sampletax.example.com/doc/adjust |
| Void URL 1,2 | 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/ |
1 You have the option of supporting a URL that merchants can customize. See Tax Profile. 2 URL is only called when the Submit Order Data provider setting is enabled. See Document Submission.
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.
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 (opens in a new tab).
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 with the relevant details.
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_idof 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_idandaccess_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.
Avoiding infinite loops
Several BigCommerce API endpoints will automatically invoke an estimate call to a tax provider under certain conditions (e.g. when there is not already a tax quote applied to a cart). These API endpoints must not be called by your tax provider's implementation as doing so will cause an infinite loop of requests, resulting in a memory timeout.
An infinite loop is able to be identified by observing any duplicated requests being received by a tax provider within a very short time frame.
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
Endpoints
- Tax Provider API Reference
- Get a Tax Provider Connection
- Delete a Tax Provider Connection
- Update a Tax Provider Connection
- Tax Classes