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. Note: Transportation charge (baseCharge) = shipping + handling + any surcharges. 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 Shipping Lanes.

Prerequisites¶

You must contact Pitney Bowes and request to be enabled to use this API. Contact Client Support at GEC-TechSupport@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 you will not be able to provide an HS code every time you issue this API call, then 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¶

If the merchant is also a PB Fulfillment or delivery customer, include the merchant’s PB Client ID as the CLIENT_ID in the shipmentOptions array.
The response object is different from request object. The response object does not return all the elements passed in the request object.
The 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 shopping cart, the response body returns the error in the unitErrors or LineErrors 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 the additionalInfo 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 `application/json`.
Accept-Language	Language and country code. Default: `en-US`
X-PB-TransactionId	A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (`-`), and underscores (`_`).

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 `USD` for US Dollars, use `CAD` for Canadian Dollars, use `GDP` for the Pound Sterling, and use `EUR` for Euros. For all currency codes, see https://www.iso.org/iso-4217-currency-codes.html.
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 `USD`. For all currency codes, see https://www.iso.org/iso-4217-currency-codes.html.
fromAddress	Address Object	The origin address. This `fromAddress` is optional, but Pitney Bowes recommends that you include this object to get more accurate quotes. If included, the object requires following fields: `addressLines` `cityTown` `postalCode` `countryCode`
toAddress	Address Object	Required. Destination address. This object requires only the `countryCode` field (unless the destination is in Canada), but Pitney Bowes recommends including the full address for the most accurate quotes. For Canadian destinations, this object requires the `postalCode`, `stateProvince`, and `countryCode` fields.
customsInfo	Customs Info Object	Customs clearance information for the commercial invoice.
basketItems	Array[Basket 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` array requires this field.
shipmentOptions.value	String	The value of the shipment option. The `shipmentOptions` array requires this field.

Customs Info Object for CBDS Quotes¶

Name	Data Type	Description
currencyCode	String	Required. The type of currency used for the monetary values in this API request. Use three uppercase letters, per ISO 4217. For example, use `USD` for US Dollars, `CAD` for Canadian Dollars, and `EUR` for Euros. The full list of currency codes can be downloaded in XLS or XML from https://www.iso.org/iso-4217-currency-codes.html.
businessType	String	Enter the type of transaction. Valid values are: `B2B` `B2C` (Default)
firstMileShippingAmount	BigDecimal	If the merchant uses a Drop-Off delivery solution, enter the shipping cost associated with bringing the parcel to the Pitney Bowes facility. The value is used in the duty-and-tax calculation for countries that include the cost in the calculation.
firstMileInsuredAmount	BigDecimal	If the merchant uses a Drop-Off delivery solution, enter the insurance fee associated with bringing the parcel to the Pitney Bowes facility, if applicable. The value is used in the duty-and-tax calculation for countries that include the fee in the calculation.
shippingAmount	BigDecimal	Enter the end-to-end shipping cost in the currency specified in the `currencyCode` field. The value is used in the duty-and-tax calculation for countries that include the cost in the calculation. Required if the merchant uses the CBDS digital-only solution (i.e., the merchant does not ship via CBDS).
insuredAmount	BigDecimal	Enter the insurance fee. Enter the full end-to-end insurance fee, if applicable. The value is used in the duty-and-tax calculation for countries that include the fee in the calculation. Required if an insurance fee applies and the merchant uses the CBDS digital-only solution (i.e., the merchant does not ship via CBDS).
customsDeclaredValue	BigDecimal	Enter the value to declare in customs for the shipment. Enter the value in the currency specified in the `currencyCode` field.
EELPFC	String	A number provided by the Automated Export System (AES). Required if the item is valued at more than $2,500 USD per Schedule B export codes.
insuredNumber	String	If the sender wishes to insure the contents, they complete an insurance receipt and affix the insured numbered label to the package. The insured number label is what this field represents.
invoiceNumber	String	The commercial invoice number assigned by the exporter.
licenseNumber	String	The export license number associated with the commodity.
portOfClearance	String	CBDS Quotes: If the port of clearance for a shipment is different from the country of destination, enter the two-character ISO country code for the port of clearance. For example, enter `NL` if a shipment destined for Germany is cleared for customs in the Netherlands. If the port of clearance and destination country are the same, leave this field blank. Required if the port of clearance is different and the merchant uses the CBDS digital-only solution (i.e., the merchant does not ship via CBDS).
sdrValue	BigDecimal	When an international parcel is insured, the insured value must be expressed in Special Drawing Rights values. E.g. $100 USD = 66.87 SDR.

Basket Items Object¶

Name	Data Type	Description
Attributes	Object
brand	String	The manufacturer’s brand name for the item. Maximum length: 255 characters
condition	String	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: `new` `used` `refurbished` `damaged` `unknown`
description	String	Required. A detailed description of the commodity. Make the description as detailed as possible to facilitate assignment of the correct HS code. Maximum length: 255 characters
eccn	String	The Export Control Classification Number (ECCN) for the commodity. Maximum length: 10 characters
hazmat	Array[String]	For a HAZMAT-flagged item, enter one or more of the HAZMAT classifications listed here.
hSTariffCode	String	Required. 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. Maximum length: 14 characters
hSTariffCodeCountry	String	Required. The two-character ISO Country Code for the country supplying the HS code. This is usually the destination country.
identifiers	Array[Object]	Additional identifiers for the item. Each object in the array defines a type of identifier and its value.
identifiers.source	String	The type of identifier, such as `MPN`, `SKU`, `UPC`, `ISBN`, or `ISSN`. Enter the identifier as a string of up to 10 characters.
identifiers.number	String	The value of the identifier. Enter a string of up to 50 characters.
imageURL	Array[String]	Enter one or more URLs that link to an image of the commodity. Enter the URLs as strings, separated by commas. You can enter an empty string if you do not have a URL.
itemDimension	Dimension Object	The dimensions for a single item.
itemId	String	Required. The merchant’s unique identifier for the commodity, such as the SKU or item code. The value might be used to verify the product during customs clearance. To avoid shipment delays, the value should be unique for individual variants of a product. To avoid problems processing the order data, make sure the value does not include leading or trailing spaces. Maximum length: 50 characters
longDescription	String
manufacturer	String	The manufacturer of the item. Maximum length: 255 characters
originCountryCode	String	The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.
pricing	Object	The pricing information for the commodity. If the information is not in the shopping cart, then this information is used.
pricing.price	BigDecimal	List price of the item.
quantity	Integer	Required. Enter the total number of items of this type of commodity.
unitPrice	BigDecimal	Required. The price of one item of this type of commodity.
unitWeight	Object	The weight and unit of measure of one item of the commodity.
unitWeight.weight	Number	The weight of the item.
unitWeight.unitOfMeasurement	String	The unit of measurement. This field can take the following values: `OZ`: Ounces `GM`: Grams `G`: Grams `LB`: Pounds `KG`: Kilograms
url	String	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. Maximum length: 1000 characters

Response Elements¶

Name

Data Type

Description

quote

Array[Quote Object]

The quotes. The array contains a quote for each available shipping method requested. Each object in the array is a separate quote.

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 `X-PB-TransactionId` header. Used for tracking the transaction.
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 `basketItems` array.
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` object. Maximum 50 characters.
quoteLines.quantity	Number	The number of items of this commodity.
quoteLines.unitRates	Rates Object	The international Transportation and Importation costs for one commodity.
quoteLines.lineRates	Rates Object	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 `quoteCurrency`.
totalRates	Rates Object	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",
        "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"
        ],
        "itemDimension": {
            "length": 14.0,
            "height": 10.0,
            "width": 4.0,
            "unitOfMeasurement": "IN"
        },
        "itemId": "43953AE0",
        "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.	1005### codes
Item-specific errors (unit errors). These errors are returned in the following array: quote.quoteLines.unitErrors	1006### codes
Line errors. These errors are returned in the following array: quote.quoteLines.lineErrors	1007### codes
PB-APIM-ERR errors. These errors apply to API access or the validity of the API call.	PB-APIM-ERR codes

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