Partners

Tax classes

Group products by tax treatment and manage the default class through the Store API.

Tax classes belong to a market and use read_markets / write_markets. They describe what is being taxed; tax zones describe where, and rate lines connect the two. Fetch the limits endpoint before rendering lists or forms. Slugs are generated when omitted and validated exactly when supplied. A market always retains one default class.

Model product tax treatment#

A tax class groups products that receive the same treatment inside one market. Create classes such as Standard, Reduced rate, or Exempt, then assign products or variants to them. Rates connect each class to each tax zone. Products without an assignment use the market's default class while use_default_tax_class is enabled; otherwise they are sold without zone tax.

Create a class#

json 
// POST /api/2025-01/markets/{marketId}/tax-classes
{
  "name": "Reduced rate",
  "slug": "reduced-rate",
  "description": "Books and qualifying essentials",
  "is_default": false
}

Fetch the limits endpoint before building a form or picker. Deleting a class that still owns rates, product assignments, variant assignments, or price-based rules uses the confirmation handshake before anything is removed. A class used by shipping, checkout fees, cash on delivery, or payment adjustments cannot be deleted until those use another class.

Endpoints#

Get tax class limits

GET read_markets

Fetch tax-class validation limits.

Returns the live tax-class limits — the per-market cap and the name, slug, description, and search length caps (all counted in characters). Read this instead of hardcoding numbers.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

List tax classes

GET read_markets

List a market's tax classes.

Returns paginated tax classes, searchable by name. Every market starts with one default class; is_default marks it. Pagination and search bounds come from the limits endpoint.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789

Query parameters

Name Type Description
page integer

Page number.

Example: 1
per_page integer

Page size (service-capped).

Example: 20
search string

Search by tax class name.

Example: reduced

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 404 MARKET_NOT_FOUND

    Market does not exist in this store.

Create a tax class

POST write_markets

Create a tax class in a market.

Creates a tax class. name is required. Omit slug to have one generated from the name — generation transliterates per the store's default locale and suffixes -2, -3, … on collision; a slug you provide is validated exactly as sent (lowercase letters, numbers, and hyphens) and rejected on duplicate rather than rewritten. Setting is_default makes this the market's default class and clears the previous default in the same write. Fires tax_classes/create.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name required string

Tax class name.

Example: Reduced rate
slug string

Slug — validated as-is when provided, generated from the name when omitted.

Example: reduced-rate
description string

Internal description.

Example: Food, books, and other reduced-rate goods
is_default boolean

Make this the market's default class. The previous default is cleared in the same write.

Example: false

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 TAX_CLASS_NAME_REQUIRED

    Name is empty after normalization.
  • 400 TAX_CLASS_NAME_TOO_LONG

    Name exceeds the limit.
  • 400 TAX_CLASS_DESCRIPTION_TOO_LONG

    Description exceeds the limit.
  • 400 MARKET_SLUG_INVALID

    Provided slug has characters outside lowercase letters, numbers, and hyphens.
  • 400 TAX_CLASS_SLUG_TOO_LONG

    Provided slug exceeds the limit.
  • 404 MARKET_NOT_FOUND

    Market does not exist in this store.
  • 409 TAX_CLASS_SLUG_DUPLICATE

    A tax class with this slug already exists in the market.
  • 409 TAX_CLASS_LIMIT_REACHED

    The market's tax class cap has been reached.

Get a tax class

GET read_markets

Fetch one tax class.

Returns the tax class.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789
taxClassId required string

Tax class id.

Example: 4e2b8c1a-7f3d-4a5b-9c6d-1e0f2a3b4c5d

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 404 MARKET_NOT_FOUND

    Market does not exist in this store.
  • 404 TAX_CLASS_NOT_FOUND

    Tax class does not exist in this market.

Update a tax class

PUT write_markets

Update a tax class.

Updates the tax class's name, slug, description, and default flag. Slug rules match create: omitted or empty regenerates from the name, a provided slug is validated as-is and rejected on duplicate. Promoting a class to default clears the previous default in the same write; a market always keeps exactly one default class. Fires tax_classes/update.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789
taxClassId required string

