Duties

Returns the live rule, HS-rate, search, and pagination limits enforced by the service. Read this before building create or edit forms instead of hardcoding values.

Returns a paginated list of the market's countries, whether duties are enabled for each country, and whether a rule already exists. The readiness counts identify shippable catalog items missing weight, HS code, or country of origin.

Returns paginated rules with their de minimis value, origin-aware default rates, HS-code rates, status, and timestamps. Use the detail endpoint before editing a rule.

The country must belong to the market, have a serving currency, and not already have a rule. Create an inactive rule while configuring rates; enable it once the required catalog data is ready. Default and HS-code rates may vary by origin country; use * as the fallback origin. Duty is charged on each line's customs value: its value after discounts, without the tax its price includes. In a tax-inclusive market, a line of 120 including 20% VAT at a 12% duty rate pays 12.00 duty, not 14.40. When the market's duty_collection_mode is collect_at_checkout, import VAT is charged on the goods plus their duty: 100 with 12 duty at 20% VAT is 22.40. Duty is calculated first; the VAT on duty uses each item's own tax rates, is always added on top of the duty (never included in a price), and is part of the order's tax total, so in a tax-inclusive market the total is prices plus duty plus VAT on duty. A successful create publishes duty_rules/create with the complete saved rule.

Use this endpoint when the destination country is known but the rule id is not. It returns the same complete object as the id-based detail endpoint.

Use the returned rule to populate an edit form. HS codes are returned in canonical even-length 2 to 12 digit form, grouped by origin country.

This is a partial update. Use explicit delete fields to remove de minimis, a default origin rate, or one HS-code rate. Sending hs_rates replaces the complete origin-to-HS map. An unchanged request publishes nothing; a successful change publishes duty_rules/update with the complete saved rule.

Future calculations stop using the rule. Existing orders retain the duty evidence saved in their pricing snapshots. A successful deletion publishes duty_rules/delete with the rule id, market id, and country code.

Checks every enabled duty rule in markets with duties turned on against the shippable items of active products, the same way checkout rates them. Items whose origin is the rule's destination pay no duty and are skipped. For each rule it returns counts and up to 20 example items for: missing_hs_code, missing_origin, missing_weight (only where the matching rate is charged per kg) and missing_rate (no rate for the item's origin and HS code, and no * default), plus unrated_origins, the origin countries with no matching rate and how many items each covers. currency_mismatch is true when the rule's currency differs from the serving currency of its destination country: checkout then charges no duty to that country at all. Each example's product_id, and variant_id for a variant, identify the item to fix. status is ok when a rule has nothing to fix and issues otherwise; the top-level status is issues when any rule has one. At checkout, an item that cannot be rated pays no duty and the order goes ahead; staff and API orders containing one are refused with an ORDER_DUTY_* error. The report is computed for the whole catalog and may be up to 60 seconds old; generated_at says when it was computed. Markets list responses include duty_health_available, which is false when there is nothing to check.