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.

Things to Consider

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

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/crossborder/hs-classification/items
Production: https://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.

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.
      currencyCode String Required. Type of currency referenced in the piece price. Use three uppercase letters, per ISO 4217. For example: USD, CAD, EUR.
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.
      name String Required. Set this to CLIENT_ID.
      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.
      hscode String The predicted HS Code for the item.
      qualityLevel String

The level of confidence in the prediction. Possible values:

  • HIGH
  • MEDIUM
  • LOW
      transactionId String The unique identifier supplied in the X-PB-TransactionId header.
      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 following errors are returned by the Retrieve HS Code API:

Error Code Error Description  
7001004 Required field value(s) are missing from the input record  
7001005 Invalid Value.  
7001012 Value exceeds supported maximum length  
7002001 Error while classifying commodity.  
7002002 The prediction services are not configured to classify for this merchant  
7002009 The prediction services are not configured to classify for this category  

For a list of all PB Shipping APIs error codes, please see Error Codes.