Calculating Duties with Avalara

How to use Avalara AvaTax Cross-Border to calculate import duties, then submit them on Violet orders.

The Cross-Border Duties guide explains how to submit duty amounts on a Violet order. This guide covers the step before that: how to actually calculate those amounts using Avalara. It walks through mapping the trade compliance data Violet already exposes into an Avalara request, reading the calculated duty back out, and passing it into Violet's rates array.

The information here is provided for general guidance only and does not constitute legal or tax advice. Violet does not calculate duties and is not affiliated with Avalara. Avalara's own documentation is the source of truth for its APIs, account setup, and pricing. We recommend consulting Avalara and a qualified trade-compliance advisor to ensure your integration is accurate for the jurisdictions you sell into.

Why Avalara

Import duties depend on what a product is (its Harmonized System classification), where it was made, where it's going, its value, and the trade agreements and de minimis thresholds between those countries. Maintaining that logic yourself across many merchants and destinations is impractical. Avalara AvaTax Cross-Border determines the applicable duty and import tax for a line item from its tariff code and destination, so you can request a landed-cost estimate at checkout instead of hard-coding rates.

Avalara is one option. Zonos and TaxJar offer comparable services, and the same overall pattern (classify, calculate, submit) applies to any of them.

Prerequisites

Before you can calculate duties with Avalara, you'll need:

1. An Avalara account with AvaTax Cross-Border enabled. Duty and import-tax calculation is a cross-border capability on top of standard AvaTax and must be provisioned on your account. See AvaTax Cross-Border.

2. API credentials for the AvaTax REST API.

