Partners

Price-based tax rules

Change a class's tax rate when an item's unit price goes above a threshold.

Price-based tax rules belong to a market and use read_markets / write_markets. They are available only for single-country, single-currency markets, with at most one rule per tax class. The pricing engine compares each unit price after merchandise discounts and before tax with the threshold, applies below_rate at or below it and above_rate above it, and then calculates duties and order totals.

Compare the price before tax#

A price-based rule sets the rate for one tax class by an item's unit price after merchandise discounts and before tax. For tax-inclusive prices the price compared is the price without tax at below_rate. At or below the threshold below_rate applies; above it, above_rate. For example, a rule with threshold 1000.00, below_rate 5.00, and above_rate 12.00 taxes a discounted unit priced at 1000.00 at 5%, and a unit priced at 1000.01 at 12%. The rule's rate is shared between the class's rate lines in proportion to their ordinary rates, so CGST 9% and SGST 9% under a 5% rule are charged as CGST 2.5% and SGST 2.5%. Shipping, cash-on-delivery charges, and checkout fees continue using their own tax classes and rates.

Check eligibility first#

Price thresholds are meaningful only in one jurisdiction and one currency, so these rules are available only when the market has exactly one country and one currency. Call the eligibility endpoint before presenting the feature. Each class may have one rule, and its ordinary zone rates must still exist wherever the class should be taxed.

json 
// POST /api/2025-01/markets/{marketId}/tax-price-rules
{
  "tax_class_id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
  "threshold_price": "1000.00",
  "below_rate": "5.00",
  "above_rate": "12.00"
}

Endpoints#

Check price-rule eligibility

GET read_markets

Check whether the market can use price-based tax rules.

Returns eligible only when the market has exactly one country and one currency. A threshold is jurisdiction-specific and currency-specific, while the current rule is scoped to the market and tax class.

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.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.

List price-based tax rules

GET read_markets

List a market's price-based tax rules.

Each rule changes item tax for one tax class according to the final unit price after discounts. Rules do not apply to shipping, COD, or checkout fees. The class must still have an ordinary rate in each applicable zone. Where the matched zone's rates for the class add up to 0% (exports, zero-rated zones), the rule is skipped and no tax is charged; catalog price estimates skip it there too. While rules exist, the market cannot add a second country or currency or replace its currency (TAX_PRICE_RULE_BLOCKS_CURRENCY_CHANGE).

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.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.

Get a price-based tax rule

GET read_markets

Fetch one price-based tax rule.

Returns the rule and its market, class, currency, threshold, and below/above rates.

Path parameters

Name Type Description
marketId required uuid

Market id.

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

Price-based tax rule 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 NOT_FOUND

    Price-based tax rule does not exist.

Create a price-based tax rule

POST write_markets

Create a price-based tax rule.

Requires a single-country, single-currency market and allows one rule per tax class. The threshold is a decimal string in the market currency, compared with each item's unit price after discounts and before tax (for tax-inclusive prices, the price without tax at below_rate); at the threshold below_rate applies. The two rates must differ, but either may be higher. The class must have ordinary zone rates wherever the rule should apply: the rule's rate is shared between those rate lines in proportion to their ordinary rates, so CGST 9% + SGST 9% under a 5% rule are charged as 2.5% + 2.5%. In a zone whose rates for the class total 0%, the rule is skipped. Fires tax_price_rules/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
tax_class_id required string

Tax class this rule overrides.

Example: 7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c
threshold_price required string

Positive amount, at most 99999999999.9999, using the market currency's decimal precision.

Example: 1000.00
below_rate required string

Percentage from 0 to 100 with at most 4 decimal places, for items whose unit price after discounts and before tax is at or below the threshold.

Example: 5.00
above_rate required string

Percentage from 0 to 100 with at most 4 decimal places, for items whose unit price after discounts and before tax is above the threshold.

Example: 18.00

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 TAX_PRICE_RULE_SINGLE_COUNTRY

    Market does not have exactly one country.
  • 400 TAX_PRICE_RULE_SINGLE_CURRENCY

    Market does not have exactly one currency.
  • 400 TAX_PRICE_RULE_THRESHOLD_INVALID

    Threshold is not positive.
  • 400 TAX_PRICE_RULE_THRESHOLD_SCALE

    Threshold exceeds the currency's decimal scale.
  • 400 TAX_PRICE_RULE_BELOW_RANGE

    At-or-below-threshold rate is outside 0 through 100.
  • 400 TAX_PRICE_RULE_ABOVE_RANGE

    Above-threshold rate is outside 0 through 100.
  • 400 TAX_PRICE_RULE_RATE_SCALE

    A price-based rate exceeds 4 decimal places; values are rejected rather than rounded.
  • 400 TAX_PRICE_RULE_RATES_EQUAL

    The at-or-below and above rates are equal.
  • 409 TAX_PRICE_RULE_DUPLICATE

    This tax class already has a price-based rule.

Update a price-based tax rule

PUT write_markets

Update threshold and rates.

Updates the threshold and below/above rates. The two rates must differ, but either may be higher. Fires tax_price_rules/update.

