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¶

To use this API, the merchant must have provided a category tree to Pitney Bowes when onboarding with CBDS.

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: You must 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 following fields in the Customs Items 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.

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 7-digit codes beginning 700####.

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