Skip to content

Commit 0c874dd

Browse files
authored
Modified section about configuring tax provider settings to streamline it for integrators (#1143)
# [TAX-2553] ## What changed? * Moved the documentation about suggesting a login flow to the "Building the App" section * Some rephrasings in the "Establishing A Connection" and the "Configure tax provider settings in the control panel" section * Added a callout in the "Configure tax provider settings in the control panel" to help guide integrators into figuring out why their tax provider is not visible. We've experienced some friction with integrators losing the plot on how to have their provider appear on the control panel. Hopefully modifying this section will make it more obvious. ## Release notes draft * Added a callout in the "Configure tax provider settings in the control panel" to help integrators figure out why their tax provider is not visible on the control panel. [TAX-2553]: https://bigcommercecloud.atlassian.net/browse/TAX-2553?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
1 parent 441540e commit 0c874dd

File tree

1 file changed

+13
-7
lines changed

1 file changed

+13
-7
lines changed

docs/integrations/tax.mdx

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,10 @@ You must build a BigCommerce [single-click app](/docs/integrations/apps/guide/ty
7878

7979
Review our [introduction to building apps](/docs/integrations/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.
8080

81+
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](/docs/integrations/apps/guide/ui). An account login flow lets you capture basic authentication credentials from merchants.
82+
83+
We also recommend that you [establish a connection](#establishing-a-connection) 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.
84+
8185
Make sure to also review our [app development best practices](/docs/integrations/apps/guide/best-practices) for some tips.
8286

8387
<Callout type="info">
@@ -98,25 +102,27 @@ When handling the OAuth flow, make sure your app requests read and write permiss
98102

99103
## Establishing a connection
100104

101-
You will be ready to set up a connection with the Tax Provider API when all of the following are true:
105+
You will be ready to set up a connection with the Tax Provider API when all the following are true:
102106

103107
* You have [shared your tax provider details](#sharing-provider-details-with-bigcommerce) 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.
104108
* BigCommerce has shared the `provider_id` of the tax provider configuration with you through email after you [shared your tax provider details](#sharing-provider-details-with-bigcommerce).
105109
* You have [built a draft app](#building-the-app) that handles the OAuth flow during app installation.
106110
* During the [OAuth flow](#installing-the-app), the app requests that the merchant authorize read and write permissions on the Information and Settings API scopes.
107111
* During the [OAuth flow](#installing-the-app), you received and stored the `client_id` and `access_token`.
108112

109-
For context, the [Tax Provider API Connection endpoints](/docs/rest-contracts/tax-app-connection) 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.
110-
111-
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](/docs/integrations/apps/guide/ui).
113+
To establish a connection, you **must** call the [Update Connection](/docs/rest-contracts/tax-app-connection#update-a-connection) Tax Connection endpoint to establish a connection.
112114

113-
We recommend calling the [Update Connection](/docs/rest-contracts/tax-app-connection#update-a-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.
115+
The [Tax Provider API Connection endpoints](/docs/rest-contracts/tax-app-connection) 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.
114116

115117
## Configure tax provider settings in the control panel
116118

117-
After you install your app and send basic authentication credentials through the [Update Connection](/docs/rest-contracts/tax-app-connection#update-a-connection) request, merchants can adjust their tax provider settings to activate supported functions on their store.
119+
After you've established a connection, merchants can adjust their tax provider settings to activate supported functions on their store.
118120

119-
Merchants can adjust these settings by navigating to **Settings > Setup > Tax > _TaxProviderName_** in the control panel.
121+
Merchants can adjust these settings by navigating to **Settings > Setup > Tax > _TaxProviderName_** in the control panel.
122+
123+
<Callout type="info">
124+
Is your tax provider not visible in the control panel? Ensure that you have sent the update connection request as described in the [establishing a connection](#establishing-a-connection) section.
125+
</Callout>
120126

121127
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.
122128

0 commit comments

Comments
 (0)