Path parameters

Name Type Description
marketId required uuid

Market id.

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

Price-based tax rule id.

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

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
threshold_price required string

Positive amount, at most 99999999999.9999, using the market currency's decimal precision.

Example: 1000.00
below_rate required string

Percentage from 0 to 100 with at most 4 decimal places, for items whose unit price after discounts and before tax is at or below the threshold.

Example: 5.00
above_rate required string

Percentage from 0 to 100 with at most 4 decimal places, for items whose unit price after discounts and before tax is above the threshold.

Example: 18.00

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 TAX_PRICE_RULE_SINGLE_COUNTRY

    Market does not have exactly one country.
  • 400 TAX_PRICE_RULE_SINGLE_CURRENCY

    Market does not have exactly one currency.
  • 400 TAX_PRICE_RULE_THRESHOLD_INVALID

    Threshold is not positive.
  • 400 TAX_PRICE_RULE_THRESHOLD_SCALE

    Threshold exceeds the currency's decimal scale.
  • 400 TAX_PRICE_RULE_BELOW_RANGE

    At-or-below-threshold rate is outside 0 through 100.
  • 400 TAX_PRICE_RULE_ABOVE_RANGE

    Above-threshold rate is outside 0 through 100.
  • 400 TAX_PRICE_RULE_RATE_SCALE

    A price-based rate exceeds 4 decimal places; values are rejected rather than rounded.
  • 400 TAX_PRICE_RULE_RATES_EQUAL

    The at-or-below and above rates are equal.
  • 409 TAX_PRICE_RULE_DUPLICATE

    This tax class already has a price-based rule.

Delete a price-based tax rule

DELETE write_markets

Delete a price-based tax rule.

Deletes the rule without changing ordinary tax rates. Fires tax_price_rules/delete.

Path parameters

Name Type Description
marketId required uuid

Market id.

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

Price-based tax rule 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 NOT_FOUND

    Price-based tax rule does not exist.

Webhook events#

Price-rule events are published for every create, update, and delete, and the saved change and its event become visible together. Payloads include the class, market currency, threshold, and both rates.

Price-based tax rule created

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

Subscribe to receive a price-based tax rule after it is created for a market's tax class.

Payload fields

Field Type Description
tax_price_rule.id string Always present

The stable price-based tax rule id.
tax_price_rule.market_id string Selectable in the Payload builder

The single-country, single-currency market where the rule applies.
tax_price_rule.tax_class_id string Selectable in the Payload builder

The tax class whose ordinary rate is replaced by this threshold rule.
tax_price_rule.threshold_price string Selectable in the Payload builder

The final unit-price threshold as a decimal string in the market currency.
tax_price_rule.below_rate string Selectable in the Payload builder

The percentage used below the threshold, as a decimal string.
tax_price_rule.above_rate string Selectable in the Payload builder

The percentage used at or above the threshold, as a decimal string.
tax_price_rule.market_name string Selectable in the Payload builder

The current market name.
tax_price_rule.tax_class_name string Selectable in the Payload builder

The current tax class name.
tax_price_rule.currency_code string Selectable in the Payload builder

The ISO 4217 currency used by the threshold.
tax_price_rule.created_at string Selectable in the Payload builder

When the rule was created.
tax_price_rule.updated_at string Selectable in the Payload builder

When the rule last changed.

Price-based tax rule updated

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

Subscribe to receive the current price-based tax rule after its threshold or below-and-above rates change.

Payload fields

Field Type Description
tax_price_rule.id string Always present

The stable price-based tax rule id.
tax_price_rule.market_id string Selectable in the Payload builder

The single-country, single-currency market where the rule applies.
tax_price_rule.tax_class_id string Selectable in the Payload builder

The tax class whose ordinary rate is replaced by this threshold rule.
tax_price_rule.threshold_price string Selectable in the Payload builder

The final unit-price threshold as a decimal string in the market currency.
tax_price_rule.below_rate string Selectable in the Payload builder

The percentage used below the threshold, as a decimal string.
tax_price_rule.above_rate string Selectable in the Payload builder

The percentage used at or above the threshold, as a decimal string.
tax_price_rule.market_name string Selectable in the Payload builder

The current market name.
tax_price_rule.tax_class_name string Selectable in the Payload builder

The current tax class name.
tax_price_rule.currency_code string Selectable in the Payload builder

The ISO 4217 currency used by the threshold.
tax_price_rule.created_at string Selectable in the Payload builder

When the rule was created.
tax_price_rule.updated_at string Selectable in the Payload builder

When the rule last changed.

Price-based tax rule deleted

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

Subscribe to remove a deleted price-based tax rule from your integration. The payload keeps its rule, market, and tax class ids.

Payload fields

Field Type Description
tax_price_rule.id string Always present

The stable price-based tax rule id.
tax_price_rule.market_id string Selectable in the Payload builder

The single-country, single-currency market where the rule applies.
tax_price_rule.tax_class_id string Selectable in the Payload builder

The tax class whose ordinary rate is replaced by this threshold rule.

Last updated Oct 21, 2026