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.

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

Customs Items Object

Required. The item details used for classification. The item field contains a customs items object. The following fields in the object are required:

  • categories

  • description

  • unitPrice

shipmentOptions

Array[Object]

Required. Specifies the merchant’s CBDS Client ID. Pitney Bowes provided this ID when the merchant onboarded to use CBDS.

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 merchant the Client ID when the merchant onboards with CBDS.

Categories Object (Request Only)

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.

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.

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

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.