TAX-1968 Update tax provider docs #2127
Conversation
| @@ -9,8 +9,7 @@ The [Tax Provider API](/docs/rest-contracts/tax) allows you to provide business- | |||
|
|
|||
| The [Tax Provider API](/docs/rest-contracts/tax) works in conjunction with a BigCommerce app, so you will need to [build an app](/docs/integrations/apps) that integrates the [Tax Provider API](/docs/rest-contracts/tax). | |||
|
|
|||
| 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. | |||
|
|
|||
| 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. | |||
There was a problem hiding this comment.
Removed nuances around "multi-tenant" and private instances.
We're looking to simplify our on-going maintenance here and have adopted an approach that speaks to simplified options from an app listing perspective (either listed or unlisted - end of story).
| | 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` | | ||
| | Tax provider type | Required | Production, Sandbox | Hierarchy of tax provider configurations, Production is primary and Sandboxes are secondary, see [sandbox tax provider configuration](#sandbox-tax-provider-configuration) for more information. | `Production` | | ||
| | Partner support email | Required | Email | Used by BigCommerce to contact tax provider, in the case we need to forward a merchant support request. | `[email protected]` | | ||
| | Links displayed in the control panel | Optional | URL, Title, Description | Link(s) displayed to merchants when they navigate to **Settings > Setup > Tax > _TaxProviderName_**. One or multiple links supported. | `support.sampletax.com`, `Sample Tax Support`, `The Sample Tax Support website.` | |
There was a problem hiding this comment.
We don't offer this feature any longer and, indeed, have removed it from our UI entirely. We expect apps to offer their own interfaces (and support links), as is warranted.
| | Partner support email | Required | Email | Used by BigCommerce to contact tax provider, in the case we need to forward a merchant support request. | `[email protected]` | | ||
| | Links displayed in the control panel | Optional | URL, Title, Description | Link(s) displayed to merchants when they navigate to **Settings > Setup > Tax > _TaxProviderName_**. One or multiple links supported. | `support.sampletax.com`, `Sample Tax Support`, `The Sample Tax Support website.` | | ||
| | Transaction type | Required | Production, Test | Whether your tax provider will be handling production traffic or conducting test transactions. | `Production` | | ||
| | Partner support email | Required | Email | Used by BigCommerce to contact tax provider, in the case we need to forward a merchant support request or discuss integration improvements. | `[email protected]` | |
There was a problem hiding this comment.
We had one tax partner recently confused around why we needed an email here, given it was only for their own usage - hence we're clarifying that it's not just to communicate between a tax partner and a merchant but also BigCommerce and the tax partner.
| | 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` | | ||
| | Tax provider type | Required | Production, Sandbox | Hierarchy of tax provider configurations, Production is primary and Sandboxes are secondary, see [sandbox tax provider configuration](#sandbox-tax-provider-configuration) for more information. | `Production` | |
There was a problem hiding this comment.
We often get confused tax partners wondering what we mean by "Sandbox" and hence we've replaced this concept with Transaction type below - which is more inline with what we care about and uses more common, clearer language.
| **Coverage** | | | | | | ||
| | Tax provider visibility | Required | Show, Hide | Tells us if tax provider should be displayed to merchants in the control panel before the tax providers app is installed on the associated store. | `Show` | |
There was a problem hiding this comment.
This isn't something we allow flexibility on anymore (to simplify our maintenance) and speaks to the Platform availability option. Previously we'd often get confused tax partners on this option - no longer!
| | Platform availability | Required | All stores, Private instance | Tells us if tax provider should work on all stores or only on the stores where a store hash has been provided. | `All stores` | | ||
| | Supported store(s) | Required if platform availability is **private instance** | Store hashes | As a private instance, tax provider configuration will only work on store hashes provided. | `dwvjntfqv,epq54yymgq` | | ||
| | Supported / unsupported countries | Required | ISO 3166-1 alpha-2 | Comma separated ISO 3166-1 alpha-2 country codes for supported countries. | `US,CA,GB,FR,AU,NZ` | | ||
| | 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` | |
There was a problem hiding this comment.
It's quite rare for us to engage with a tax provider that is seeking to offer availability to all stores - hence we've flipped around the language a little here, and also changed the language away from specific store hashes.
| | Supported store(s) | Required if platform availability is **private instance** | Store hashes | As a private instance, tax provider configuration will only work on store hashes provided. | `dwvjntfqv,epq54yymgq` | | ||
| | Supported / unsupported countries | Required | ISO 3166-1 alpha-2 | Comma separated ISO 3166-1 alpha-2 country codes for supported countries. | `US,CA,GB,FR,AU,NZ` | | ||
| | 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 may also select to support to all countries, or all countries except a list of unsupported countries. | `US,CA,GB,FR,AU,NZ` | |
There was a problem hiding this comment.
I've attempted to clarify this a little more from the perspective of "all countries" and "unsupported countries", not just focusing on the supported countries.
| **Coverage** | | | | | | ||
| | Tax provider visibility | Required | Show, Hide | Tells us if tax provider should be displayed to merchants in the control panel before the tax providers app is installed on the associated store. | `Show` | | ||
| | Platform availability | Required | All stores, Private instance | Tells us if tax provider should work on all stores or only on the stores where a store hash has been provided. | `All stores` | | ||
| | Supported store(s) | Required if platform availability is **private instance** | Store hashes | As a private instance, tax provider configuration will only work on store hashes provided. | `dwvjntfqv,epq54yymgq` | |
There was a problem hiding this comment.
This isn't a feature we offer any more. This is handled by an unlisted app with a limited availability tax provider. The result is that the tax provider manages who has access directly (e.g. if someone gets a hold of the direct link it's up to them to authenticate the account, which is nothing to do with BigCommerce).
In particular this means our maintenance burden is significantly reduced since we're not constantly updating store hashes.
|
Whoops, wrong repo! |
TAX-1968
What changed?