Tax class id.

Example: 4e2b8c1a-7f3d-4a5b-9c6d-1e0f2a3b4c5d

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name required string

Tax class name.

Example: Reduced rate
slug string

Slug — validated as-is when provided, generated from the name when omitted.

Example: reduced-rate
description string

Internal description.

Example: Food, books, and other reduced-rate goods
is_default boolean

Make this the market's default class. The previous default is cleared in the same write.

Example: false

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 TAX_CLASS_NAME_REQUIRED

    Name is empty after normalization.
  • 400 TAX_CLASS_NAME_TOO_LONG

    Name exceeds the limit.
  • 400 TAX_CLASS_DESCRIPTION_TOO_LONG

    Description exceeds the limit.
  • 400 MARKET_SLUG_INVALID

    Provided slug has characters outside lowercase letters, numbers, and hyphens.
  • 400 TAX_CLASS_SLUG_TOO_LONG

    Provided slug exceeds the limit.
  • 404 MARKET_NOT_FOUND

    Market does not exist in this store.
  • 409 TAX_CLASS_SLUG_DUPLICATE

    A tax class with this slug already exists in the market.
  • 409 TAX_CLASS_LIMIT_REACHED

    The market's tax class cap has been reached.
  • 404 TAX_CLASS_NOT_FOUND

    Tax class does not exist in this market.

Bulk delete tax classes

POST write_markets

Delete a selected set of tax classes atomically.

Send 1 to list_max_limit unique tax-class UUIDs from the same market. The service validates the full selection before deleting anything. A default class, a class assigned to shipping, checkout fees, cash on delivery or payment adjustments, a missing class, a duplicate or malformed id, or an oversized selection rejects the whole request. If any class has dependent rates, product or variant assignments, or price rules, the first request returns all warnings and a confirmation token bound to the exact sorted selection. Repeat the identical selection with confirmed and confirmation_token. All deletions, per-class audit records, and tax_classes/delete webhook events commit in one transaction or all roll back.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
tax_class_ids required array<uuid>

Unique tax-class UUIDs from this market; maximum list_max_limit.

Example: ["4e2b8c1a-7f3d-4a5b-9c6d-1e0f2a3b4c5d"]
confirmed boolean

Set to true only when repeating the identical selection after confirmation is requested.

Example: true
confirmation_token string

The single-use token returned for this exact selection.

Example: confirmation-token

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 INVALID_INPUT

    The bulk selection is empty, malformed, duplicated, or exceeds list_max_limit.
  • 400 MARKET_CONFIRMATION_INVALID

    The confirmation token is invalid, expired, already used, or belongs to another selection.
  • 400 TAX_CLASS_DEFAULT_DELETE_LOCKED

    The default class can't be deleted — promote another class first.
  • 404 MARKET_NOT_FOUND

    Market does not exist in this store.
  • 404 TAX_CLASS_NOT_FOUND

    Tax class does not exist in this market.
  • 409 TAX_CLASS_SHIPPING_ASSIGNED

    Shipping settings or methods use this class. Assign them a different class before deleting it.
  • 409 TAX_CLASS_CHARGES_ASSIGNED

    Checkout fees, cash-on-delivery settings or payment adjustments use this class. Choose a different class there before deleting it.
  • 409 CONFIRMATION_REQUIRED

    The class has dependents; retry with confirmed and the returned confirmation_token.

Delete a tax class

DELETE write_markets

Delete one tax class. Use the bulk-delete endpoint for a selection. Each successful deletion records the class and market names in its audit entry.

Deletes the tax class together with its rates, product and variant assignments, and price rules. The default class can't be deleted — promote another class first. Shipping settings and shipping methods must be reassigned before deleting their tax class (TAX_CLASS_SHIPPING_ASSIGNED), and so must checkout fees, cash-on-delivery settings and payment adjustments (TAX_CLASS_CHARGES_ASSIGNED). When the class still has dependents, the first call returns a confirmation response listing what will be removed; retry with confirmed and the returned confirmation_token to proceed. Products left without a class are taxed by the market's default class while use_default_tax_class is on, and sold untaxed when it is off. Fires tax_classes/delete.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789
taxClassId required string

