Lookup Tariff Codes
Classify
Overview
The Classify endpoint, offers a range of features to assist customers in classifying their products and validating pre-existing HS codes.
Using just a product name(description), Classify will provide the corresponding HS (Harmonized System) code. However, the more product details you provide, the more accurate your result will be. Learn about the best practices for Classify input fields.
By default, Classify returns a universal (6 digit) HS code if a destination country is not provided in the request. Universal codes are used by all WCO member countries; however, we recommend using country-specific codes for more accurate and smooth customs clearance experience.
To request a country-specific (8+ digit) classification, provide a destination country in your request. Learn more about the differences between universal and country-specific HS codes.
For example, if you request a country-specific HS code, Classify will return the WCO tariff schedule description for the chapter, heading, subheading, and tariff level codes.
URLs:
UAT: https://api.uat.nzpost.co.nz/lookup-tariff-codes/v1/classify/*
PROD: https://api.uat.nzpost.co.nz/lookup-tariff-codes/v1/classify/*
Where,
- The classify endpoint offers multiple classify options as listed below:
- ClassifyItems
- ClassifyAlternates
- ValidateAndClassify
- CheckCoherenceAndClassify
- ValidateOnly
- RetrieveClassifications
- BulkClasiffications
Usecases
Below are the use cases where the Classify endpoint and its various options can provide value to the API consumer.
| Usecases | Classify Option | For which scenario, this feature is used… |
|---|---|---|
| Get HS Code for Single/Multiple items | ClassifyItems | If I have single/multiple products to classify and have the name of the product, then use this option to get the a universal (6-digit) HS code in return.Additionally, if I provide the destination country along with the name of the product, then I will get a country-specific (8+ digit code) in return. |
| Get up to five HS Code Alternatives for single/multiple items | ClassifyAlternates | If I have a single / multiple product(s) to classify, but I also need to explore what are closely matched HS code alternatives and I have the name of the product(s), then use this option to get a list of HS code alternatives, each accompanied by a probability mass, providing additional options alongside the standard classify response. |
| Validate the Pre existing HS Codes | Validate only | If I have a HS code and I want to validate that HS code, then I only need to provide an HS code. If I want to validate a country-specific code, Then I also need to provide a ship-to country. This option will verify its validity against the current tariff schedule of the specified ship-to country in the request. |
| Validate and Classify | If I want to validate the HS code and then classify the request in case of an invalid HS code response, and I provide a name of the product along with the HS code, then it will return the appropriate HS code classification if the result is invalid. | |
| Check coherency and Classify | If I have a HS code and the name of the product, but I want to check the coherency of the HS code and description of the product, then I use this option to check the coherency of the provided HS code, then classify the request. This option provides the correct HS code option in case of an invalid response. | |
| Retrieve historical data for Pre Classiffied items | RetrieveClassifications | If I have an ID for an already requested classify option and I want to verify its response payload now then I can use this feature. |
| Get HS Code and descriptions for bulk items (1000 items) | BulkClasiffications | If I have bulk products to classify and have the name of each product, then use this option to get the a universal (6-digit) HS code in return for each product. Additionally, if I provide the destination country along with the name of the product, then I will get a country-specific (8+ digit code) in return. |
Features and descriptions - Classify Options
The Classify endpoint offers a range of classification and validation features based on the classify option you choose.
If you do not specify your preference in your classify request, we will default to ClassifyItems.
| Classify Option | Description | Rules |
|---|---|---|
| ClassifyItems | Request single/ multiple classifications. | Item name field is required. |
| BulkClasiffications | Request bulk classifications (1000 items) in a single request. | Item name field is required. |
| ClassifyAlternates | In a standard ClassifyItems response, Classify returns a single HS code. ClassifyAlternates, on the other hand, modifies the response to give you up to five HS code options. This will allow informed decision-making for your products classifications. | Item name field is required. |
| ValidateAndClassify | If you want to validate the code and then classify the request in case of an invalid HS code response, provide a name along with the HS code.This will ensure that item details to use as a basis for classification if the result is invalid. | Item HS code and name fields are required. |
| CheckCoherenceAndClassify | If you want to check the coherency of the code and then classify the request in case of an invalid HS code response, provide a name along with the HS code.This will ensure that item details to use as a basis for classification if the result is invalid. | Item HS code and name are required. |
| ValidateOnly | Provide an existing HS code to check its validity against the WCO tariff schedule. | Item HS code field is required. |
| RetrieveClassifications | Provide a classify id returned from Classify options (except ValidateOnly option) to retrieve historical quotes for pre-classified items. | Item id fields is required. |
Points to consider
- BulkClasiffications feature support up to 1000 items in a single API call and All other classify features support up to 100 items in a single API call.
- We have the Json Threat Protection policy enabled for this API. As a result, the maximum length allowed for a string value in the request payload is 200 characters. Please make sure to adhere to this limit when submitting requests
- To request a universal (6 digit) code, leave the destination country empty. To request a country-specific (8+ digit code), provide a destination country.
- While only a name or an HS code is required for classification/ validation, the more info (description, destination, and country-code, etc.) you provide the more accurate the classification will be.
- Classify currently supports country import codes only. It does not handle export codes such as the U.S. Census Bureau's Schedule B codes.
Classify Options
1. ClassifyItems
Using just a product name, ClassifyItems will provide the corresponding HS (Harmonised System) code. However, the more product details you provide, the more accurate your result will be. Learn about the best practices for Classify input fields.
By default, Classify returns a universal (6 digit) HS code if a destination country is not provided in the request. Universal codes are used by all WCO member countries; however, we recommend using country-specific codes.
The Classify object will return the chapter, heading, subheading, tariff country-specific HS code, and descriptions in the codes array.
| Fields to send in the Request | Fields return in the Response | |
|---|---|---|
| categories | Optional | id |
| countryOfOrigin | Optional | categories |
| description | Optional | confidenceScore |
| imageUrl | Optional | countryOfOrigin |
| itemAge | Optional | customsDescription |
| material | Optional | description |
| productId | Optional | imageUrl |
| configuration.itemKey | Optional | material |
| configuration.productId | Optional | name |
| configuration.shipToCountries | Optional (Required for 8+ digit code) | productId |
| configuration.sku | Optional | hsCode{ code description{friendly full htsItem} fragments { code type description} } |
| name | Required | configuration{ groupId itemKey marketProfile productId shipToCountry sku } |
2. ClassifyAlternates
ClassifyAlternates utilises an advanced method to generate diverse HS code alternatives. These alternatives rely on probability values associated with each subheading, derived from data indicating the likelihood of accurate classification. Each subheading alternate corresponds to its most likely tariff code, especially for country-specific requests.
The ClassifyAlternates response provides a list of HS code alternatives, each accompanied by a probability mass, providing additional options alongside the standard Classify response. This probability mass represents the confidence level, or the likelihood, that the product accurately fits under that specific HS code.
Within the ClassifyAlternates response, we offer up to five subheadings and tariff codes for each item, although the options may be fewer due to limited availability or the exclusion of those with very low probability masses.
| Fields to send in the Request | Fields return in the Response | |
|---|---|---|
| categories | Optional | id |
| countryOfOrigin | Optional | categories |
| description | Optional | countryOfOrigin |
| imageUrl | Optional | customsDescription |
| itemAge | Optional | description |
| material | Optional | imageUrl |
| productId | Optional | material |
| configuration.itemKey | Optional | name |
| configuration.productId | Optional | productId |
| configuration.shipToCountries | Optional (Required for 8+ digit code) | confidenceScore |
| configuration.sku | Optional | customsDescription |
| name | Required | hsCode { code description { friendly full htsItem} fragments { code description } } |
| configuration { groupId itemKey marketProfile productId shipToCountry sku } | ||
| alternates { subheadingAlternate { code fragments { code description } } probabilityMass tariffAlternates { code } } |
3. ValidateOnly
The ValidateOnly endpoint allows you to validate a pre-existing HS code.
To validate a 6 digit HS code, you only need to provide a 6 digit HS code.
If you want to validate a country-specific (8+ digit) tariff code, you will also need to provide a ship-to country.
| Fields to send in the Request | Fields return in the Response | |
|---|---|---|
| configuration.hsCodeProvided | Required | hsCode { codeType countryCode effectiveAt majorVersion code description { full friendly htsItem } fragments { code description type } } and hsCodeProvidedValidation { code result type } } |
| configuration.shipToCountries | Optional (Required for 8+ digit code) | configuration { shipToCountry sku } |
4. ValidateAndClassify
If you want to validate the HS code and then classify the request provide a name along with the HS code. In case, if the provided HS code is invalid, then this endpoint will use the provided name to get matching valid HS code.
When you choose to validate your provided HS code, ValidateAndClassify will verify its validity against the current tariff schedule of the specified ship-to country in the classification request. For example, if the request is for TW (Taiwan), we will check the 2022 tariff schedule for Taiwan. If the Taiwan HS code provided in the classification request is a non existent code or is from the 2017 version and has since been modified in the 2022 version, it will be marked as invalid.
If you don't provide a ship-to country when validating a universal 6 digit code, it will validate against the latest WCO tariff nomenclature schedule, currently the 2022 version, which updates every five years. If you provide more than 6 digits and you provide an 8+ country-specific HS code in the request, we'll ignore all digits beyond the universal 6. If the provided HS code is not found in any WCO version, ValidateAndClassify will ignore it, mark it as invalid, and Classify the item based solely on the product details provided in your request.
| Fields to send in the Request | Fields return in the Response | |
|---|---|---|
| categories | Optional | id |
| configuration.hsCodeProvided | Required | categories |
| configuration.hsCodeType | Optional | confidenceScore |
| configuration.itemKey | Optional | countryOfOrigin |
| configuration.productId | Optional | customsDescription |
| configuration.shipToCountries | Optional (Required for 8+ digit code) | description |
| configuration.sku | Optional | imageUrl |
| countryOfOrigin | Optional | material |
| description | Optional | name |
| imageUrl | Optional | productId |
| itemAge | Optional | hsCodeProvidedValidation { code result type } |
| material | Optional | hsCode { code description{friendly full htsItem} fragments { code type description} } |
| name | Required | configuration { groupId hsCodeProvided itemKey marketProfile productId shipToCountry sku } |
| productId | Optional |
5. CheckCoherenceAndClassify
When checking the coherency of a provided HS code, CheckCoherenceAndClassify goes beyond the validation process described above and also assesses whether the code provided matches the description of the item. This ensures that the HS code provided reasonably matches the characteristics of the item, resulting in an accurate HS code and seamless customs clearance.
Similar to ValidateAndClassify, when CheckCoherenceAndClassify is requested and the HS code is invalid, the provided HS code is ignored, and the classification is based on the product details. If the HS code is valid, CheckCoherenceAndClassify proceeds to check the coherency and determine whether the provided HS code was coherent, somewhat coherent, or not coherent.
If CheckCoherenceAndClassify deems the provided HS code “coherent”, it will return the provided HS code as the response. If the endpoint determines the provided HS code is “somewhat coherent” or “not coherent”, it ignores the provided HS code and classifies based on the name field provided. In either case, the endpoint will return the coherency status.
| Fields to send in the Request | Fields return in the Response | |
|---|---|---|
| categories | Optional | id |
| configuration.hsCodeProvided | Required | categories |
| configuration.hsCodeType | Optional | confidenceScore |
| configuration.itemKey | Optional | countryOfOrigin |
| configuration.productId | Optional | customsDescription |
| configuration.shipToCountries | Optional (Required for 8+ digit code) | description |
| configuration.sku | Optional | imageUrl |
| countryOfOrigin | Optional | material |
| description | Optional | name |
| imageUrl | Optional | productId |
| itemAge | Optional | hsCodeProvidedValidation { code result type } |
| material | Optional | hsCode { code description{friendly full htsItem} fragments { code type description} } |
| name | Required | configuration { groupId hsCodeProvided itemKey marketProfile productId shipToCountry sku } |
| productId | Optional |
6. RetrieveClassifications
The RetrieveClassifications option will help you to retrieve historical quotes for pre-classified items. For each Classify option (except for ValidateOnly) call, you will get a unique id in the response, as shown in the screenshot below. This id can be used to request the results obtained in a previous Classify options requests.
The following is a JSON response payload from a ClassifyItems API call.
The id can be used in a RetrieveClassifications API call to retrieve the original API response for the ClassifyItems call.
The id can be used to retrieve data for up to one year from the original API request.
| Fields to send in the Request | Fields return in the Response | |
|---|---|---|
| id | Required | categories |
| confidenceScore | ||
| countryOfOrigin | ||
| createdAt | ||
| customsDescription | ||
| description | ||
| id | ||
| imageUrl | ||
| material | ||
| mode | ||
| name | ||
| productId | ||
| alternates { probabilityMass subheadingAlternate { code codeType countryCode } tariffAlternates { code codeType countryCode description { friendly full htsItem } fragments { code description type } } } | ||
| configuration { groupId hsCodeProvided itemKey marketProfile productId shipToCountry sku } hsCode { code codeType countryCode } |
7. BulkClasiffications
Using just a product name, BulkClasiffications will provide the corresponding HS (Harmonised System) code. However, the more product details you provide, the more accurate your result will be. Learn about the best practices for Classify input fields.
By default, Classify returns a universal (6 digit) HS code if a destination country is not provided in the request. Universal codes are used by all WCO member countries; however, we recommend using country-specific codes.
The Classify object will return the chapter, heading, subheading, tariff country-specific HS code, and descriptions in the codes array. This fauture allows to classify up to 1000 items in a single call.
| Fields to send in the Request | Fields return in the Response | |
|---|---|---|
| categories | Optional | id |
| countryOfOrigin | Optional | categories |
| description | Optional | confidenceScore |
| imageUrl | Optional | countryOfOrigin |
| itemAge | Optional | customsDescription |
| material | Optional | description |
| productId | Optional | imageUrl |
| configuration.itemKey | Optional | material |
| configuration.productId | Optional | name |
| configuration.shipToCountries | Optional (Required for 8+ digit code) | productId |
| configuration.sku | Optional | hsCode{ code description{friendly full htsItem} fragments { code type description} } |
| name | Required | configuration{ groupId itemKey marketProfile productId shipToCountry sku } |
Below are the tables detailing each field in the Request and Response payloads.
Input Fields (classify_request)
It is important to note that while only a few fields are required to call each classify_option, providing more product details can greatly enhance the accuracy of the Classify results.
Below is a comprehensive explanation of each input field accepted by Classify. By understanding these input fields, you can maximize their usage and generate highly accurate classifications.
| Field Name | Description |
|---|---|
| name | The name of the product. |
| description | An in-depth, long-form description of the product. |
| imageUrl | Link to an image of the product. Note: Make sure you use a link to the actual image URL and not the product page URL. |
| imageAge | The items physical age. E.g. 2years. |
| id | A unique identifier returned in the Classification responses except for ValidateOnly. This id can be used to retrieve the pre-classified items details by using RetrieveClassifications Classify option. |
| categories | General sub-product categories, e.g. Clothing & Accessories, Pet Supplies, Office Products or Baby Clothes, Pet Beds, Adhesives & Tape. |
| material | What the product is made from, e.g. plastic, wood, steel. |
| countryOfOrigin | The two-letter abbreviation (ISO code) for the country of manufacture or production of the product. |
| hsCodeProvided | Include an existing HS code in your classification request to guide the API. Depending on your preference and the origin of your provided HS code, Classify can validate the HS code and check its coherency against the item's description details. |
| shipToCountry | Identifies which country the product will be classified to. The destination country must be displayed with each country’s two-letter abbreviation (ISO code)] and not the actual country name, e.g. AU, not Australia. Including this field will enable Classify to return an 8+ digit country-specific HS code instead of the universal 6 digit code. |
| productId | Your internal product ID or any number that can be used to uniquely identify each product. |
| request_id | An optional ID that allows us to identify your request in our systems. This can be useful if we need to provide support for individual API requests. If the value is unique it makes it easier for us to provide support. For example, 'T8RF9S'. |
Output Fields (classify_response)
The Classify endpoint returns the following fields in the response based on the classify_option requested. Please refer to API Specification types for more information about each field.
| Field Name | Description |
|---|---|
| success | Flag indicating success or failure of the request. Values are true or false. |
| request_id | The optional ID provided in the original API request that allows us to identify your request in our systems. For example, 'T8RF9S'. |
| message_id | A globally-unique system-generated id associated with the request. E.g. 52fe9dca-7672-4938-a648-a75e272b4136. If requesting support, providing this value to us greatly improves our ability to help you. |
| classify_option_provided | User provided classify_option while requesting classifications. E.g. ClassifyItems. |
| alternates | In a standard response, Classify returns a single HS code. Classify alternates, on the other hand, modifies the response to give you up to five HS code options. |
| categories | The category hierarchy associated with an item for classification. E.g. "Wireless phone" or ["Wireless phone"]. |
| confidenceScore | Measures the confidence in accuracy of an HS code generated by Classify. This allows you to easily flag codes that may be inaccurate for refinement. E.g. 1.0=100%. |
| countryOfOrigin | The ISO 3166 code to indicate which country the CatalogItem was manufactured in to generate an accurate Classification. Two letter country code. E.g. IN. |
| customsDescription | The calculated description for customs. E.g. Luggage bags. |
| description | The full description associated with an item. E.g. "Luggage bags cases wallets purses boxes and similar containers of leather plastics textile materials or of paper." |
| hsCode | The HsCode object. This object contains HS code related information, for example the HS code is under the 'code' field. For details on the additional child objects check the API documentation. |
| hsCodeProvidedValidation | The status of the customer or third party provided hsCode. |
| hsCodeProvidedValidationResult | The status of the overall hsCodeProvidedValidation. E.g. VALID, INVALID. |
| id | A unique identifier returned in all Classification responses except for ValidateOnly. This id can be used to retrieve the pre-classified items details by using RetrieveClassifications Classify option. |
| imageUrl | If you provided an imageUrl in your original API request, it will be returned in the response payload. |
| imageAge | If you provided an imageAge in your original API request, it will be returned in the response payload. |
| material | The material composition of an item for classification. E.g. Leather. |
| name | The product name or short description. E.g. Leather Bag. |
| productId | The product id provided at time of classification input. |