From 8ed518cdde9766f360effe7c9da2688b875d1947 Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Tue, 31 Mar 2026 13:41:16 +1100
Subject: [PATCH 01/18] doc(tax): TAX-2677 add v3 tax class batch endpoints

---
 reference/tax_classes.v3.yaml | 358 ++++++++++++++++++++++++++++++++++
 1 file changed, 358 insertions(+)
 create mode 100644 reference/tax_classes.v3.yaml

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
new file mode 100644
index 000000000..be9835d06
--- /dev/null
+++ b/reference/tax_classes.v3.yaml
@@ -0,0 +1,358 @@
+openapi: 3.0.3
+info:
+  title: BigCommerce Internal API — Tax classes (batch Tax API)
+  description: |
+    OpenAPI for batch operations implemented by `Bigcommerce\Tax\Api\V1\Classes\ClassesController`
+    (`batchPostAction`, `batchPutAction`, `batchDeleteAction`) via `TaxBatchResourceController`.
+
+    **Route:** `tax/class` → controller `Bigcommerce\Tax\Api\V1\Classes\ClassesController`
+    (`config/routes/V1/api_internal.php`). Full path is typically `/v1/tax/class` on the internal API host.
+
+    **Auth:** `admin` and `hawk` (hawk config includes `api_proxy`).
+
+    **Write access:** `TaxResourceController::beforeAction` enforces `Manage_Tax` for non-read-only actions and CSRF where applicable.
+
+    **Responses:** Successful JSON bodies use the internal API envelope from `ResourceController::handleResponse`:
+    `{ "data": ..., "meta": ... }`. Collection payloads from Fractal omit the inner `meta` key (it is hoisted to the outer `meta`).
+    Batch POST/PUT return an array of tax class resources under `data` (see `ClassTransformer`).
+
+    **DELETE:** `batchDeleteAction` uses `ClassesServiceRequest` built from query parameters; the path segment `:id`
+    is ignored (`TaxBatchResourceController::deleteAction`). Deletes require `id:in` filter with the `in` operator.
+  version: 1.0.0
+
+servers:
+  - url: https://internalapi-{store_id}.{host}/v1
+    variables:
+      store_id:
+        default: '123456'
+      host:
+        default: mybigcommerce.com
+
+tags:
+  - name: Tax — Class (batch)
+    description: V1 Tax API tax class batch CRUD (internal).
+
+paths:
+  /tax/class:
+    post:
+      tags: [Tax — Class (batch)]
+      summary: Batch create tax classes
+      description: |
+        `batchPostAction`: JSON array of create items. Max **50** items per request (`TaxBatchResourceValidator`).
+        Each `name` must be **1–100** characters, non-empty, and cannot contain angle brackets,
+        braces, backticks, parentheses, semicolon, or pipe (see `TaxBatchResourceValidator::INVALID_DISPLAY_CHARACTERS`).
+        Names must be **unique case-insensitively** within the batch.
+
+        Conflicting names against existing data produce **409** (`DuplicateTaxClassNamesException` → `InternalApiException::create409`).
+      operationId: taxClassBatchPost
+      security:
+        - adminAuth: []
+        - hawkAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TaxClassCreateBatch'
+            example:
+              - name: Class One
+              - name: Class Two
+      responses:
+        '200':
+          description: Created classes returned as a collection (default response status unless overridden upstream).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TaxClassCollectionEnvelope'
+        '400':
+          description: Bad request (e.g. invalid input via `InvalidInputException`, default status 400).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '409':
+          description: Duplicate tax class names (conflict).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '413':
+          description: Batch exceeds limit (50 items).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '422':
+          description: |
+            Unprocessable entity — empty body, non-array batch shape, duplicate `name` or `id` in batch per validator,
+            or other `InternalApiException::create422` cases.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '403':
+          description: Authentication or `Manage_Tax` denied.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '500':
+          description: Unexpected error (wrapped by internal API factory in production).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+
+    put:
+      tags: [Tax — Class (batch)]
+      summary: Batch update tax classes
+      description: |
+        `batchPutAction` (collection **PUT** only — `TaxBatchResourceController` allows PUT when `isCollection` is true).
+
+        Request body: non-empty array, max **50** items. Each item must include:
+        - `id`: positive integer (**unique** across the batch)
+        - At least one non-`id` field; schema allows `name` (optional in Respect `keySet`, but **required in practice** so the item is not id-only).
+
+        `name` when present: same length and character rules as create; **unique case-insensitively** in the batch.
+
+        `ClassesNotFoundException` from `TaxClassService::update` → **400** (`InternalApiException::create400`).
+        Duplicate names → **409** (same as create).
+      operationId: taxClassBatchPut
+      security:
+        - adminAuth: []
+        - hawkAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TaxClassUpdateBatch'
+            example:
+              - id: 1
+                name: Renamed One
+              - id: 2
+                name: Renamed Two
+      responses:
+        '200':
+          description: Updated classes returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TaxClassCollectionEnvelope'
+        '400':
+          description: One or more classes not found (update).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '409':
+          description: Duplicate tax class names.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '413':
+          description: Batch exceeds 50 ids/items.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '422':
+          description: Validation error (format, duplicate `id` in batch, invalid id values, id-only update payload, etc.).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '403':
+          description: Authentication or permission denied.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '500':
+          description: Server error.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+
+    delete:
+      tags: [Tax — Class (batch)]
+      summary: Batch delete tax classes
+      description: |
+        `deleteAction` → `batchDeleteAction`. Request must include filter **`id:in`** with comma-separated positive integer ids
+        (`validateBatchRequestUsesSupportedOperator` requires operator `in`; `getIdList()` reads the `in` criterion).
+
+        Max **50** ids (`validateBatchRequestLimit`). Empty id list → **404** (`validateNonEmptyQueryFilter`).
+        Invalid id values → **422**. `ClassesNotFoundException` on delete → **400**.
+
+        Success returns **204 No Content** (`RESULT_NO_CONTENT`).
+        The `:id` path parameter on singular delete routes is **not used** for the id list.
+      operationId: taxClassBatchDelete
+      security:
+        - adminAuth: []
+        - hawkAuth: []
+      parameters:
+        - name: id:in
+          in: query
+          required: true
+          description: |
+            Internal filter parameter: field `id`, operator `in`, comma-separated ids (e.g. `1,2,3`).
+            Must use the `in` operator; other filter operators are rejected with **400**.
+          schema:
+            type: string
+          example: '101,102,103'
+      responses:
+        '204':
+          description: All listed classes deleted successfully.
+        '400':
+          description: Delete failed (e.g. class not found).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '404':
+          description: Missing or empty `id:in` filter.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '413':
+          description: More than 50 ids.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '422':
+          description: Invalid id values in filter.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '403':
+          description: Authentication or permission denied.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+        '500':
+          description: Server error.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemResponseEnvelope'
+
+components:
+  securitySchemes:
+    adminAuth:
+      type: apiKey
+      in: header
+      name: X-Auth-Client
+      description: Internal API admin authentication (see platform docs).
+    hawkAuth:
+      type: apiKey
+      in: header
+      name: X-Auth-Client
+      description: Hawk-authenticated clients (e.g. API proxy).
+
+  schemas:
+    TaxClassCreateBatch:
+      type: array
+      minItems: 1
+      maxItems: 50
+      items:
+        type: object
+        required:
+          - name
+        properties:
+          name:
+            type: string
+            minLength: 1
+            maxLength: 100
+            description: >
+              Must not contain < > { } ` ( ) ; | (see TaxBatchResourceValidator::INVALID_DISPLAY_CHARACTERS).
+        additionalProperties: false
+
+    TaxClassUpdateBatch:
+      type: array
+      minItems: 1
+      maxItems: 50
+      items:
+        type: object
+        required:
+          - id
+          - name
+        description: |
+          Code allows optional `name` in Respect rules but requires at least one non-id field; only `name` is permitted besides `id`.
+        properties:
+          id:
+            type: integer
+            minimum: 1
+          name:
+            type: string
+            minLength: 1
+            maxLength: 100
+        additionalProperties: false
+
+    TaxClassResource:
+      type: object
+      required:
+        - id
+        - name
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+          description: ISO-8601 (`DateTimeInterface::ATOM`).
+        updated_at:
+          type: string
+          format: date-time
+
+    TaxClassCollectionEnvelope:
+      type: object
+      required:
+        - data
+        - meta
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/TaxClassResource'
+        meta:
+          type: object
+          description: Fractal / serializer metadata (may be empty object).
+
+    Problem:
+      type: object
+      description: RFC 7807-style problem object (optional fields omitted when empty).
+      properties:
+        title:
+          type: string
+        status:
+          type: integer
+        type:
+          type: string
+          format: uri
+        detail:
+          type: string
+        code:
+          type: integer
+        errors:
+          type: object
+          additionalProperties: true
+
+    ProblemResponseEnvelope:
+      type: object
+      properties:
+        errors:
+          type: array
+          items:
+            $ref: '#/components/schemas/Problem'
+        meta:
+          type: object

From aa5f0b6ae9e7e298c0e707f229381c33c3c7d9d2 Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Tue, 31 Mar 2026 13:58:02 +1100
Subject: [PATCH 02/18] TAX-2677: docs(tax) - Remove internal-facing language
 from tax class batch spec

Rewrite descriptions to be public-facing: remove PHP class names, internal
route details, implementation exception references, and all uses of "internal"
as a label. Port info metadata and security scheme style from v2 spec.

Refs TAX-2677
Co-Authored-By: Claude <noreply@anthropic.com>
---
 reference/tax_classes.v3.yaml | 107 ++++++++++++++++++++--------------
 1 file changed, 64 insertions(+), 43 deletions(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index be9835d06..08af17c29 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -1,23 +1,20 @@
 openapi: 3.0.3
 info:
-  title: BigCommerce Internal API — Tax classes (batch Tax API)
+  title: Tax Classes
   description: |
-    OpenAPI for batch operations implemented by `Bigcommerce\Tax\Api\V1\Classes\ClassesController`
-    (`batchPostAction`, `batchPutAction`, `batchDeleteAction`) via `TaxBatchResourceController`.
+    Manage tax calculations applied to sales. Tax classes are used to apply different tax rates for specific types of products and orders.
 
-    **Route:** `tax/class` → controller `Bigcommerce\Tax\Api\V1\Classes\ClassesController`
-    (`config/routes/V1/api_internal.php`). Full path is typically `/v1/tax/class` on the internal API host.
+    This API exposes batch operations (`POST`, `PUT`, `DELETE`) for tax classes.
 
-    **Auth:** `admin` and `hawk` (hawk config includes `api_proxy`).
+    **Responses:** Successful JSON bodies use the envelope format:
+    `{ "data": ..., "meta": ... }`. Batch POST/PUT return an array of tax class resources under `data`.
 
-    **Write access:** `TaxResourceController::beforeAction` enforces `Manage_Tax` for non-read-only actions and CSRF where applicable.
-
-    **Responses:** Successful JSON bodies use the internal API envelope from `ResourceController::handleResponse`:
-    `{ "data": ..., "meta": ... }`. Collection payloads from Fractal omit the inner `meta` key (it is hoisted to the outer `meta`).
-    Batch POST/PUT return an array of tax class resources under `data` (see `ClassTransformer`).
-
-    **DELETE:** `batchDeleteAction` uses `ClassesServiceRequest` built from query parameters; the path segment `:id`
-    is ignored (`TaxBatchResourceController::deleteAction`). Deletes require `id:in` filter with the `in` operator.
+    **DELETE:** Deletes are filter-based using the `id:in` query parameter. The request must specify the ids to delete — there is no single-resource delete on this endpoint.
+  termsOfService: 'https://www.bigcommerce.com/terms'
+  contact:
+    name: BigCommerce
+    url: 'https://www.bigcommerce.com'
+    email: support@bigcommerce.com
   version: 1.0.0
 
 servers:
@@ -30,7 +27,7 @@ servers:
 
 tags:
   - name: Tax — Class (batch)
-    description: V1 Tax API tax class batch CRUD (internal).
+    description: Batch create, update, and delete tax classes.
 
 paths:
   /tax/class:
@@ -38,12 +35,12 @@ paths:
       tags: [Tax — Class (batch)]
       summary: Batch create tax classes
       description: |
-        `batchPostAction`: JSON array of create items. Max **50** items per request (`TaxBatchResourceValidator`).
-        Each `name` must be **1–100** characters, non-empty, and cannot contain angle brackets,
-        braces, backticks, parentheses, semicolon, or pipe (see `TaxBatchResourceValidator::INVALID_DISPLAY_CHARACTERS`).
+        Creates multiple tax classes in a single request. Max **50** items per request.
+        Each `name` must be **1–100** characters and cannot contain angle brackets,
+        braces, backticks, parentheses, semicolons, or pipes.
         Names must be **unique case-insensitively** within the batch.
 
-        Conflicting names against existing data produce **409** (`DuplicateTaxClassNamesException` → `InternalApiException::create409`).
+        Conflicting names against existing tax classes produce **409**.
       operationId: taxClassBatchPost
       security:
         - adminAuth: []
@@ -59,13 +56,13 @@ paths:
               - name: Class Two
       responses:
         '200':
-          description: Created classes returned as a collection (default response status unless overridden upstream).
+          description: Created classes returned as a collection.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/TaxClassCollectionEnvelope'
         '400':
-          description: Bad request (e.g. invalid input via `InvalidInputException`, default status 400).
+          description: Bad request (e.g. invalid input).
           content:
             application/problem+json:
               schema:
@@ -84,8 +81,7 @@ paths:
                 $ref: '#/components/schemas/ProblemResponseEnvelope'
         '422':
           description: |
-            Unprocessable entity — empty body, non-array batch shape, duplicate `name` or `id` in batch per validator,
-            or other `InternalApiException::create422` cases.
+            Unprocessable entity — empty body, non-array batch shape, or duplicate `name` or `id` within the batch.
           content:
             application/problem+json:
               schema:
@@ -97,7 +93,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ProblemResponseEnvelope'
         '500':
-          description: Unexpected error (wrapped by internal API factory in production).
+          description: Unexpected server error.
           content:
             application/problem+json:
               schema:
@@ -107,16 +103,14 @@ paths:
       tags: [Tax — Class (batch)]
       summary: Batch update tax classes
       description: |
-        `batchPutAction` (collection **PUT** only — `TaxBatchResourceController` allows PUT when `isCollection` is true).
+        Updates multiple tax classes in a single request. Collection PUT only.
 
         Request body: non-empty array, max **50** items. Each item must include:
         - `id`: positive integer (**unique** across the batch)
-        - At least one non-`id` field; schema allows `name` (optional in Respect `keySet`, but **required in practice** so the item is not id-only).
+        - `name`: same length and character rules as create; **unique case-insensitively** in the batch.
 
-        `name` when present: same length and character rules as create; **unique case-insensitively** in the batch.
-
-        `ClassesNotFoundException` from `TaxClassService::update` → **400** (`InternalApiException::create400`).
-        Duplicate names → **409** (same as create).
+        Returns **400** if one or more specified classes are not found.
+        Duplicate names → **409**.
       operationId: taxClassBatchPut
       security:
         - adminAuth: []
@@ -180,14 +174,13 @@ paths:
       tags: [Tax — Class (batch)]
       summary: Batch delete tax classes
       description: |
-        `deleteAction` → `batchDeleteAction`. Request must include filter **`id:in`** with comma-separated positive integer ids
-        (`validateBatchRequestUsesSupportedOperator` requires operator `in`; `getIdList()` reads the `in` criterion).
+        Deletes multiple tax classes in a single request. The request must include the **`id:in`** query parameter
+        with a comma-separated list of positive integer ids.
 
-        Max **50** ids (`validateBatchRequestLimit`). Empty id list → **404** (`validateNonEmptyQueryFilter`).
-        Invalid id values → **422**. `ClassesNotFoundException` on delete → **400**.
+        Max **50** ids. Empty id list → **404**. Invalid id values → **422**.
+        Returns **400** if one or more specified classes are not found.
 
-        Success returns **204 No Content** (`RESULT_NO_CONTENT`).
-        The `:id` path parameter on singular delete routes is **not used** for the id list.
+        Success returns **204 No Content**.
       operationId: taxClassBatchDelete
       security:
         - adminAuth: []
@@ -197,7 +190,7 @@ paths:
           in: query
           required: true
           description: |
-            Internal filter parameter: field `id`, operator `in`, comma-separated ids (e.g. `1,2,3`).
+            Comma-separated list of tax class ids to delete (e.g. `1,2,3`).
             Must use the `in` operator; other filter operators are rejected with **400**.
           schema:
             type: string
@@ -248,12 +241,40 @@ components:
       type: apiKey
       in: header
       name: X-Auth-Client
-      description: Internal API admin authentication (see platform docs).
+      description: |-
+        ### Required permissions
+
+        | Permission | Description |
+        |:-----------|:------------|
+        | `Manage_Tax` | Required for write operations (POST, PUT, DELETE). Read-only actions do not require this permission. |
+
+        ### Authentication header
+
+        | Header | Argument | Description |
+        |:-------|:---------|:------------|
+        | `X-Auth-Client` | `client_id` | Admin client identifier. |
+
+        ### Further reading
+
+        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).
     hawkAuth:
       type: apiKey
       in: header
       name: X-Auth-Client
-      description: Hawk-authenticated clients (e.g. API proxy).
+      description: |-
+        ### Overview
+
+        Hawk-authenticated clients authorized via the hawk configuration.
+
+        ### Required permissions
+
+        | Permission | Description |
+        |:-----------|:------------|
+        | `Manage_Tax` | Required for write operations (POST, PUT, DELETE). |
+
+        ### Further reading
+
+        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).
 
   schemas:
     TaxClassCreateBatch:
@@ -270,7 +291,7 @@ components:
             minLength: 1
             maxLength: 100
             description: >
-              Must not contain < > { } ` ( ) ; | (see TaxBatchResourceValidator::INVALID_DISPLAY_CHARACTERS).
+              Must not contain < > { } ` ( ) ; |
         additionalProperties: false
 
     TaxClassUpdateBatch:
@@ -283,7 +304,7 @@ components:
           - id
           - name
         description: |
-          Code allows optional `name` in Respect rules but requires at least one non-id field; only `name` is permitted besides `id`.
+          Each item must include `id` and at least one other field. Only `name` is permitted alongside `id`.
         properties:
           id:
             type: integer
@@ -309,7 +330,7 @@ components:
         created_at:
           type: string
           format: date-time
-          description: ISO-8601 (`DateTimeInterface::ATOM`).
+          description: ISO-8601 timestamp.
         updated_at:
           type: string
           format: date-time
@@ -326,7 +347,7 @@ components:
             $ref: '#/components/schemas/TaxClassResource'
         meta:
           type: object
-          description: Fractal / serializer metadata (may be empty object).
+          description: Response metadata (may be an empty object).
 
     Problem:
       type: object

From f6060adce4ead7de3d2564f1c3eb1e5df72cca85 Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Tue, 31 Mar 2026 14:00:09 +1100
Subject: [PATCH 03/18] TAX-2677: docs(tax) - Update server URL to public API
 gateway

Replace internal API host with standard BigCommerce API Gateway server
configuration, matching the pattern used in the v2 tax classes spec.

Refs TAX-2677
Co-Authored-By: Claude <noreply@anthropic.com>
---
 reference/tax_classes.v3.yaml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index 08af17c29..7ae17a7cf 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -18,12 +18,12 @@ info:
   version: 1.0.0
 
 servers:
-  - url: https://internalapi-{store_id}.{host}/v1
+  - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3'
     variables:
-      store_id:
-        default: '123456'
-      host:
-        default: mybigcommerce.com
+      store_hash:
+        default: store_hash
+        description: Permanent ID of the BigCommerce store.
+    description: BigCommerce API Gateway
 
 tags:
   - name: Tax — Class (batch)

From eb9d086ce158624665cfcf99283f72477e6a9565 Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Tue, 31 Mar 2026 16:11:47 +1100
Subject: [PATCH 04/18] TAX-2677: docs(tax) - Address PR review feedback on tax
 class batch spec

- Rename path /tax/class to /tax/classes
- Rename tag to "Tax Classes" to match conventions used elsewhere
- Remove "Batch" prefix from operation summaries
- Move name character restriction detail to the name field schema description
- Fix uniqueness scope: names must be unique across the store, not just the batch
- Update info description per reviewer suggestion

Refs TAX-2677
Co-Authored-By: Claude <noreply@anthropic.com>
---
 reference/tax_classes.v3.yaml | 30 ++++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index 7ae17a7cf..65943fc5e 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: Tax Classes
   description: |
-    Manage tax calculations applied to sales. Tax classes are used to apply different tax rates for specific types of products and orders.
+    Manage tax classification options available on your store. Tax classes are used to apply different tax rates to products and other item types.
 
     This API exposes batch operations (`POST`, `PUT`, `DELETE`) for tax classes.
 
@@ -26,21 +26,20 @@ servers:
     description: BigCommerce API Gateway
 
 tags:
-  - name: Tax — Class (batch)
-    description: Batch create, update, and delete tax classes.
+  - name: Tax Classes
+    description: Create, update, and delete tax classes.
 
 paths:
-  /tax/class:
+  /tax/classes:
     post:
-      tags: [Tax — Class (batch)]
-      summary: Batch create tax classes
+      tags:
+        - Tax Classes
+      summary: Create tax classes
       description: |
         Creates multiple tax classes in a single request. Max **50** items per request.
-        Each `name` must be **1–100** characters and cannot contain angle brackets,
-        braces, backticks, parentheses, semicolons, or pipes.
-        Names must be **unique case-insensitively** within the batch.
+        Names must be **unique case-insensitively** across the store (both existing classes and the incoming batch).
 
-        Conflicting names against existing tax classes produce **409**.
+        Conflicting names produce **409**.
       operationId: taxClassBatchPost
       security:
         - adminAuth: []
@@ -100,14 +99,15 @@ paths:
                 $ref: '#/components/schemas/ProblemResponseEnvelope'
 
     put:
-      tags: [Tax — Class (batch)]
+      tags:
+        - Tax Classes
       summary: Batch update tax classes
       description: |
         Updates multiple tax classes in a single request. Collection PUT only.
 
         Request body: non-empty array, max **50** items. Each item must include:
         - `id`: positive integer (**unique** across the batch)
-        - `name`: same length and character rules as create; **unique case-insensitively** in the batch.
+        - `name`: same length and character rules as create; **unique case-insensitively** across the store.
 
         Returns **400** if one or more specified classes are not found.
         Duplicate names → **409**.
@@ -171,7 +171,8 @@ paths:
                 $ref: '#/components/schemas/ProblemResponseEnvelope'
 
     delete:
-      tags: [Tax — Class (batch)]
+      tags:
+        - Tax Classes
       summary: Batch delete tax classes
       description: |
         Deletes multiple tax classes in a single request. The request must include the **`id:in`** query parameter
@@ -291,7 +292,8 @@ components:
             minLength: 1
             maxLength: 100
             description: >
-              Must not contain < > { } ` ( ) ; |
+              Tax class name. Must be 1–100 characters and cannot contain
+              < > { } ` ( ) ; |
         additionalProperties: false
 
     TaxClassUpdateBatch:

From a5248fbae34888dcfc701a886abaf8f24d91c1be Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Tue, 31 Mar 2026 16:19:35 +1100
Subject: [PATCH 05/18] TAX-2677: docs(tax) - Move name uniqueness constraint
 to field schema

Refs TAX-2677
Co-Authored-By: Claude <noreply@anthropic.com>
---
 reference/tax_classes.v3.yaml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index 65943fc5e..079b29a31 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -37,9 +37,6 @@ paths:
       summary: Create tax classes
       description: |
         Creates multiple tax classes in a single request. Max **50** items per request.
-        Names must be **unique case-insensitively** across the store (both existing classes and the incoming batch).
-
-        Conflicting names produce **409**.
       operationId: taxClassBatchPost
       security:
         - adminAuth: []
@@ -293,7 +290,8 @@ components:
             maxLength: 100
             description: >
               Tax class name. Must be 1–100 characters and cannot contain
-              < > { } ` ( ) ; |
+              < > { } ` ( ) ; |. Must be unique case-insensitively across the store
+              (both existing classes and the incoming batch). Conflicting names produce a 409.
         additionalProperties: false
 
     TaxClassUpdateBatch:

From 750a077bc6dd23d293561c7089d605413bfefc9b Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Tue, 31 Mar 2026 16:24:23 +1100
Subject: [PATCH 06/18] TAX-2677: docs(tax) - Remove hawk and admin security
 schemes

Refs TAX-2677
Co-Authored-By: Claude <noreply@anthropic.com>
---
 reference/tax_classes.v3.yaml | 52 ++---------------------------------
 1 file changed, 3 insertions(+), 49 deletions(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index 079b29a31..e23dec64f 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -38,9 +38,7 @@ paths:
       description: |
         Creates multiple tax classes in a single request. Max **50** items per request.
       operationId: taxClassBatchPost
-      security:
-        - adminAuth: []
-        - hawkAuth: []
+
       requestBody:
         required: true
         content:
@@ -109,9 +107,7 @@ paths:
         Returns **400** if one or more specified classes are not found.
         Duplicate names → **409**.
       operationId: taxClassBatchPut
-      security:
-        - adminAuth: []
-        - hawkAuth: []
+
       requestBody:
         required: true
         content:
@@ -180,9 +176,7 @@ paths:
 
         Success returns **204 No Content**.
       operationId: taxClassBatchDelete
-      security:
-        - adminAuth: []
-        - hawkAuth: []
+
       parameters:
         - name: id:in
           in: query
@@ -234,46 +228,6 @@ paths:
                 $ref: '#/components/schemas/ProblemResponseEnvelope'
 
 components:
-  securitySchemes:
-    adminAuth:
-      type: apiKey
-      in: header
-      name: X-Auth-Client
-      description: |-
-        ### Required permissions
-
-        | Permission | Description |
-        |:-----------|:------------|
-        | `Manage_Tax` | Required for write operations (POST, PUT, DELETE). Read-only actions do not require this permission. |
-
-        ### Authentication header
-
-        | Header | Argument | Description |
-        |:-------|:---------|:------------|
-        | `X-Auth-Client` | `client_id` | Admin client identifier. |
-
-        ### Further reading
-
-        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).
-    hawkAuth:
-      type: apiKey
-      in: header
-      name: X-Auth-Client
-      description: |-
-        ### Overview
-
-        Hawk-authenticated clients authorized via the hawk configuration.
-
-        ### Required permissions
-
-        | Permission | Description |
-        |:-----------|:------------|
-        | `Manage_Tax` | Required for write operations (POST, PUT, DELETE). |
-
-        ### Further reading
-
-        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).
-
   schemas:
     TaxClassCreateBatch:
       type: array

From 7d1158be268adc3e30ccd85db72db327e87f33e9 Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Tue, 31 Mar 2026 16:28:45 +1100
Subject: [PATCH 07/18] TAX-2677: docs(tax) - Add X-Auth-Token security scheme
 with MANAGE_TAX permission

Refs TAX-2677
Co-Authored-By: Claude <noreply@anthropic.com>
---
 reference/tax_classes.v3.yaml | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index e23dec64f..a634b8567 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -25,6 +25,9 @@ servers:
         description: Permanent ID of the BigCommerce store.
     description: BigCommerce API Gateway
 
+security:
+  - X-Auth-Token: []
+
 tags:
   - name: Tax Classes
     description: Create, update, and delete tax classes.
@@ -228,6 +231,32 @@ paths:
                 $ref: '#/components/schemas/ProblemResponseEnvelope'
 
 components:
+  securitySchemes:
+    X-Auth-Token:
+      name: X-Auth-Token
+      description: |-
+        ### OAuth scopes
+
+        | UI Name | Permission | Parameter |
+        |:--------|:-----------|:----------|
+        | Tax | modify | `MANAGE_TAX` |
+
+        ### 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:
     TaxClassCreateBatch:
       type: array

From 7a4ce1b400fbd1e7a52ec000a526d3b5c3564bf9 Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 13:29:48 +1100
Subject: [PATCH 08/18] TAX-2677: docs(tax) - Address low-priority PR review
 suggestions

Update PUT and DELETE operation summaries to remove "Batch" prefix.
Capitalize "IDs" consistently throughout DELETE endpoint descriptions
and replace "batch" with "request" in uniqueness constraint text.

Refs TAX-2677
Co-Authored-By: Claude <noreply@anthropic.com>
---
 reference/tax_classes.v3.yaml | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index a634b8567..c15b2dcaf 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -99,12 +99,12 @@ paths:
     put:
       tags:
         - Tax Classes
-      summary: Batch update tax classes
+      summary: Update tax classes
       description: |
         Updates multiple tax classes in a single request. Collection PUT only.
 
         Request body: non-empty array, max **50** items. Each item must include:
-        - `id`: positive integer (**unique** across the batch)
+        - `id`: positive integer (**unique** across the request)
         - `name`: same length and character rules as create; **unique case-insensitively** across the store.
 
         Returns **400** if one or more specified classes are not found.
@@ -169,12 +169,12 @@ paths:
     delete:
       tags:
         - Tax Classes
-      summary: Batch delete tax classes
+      summary: Delete tax classes
       description: |
         Deletes multiple tax classes in a single request. The request must include the **`id:in`** query parameter
-        with a comma-separated list of positive integer ids.
+        with a comma-separated list of positive integer IDs.
 
-        Max **50** ids. Empty id list → **404**. Invalid id values → **422**.
+        Max **50** IDs. Empty ID list → **404**. Invalid ID values → **422**.
         Returns **400** if one or more specified classes are not found.
 
         Success returns **204 No Content**.
@@ -185,7 +185,7 @@ paths:
           in: query
           required: true
           description: |
-            Comma-separated list of tax class ids to delete (e.g. `1,2,3`).
+            Comma-separated list of tax class IDs to delete (e.g. `1,2,3`).
             Must use the `in` operator; other filter operators are rejected with **400**.
           schema:
             type: string
@@ -206,13 +206,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/ProblemResponseEnvelope'
         '413':
-          description: More than 50 ids.
+          description: More than 50 IDs.
           content:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/ProblemResponseEnvelope'
         '422':
-          description: Invalid id values in filter.
+          description: Invalid ID values in filter.
           content:
             application/problem+json:
               schema:

From 79bf98c4488dabccba8d2bbfb360c52859fb0dfd Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 13:52:27 +1100
Subject: [PATCH 09/18] TAX-2677: docs(tax) - Capitalize ID in PUT 422 response
 description

Capitalize "id" to "ID" in the 422 error description for the batch
update endpoint, consistent with capitalization elsewhere in the spec.

Refs TAX-2677
Co-Authored-By: Claude <noreply@anthropic.com>
---
 reference/tax_classes.v3.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index c15b2dcaf..a16f73bb1 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -148,7 +148,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ProblemResponseEnvelope'
         '422':
-          description: Validation error (format, duplicate `id` in batch, invalid id values, id-only update payload, etc.).
+          description: Validation error (format, duplicate `id` in batch, invalid ID values, ID-only update payload, etc.).
           content:
             application/problem+json:
               schema:

From fd1d1731b4c9cab1a992169cc452b7d25f50a4f3 Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 13:54:43 +1100
Subject: [PATCH 10/18] TAX-2677: docs(tax) - Capitalize IDs in DELETE endpoint
 description

Capitalize "ids" to "IDs" in the info description for the DELETE
endpoint for consistent terminology throughout the spec.

Refs TAX-2677
Co-Authored-By: Claude <noreply@anthropic.com>
---
 reference/tax_classes.v3.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index a16f73bb1..7b9d9c4a4 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -9,7 +9,7 @@ info:
     **Responses:** Successful JSON bodies use the envelope format:
     `{ "data": ..., "meta": ... }`. Batch POST/PUT return an array of tax class resources under `data`.
 
-    **DELETE:** Deletes are filter-based using the `id:in` query parameter. The request must specify the ids to delete — there is no single-resource delete on this endpoint.
+    **DELETE:** Deletes are filter-based using the `id:in` query parameter. The request must specify the IDs to delete — there is no single-resource delete on this endpoint.
   termsOfService: 'https://www.bigcommerce.com/terms'
   contact:
     name: BigCommerce

From c23ac41d64ce8193c02494d939a5d5d64a8de85a Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 13:57:24 +1100
Subject: [PATCH 11/18] doc(tax): TAX-2677 remove description for tags

---
 reference/tax_classes.v3.yaml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index 7b9d9c4a4..1fab61106 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -30,7 +30,6 @@ security:
 
 tags:
   - name: Tax Classes
-    description: Create, update, and delete tax classes.
 
 paths:
   /tax/classes:

From 9f87e8d7fd60c6590890dc4c650912a1ad104e69 Mon Sep 17 00:00:00 2001
From: "vincent.zhao" <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 14:09:28 +1100
Subject: [PATCH 12/18] Update reference/tax_classes.v3.yaml

Co-authored-by: Brett Daniels <theromulans@gmail.com>
---
 reference/tax_classes.v3.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index 1fab61106..58cb95ccb 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -286,7 +286,7 @@ components:
           - id
           - name
         description: |
-          Each item must include `id` and at least one other field. Only `name` is permitted alongside `id`.
+          Each item must include `id` and at least one other field.
         properties:
           id:
             type: integer

From 55a71d557fed608209ac1f29c31ca7cb95a86ee7 Mon Sep 17 00:00:00 2001
From: "vincent.zhao" <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 14:09:50 +1100
Subject: [PATCH 13/18] Update reference/tax_classes.v3.yaml

Co-authored-by: Brett Daniels <theromulans@gmail.com>
---
 reference/tax_classes.v3.yaml | 9 +--------
 1 file changed, 1 insertion(+), 8 deletions(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index 58cb95ccb..baef10783 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -100,14 +100,7 @@ paths:
         - Tax Classes
       summary: Update tax classes
       description: |
-        Updates multiple tax classes in a single request. Collection PUT only.
-
-        Request body: non-empty array, max **50** items. Each item must include:
-        - `id`: positive integer (**unique** across the request)
-        - `name`: same length and character rules as create; **unique case-insensitively** across the store.
-
-        Returns **400** if one or more specified classes are not found.
-        Duplicate names → **409**.
+        Updates multiple tax classes in a single request. Max **50** items per request.
       operationId: taxClassBatchPut
 
       requestBody:

From 495f974c3886714a5e6ef16611653d217a4c9ea1 Mon Sep 17 00:00:00 2001
From: "vincent.zhao" <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 14:10:09 +1100
Subject: [PATCH 14/18] Update reference/tax_classes.v3.yaml

Co-authored-by: Brett Daniels <theromulans@gmail.com>
---
 reference/tax_classes.v3.yaml | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index baef10783..05675be20 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -163,13 +163,7 @@ paths:
         - Tax Classes
       summary: Delete tax classes
       description: |
-        Deletes multiple tax classes in a single request. The request must include the **`id:in`** query parameter
-        with a comma-separated list of positive integer IDs.
-
-        Max **50** IDs. Empty ID list → **404**. Invalid ID values → **422**.
-        Returns **400** if one or more specified classes are not found.
-
-        Success returns **204 No Content**.
+        Deletes multiple tax classes in a single request. Max **50** items per request.
       operationId: taxClassBatchDelete
 
       parameters:

From 273bf1920ee8baa363e65e4f4ec65e173871584c Mon Sep 17 00:00:00 2001
From: "vincent.zhao" <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 14:11:01 +1100
Subject: [PATCH 15/18] Update reference/tax_classes.v3.yaml

Co-authored-by: Brett Daniels <theromulans@gmail.com>
---
 reference/tax_classes.v3.yaml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index 05675be20..a424bfe99 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -172,7 +172,6 @@ paths:
           required: true
           description: |
             Comma-separated list of tax class IDs to delete (e.g. `1,2,3`).
-            Must use the `in` operator; other filter operators are rejected with **400**.
           schema:
             type: string
           example: '101,102,103'

From f7c416d78f58a092b742bba762cecba1b73c284b Mon Sep 17 00:00:00 2001
From: "vincent.zhao" <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 14:11:22 +1100
Subject: [PATCH 16/18] Update reference/tax_classes.v3.yaml

Co-authored-by: Brett Daniels <theromulans@gmail.com>
---
 reference/tax_classes.v3.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index a424bfe99..7d6d8a65d 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -179,7 +179,7 @@ paths:
         '204':
           description: All listed classes deleted successfully.
         '400':
-          description: Delete failed (e.g. class not found).
+          description: Delete failed (e.g., class not found).
           content:
             application/problem+json:
               schema:

From ea835aab87d638b6d024ae7543685853571a07dd Mon Sep 17 00:00:00 2001
From: "vincent.zhao" <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 14:11:31 +1100
Subject: [PATCH 17/18] Update reference/tax_classes.v3.yaml

Co-authored-by: Brett Daniels <theromulans@gmail.com>
---
 reference/tax_classes.v3.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index 7d6d8a65d..b2d7b780d 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -171,7 +171,7 @@ paths:
           in: query
           required: true
           description: |
-            Comma-separated list of tax class IDs to delete (e.g. `1,2,3`).
+            Comma-separated list of tax class IDs to delete (e.g., `1,2,3`).
           schema:
             type: string
           example: '101,102,103'

From 194b1d49e1da63cae56e092e46fe15668aa75b23 Mon Sep 17 00:00:00 2001
From: "vincent.zhao" <vincent.zhao@bigcommerce.com>
Date: Wed, 1 Apr 2026 14:11:40 +1100
Subject: [PATCH 18/18] Update reference/tax_classes.v3.yaml

Co-authored-by: Brett Daniels <theromulans@gmail.com>
---
 reference/tax_classes.v3.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/tax_classes.v3.yaml b/reference/tax_classes.v3.yaml
index b2d7b780d..17b3a06d8 100644
--- a/reference/tax_classes.v3.yaml
+++ b/reference/tax_classes.v3.yaml
@@ -58,7 +58,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/TaxClassCollectionEnvelope'
         '400':
-          description: Bad request (e.g. invalid input).
+          description: Bad request (e.g., invalid input).
           content:
             application/problem+json:
               schema: