Duties

Duty rules belong to duty-enabled market countries and use read_markets / write_markets. Each country has at most one rule. Its de minimis value is an exact decimal in the currency assigned to that country in Pricing. Default and HS-code rates preserve one of three explicit shapes: ad_valorem uses rate, specific uses amount plus per, and compound uses all three. Irrelevant fields are rejected, not ignored. HS codes accept dotted, spaced, or hyphenated display forms but are stored canonically as an even 2-12 digit code; canonical collisions fail the write. Update is partial, with explicit clear flags for de minimis and the default rate, while hs_rates replaces the complete map.

Endpoints#

Get duty limits

GET read_markets

Get duty limits.

Returns live country-rule, HS-rate, search, and pagination limits.

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

409 MARKET_DUTIES_DISABLED
Enable duties for the market before mutating rules.
400 MARKET_DUTY_RATE_TYPE_INVALID
Rate type is not ad_valorem, specific, or compound.
400 MARKET_DUTY_RATE_SHAPE_INVALID
The rate contains fields irrelevant to its type.
400 MARKET_DUTY_HS_CODE_INVALID_FORMAT
HS code cannot be normalized to an even 2-12 digit level.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 DUTY_RULE_NOT_FOUND
The duty rule does not exist in this market.

Response

200

Sample response

{"success":true,"data":{}}

List duty countries

GET read_markets

List duty countries.

Returns market countries and whether each is enabled for duty rules; supports search and pagination.

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

409 MARKET_DUTIES_DISABLED
Enable duties for the market before mutating rules.
400 MARKET_DUTY_RATE_TYPE_INVALID
Rate type is not ad_valorem, specific, or compound.
400 MARKET_DUTY_RATE_SHAPE_INVALID
The rate contains fields irrelevant to its type.
400 MARKET_DUTY_HS_CODE_INVALID_FORMAT
HS code cannot be normalized to an even 2-12 digit level.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 DUTY_RULE_NOT_FOUND
The duty rule does not exist in this market.

Response

200

Sample response

{"success":true,"data":{}}

List duty rules

GET read_markets

List duty rules.

Returns paginated country rules with rich default and HS-code rates.

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

409 MARKET_DUTIES_DISABLED
Enable duties for the market before mutating rules.
400 MARKET_DUTY_RATE_TYPE_INVALID
Rate type is not ad_valorem, specific, or compound.
400 MARKET_DUTY_RATE_SHAPE_INVALID
The rate contains fields irrelevant to its type.
400 MARKET_DUTY_HS_CODE_INVALID_FORMAT
HS code cannot be normalized to an even 2-12 digit level.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 DUTY_RULE_NOT_FOUND
The duty rule does not exist in this market.

Response

200

Sample response

{"success":true,"data":{}}

Create a duty rule

POST write_markets

Create a duty rule.

Creates one rule for a duty-enabled market country. Rates are ad_valorem, specific, or compound and reject fields irrelevant to their type.

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
`country_code` required	`string`	Duty-enabled ISO country code.
`de_minimis_value`	`decimal-string\|null`	Non-negative threshold in the country's assigned currency.
`default_duty_rate`	`object\|null`	Rich rate: type plus applicable rate and/or amount/per.
`hs_rates`	`object`	HS-code to rich rate object.
`is_enabled` required	`boolean`	Whether this rule participates in resolution.

Errors

409 MARKET_DUTIES_DISABLED
Enable duties for the market before mutating rules.
400 MARKET_DUTY_RATE_TYPE_INVALID
Rate type is not ad_valorem, specific, or compound.
400 MARKET_DUTY_RATE_SHAPE_INVALID
The rate contains fields irrelevant to its type.
400 MARKET_DUTY_HS_CODE_INVALID_FORMAT
HS code cannot be normalized to an even 2-12 digit level.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 DUTY_RULE_NOT_FOUND
The duty rule does not exist in this market.

Response

201

Sample response

