openapi: 3.1.0
info:
  title: 'Integrations: Tax Provider Connection'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/tax/providers/{provider_id}/connection:
    get:
      operationId: getTaxProviderConnection
      summary: Get Connection Status
      description: |
        Retrieve the connection status of the specified tax provider in the context of a store.

        > #### Note
        > * Requires **read** permissions on the **Information and Settings** scope.
      tags:
        - taxProviderConnection
      parameters:
        - name: provider_id
          in: path
          description: >-
            The Tax Providerʼs `provider_id` provided by BigCommerce after the provider [shares their provider
            details](/developer/docs/integrations/tax-providers#sharing-provider-details-with-bigcommerce).
          required: true
          schema:
            type: string
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Information & Settings | modify | `store_v2_information` |

            |  Information & Settings | read-only | `store_v2_information_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-connection'
        '404':
          description: Provider does not exist
          content:
            application/json:
              schema:
                description: Any type
    put:
      operationId: updateTaxProviderConnection
      summary: Update Connection
      description: >-
        Set authentication information associated with a merchant's account on the tax provider's infrastructure:

        - [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
        (developer.mozilla.org) credentials

        - (optional) Tax provider profile used in customized endpoint urls for tax provider calls. This is only
        available for tax providers that support this feature.


        The configured `username`, `password`, and `profile` (if available) are used to authenticate each API request to
        the Tax Provider from the associated store. 

        The tax provider's `profile` will be included in the URL for [Tax Provider
        API](/developer/api-reference/rest/integrations/tax-provider) endpoints. 


        > #### Note

        > * This operation will be logged in [Store Logs](https://support.bigcommerce.com/s/article/Using-Store-Logs)
        under **Staff Actions**.

        > * Requires **write** permissions on the **Information and Settings**
        [scope](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).
      tags:
        - taxProviderConnection
      parameters:
        - name: provider_id
          in: path
          description: >-
            The Tax Providerʼs `provider_id` provided by BigCommerce after the provider [shares their provider
            details](/developer/docs/integrations/tax-providers#sharing-provider-details-with-bigcommerce).
          required: true
          schema:
            type: string
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Information & Settings | modify | `store_v2_information` |

            |  Information & Settings | read-only | `store_v2_information_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-connection'
        '404':
          description: Provider does not exist
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Unprocessable Entity, will include a specific error message referencing the issue.
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: >-
          Basic authentication information, associated with a merchant account on the third-party tax providerʼs
          infrastructure.
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: >-
                    Public identifying information representing a unique account on the tax provider's infrastructure.
                    Should not contain any personal identifying information (e.g. a personal email address).
                password:
                  type: string
                profile:
                  type: string
                  description: >-
                    Optional field that allows merchants to customize Tax Provider API endpoint URLs. Only available for
                    supporting providers.
    delete:
      operationId: deleteTaxProviderConnection
      summary: Delete Connection
      description: >
        Remove any previously set basic connection credentials for the specified provider. If the specified provider is
        the active tax provider on the store, the store's active tax provider will be reset to BigCommerce Manual Tax.
        It is suggested to call this endpoint during a single-click app [uninstall
        callback](/developer/docs/integrations/apps/guide/handling-callbacks#uninstall-callback).


        > #### Note

        > * This operation will be logged in [Store Logs](https://support.bigcommerce.com/s/article/Using-Store-Logs)
        under **Staff Actions**.

        > * Requires **write** permissions on the **Information and Settings**
        [scope](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).
      tags:
        - taxProviderConnection
      parameters:
        - name: provider_id
          in: path
          description: >-
            The Tax Providerʼs `provider_id` provided by BigCommerce after the provider [shares their provider
            details](/developer/docs/integrations/tax-providers#sharing-provider-details-with-bigcommerce).
          required: true
          schema:
            type: string
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Information & Settings | modify | `store_v2_information` |

            |  Information & Settings | read-only | `store_v2_information_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-connection'
        '404':
          description: Provider or provider connection does not exist
          content:
            application/json:
              schema:
                description: Any type
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    ResponseConnectionDataTarget:
      type: object
      properties:
        country_codes:
          type: array
          items:
            type: string
          description: The list of country codes where the tax provider connection is active. ISO 3166-1 alpha-2.
        subdivision_codes:
          type: array
          items:
            type: string
          description: The list of subdivision codes where the tax provider connection is active. ISO 3166-2.
      description: The countries and subdivisions in which this tax provider connection is active.
      title: ResponseConnectionDataTarget
    ResponseConnectionData:
      type: object
      properties:
        username:
          type: string
          description: >-
            Identifies a unique account on the external tax provider infrastructure. May be used to reconcile the two
            platforms.
        configured:
          type: boolean
          description: >-
            Describes whether the stored credentials are considered complete and configured, ready to be used for Tax
            Provider API requests.


            Merchants may enable any **configured** tax provider for storefront tax quotation.
        profile:
          type: string
          description: >-
            When supported by the tax provider configuration, the profile value is used to generate a unique Tax
            Provider API request URL for this connection.


            If not set, this value will be blank. Please ensure merchants set this value if using dynamic request URLs,
            blank values cannot generate valid URLs.
        target:
          $ref: '#/components/schemas/ResponseConnectionDataTarget'
          description: The countries and subdivisions in which this tax provider connection is active.
      title: ResponseConnectionData
    response-connection:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ResponseConnectionData'
      title: response-connection
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--------|:-----------|:----------|

        |  Information & Settings | modify | `store_v2_information` |

        |  Information & Settings | read-only | `store_v2_information_read_only` |


        ### Authentication header


        | Header | Argument | Description |

        |:-------|:---------|:------------|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to
        API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example
        Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API
        Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status
        Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