Tax class id.

Example: 4e2b8c1a-7f3d-4a5b-9c6d-1e0f2a3b4c5d

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
confirmed boolean

On a confirmation retry, set this to true and send the returned confirmation_token. Omit it on the first request.
confirmation_token string

Token from the CONFIRMATION_REQUIRED response. Omit it on the first request and resend the exact same id selection when using it.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 INVALID_INPUT

    The bulk selection is empty, malformed, duplicated, or exceeds list_max_limit.
  • 400 MARKET_CONFIRMATION_INVALID

    The confirmation token is invalid, expired, already used, or belongs to another selection.
  • 400 TAX_CLASS_DEFAULT_DELETE_LOCKED

    The default class can't be deleted — promote another class first.
  • 404 MARKET_NOT_FOUND

    Market does not exist in this store.
  • 404 TAX_CLASS_NOT_FOUND

    Tax class does not exist in this market.
  • 409 TAX_CLASS_SHIPPING_ASSIGNED

    Shipping settings or methods use this class. Assign them a different class before deleting it.
  • 409 TAX_CLASS_CHARGES_ASSIGNED

    Checkout fees, cash-on-delivery settings or payment adjustments use this class. Choose a different class there before deleting it.
  • 409 CONFIRMATION_REQUIRED

    The class has dependents; retry with confirmed and the returned confirmation_token.

Webhook events#

Tax-class events are published for every create, update, and confirmed delete. Making a class the default also publishes an update for the class that stops being the default. The saved change and its event become visible together. Delete payloads preserve the class identity after its dependent data has been removed.

Tax class created

EVENT tax_classes/create App scope: read_markets Staff permission: markets:write

Subscribe to receive the saved tax class after it is created in a market.

Payload fields

Field Type Description
tax_class.id string Always present

The stable tax class id.
tax_class.market_id string Selectable in the Payload builder

The market where the tax class is available.
tax_class.name string Selectable in the Payload builder

The merchant-facing tax class name.
tax_class.slug string Selectable in the Payload builder

The tax class's URL-safe identifier within the market.
tax_class.description string Selectable in the Payload builder

The optional explanation of which products use this class.
tax_class.is_default boolean Selectable in the Payload builder

Whether products without an explicit assignment use this class.
tax_class.created_at string Selectable in the Payload builder

When the tax class was created.
tax_class.updated_at string Selectable in the Payload builder

When the tax class last changed.

Tax class updated

EVENT tax_classes/update App scope: read_markets Staff permission: markets:write

Subscribe to receive the current tax class after its name, slug, description, or default status changes.

Payload fields

Field Type Description
tax_class.id string Always present

The stable tax class id.
tax_class.market_id string Selectable in the Payload builder

The market where the tax class is available.
tax_class.name string Selectable in the Payload builder

The merchant-facing tax class name.
tax_class.slug string Selectable in the Payload builder

The tax class's URL-safe identifier within the market.
tax_class.description string Selectable in the Payload builder

The optional explanation of which products use this class.
tax_class.is_default boolean Selectable in the Payload builder

Whether products without an explicit assignment use this class.
tax_class.created_at string Selectable in the Payload builder

When the tax class was created.
tax_class.updated_at string Selectable in the Payload builder

When the tax class last changed.

Tax class deleted

EVENT tax_classes/delete App scope: read_markets Staff permission: markets:write

Subscribe to remove a deleted tax class from your integration. The payload keeps its id, market id, last known name, and slug.

Payload fields

Field Type Description
tax_class.id string Always present

The stable tax class id.
tax_class.market_id string Selectable in the Payload builder

The market where the tax class is available.
tax_class.name string Selectable in the Payload builder

The merchant-facing tax class name.
tax_class.slug string Selectable in the Payload builder

The tax class's URL-safe identifier within the market.

Last updated Oct 21, 2026