# Avalara Cross Border Tariff Content

### Access to the Production API
To interact with this API, you need to acquire a bearer token.
To acquire a bearer token:
1. [Create a License Key](https://knowledge.avalara.com/bundle/bhk1662649440973_bhk1662649440973/page/Get_your_license_key.html).
2. Call Avalara Identity to get an access token:
    ```bash
        curl -X POST https://identity.avalara.com/connect/token
             -H "Content-Type: application/x-www-form-urlencoded"
             -d "grant_type=client_credentials&client_id=&client_secret=&scope=avatax_api"
    ```
    Sample response (json)
    ```json
        {
            "access_token": "",
            "expires_in": 3600,
            "token_type": "Bearer",
            "scope": "avatax_api"
        }
    ```
3. The `access_token` can be used to interact with the API.
4. The `access_token` is valid for 1 hour, after which you will need to request a fresh token.

### Access to the Sandbox API
To interact with the Sandbox API, you can request for a bearer token from your Avalara integration specialist.
You can use the bearer token issued for a fixed number of requests against the sandbox API.

Source: https://developer.avalara.com/products/trade-and-tariff-library/api/

**Version:** 1.0
**Base URL:** /

---

## Endpoints

### Tradedata

#### Get import schedule data.

`GET /hscodeselfclassify/tradedata/importschedule/{hscode}/{origin}/{destination}`

Gets the import schedule data for a specific HS code, origin, and destination country.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `hscode` | string | path | Yes | The HS (Harmonized System) code for the product. |
| `origin` | string | path | Yes | The code for origin country in ISO 3166-1 alpha-2 format. |
| `destination` | string | path | Yes | The code for destination country in ISO 3166-1 alpha-2 format. |
| `language` | string | query | No | The language code for the response. |
| `avalara-version` |  | header | Yes | API version. Current version is 1.0. |

#### Download import schedule data.

`GET /hscodeselfclassify/tradedata/importschedule/download/{destination}`

Downloads import schedule data for a specific destination country in the specified format (JSON, XML, or Excel).

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `destination` | string | path | Yes | The code for destination country in ISO 3166-1 alpha-2 format. |
| `format` | string | query | No | The format for the response. Allowed values: json, xml, excel. |
| `language` | string | query | No | The language code for the response. |
| `avalara-version` |  | header | Yes | API version. Current version is 1.0. |

---

## Models

### DutiesProjection

Duty information for a single trading partner or duty regime applicable to an HS code, including the rate, the type of duty, and any Meursing component.

| Property | Type | Description |
|---|---|---|
| `name` | string | Short name of the trading partner or duty regime. |
| `longName` | string | Full descriptive name of the trading partner or duty regime. |
| `rate` | string | Duty rate that applies, expressed as a percentage string. |
| `type` | string | Category of duty (for example, MFN, Preferential, or Other). |
| `meursing` | boolean | When true, indicates that an EU Meursing additional code applies to this duty (typically for agricultural goods containing milk fats, sugars, or starches). When false, no Meursing component applies. |

### ImportScheduleProjection

Import duty schedule for a destination country, including the country identification, the schedule version, the default duty group name, and the hierarchical tree of tariff entries.

| Property | Type | Description |
|---|---|---|
| `country` | string | Display name of the destination country, in uppercase. |
| `iso2` | string | Destination country code in ISO 3166-1 alpha-2 format. |
| `version` | string | Version identifier of the tariff data used to build this import schedule. |
| `generalGroupName` | string | Name of the default duty group that applies when no more specific group matches. |
| `children` | array | Hierarchical tree of tariff entries (sections, chapters, headings, and items) that make up the import schedule for this destination. |

### TradeDataProjection

A node in the hierarchical tariff tree. Each node represents a section, chapter, heading, subheading, or item, and may contain child entries, localized descriptions, and duty information.

| Property | Type | Description |
|---|---|---|
| `id` | string | Internal identifier for this tariff entry. Unique within the schedule. |
| `type` | string | Type of tariff hierarchy node. |
| `code` | string | Official tariff code for this entry (HS code or section/chapter identifier). May be empty for grouping entries that do not have a code of their own. |
| `desc` | string | Description of the tariff entry in the response language. |
| `descriptions` | object | Localized descriptions keyed by ISO 639-1 language code (for example, EN, FR, DE). |
| `uom` | string | Unit of measure for this entry. Typically empty for non-leaf entries. |
| `duties` | object | Duty information for this entry, keyed by trading partner or duty regime. |
| `children` | object | Child tariff entries nested under this node. |

### AvalaraAPIExceptionDetails

Standard error response payload returned by the API when a request fails. Provides a short error title, the HTTP status code, and a human-readable detail message.

| Property | Type | Description |
|---|---|---|
| `title` | string | Short, human-readable error category. |
| `status` | integer | HTTP status code returned with the error response. |
| `detail` | string | Human-readable explanation of the specific error condition. Suitable for surfacing to end users or logging. |