Importable Tariff API Documentation

The Importable API provides developers with access to tariff information, item search, and detailed item descriptions. The API supports Bearer Token authentication, where each request consumes one token. Tokens do not expire and are required for all requests.

Setup

1. Generate Bearer Token

Before you can make requests to the API, you'll need to generate a Bearer token from your user account.

Steps to Generate a Token:

  1. Log in to your Importable account.
  2. Navigate to the API section of your Account Info page.
  3. Click on the "Generate Access Token" button.
  4. Once generated, the token will be displayed. Copy this token for use in your API requests.
Important Notes:
  • Tokens do not expire.
  • Each request consumes 1 token.
  • Ensure that API Access is enabled in your account settings by clicking "Enable API" if it’s not already activated.

2. Authentication (Bearer Token)

All API requests must include the Bearer token for authentication. This is done by setting an Authorization header in your HTTP requests.

How to Include the Bearer Token in Your Requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Where YOUR_ACCESS_TOKEN is the token you generated from your account page.

Content-Type Header:

When sending requests expect JSON data. Include the following header:

Content-Type: application/json

3. Base URL

The base URL for the API is:

https://importable.app

This is the root URL for all API endpoints, and you will append the specific endpoint paths to this base URL.

Authentication Failure

If authentication fails (e.g., due to an invalid or missing token), the API will return the following response:

{
    "message": "Unauthenticated."
}

Endpoints

1. Get Tariff

Retrieve detailed information about a specific tariff code.

Endpoint:

GET /api/v1/tariffs/{tariff_code}

Parameters:

  • tariff_code (required): The unique code representing the tariff (formatted as 9999.9999).

Sample Request:

GET /api/v1/tariffs/2815.1100

Response Format:

{
    "links": {
        "self": "https://importable.app/api/v1/tariffs/2815.1100"
    },
    "data": {
        "type": "tariffs",
        "id": "2815.1100",
        "attributes": {
            "code": "2815.1100",
            "general_rate": 0.45,
            "excise_rate": null,
            "specific_rate": null,
            "specific_rate_type": null,
            "environmental_levy": null,
            "environmental_levy_type": null
        }
    }
}

Query Parameter: include=descriptions

The include=descriptions query parameter will return hierarchical descriptions for the tariff code.

Sample Request with include=descriptions:

GET /api/v1/tariffs/2815.1100?include=descriptions

Sample Response with Descriptions:

{
    "links": {
        "self": "https://importable.app/api/v1/tariffs/2815.1100?include=descriptions"
    },
    "data": {
        "type": "tariffs",
        "id": "2815.1100",
        "attributes": {
            "code": "2815.1100",
            "general_rate": 0.45,
            "excise_rate": null,
            "specific_rate": null,
            "specific_rate_type": null,
            "environmental_levy": null,
            "environmental_levy_type": null
        },
        "descriptions": {
            "code": "2815.1100",
            "article_description": "Solid",
            "subheading": {
                "has_subheading": false,
                "code": "",
                "article_description": ""
            },
            "subheadingx": {
                "has_subheadingx": true,
                "code": "2815.1",
                "article_description": "Sodium hydroxide (caustic soda)"
            },
            "heading": {
                "has_heading": true,
                "code": "2815",
                "article_description": "Sodium hydroxide (caustic soda); potassium hydroxide (caustic potash); peroxides of sodium or potassium."
            }
        }
    }
}

Response Attribute Explanation:

  • code: The tariff code (e.g., 2815.1100).
  • general_rate: The duty rate as specified in the tariff schedule, in decimal format (e.g., 0.45 means 45%). It will be 0 for duty-free and null if not applicable.
  • excise_rate: The excise duty rate, or null if not applicable.
  • specific_rate: The specific rate for the tariff code, or null if not applicable.
  • specific_rate_type: The specific rate type, which can be one of the following values:
    • PFG - Proof Gallon
    • USG - US Gallon
    • IPG - Imperial Gallon
    • STK - Stick
  • environmental_levy: The environmental levy amount, percentage, or null if not applicable.
  • environmental_levy_type: Either PERCENTAGE or FIXED, indicating the type of levy.

2. Search Items

Search for items based on a query string.

Endpoint:

GET /api/v1/search

Parameters:

  • q (required): The search query string.

Sample Request:

GET /api/v1/search?q=tv

Sample Response:

{
    "links": {
        "self": "https://importable.app/api/v1/search?q=tv"
    },
    "data": [
        {
            "type": "items",
            "id": "1f209fe0-a946-11ef-ba9e-0cf6ac7c678f",
            "attributes": {
                "description": "TV Box",
                "attributes": null
            }
        },
        {
            "type": "items",
            "id": "1f2787d8-a946-11ef-ba9e-0cf6ac7c678f",
            "attributes": {
                "description": "TV Mount",
                "attributes": null
            }
        }
        ]
}

Response Attribute Explanation:

  • id: The unique identifier for the item.
  • description: A textual description of the item.
  • attributes: Characteristics of the item to differentiate it from other items of the same description.

3. Get Item

Retrieve detailed information for a specific item.

Endpoint:

GET /api/v1/items/{item_id}

Sample Request:

GET /api/v1/items/1f209fe0-a946-11ef-ba9e-0cf6ac7c678f

Sample Response:

{
    "links": {
        "self": "https://importable.app/api/v1/items/1f209fe0-a946-11ef-ba9e-0cf6ac7c678f"
    },
    "data": {
        "type": "items",
        "id": "1f209fe0-a946-11ef-ba9e-0cf6ac7c678f",
        "attributes": {
            "description": "TV Box",
            "attributes": null,
            "tariff": {
                "code": "8528.7110",
                "general_rate": 0,
                "excise_rate": null,
                "specific_rate": null,
                "specific_rate_type": null,
                "environmental_levy": 5,
                "environmental_levy_type": "FIXED"
            }
        }
    }
}

Error Codes and Responses

401 - Unauthorized

If authentication fails (e.g., invalid or missing token), the API will return:

{
    "message": "Unauthenticated."
}

422 - Unprocessable Entity

Occurs when the q parameter is missing in the Search Items request.

{
    "message": "Query parameter q is required to search."
}

429 - Too Many Requests

Occurs when the user has exhausted their available tokens or their API access is disabled.

Response for Exhausted Tokens:

{
    "message": "No tokens available."
}

Response for Inactive API Access:

{
    "message": "No active API access."
}

404 - Not Found

Occurs when the specified tariff id or item id cannot be found in the database.

Response for No Tariff:

{
    "message": "The tariff code provided was not found."
}

Response for No Item:

{
    "message": "No item for the id provided."
}