Retrieve the Predicted HS Code

HTTP Request

POST /v1/crossborder/hs-classification/items

Summary

This operation predicts the HS code for a parcel being shipped internationally and gives the level of confidence in the prediction.

Considerations

1. To use this API, provide a category tree to Pitney Bowes.

2. You can supply the HS code from another country to help with the prediction. To do so, include the following fields in the request:

   • item.hSTariffCode: Set this to the HS code that another country uses for the commodity.

   • item.hSTariffCodeCountry: Set this to the country code of that country.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/crossborder/hs-classification/items
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/crossborder/hs-classification/items

Request Header

Name	Description
Authorization	Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type	Required. The media type of the request entity. Set this to application/json.
X-PB-TransactionId	Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_). Important: Ensure this is a unique ID.

Request Elements

Name	Data Type	Description
fromCountry	String	Required. The origin country for the shipment.
toCountry	String	Required. The destination country for the shipment.
customsInfo	Object	Required. Sets the currency code.
customsInfo.currencyCode	String	Required. The type of currency referenced in the piece price. Use three uppercase letters, per ISO 4217. For example, use USD for US Dollars, use CAD for Canadian Dollars, and use EUR for Euros. For all currency codes, see https://www.iso.org/iso-4217-currency-codes.html.
item	Item Object	Required. The commodity details. The API uses this information for classification.
shipmentOptions	Array[Object]	Required. Specifies the merchant’s CBDS client ID.
shipmentOptions.name	String	Required. Set this to CLIENT_ID.
shipmentOptions.value	String	Required. Set this to the merchant’s CBDS client ID. Pitney Bowes assigns the client ID when the merchant onboards with CBDS.

Item Object

Name	Data Type	Description
categories	Array[Categories Object]	Required. The commodity’s category information based on the category tree supplied to Pitney Bowes.
description	String	Required. A detailed description of the commodity. Make the description as detailed as possible to facilitate assignment of the correct HS code. Maximum length: 255 characters
unitPrice	BigDecimal	Required. The price of one item of this type of commodity.
eccn	String	The Export Control Classification Number (ECCN) for the commodity, up to 10 characters.
hazmat	Array[String]	For a HAZMAT-flagged item, enter one or more of the HAZMAT classifications listed here.
hSTariffCode	String	To help with prediction, you can use this field to supply the HS code from another country. Set this to the HS code that another country uses for the commodity, up to 14 characters. Indicate which country in the hSTariffCodeCountry field.
hSTariffCodeCountry	String	To help with prediction, set this to the two-character ISO Country Code for the country supplying the HS code in the hSTariffCode field. Required if the hSTariffCode field is used.
itemId	String	The merchant’s unique identifier for the commodity, such as the SKU or item code. Make sure the value does not include leading or trailing spaces. Maximum length: 50 characters
manufacturer	String	The manufacturer of the item, up to 255 characters.
originCountryCode	String	The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.
url	String	The commodity’s URL on the merchant site, up to 1000 characters.

Categories Object

The item.categories array takes the categories object.

Name	Data Type	Description
categoryCode	String	Required. The item’s category identifier based on the product categories agreed on with Pitney Bowes. The maximum length is 50 characters.
categoryNamePath	String	Hierarchical path to the category represented by the category name of each level, concatenated with a pipe (|) delimiter. For example: CONSUMABLES AND GROCERY|BABY|BABY CARE|BABY CONSUMABLES|BABY FOOD
categoryCodePath	String	Hierarchical path to the category represented by the category ID of each level, concatenated with a colon delimiter. For example: 9785:8266:9798:9799:10203
parentCategoryCode	String	Parent category of the item’s category identifier, based on the merchant product categories agreed on with Pitney Bowes. Maximum 50 characters.
descriptions	Array[Object]	The description of the category. You can include multiple objects for descriptions in multiple languages.
descriptions.locale	String	The language used for the category description. For example, en_US. The maximum length is 10 characters. This field is required by the descriptions array.
descriptions.name	String	The category description. The maximum length is 255 characters. This field is required by the descriptions array.
descriptions.parentsNames	Array[String(255)]	The tree of parent names to reach this category. parentNames[0] must be the top-level name, and parentNames[Max Length-1] must be the name of the parent category containing this category. Maximum 255 characters.
categorySiteId	String	The category site ID if the eBay category is referred.

Response Elements

Name	Data Type	Description
classificationResult	Object	An object containing the predicted HS code and the level of confidence in the prediction.
classificationResult.hscode	String	The predicted HS code for the item.
classificationResult.qualityLevel	String	The level of confidence in the prediction. Possible values: HIGH MEDIUM LOW
classificationResult.transactionId	String	The unique identifier supplied in the X-PB-TransactionId header.
classificationResult.pbTransactionId	String	A Pitney Bowes-generated identifier for tracking the transaction.

Sample Request

curl -X POST ".../v1/crossborder/hs-classification/items" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 49612270" \
-d '
{
    "fromCountry": "CN",
    "toCountry": "US",
    "customsInfo": {
        "currencyCode": "USD"
    },
    "item": {
        "categories": [ {
            "categoryCode": "CATEGORY_0345",
            "categoryNamePath": "Apparel|Sportswear|Hiking",
            "categoryCodePath": "CATEGORY_0009:CATEGORY_0055:CATEGORY_0345"
        } ],
        "description": "Men's Gore-Tex Ultralight Packable Windproof Insect Shield Jacket",
        "itemId": "G_123456",
        "unitPrice": 120.00,
        "url": "http://www.example.com/shop/jackets/G_123456"
    },
    "shipmentOptions": [ {
        "name": "CLIENT_ID",
        "value": "ABCD
    } ]
}'

Sample Response

{
    "classificationResult": {
        "hscode": "6201935220",
        "qualityLevel": "MEDIUM",
        "transactionId": "49612270",
        "pbTransactionId": "d4f4ffb6-c518-4ad1-843b-5212b688be6c"
    }
}

Error Codes

The HS Code API returns 70-Prefix Error Codes (Retrieve HS Code API).

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.

 
 
 
 

• next
• previous |

© Copyright 2023 Pitney Bowes Inc. All rights reserved.