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.

Multi-tenant tax providers can publish their BigCommerce app so that it's discoverable by anyone or publish their app as unlisted so it can only be installed using a URL. Furthermore, tax solutions that have been built in-house or for specific merchants by digital agencies are also supported as private instances and will only work on the specified stores.

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.

⁺ 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.

Sandbox tax provider configuration

Sandbox tax provider configurations are nested within your production tax provider configuration, as such tax providers requiring a sandbox tax provider configuration should also provide details for their production tax provider configuration.

Additionally, when providing the details for a sandbox tax provider configuration, it's unnecessary to specify the below properties because they are inherited from the primary production tax provider configuration (all other properties are still required):

• Merchant support email
• Merchant support URL
• Tax provider visibility
• Platform availability, i.e. all stores or only specified store hashes
• Supported / unsupported countries

Building the app

Tax providers must build a BigCommerce single-click app to utilize the Tax Provider API to provide tax estimates and submit tax documents. A BigCommerce single-click app provides many benefits. For example, it enables tax providers to promote their solution in the BigCommerce App Marketplace, ask for merchant authorization of API scopes during app install, and 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.

Installing the app

When the merchant clicks Install on a tax provider's single-click app, it's essential that the app successfully 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, tax providers must ensure their app is requesting read and write permissions on the Information and Settings API scopes. Additionally, the tax provider should store the client_id and access_token that are received. Both are required later when establishing a connection with the Tax Provider API.

Establishing a connection

A tax provider is ready to establish a connection with the Tax Provider API when all of the following are true:

• Tax provider has shared their 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 (see Sharing provider details with BigCommerce).
• BigCommerce has shared the provider_id of the tax provider configuration with the tax provider through email (see Sharing provider details with BigCommerce).
• Tax provider has built a draft app that successfully handles the OAuth flow during app installation (see Building the app).
• During the OAuth flow the app requested the merchant to authorize read and write permissions on the Information and Settings API scopes (see Installing the app).
• During the OAuth flow the client_id and access_token was received and stored by the tax provider (see Installing the app).

For context, the Tax Provider API Connection endpoints provide an added layer of security for tax providers. They set basic authentication credentials for the tax provider and these basic credentials are used to authenticate each API request to the tax provider from the associated store.

If the tax provider supports all eligible stores, then they may choose to provide an account registration flow in their app iFrame in order to capture these basic authentication credentials from merchants. Learn more about designing the app UI here.

If the tax provider is a private instance, then they may choose to provide the basic authentication credentials themselves.

In either case, the Update Connection endpoint should be called after the tax provider's app has been successfully installed. Tax providers will need to include store_hash, provider_id, and X-Auth-Token(access_token) values.

We recommend calling the Update Connection endpoint immediately after the app has been successfully installed, otherwise your tax provider will not be displayed when merchants navigate to the Settings > Setup > Tax page in the control panel.

The Get a Connection request may be used at any time to retrieve the connection status of the specified tax provider in the context of a store.

Enabling tax providers in the control panel

Once you have successfully installed the tax provider's app and provided basic authentication credentials through the Update a Connection request, merchants can enable the tax provider on all test stores supplied by the tax provider in sharing provider details with BigCommerce.

To enable the tax provider, merchants must navigate to Settings > Setup > Tax in the control panel and click Enable next to the associated tax provider.

If document submission is supported, navigate to the provider's settings menu, found at Settings > Setup > Tax > TaxProviderName in the control panel and ensure the Submit Order Data checkbox is checked.

Tax estimation

When tax estimates are requested

Once the tax provider app has been enabled in the control panel, the tax provider 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 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

Responding to tax estimate requests

When responding to tax estimate requests sent by BigCommerce, tax providers are required to include aggregates and breakdowns of sales tax amounts and rates for product item prices, shipping and handling prices. This is because when navigating to the Settings > Setup > Tax > Tax Settings page in the control panel, merchants have the ability to specify whether they would like to show taxes in cart, checkout, orders and invoice As one summarized line item or Broken down by tax rate.

View the Estimate Taxes API reference.

Document submission

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

Supporting document submission is optional. However, tax providers wishing to support this functionality must share document submission URLs with BigCommerce when sharing provider details with BigCommerce.

If document submission is supported, navigate to Settings > Setup > Tax > TaxProviderName in the control panel and ensure the Submit Order Data checkbox is checked.

View the Commit Tax Quote API reference.

Testing

Prior to testing a tax provider, the merchant or partner test store should have the following configured in the control panel:

• The store default country, found by navigating to Settings > Setup > Store profile, is set to a country that is supported by the tax provider
• 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, is enabled
• 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 selection will trigger a sample tax estimate request to be sent to the estimate URL provided by the tax provider. If the connection is unsuccessful, merchants can navigate to Settings > Advanced > Store logs in the control panel to view the error and its description to assist with triaging 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

• Tax Provider API Reference
• Get a Tax Provider Connection
• Delete a Tax Provider Connection
• Update a Tax Provider Connection
• Tax Classes