{"success":true,"data":{}}

Get a duty rule by country

GET read_markets

Get a duty rule by country.

Returns the rule for one ISO country code.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`countryCode` required	`string`	ISO country code.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

409 MARKET_DUTIES_DISABLED
Enable duties for the market before mutating rules.
400 MARKET_DUTY_RATE_TYPE_INVALID
Rate type is not ad_valorem, specific, or compound.
400 MARKET_DUTY_RATE_SHAPE_INVALID
The rate contains fields irrelevant to its type.
400 MARKET_DUTY_HS_CODE_INVALID_FORMAT
HS code cannot be normalized to an even 2-12 digit level.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 DUTY_RULE_NOT_FOUND
The duty rule does not exist in this market.

Response

200

Sample response

{"success":true,"data":{}}

Get a duty rule

GET read_markets

Get a duty rule.

Returns one country rule and its canonical 2-12 digit HS map.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`ruleId` required	`uuid`	Duty country rule ID.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

409 MARKET_DUTIES_DISABLED
Enable duties for the market before mutating rules.
400 MARKET_DUTY_RATE_TYPE_INVALID
Rate type is not ad_valorem, specific, or compound.
400 MARKET_DUTY_RATE_SHAPE_INVALID
The rate contains fields irrelevant to its type.
400 MARKET_DUTY_HS_CODE_INVALID_FORMAT
HS code cannot be normalized to an even 2-12 digit level.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 DUTY_RULE_NOT_FOUND
The duty rule does not exist in this market.

Response

200

Sample response

{"success":true,"data":{}}

Update a duty rule

PUT write_markets

Update a duty rule.

Partially updates a rule. Explicit clear flags remove de minimis or the default rate; hs_rates replaces the complete canonical map.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`ruleId` required	`uuid`	Duty country rule ID.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`de_minimis_value`	`decimal-string\|null`	Non-negative threshold in the country's assigned currency.
`default_duty_rate`	`object\|null`	Rich rate: type plus applicable rate and/or amount/per.
`hs_rates`	`object`	HS-code to rich rate object.
`is_enabled` required	`boolean`	Whether this rule participates in resolution.
`clear_de_minimis_value`	`boolean`	Explicitly clear de minimis.
`clear_default_duty_rate`	`boolean`	Explicitly clear the default rate.

Errors

409 MARKET_DUTIES_DISABLED
Enable duties for the market before mutating rules.
400 MARKET_DUTY_RATE_TYPE_INVALID
Rate type is not ad_valorem, specific, or compound.
400 MARKET_DUTY_RATE_SHAPE_INVALID
The rate contains fields irrelevant to its type.
400 MARKET_DUTY_HS_CODE_INVALID_FORMAT
HS code cannot be normalized to an even 2-12 digit level.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 DUTY_RULE_NOT_FOUND
The duty rule does not exist in this market.

Response

200

Sample response

{"success":true,"data":{}}

Delete a duty rule

DELETE write_markets

Delete a duty rule.

Deletes a country rule and all HS-code rates.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`ruleId` required	`uuid`	Duty country rule ID.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

409 MARKET_DUTIES_DISABLED
Enable duties for the market before mutating rules.
400 MARKET_DUTY_RATE_TYPE_INVALID
Rate type is not ad_valorem, specific, or compound.
400 MARKET_DUTY_RATE_SHAPE_INVALID
The rate contains fields irrelevant to its type.
400 MARKET_DUTY_HS_CODE_INVALID_FORMAT
HS code cannot be normalized to an even 2-12 digit level.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 DUTY_RULE_NOT_FOUND
The duty rule does not exist in this market.

Response

200

Sample response

{"success":true,"data":{}}

Webhook events#

Duty-rule events are inserted in the same database transaction as every create, update, or delete. Payloads preserve ad valorem, specific, and compound rate shapes.

Duty rule created

EVENT duty_rules/create write_markets markets:write

Fired when a country duty rule is created in a market.

