Key highlights
-
A brand new v3 endpoint offers builders and system integrators full batch management over tax class configuration — no management panel required.
-
Create, replace, and delete as much as 50 tax courses in a single API request — no guide management panel updates wanted.
-
Designed for automation: splendid for multi-store administration, ERP integrations, and headless deployments the place tax configuration have to be scripted at scale.
-
Works in live performance with the Tax Charges & Zones API, supplying you with full programmatic management over the complete guide tax configuration stack.
What the Tax Lessons API endpoint does
Tax courses decide how various kinds of merchandise are taxed. Beforehand, creating and managing them required guide work within the BigCommerce management panel. The brand new Tax Lessons API (POST /v3/tax/courses) adjustments that.
The endpoint helps three batch operations — create, replace, and delete — all on the identical /tax/courses 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 somewhat than a request physique.
API reference documentation for Tax Lessons API might be considered right here.
Why this issues
For retailers operating advanced catalogs — particularly these with bodily items, digital merchandise, and companies promoting throughout a number of jurisdictions — conserving tax courses in sync with product taxonomy has all the time been a friction level. Till now, there was no dependable technique 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 embrace tax class setup in the identical pipeline as the remainder of your catalog and configuration work.
Pattern use instances
Multi-store provisioning — Routinely replicate a constant set of tax courses throughout new storefronts at setup time, with out guide configuration for every.
ERP & PIM integration — Hold tax class definitions in sync with product taxonomy adjustments originating in an ERP or PIM system, with out human intervention.
Headless deployments — Embrace 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 courses when product traces change, somewhat than modifying them one after the other within the management panel.
The way it works
The Tax Lessons API does not function in isolation. Tax courses sit on the basis of BigCommerce’s fundamental tax configuration mannequin, and work together with a number of different API endpoints:
-
Tax Lessons API → Tax Charges & Zones API — Tax charges embrace a
class_ratesentry for every tax class outlined on the shop. Whenever you create a brand new tax class, the tax fee can be handled as a zero worth (0% tax fee) till that you must add a corresponding entry to every of your present tax charges. -
Tax Lessons API → Catalog Merchandise API — Merchandise are assigned to a tax class through the
tax_class_iddiscipline. Whenever you create new tax courses, you may assign merchandise to them utilizing the usual Catalog Merchandise API. -
Tax Lessons API → Order Charges API — Charges could optionally be assigned to particular tax courses through the
tax_class_id discipline. In lieu of any specific project, the shop’s international payment tax class can be used. -
Tax Charges & Zones API → Tax Settings API — Tax zones (managed through the Tax Charges & Zones API) are referenced straight in Tax Settings, together with the visitor shopper tax zone and the shop tax zone that describes pricing calculation outcomes.
Necessary: Deleting a tax class doesn’t robotically replace related tax charges or product assignments. Earlier than deleting, audit which merchandise reference the category through the Catalog Merchandise API and which charges embrace it through the Tax Charges & Zones API, and replace them accordingly.
This is a minimal instance of making two tax courses in a single request:
POST /shops/{store_hash}/v3/tax/courses
X-Auth-Token: {access_token}
[
  { "name": "General Merchandise" },
  { "name": "Digital Goods" }
]
// Returns created tax class objects with id, title,
// created_at, and updated_at fields.
For public API accounts, the required OAuth scope is Data & Settings. For retailer customers, the required retailer permission is Handle Tax.
Full API reference documentation is out there on the BigCommerce Developer Heart.
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 guide tax setup.
