docs(tax): TAX-1750 add docs for /v3/tax/customers endpoint

reference/tax_customers.v3.yml

@@ -0,0 +1,187 @@
+openapi: '3.0.0'
+info:
+  title: Tax Customers
+  description: Configure customer tax data for use in tax calculations.
+  termsOfService: 'https://www.bigcommerce.com/terms'
+  contact:
+    name: BigCommerce
+    url: 'https://www.bigcommerce.com'
+    email: [email protected]
+  version: ''
+security:
+  - X-Auth-Token: []
+tags:
+  - name: Tax Customers
+servers:
+  - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3'
+    variables:
+      store_hash:
+        default: store_hash
+        description: Permanent ID of the BigCommerce store.
+    description: BigCommerce API Gateway
+paths:
+    "/tax/customers":
+      parameters:
+        - $ref: '#/components/parameters/ContentType'
+      get:
+        tags:
+          - Tax Customers
+        summary: Get Tax Customers
+        description: Retrieves a list of customer tax data.
+        operationId: getTaxCustomers
+        parameters:
+          - $ref: "#/components/parameters/customer_idin"
+        responses:
+          "200":
+            description: OK
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    data:
+                      type: array
+                      items:
+                        $ref: "#/components/schemas/TaxCustomer"
+                    meta:
+                      $ref: "#/components/schemas/MetaOpen"
+          "400":
+            description: Request parameters invalid
+      put:
+        tags:
+          - Tax Customers
+        summary: Update Tax Customers
+        description: |-
+          Update the tax data associated with one or more customers.
+          This operation will be additive to any values already associated with the customer, overwriting any existing values.
+        operationId: updateTaxCustomers
+        parameters:
+          - $ref: '#/components/parameters/ContentType'
+        requestBody:
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/TaxCustomer"
+              examples:
+                Example:
+                  value:
+                    - customer_id: 157
+                      tax_properties:
+                        A-123456789: "26"
+                        B-6731789: "200"
+          required: true
+        responses:
+          "200":
+            description: OK
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    data:
+                      type: array
+                      items:
+                        $ref: "#/components/schemas/TaxCustomer"
+                    meta:
+                      $ref: "#/components/schemas/MetaOpen"
+          "422":
+            description: The request body does not meet specifications.
+      delete:
+        tags:
+          - Tax Customers
+        summary: Delete Tax Customers
+        description: Delete tax data that is associated with one or more customers.
+        operationId: deleteTaxCustomers
+        parameters:
+          - $ref: "#/components/parameters/customer_idin"
+        responses:
+          "204":
+            description: No Content
+          "400":
+            description: Request parameters invalid
+components:
+  parameters:
+    Accept:
+      name: Accept
+      in: header
+      required: true
+      description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.'
+      schema:
+        type: string
+        default: 'application/json'
+    ContentType:
+      name: Content-Type
+      in: header
+      required: true
+      description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.'
+      schema:
+        type: string
+        default: 'application/json'
+    customer_idin:
+      name: customer_id:in
+      in: query
+      required: false
+      description: ID of customer. To target multiple customers, provide a comma-separated list of IDs such as `12,34,56`.
+      style: form
+      explode: false
+      schema:
+        type: array
+        items:
+          type: integer
+  securitySchemes:
+    X-Auth-Token:
+      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](/docs/start/authentication/api-accounts). |
+
+        ### Further reading
+
+        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).
+
+        For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).
+
+        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).
+      type: apiKey
+      in: header
+  schemas:
+    TaxCustomer:
+      type: object
+      description: Represents a customer and their associated tax-related attributes.
+      properties:
+        customer_id:
+          type: integer
+          description: A reference to the customer.
+          example: 157
+        tax_properties:
+          type: object
+          properties: { }
+          additionalProperties: true
+          description: |-
+            A simple key-value pairing.
+            The tax property must be defined to associate a value.
+            These values will be sent to the active tax provider during Tax Provider API operations whenever the associated customer is included in the operation.
+          example:
+            A-123456789: "26"
+            B-6731789: "200"
+      required:
+        - customer_id
+        - tax_properties
+    MetaOpen:
+      title: Response meta
+      type: object
+      properties: { }
+      additionalProperties: true
+      description: Response metadata.