TAX-2677: docs(tax) - Add v3 tax class batch endpoints OpenAPI spec by bc-vincent-zhao · Pull Request #1301 · bigcommerce/docs

bc-vincent-zhao · 2026-03-31T02:43:32Z

What/Why?

Adds a new OpenAPI 3.0 spec (reference/tax_classes.v3.yaml) documenting the internal v1 Tax API batch endpoints for tax classes (POST /tax/class, PUT /tax/class, DELETE /tax/class).

Key details captured in the spec:

Batch size limit: 50 items per request (TaxBatchResourceValidator)
Name validation rules: 1–100 chars, case-insensitive uniqueness, disallowed characters
DELETE uses id:in query filter; path segment :id is ignored
Response envelope follows internal API pattern ({ "data": ..., "meta": ... })
409 on duplicate names, 413 on batch size exceeded, 422 on shape/validation failures

Rollout/Rollback

Documentation-only change — no code deployed. No rollback needed.

Testing

Verify the spec renders correctly in the docs portal and that all three batch endpoints (POST, PUT, DELETE) display with accurate request/response schemas.

Fixes TAX-2677
Co-Authored-By: Claude noreply@anthropic.com

reference/tax_classes.v3.yaml

theromulans · 2026-03-31T05:08:03Z

Thanks for this, would be excellent to get our documentation update up and running 👏

…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>

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>

- 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>

Refs TAX-2677 Co-Authored-By: Claude <noreply@anthropic.com>

…X permission Refs TAX-2677 Co-Authored-By: Claude <noreply@anthropic.com>

reference/tax_classes.v3.yaml

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>

bc-vincent-zhao

thanks @theromulans updated as you recommended.

reference/tax_classes.v3.yaml

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>

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

Co-authored-by: Brett Daniels <theromulans@gmail.com>

theromulans

🚀 Thanks @bc-vincent-zhao !

theromulans · 2026-04-07T04:28:11Z

@bc-vincent-zhao Is your expectation that these docs should appear online without any further work? Just observing the rollout section doesn't list any further effort and the ticket is closed 👀 Concerned we may have missed part of the ticket's expected outcomes before closing.

bc-vincent-zhao · 2026-04-07T05:33:06Z

@theromulans thanks for the reminder, yes, I was expecting the new endpoint automatically appear on dev doc, I may have missed a nav link update, let me double check.

bc-vincent-zhao · 2026-04-07T05:57:47Z

@bigcommerce/dev-docs-team would you please help us understand how to get a new endpoint published ? In this PR I created a entire new swagger yml for v3 tax classes endpoint, how can I get it published alongside the current v2 version (https://developer.bigcommerce.com/docs/rest-management/tax/tax-classes) ?

Thanks in advance 🙇

chris-nowicki · 2026-04-07T15:10:58Z

@bigcommerce/dev-docs-team would you please help us understand how to get a new endpoint published ? In this PR I created a entire new swagger yml for v3 tax classes endpoint, how can I get it published alongside the current v2 version (https://developer.bigcommerce.com/docs/rest-management/tax/tax-classes) ?

Thanks in advance 🙇

Hey @bc-vincent-zhao we have officially closed this repository and the dev-center repository. We are in a docs freeze this week while we get ready to go live with the new docs site on Monday the 13th. However, I was able to get your v3 tax classes into the new site that you can preview here :) - https://docs-beta.bigcommerce.com/developer/api-reference/rest/admin/management/tax/tax-classes/get-tax-classes

New Docs Rep is HERE -> https://github.com/bigcommerce/docs-v2
Currently the preview for the new docs site is docs-beta.bigcommerce.com and next monday that will change to docs.bigcommerce.com

theromulans reviewed Mar 31, 2026

View reviewed changes

reference/tax_classes.v3.yaml Outdated Show resolved Hide resolved