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

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.

Getting HS Codes and Origin Data

Many merchants have HS codes configured on their products. When available, Violet surfaces this data on SKUs:

{
  "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.

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.

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:

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": "[email protected]"
    },
    "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:

"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 — Full CreateOrder documentation including the rates array

• Tax Remittance — Tax calculation responsibilities for channels