Request CBDS Quotes for all Items in a Shopping Cart¶
HTTP Request¶
POST /v1/crossborder/checkout/quotes
Summary¶
This operation integrates with Pitney Bowes Cross-Border Delivery Service (CBDS) to provide an estimate of the duties, taxes, and transportation costs for each item in a buyer’s online shopping cart. The API returns quotes for all eligible items. If an item in the cart is ineligible—for example if an item is oversized—the API returns quotes for all eligible items and returns an item-specific error for the ineligible item.
CBDS estimates costs based on the destination address, the service level, and the item details. The more details provided in the API request, the more accurate is the estimate. The quotes are estimates and not guarantees.
For supported countries and services, see Supported Countries (Shipping Lanes).
Prerequisites¶
You must contact Pitney Bowes and request to be enabled to use this API. Contact Client Support at ClientSupportTechServices@pb.com.
This API uses the commodity’s HS code for tariff classification. Pitney Bowes provides two options for supplying an HS code:
Provide the HS code in the API request’s
basketItems.hSTariffCode
field whenever you issue this API call. If you choose this option, you must always provide an HS code when invoking this API.Example:
"basketItems": [ { "hSTariffCode": "4203100001", ... } ]
If will not be able to provide an HS code every time you issue this API call, then you must provide Pitney Bowes a category tree before you first use this API. Pitney Bowes will use the category tree to assign HS codes. If you do not have a category tree, Pitney Bowes can provide one.
Considerations¶
The
toAddress
requires only thecountryCode
field (unless the destination is in Canada), but Pitney Bowes recommends including the full address for the most accurate quotes.For Canadian destinations, the
toAddress
also requires thepostalCode
andstateProvince
fields.The
fromAddress
is optional but if specified in the request, it must include the following:addressLines
cityTown
postalCode
countryCode
If the merchant is also a PB Standard fulfillment or delivery customer, include the merchant’s PB Standard Client ID as the
CLIENT_ID
in theshipmentOptions
array.The Quotes API’s response object is different from request object. The response object does not return all the elements passed in the request object.
The Quotes API can return a successful response even if there are errors with one or more items in the shopping cart.
If there is an error with an item in the shipping cart, the response body returns the error in the
unitErrors
orLineErrors
field. An item would return an error if, for example, it were missing mandatory information or had restrictions.If an item is found to be restricted, the API returns error
1006009
for the item and returns the restriction information in theadditionalInfo
field. The API still returns quotes for remaining items in the cart.
Request URLs¶
Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/crossborder/checkout/quotes
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/crossborder/checkout/quotes
Request Headers¶
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 |
Accept-Language |
Language and country code. Default: |
X-PB-TransactionId |
A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens ( |
Note: This operation returns errors using the standard error object, and therefore it is not necessary to include the X-PB-UnifiedErrorStructure header in the API request.
Request Elements¶
Name |
Data Type |
Description |
---|---|---|
quoteCurrency |
String |
Required. The currency to return the quotes in. Enter the currency of your (the developer’s) country. Use three uppercase letters, per ISO 4217. For example, use |
basketCurrency |
String |
Required. The default currency of the shopping cart. Enter the currency of your (the developer’s) country. Use three uppercase letters, per ISO 4217. For example, for US Dollars use |
fromAddress |
The origin address. Pitney Bowes recommends that you include this information to get more accurate quotes. The object requires following fields, as noted above in Considerations:
|
|
toAddress |
Required. Destination address. This object requires only the |
|
customsInfo |
Customs clearance information. |
|
basketItems |
Array[Customs Items Object] |
Required. The items in the buyer’s shopping cart. Each object in the array specifies a different item. |
rates |
Array[Rates Object] |
Required. Specifies the carrier, service, parcel, and other information. In a response, this field also contains the service charges. |
shipmentOptions |
Array[Object] |
Any shipment options to be applied. Each object in this array defines a different option. |
shipmentOptions.name |
String |
The name of the shipment option. The |
shipmentOptions.value |
String |
The value of the shipment option. The |
Basket Items¶
The basketItems array takes the Customs Items object, described in the table below. The fields that apply to CBDS are marked CBDS. Some fields in the table below do not apply to this operation. The table lists fields alphabetically.
Name |
Data Type |
Description |
---|---|---|
brand |
String |
CBDS Only. The manufacturer’s brand name for the item. The maximum length is 255 characters. |
categories |
Array[Categories Object] |
CBDS Only. Conditional. Associated categories. The merchant’s category tree must have been provided to Pitney Bowes in advance. Do not use this array if the merchant did not provide a category tree. This field is required by the HS Code API. |
condition |
String |
CBDS Only. Condition of the commodity. If the merchant is using an eBay-specific category tree, enter the eBay item’s conditionId. Otherwise use one of the following values:
|
description |
String |
Required. A detailed description of the commodity. For CBDS, make the description as detailed as possible to facilitate assignment of the correct HS code. |
eccn |
String |
CBDS Only. The Export Control Classification Number (ECCN) for the commodity. The maximum length is 10 characters. |
hazmats |
Array[String] |
CBDS Only. For a HAZMAT-flagged item, enter one or more of the HAZMAT classifications listed here. |
hSTariffCode |
String |
Conditional. The destination country’s tariff-classification number for the commodity. Most countries use the six-digit Harmonized System (HS) as the basis for their tariff classifications and add additional digits for more detail. The maximum length is 14 characters. This field is required for the Shopping Cart Quotes API. If you are using the Predicted HS Code API, you can supply the HS code from another country in this field to help with the prediction. See the instructions in the API’s Considerations. |
hSTariffCodeCountry |
String |
CBDS Only. Conditional. The two-character ISO Country Code for the country supplying the HS code. This is usually the destination country. This field is required if the |
identifiers |
Array[Object] |
CBDS Only. Additional identifiers for the item. Each object in the array defines a type of identifier and its value. |
identifiers.source |
String |
CBDS Only. The type of identifier, such as |
identifiers.number |
String |
CBDS Only. The value of the identifier. Enter a String of up to 50 characters. This field is required by the |
imageURL |
Array[String] |
CBDS Only. Enter one or more URLs that link to an image of the commodity. Enter the URLs as Strings, separated by commas. |
itemDimension |
CBDS Only. The dimensions for a single item. To enter dimensions, see the Dimension Object. |
|
itemId |
String |
CBDS Only. Required. The merchant’s unique identifier for the commodity, such as the SKU. The maximum length is 50 characters. |
manufacturer |
String |
CBDS Only. The manufacturer of the item. The maximum length is 255 characters. |
netCostMethod |
String |
UPS Only. |
originCountryCode |
String |
Conditional. The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values. This field is required by FedEx and UPS. |
originStateProvince |
String |
UPS Only. |
preferenceCriterion |
String |
UPS Only. |
pricing |
Object |
CBDS Only. The pricing information for the commodity. If the information is not in the shopping cart, then this information is used. |
pricing.price |
BigDecimal |
CBDS Only. List price of the item. |
producerAddress |
UPS Only. |
|
producerDetermination |
String |
UPS Only. |
producerId |
String |
UPS Only. |
quantity |
Integer |
Required, except for the HS Code API. Enter the total number of items of this type of commodity. For PB Expedited (USPS), the number of items cannot exceed 9999. USPS limits the number of items of one commodity to 9999. Note: This field is optional for the HS Code API. |
quantityUOM |
String |
FedEx, UPS Only. Required. The 1-to-3 character code for the unit of measurement, such as |
unitPrice |
BigDecimal |
Required. The price of one item of this type of commodity. |
unitWeight |
Object |
Required, except for CBDS. The weight and unit of measure of one item of the commodity. Note: This field is optional for CBDS. |
unitWeight.weight |
Number |
The weight of the item. This field is required by the |
unitWeight.unitOfMeasurement |
String |
The unit of measurement. This field is required by the |
url |
String |
CBDS Only. Required. Enter the commodity’s URL on the merchant site. Ensure the URL works. Providing an accurate URL helps Pitney Bowes assign the correct HS code. The maximum length for this field is 1000 characters. |
Response Elements¶
Name |
Data Type |
Description |
---|---|---|
quote |
Array[CBDS Quote Object] |
The quotes. The array contains a quote for each available shipping method requested. Each object in the array is a separate quote. |
CBDS Quote Object¶
Name |
Data Type |
Description |
---|---|---|
errors |
Array[Error Object] |
Any quote-level errors. |
quoteCurrency |
String |
The currency of the quote, returned as a three-character code per ISO 4217. For possible codes, see https://www.iso.org/iso-4217-currency-codes.html. |
transactionId |
String |
The transaction ID supplied by the client as part of the |
pbTransactionId |
String |
A unique Pitney Bowes generated identifier used for tracking the transaction. |
quoteLines |
Array[Object] |
The line-level detail of the quote. The lines are returned in the same order
as the items are listed in the request’s |
quoteLines.lineId |
String |
The unique identifier for the line within the input basket. Maximum 50 characters. |
quoteLines.itemId |
String |
The merchant’s unique identifier for the commodity. Maximum 50 characters. |
quoteLines.quoteLineId |
String |
The unique identifier for the line within the |
quoteLines.quantity |
Number |
The number of items of this commodity. |
quoteLines.unitRates |
The international Transportation and Importation costs for one commodity. |
|
quoteLines.lineRates |
Each of the elements of the unitRates multiplied by quantity. |
|
quoteLines.lineErrors |
Array[Error Object] |
Any errors on the quantity of the commodities on the line. |
quoteLines.unitErrors |
Array[Error Object] |
Any errors on the individual commodity. |
totalPrice |
BigDecimal |
The total value of the commodities, returned in the currency listed in |
totalRates |
The rates for every requested service level. |
Sample Request¶
See the following examples:
Sample CBDS Quotes Request¶
curl -X POST .../v1/crossborder/checkout/quotes \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 774318678" \
-d '
{
"quoteCurrency": "USD",
"basketCurrency": "USD",
"fromAddress": {
"addressLines": [ "2935 Lorne Avenue" ],
"cityTown": "Saskatoon",
"postalCode": "S7J 0S5",
"countryCode": "CN"
},
"toAddress": {
"countryCode": "US"
},
"customsInfo": {
"currencyCode": "USD",
"businessType": "B2C",
"firstMileShippingAmount": 1.12,
"firstMileInsuredAmount": 0.42,
"shippingAmount": 4.12,
"insuredAmount": 1.00,
"customsDeclaredValue": 90.00
},
"basketItems": [ {
"Attributes": {
"type": "material",
"name": "fabric",
"value": "cotton"
},
"brand": "Acme Brand",
"categories": [ {
"categoryCode": "UNKNOWN",
"parentCategoryCode": "6500",
"descriptions": [ {
"locale": "en_US",
"name": "Shirts",
"parentsNames": [ "Clothing", "Men" ]
} ],
"categoryNamePath": "Clothing|Men|Shirts",
"categoryCodePath": "3400:6500:4356"
} ],
"condition": "new",
"description": "clothing men shirt casual button-down slim fit cotton wrinkle-free single-needle construction",
"eccn": "EAR99",
"hSTariffCode": "6203221000",
"hSTariffCodeCountry": "US",
"identifiers": [ {
"number": "841843",
"source": "MPN"
} ],
"imageURL": [
"http://www.example.com/shop/43953AE0/image01.png"
],
"itemId": "43953AE0",
"itemDimension": {
"length": 14.0,
"height": 10.0,
"width": 4.0,
"unitOfMeasurement": "IN"
},
"longDescription": "clothing men shirt casual button-down slim fit cotton wrinkle-free single-needle construction",
"manufacturer": "Acme Inc.",
"originCountryCode": "US",
"quantity": 2,
"unitPrice": 45.00,
"unitWeight": {
"weight": 12,
"unitOfMeasurement": "OZ"
},
"url": "http://www.example.com/shop/43953AE0"
} ],
"rates": [ {
"carrier": "PBI",
"serviceId": "PBXPS"
} ],
"shipmentOptions": [ {
"name": "CLIENT_ID",
"value": "01200340"
},{
"name": "CARRIER_FACILITY_ID",
"value": "12349876"
} ]
}'
Sample CBDS Quotes Response¶
{
"quote": [ {
"quoteCurrency": "USD",
"transactionId": "774318678",
"pbTransactionId": "5bb4d0e3-afde-46a5-922e-66256fc24c6c",
"quoteLines": [ {
"lineId": "1",
"itemId": "43953AE0",
"quoteLineId": "1",
"quantity": 2,
"unitRates": {
"unitPrice": 45,
"totalTaxAmount": 3.12,
"totalDutyAmount": 0,
"serviceId": "PBXPS",
"baseCharge": 5.62,
"deliveryCommitment": {},
"totalCarrierCharge": 11.74
},
"lineRates": {
"linePrice": 90,
"totalTaxAmount": 6.24,
"totalDutyAmount": 0,
"serviceId": "PBXPS",
"baseCharge": 11.24,
"deliveryCommitment": {},
"totalCarrierCharge": 17.48
}
} ],
"totalPrice": 90,
"totalRates": {
"serviceId": "PBXPS",
"baseCharge": 0,
"deliveryCommitment": {},
"totalCarrierCharge": 0,
"totalDutyAmount": 0,
"totalTaxAmount": 0
}
} ]
}
Sample CBDS Quotes Response with Errors¶
{
"quote": [ {
"quoteCurrency": "USD",
"quoteLines": [ {
"lineId": "1",
"merchantComRefId": "13MS-1234567",
"quantity": 1,
"unitErrors": [ {
"error": 1006012,
"message": "Categories associated with the commodity are not available for quoting"
} ]
} ],
"errors": [ {
"error": 1005011,
"message": "There are errors at the Quote Item Level"
} ]
} ]
}
Error Codes¶
This operation returns the following errors:
Error Type |
Codes |
---|---|
Quote-level errors. |
|
Item-specific errors (unit errors). These errors are returned in the following array: quote.quoteLines.unitErrors
|
|
Line errors. These errors are returned in the following array: quote.quoteLines.lineErrors
|
|
PB-APIM-ERR errors. These errors apply to API access or the validity of the API call. |
For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.