> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/prism/checkout-guides/guides/calculating-duties-with-avalara.md). # Calculating Duties with Avalara The [Cross-Border Duties](/prism/checkout-guides/guides/cross-border-duties.md) 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](https://www.avalara.com). 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. {% hint style="info" %} 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. {% endhint %} ## 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](https://zonos.com) and [TaxJar](https://www.taxjar.com) 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](https://www.avalara.com/us/en/products/global-commerce-offerings/avatax-cross-border.html). 2. **API credentials** for the [AvaTax REST API](https://developer.avalara.com/api-reference/avatax/rest/v2/). 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](https://www.avalara.com/us/en/products/tariff-code-classification.html) 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`: ```json { "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 | {% hint style="warning" %} **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`. {% endhint %} {% hint style="info" %} `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](/prism/checkout-guides/guides/cross-border-duties.md#getting-hs-codes-and-origin-data) for more on this data. {% endhint %} ## Step 2: Request a duty calculation from Avalara Duties are calculated through Avalara's [`CreateTransaction`](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/CreateTransaction/) endpoint, the same endpoint used for sales tax, extended with cross-border fields. Map the Violet data from Step 1 onto the request: ```json POST https://rest.avatax.com/api/v2/transactions/create { "type": "SalesOrder", "companyCode": "YOUR_COMPANY_CODE", "date": "2026-07-28", "customerCode": "ada@example.com", "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`). | {% hint style="warning" %} 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](https://developer.avalara.com/api-reference/avatax/rest/v2/) and [duty calculation guide](https://developer.avalara.com/avatax/dev-guide/transactions/duty-calc/) before you build against them. {% endhint %} ## 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: ```json { "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: ```json 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](/prism/checkout-guides/guides/cross-border-duties.md#submitting-duties) for the full field reference and combined tax + duty examples. {% hint style="warning" %} **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. {% endhint %} ## 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](/prism/checkout-guides/guides/cross-border-duties.md): How duties flow through Violet's checkout, and the full `rates` field reference * [Direct Order Submission](/prism/checkout-guides/guides/direct-order-submission.md): Full CreateOrder documentation * [Tax Remittance](/prism/checkout-guides/guides/tax-remittance.md): Tax calculation responsibilities for channels * [Avalara AvaTax Cross-Border](https://www.avalara.com/us/en/products/global-commerce-offerings/avatax-cross-border.html) and the [AvaTax API reference](https://developer.avalara.com/api-reference/avatax/rest/v2/) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.violet.io/prism/checkout-guides/guides/calculating-duties-with-avalara.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.