3. Fully qualified HS/tariff codes on your products. Avalara requires a fully qualified tariff code (the HS root plus the destination country's extension) on each line to calculate duty accurately. You can supply codes you already have, including the ones Violet surfaces, or use Avalara Tariff Code Classification to assign them automatically.

Step 1: Get trade compliance data from Violet

Many merchants configure HS codes and country of origin on their products, and Violet surfaces this on the SKU as trade_compliance:

{
  "sku_id": 32671,
  "trade_compliance": {
    "harmonized_system_code": "6204.43",
    "country_code_of_origin": "IT",
    "province_code_of_origin": null
  }
}

Violet field	Avalara input
trade_compliance.harmonized_system_code	The tariff code (hsCode) sent to Avalara for classification
trade_compliance.country_code_of_origin	Country of manufacture, passed as a line parameter (see the note below)
SKU price and quantity	The line value Avalara applies the duty rate to
Shopper's shipping address country	The destination (shipTo) that determines which duties apply

Country of origin is not the same as the ship-from location. Avalara's shipFrom address is where the goods physically ship from, for example a merchant's warehouse. The country where a product was manufactured is what drives duty rates and trade-agreement eligibility, and it can differ from the ship-from country. Pass country_code_of_origin as the manufactured origin (via a line parameter such as CountryOfManufacture), not as shipFrom.country.

trade_compliance is present when the merchant has configured HS codes on the SKU. If it's absent, obtain the code from the merchant or classify the product yourself (for example, via Avalara Tariff Code Classification) before calculating duty. See Cross-Border Duties for more on this data.

Step 2: Request a duty calculation from Avalara

Duties are calculated through Avalara's CreateTransaction endpoint, the same endpoint used for sales tax, extended with cross-border fields. Map the Violet data from Step 1 onto the request:

POST https://rest.avatax.com/api/v2/transactions/create

{
  "type": "SalesOrder",
  "companyCode": "YOUR_COMPANY_CODE",
  "date": "2026-07-28",
  "customerCode": "[e-mail]",
  "currencyCode": "USD",
  "isSellerImporterOfRecord": true,
  "deliveryTerms": "DDP",
  "addresses": {
    "shipFrom": { "country": "IT" },
    "shipTo": {
      "line1": "200 West St",
      "city": "New York",
      "region": "NY",
      "country": "US",
      "postalCode": "10282"
    }
  },
  "lines": [
    {
      "number": "1",
      "itemCode": "SKU-32671",
      "hsCode": "6204.43",
      "quantity": 1,
      "amount": 172.00,
      "parameters": [
        { "name": "CountryOfManufacture", "value": "IT" }
      ]
    }
  ]
}

The cross-border-specific inputs to note:

Field	Purpose
type	Use SalesOrder for a non-committing estimate (ideal for quoting at checkout). Use SalesInvoice to record the transaction once the order is placed.
isSellerImporterOfRecord	Set to true so Avalara includes import duty and import tax in the response. Defaults to false, in which case duties are not returned.
deliveryTerms	DDP (Delivered Duty Paid) indicates the seller side bears duties. Together with isSellerImporterOfRecord, this drives whether duties are calculated.
addresses.shipFrom	The physical origin the goods ship from (a warehouse or merchant location), not necessarily the country of manufacture.
addresses.shipTo	The shopper's destination, which determines the applicable duties.
lines[].hsCode	The fully qualified tariff code for the line, from harmonized_system_code or from Avalara's classification service.
lines[].parameters	Where the manufactured origin is passed (for example CountryOfManufacture), sourced from country_code_of_origin.
lines[].amount	Line value the duty rate is applied to (Avalara uses major currency units, for example 172.00).

Field names, required setup, and behavior are defined by Avalara and may change. The exact parameter names for origin and delivery terms, and the response shape, should be confirmed against the current Avalara AvaTax API reference and duty calculation guide before you build against them.

Step 3: Read the calculated duty from the response

Avalara returns cross-border charges under the LandedCost tax type, with a taxSubType distinguishing import duty from import tax. Read the duty (and, depending on your model, the import-tax) entries and sum them per line:

{
  "totalTax": 32.68,
  "summary": [
    {
      "taxType": "LandedCost",
      "taxSubType": "ImportDuty",
      "rate": 0.19,
      "tax": 32.68
    }
  ]
}

In this example the response returns 32.68 of import duty. If import VAT/GST also applies at the border, it appears as a separate LandedCost entry with a different taxSubType (for example ImportVAT); decide whether to treat that as duty, tax, or roll it into the shopper's total based on your agreement with the merchant.

Step 4: Submit the duty on the Violet order

Convert Avalara's amount into cents and submit it in the rates array with type: "DUTY" on the corresponding SKU when creating the order:

POST /v1/orders

{
  "order": {
    "bags": [
      {
        "skus": [
          {
            "sku_id": 32671,
            "price": 17200,
            "quantity": 1,
            "rates": [
              {
                "name": "Import Duty (IT to US)",
                "type": "DUTY",
                "rate": 19.0,
                "amount": 3268
              }
            ]
          }
        ]
      }
    ]
  }
}

Violet sums DUTY rates into the duty_total on the bag and order, and includes them in total = sub_total + shipping_total + tax_total + duty_total - discount_total. See Cross-Border Duties for the full field reference and combined tax + duty examples.

Cart estimates will not include duties. Commerce platforms don't expose duty amounts through their cart APIs, so a Violet cart estimate reflects sales tax and shipping only. Call Avalara with type: "SalesOrder" to quote duties yourself and add them on top of the estimated total before the shopper pays.

End-to-End Flow

1. Read trade_compliance (HS code, origin) from Violet SKUs
                    │
2. Collect the shopper's destination address
                    │
3. POST to Avalara CreateTransaction (type: SalesOrder,
   isSellerImporterOfRecord: true, deliveryTerms: DDP)
                    │
4. Read import duty (LandedCost / ImportDuty) per line from the response
                    │
5. Convert to cents, then submit as a DUTY rate on Violet CreateOrder
                    │
6. Violet rolls duties into duty_total, distributions, and settlement

Related Resources

• Cross-Border Duties: How duties flow through Violet's checkout, and the full rates field reference

• Direct Order Submission: Full CreateOrder documentation

• Tax Remittance: Tax calculation responsibilities for channels

• Avalara AvaTax Cross-Border and the AvaTax API reference