# Cross-Border Duties When your marketplace handles international orders, you may need to calculate and submit import duties alongside taxes. This guide explains how duties work with Violet's checkout flow. ## What Violet Provides Violet supports duties end-to-end across the checkout and order lifecycle: * **HS Codes on Products** — Many merchants configure Harmonized System (HS) codes and country of origin on their products. Violet passes this data through the API on Offers and SKUs, giving you the inputs needed to calculate duties. * **Duty submission at checkout** — You can submit duty amounts in the `rates` array on each SKU using `type: "DUTY"`. Violet handles duties at the line item level, bag total, and order total — including in distributions and settlement. * **Flexible calculation** — You can calculate duties using a third-party service with HS codes, apply a fixed percentage or amount from the merchant, or use your own calculation logic. ## How It Works 1. **Get HS codes** — Pull HS codes and country of origin from the product catalog via the Violet API, or determine them yourself 2. **Determine the duty model** — Check with the merchant whether they use DDP (Delivered Duty Paid) or DDU (Delivered Duty Unpaid). Most cross-border merchants today use DDP. 3. **Calculate the duty amount** per SKU — using a calculation service, a merchant-provided flat rate, or your own logic 4. **Submit duties** in the cart or CreateOrder request using `type: "DUTY"` in the `rates` array {% hint style="warning" %} **Cart estimates will not include calculated duties.** Commerce platforms like Shopify do not expose calculated duty amounts through their APIs. When you estimate a cart through Violet, the returned totals reflect sales tax and shipping only. You are responsible for calculating and adding duty amounts on top of the estimated totals according to your operational requirements, or agreement with the Merchant. {% endhint %} ## Getting HS Codes and Origin Data Many merchants have HS codes configured on their products. When available, Violet surfaces this data on SKUs: ```json { "sku_id": 32671, "trade_compliance": { "harmonized_system_code": "6204.43", "country_code_of_origin": "IT", "province_code_of_origin": null } } ``` | Field | Description | | ------------------------- | ------------------------------------------------------- | | `harmonized_system_code` | HS code for international tariff classification | | `country_code_of_origin` | ISO country code where the product was manufactured | | `province_code_of_origin` | Subdivision within the origin country (when applicable) | You can use these HS codes — or determine them yourself — to calculate duties via a third-party service such as Avalara, Zonos, or TaxJar. {% hint style="info" %} `trade_compliance` is present when the merchant has configured HS codes on the SKU in their commerce platform. If absent for a given product, you will need to obtain this information directly from the merchant or classify the product yourself. {% endhint %} ## Calculating Duties There are two common approaches: ### Using HS Codes + a Calculation Service Feed the HS code, country of origin, and destination address into a duty calculation service to get the applicable rate and amount. This approach scales well across many merchants and product categories. ### Using a Fixed Rate or Amount Some merchants apply a known flat percentage or fixed amount for duties. You may also decide to apply a fixed rate yourself based on your business model. Either way, you can pass the calculated value directly into the `rates` array. ## Submitting Duties Pass duties as a `rates` entry with `type: "DUTY"` on each SKU: ```json POST /v1/orders { "payment_method": { "type": "SINGLE_USE_CARD_TOKEN", "payment_provider": "STRIPE", "token": "tok_..." }, "order": { "app_order_id": "00100100", "customer": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com" }, "bags": [ { "skus": [ { "sku_id": 32671, "price": 17200, "quantity": 1, "rates": [ { "name": "Import Duty (IT→US)", "type": "DUTY", "amount": 3268 } ] } ], "shipping_method": { "label": "Standard Shipping", "price": 0 } } ], "shipping_address": { "address_1": "200 West St", "address_2": "Floor 30", "city": "New York", "state": "NY", "country": "US", "postal_code": "10282" }, "currency": "USD" } } ``` Duty amounts submitted this way are reflected at every level: line item rates, bag totals, and order totals — including distributions and settlement. ### Combining Duties and Taxes When both sales tax and duties apply to a SKU, include both in the `rates` array: ```json "skus": [ { "sku_id": 32671, "price": 17200, "quantity": 1, "rates": [ { "name": "NY Sales Tax", "type": "TAX", "rate": 8.875, "amount": 1527 }, { "name": "Import Duty (IT→US)", "type": "DUTY", "rate": 19.0, "amount": 3268 } ] } ] ``` ### Rates Field Reference | Field | Type | Required | Description | | -------- | ------- | ------------------------- | ------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | Display name (e.g., "Import Duty (IT→US)") | | `type` | string | Yes | `TAX` for sales tax, VAT, GST. `DUTY` for import duties, tariffs, customs fees. | | `amount` | integer | Either `amount` or `rate` | Amount in cents (e.g., 3268 = $32.68) | | `rate` | number | Either `amount` or `rate` | Percentage (e.g., 19.0). If both are provided, Violet uses `amount` for calculations but persists both. | ## Example: Flat-Rate Duty A merchant imports goods from Italy to the US and applies a flat 19% duty. | Line Item | Value | | --------------- | ----------- | | Product | $172.00 | | Sales Tax | $0.00 | | Shipping | $0.00 | | Duty (19%) | $32.68 | | **Order Total** | **$204.68** | Calculation: `$172.00 × 0.19 = $32.68` → submit `"amount": 3268` with `"type": "DUTY"`. ## DDP vs DDU How you present duties to shoppers depends on your marketplace model and the merchant's preference. Check with each merchant on which model they use. | Model | Description | Shopper Experience | | ------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **DDP** (Delivered Duty Paid) | Channel collects duties at checkout and submits them with the order | Shopper sees the total including duties before paying. No surprise fees at delivery. | | **DDU** (Delivered Duty Unpaid) | Duties are not collected at checkout | Shopper may be charged duties by the carrier at delivery. Can lead to refused deliveries and negative experience. | Most cross-border merchants today use **DDP**. Violet's `DUTY` rate type supports both models — you calculate and submit the duty amount regardless of who ultimately bears the cost. ## Platform Behavior When Violet submits an order with `DUTY` rates to the merchant's commerce platform: | Platform | Behavior | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Shopify** | Duty amounts are registered on the platform and reflected in the order. On Shopify, duties are summed into the order's tax total in the merchant's admin view. | ## Related Resources * [Direct Order Submission](https://docs.violet.io/prism/checkout-guides/guides/direct-order-submission) — Full CreateOrder documentation including the `rates` array * [Tax Remittance](https://docs.violet.io/prism/checkout-guides/guides/tax-remittance) — Tax calculation responsibilities for channels