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. 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:
|
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:
|
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.