Payload fields

Field	Type	Description
`duty_rule.id`	`string`	Always present
`duty_rule.market_id`	`string`	Can be removed/added via the Payload builder
`duty_rule.country_code`	`string`	Can be removed/added via the Payload builder
`duty_rule.de_minimis_value`	`string`	Can be removed/added via the Payload builder
`duty_rule.de_minimis_currency`	`string`	Can be removed/added via the Payload builder
`duty_rule.default_duty_rate.type`	`string`	Can be removed/added via the Payload builder
`duty_rule.default_duty_rate.rate`	`string`	Can be removed/added via the Payload builder
`duty_rule.default_duty_rate.amount`	`string`	Can be removed/added via the Payload builder
`duty_rule.default_duty_rate.per`	`string`	Can be removed/added via the Payload builder
`duty_rule.hs_rates`	`object`	Can be removed/added via the Payload builder
`duty_rule.is_enabled`	`boolean`	Can be removed/added via the Payload builder
`duty_rule.created_at`	`string`	Can be removed/added via the Payload builder
`duty_rule.updated_at`	`string`	Can be removed/added via the Payload builder

Payload shape

Sample payload

{
  "duty_rule": {
    "country_code": "...",
    "created_at": "2026-06-09T12:00:00Z",
    "de_minimis_currency": null,
    "de_minimis_value": null,
    "default_duty_rate": {
      "amount": "...",
      "per": "...",
      "rate": "...",
      "type": "..."
    },
    "hs_rates": "...",
    "id": 7,
    "is_enabled": false,
    "market_id": "...",
    "updated_at": "2026-06-09T12:00:00Z"
  }
}

Duty rule updated

EVENT duty_rules/update write_markets markets:write

Fired when a country duty rule or its HS rates change.

Payload fields

Field	Type	Description
`duty_rule.id`	`string`	Always present
`duty_rule.market_id`	`string`	Can be removed/added via the Payload builder
`duty_rule.country_code`	`string`	Can be removed/added via the Payload builder
`duty_rule.de_minimis_value`	`string`	Can be removed/added via the Payload builder
`duty_rule.de_minimis_currency`	`string`	Can be removed/added via the Payload builder
`duty_rule.default_duty_rate.type`	`string`	Can be removed/added via the Payload builder
`duty_rule.default_duty_rate.rate`	`string`	Can be removed/added via the Payload builder
`duty_rule.default_duty_rate.amount`	`string`	Can be removed/added via the Payload builder
`duty_rule.default_duty_rate.per`	`string`	Can be removed/added via the Payload builder
`duty_rule.hs_rates`	`object`	Can be removed/added via the Payload builder
`duty_rule.is_enabled`	`boolean`	Can be removed/added via the Payload builder
`duty_rule.created_at`	`string`	Can be removed/added via the Payload builder
`duty_rule.updated_at`	`string`	Can be removed/added via the Payload builder

Payload shape

Sample payload

{
  "duty_rule": {
    "country_code": "...",
    "created_at": "2026-06-09T12:00:00Z",
    "de_minimis_currency": null,
    "de_minimis_value": null,
    "default_duty_rate": {
      "amount": "...",
      "per": "...",
      "rate": "...",
      "type": "..."
    },
    "hs_rates": "...",
    "id": 7,
    "is_enabled": false,
    "market_id": "...",
    "updated_at": "2026-06-09T12:00:00Z"
  }
}

Duty rule deleted

EVENT duty_rules/delete write_markets markets:write

Fired when a country duty rule is deleted.

Payload fields

Field	Type	Description
`duty_rule.id`	`string`	Always present
`duty_rule.market_id`	`string`	Can be removed/added via the Payload builder
`duty_rule.country_code`	`string`	Can be removed/added via the Payload builder

Payload shape

Sample payload

{
  "duty_rule": {
    "country_code": "...",
    "id": 7,
    "market_id": "..."
  }
}