Key highlights
-
A brand new v3 endpoint provides builders and system integrators full batch management over tax class configuration — no management panel required.
-
Create, replace, and delete as much as 50 tax lessons in a single API request — no handbook management panel updates wanted.
-
Designed for automation: perfect for multi-store administration, ERP integrations, and headless deployments the place tax configuration should be scripted at scale.
-
Works in live performance with the Tax Charges & Zones API, providing you with full programmatic management over your entire handbook tax configuration stack.
What the Tax Courses API endpoint does
Tax lessons decide how several types of merchandise are taxed. Beforehand, creating and managing them required handbook work within the BigCommerce management panel. The brand new Tax Courses API (POST /v3/tax/lessons) modifications that.
The endpoint helps three batch operations — create, replace, and delete — all on the identical /tax/lessons path. Every operation accepts as much as 50 objects per request and returns structured JSON responses in BigCommerce’s commonplace envelope format. Deletes are filter-based, utilizing the id:in question parameter fairly than a request physique.
API reference documentation for Tax Courses API may be seen right here.
Why this issues
For retailers working complicated catalogs — particularly these with bodily items, digital merchandise, and providers promoting throughout a number of jurisdictions — retaining tax lessons in sync with product taxonomy has at all times been a friction level. Till now, there was no dependable option to script it.
This endpoint unlocks tax class administration as a part of a repeatable, version-controlled deployment workflow. Whether or not you are provisioning a brand new retailer, syncing from an ERP, or managing a fleet of storefronts, now you can embody tax class setup in the identical pipeline as the remainder of your catalog and configuration work.
Pattern use circumstances
Multi-store provisioning — Routinely replicate a constant set of tax lessons throughout new storefronts at setup time, with out handbook configuration for every.
ERP & PIM integration — Maintain tax class definitions in sync with product taxonomy modifications originating in an ERP or PIM system, with out human intervention.
Headless deployments — Embody tax class setup as a scripted step in headless retailer deployment pipelines, alongside catalog, channel, and settings configuration.
Catalog restructuring — Batch-rename or consolidate tax lessons when product strains change, fairly than modifying them one after the other within the management panel.
The way it works
The Tax Courses API would not function in isolation. Tax lessons sit on the basis of BigCommerce’s primary tax configuration mannequin, and work together with a number of different API endpoints:
-
Tax Courses API → Tax Charges & Zones API — Tax charges embody a
class_ratesentry for every tax class outlined on the shop. Whenever you create a brand new tax class, the tax charge will probably be handled as a zero worth (0% tax charge) till that you must add a corresponding entry to every of your current tax charges. -
Tax Courses API → Catalog Merchandise API — Merchandise are assigned to a tax class by way of the
tax_class_iddiscipline. Whenever you create new tax lessons, you’ll be able to assign merchandise to them utilizing the usual Catalog Merchandise API. -
Tax Courses API → Order Charges API — Charges could optionally be assigned to particular tax lessons by way of the
tax_class_id discipline. In lieu of any express task, the shop’s international payment tax class will probably be used. -
Tax Charges & Zones API → Tax Settings API — Tax zones (managed by way of the Tax Charges & Zones API) are referenced instantly in Tax Settings, together with the visitor shopper tax zone and the shop tax zone that describes pricing calculation outcomes.
Vital: Deleting a tax class doesn’t routinely replace related tax charges or product assignments. Earlier than deleting, audit which merchandise reference the category by way of the Catalog Merchandise API and which charges embody it by way of the Tax Charges & Zones API, and replace them accordingly.
This is a minimal instance of making two tax lessons in a single request:
POST /shops/{store_hash}/v3/tax/lessons
X-Auth-Token: {access_token}
[
{ "name": "General Merchandise" },
{ "name": "Digital Goods" }
]
// Returns created tax class objects with id, identify,
// created_at, and updated_at fields.
For public API accounts, the required OAuth scope is Info & Settings. For retailer customers, the required retailer permission is Handle Tax.
Full API reference documentation is accessible on the BigCommerce Developer Middle.
The ultimate phrase
Tax class configuration is now absolutely programmable. Whether or not you are managing a single retailer or a fleet of them, tax class configuration can now be a part of your automated deployment and integration workflows — constant, repeatable, and version-controlled. Pair it with the Tax Charges & Zones API for end-to-end programmatic management over your handbook tax setup.
