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.

Prerequisites

  1. You must contact Pitney Bowes and request to be enabled to use this API. Contact Client Services Tech Support at ClientServicesTechSupport@pb.com.
  2. To help CBDS calculate duties and taxes more accurately, provide Pitney Bowes a category tree before using this API. If you do not have a category tree, Pitney Bowes can provide one.

Things to Consider

  1. The toAddress 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, the toAddress also requires the postalCode and stateProvince fields.

  2. The fromAddress is optional but if specified in the request, it must include the following:

    • addressLines
    • cityTown
    • postalCode
    • countryCode
  3. If the merchant is also a PB Standard fulfillment or delivery customer, include the PB Standard Merchant ID as the CLIENT_ID in the shipmentOptions array.

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

  5. The Quotes API can return a successful response even if there are errors with one or more items in the shopping cart.

  6. If there is an error with an item in the shipping 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.

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

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

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
fromAddress Address Object 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 Things to Consider: addressLines, cityTown, postalCode, and countryCode.
toAddress Address Object Required. Destination address. This object requires only the countryCode field, except for Canadian destinations, which also require the postalCode and stateProvince fields. However, Pitney Bowes recommends that you include the full address to get more accurate quotes.
rates Array[Rates Object] Required. Specifies the carrier, service, parcel, and other information. In a response, this field also contains the service charges.
quoteCurrency String Required. The currency to return the quotes in. Enter the currency of your (the developer’s) country. Use three uppercase letters, per the ISO currency code (ISO 4217). For example: USD, CAD, EUR, GDP (U.K.)
basketCurrency String Required. The default currency of the shopping cart. Enter the currency of your (the developer’s) country. Use three uppercase letters, per the ISO currency code (ISO 4217). For example: USD, CAD, EUR, GDP (U.K.)
basketItems Array[Custom Items Object] Required. The items in the buyer’s shopping cart. Each object in the array specifies a different item.
shipmentOptions Array[Object] Any shipment options to be applied. Each object in this array defines a different option.
        name String The name of the shipment option. The shipmentOptions array requires this field.
        value String The value of the shipment option. The shipmentOptions array requires this field.

Request Elements: Basket Items

The basketItems array takes the Customs Items Object. The object’s elements are described in the table below. Fields that apply to CBDS are marked as such. Required fields are marked REQUIRED. Fields are listed alphabetically.

Name
Data Type Description
Applies to these Carriers
brand String The manufacturer’s brand name for the item. The maximum length is 255 characters. CBDS (PBI)
categories Array[Categories Object] Associated categories. The merchants category tree must have been provided to Pitney Bowes in advance. Do not use this array if the category tree has not been provided in advance. CBDS (PBI)
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
CBDS (PBI)
description String

REQUIRED. A detailed description of the commodity.

For the PB Cross-Border Delivery Service (CBDS), which uses a carrier value of PBI, make the description as detailed as possible to facilitate assignment of the correct HS Code.

USPS, CBDS (PBI), FedEx, UPS
eccn String The Export Control Classification Number (ECCN) for the commodity. The maximum length is 10 characters. CBDS (PBI)
hazmats Array[String] The identification of a HAZMAT-flagged item. For valid values please see How do I identify a HAZMAT-flagged item? CBDS (PBI)
hSTariffCode String

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.

If you use this field for a CBDS (PBI) operation, you must also enter information in the hSTariffCodeCountry field.

USPS, CBDS (PBI), FedEx, UPS
hSTariffCodeCountry String The two-character ISO country code for the destination country. This field is required for CBDS if the hSTariffCode field is used. CBDS (PBI)
identifiers Array[Object] Additional identifiers for the item. For example: CBDS (PBI)
      number String The value of the identifier. The maximum length is 50 characters. This field is required by the identifiers array. CBDS (PBI)
      source String The type of identifier, such as MPN, SKU, UPC, ISBN, or ISSN. The maximum length is 10 characters. This field is required by the identifiers array. CBDS (PBI)
imageURL Array[String] URLs to images of the commodity. CBDS (PBI)
itemDimension Object The dimensions for a single item. CBDS (PBI)
      length BigDecimal The longest dimension. This field is required by the itemDimension object. CBDS (PBI)
      height BigDecimal The second longest dimension. This field is required by the itemDimension object. CBDS (PBI)
      width BigDecimal The shortest dimension. This field is required by the itemDimension object. CBDS (PBI)
      unitOfMeasurement String

The unit of measurement. This field is required by the itemDimension object. Valid values are:

  • IN: Inches
  • FT: Feet
  • YD: Yards
  • CM: Centimeters
  • M: Meters
CBDS (PBI)
itemId String REQUIRED for CBDS (PBI). The merchant’s unique identifier for the commodity. The maximum length is 50 characters. CBDS (PBI)
manufacturer String The manufacturer of the item. The maximum length is 255 characters. CBDS (PBI)
netCostMethod String   UPS
originCountryCode String The country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values. USPS, CBDS (PBI), FedEx, UPS
originStateProvince String   UPS
preferenceCriterion String   UPS
pricing Object The pricing information for the commodity. If the information is not in the shopping cart, then this information is used. CBDS (PBI)
      price BigDecimal List price of the item. CBDS (PBI)
producerAddress Address Object   UPS
producerDetermination String   UPS
producerId String   UPS
quantity Integer

REQUIRED. The total number of items of this type of commodity.

If you use USPS is the carrier, the number of items of one commodity cannot exceed 9999. USPS limits the number of items of one commodity to 9999.

USPS, CBDS (PBI), FedEx, UPS
quantityUOM String   UPS
unitPrice BigDecimal REQUIRED. The price of one item of this type of commodity. USPS, CBDS (PBI), FedEx, UPS
unitWeight Object REQUIRED for most international shipments. The weight of one item of this type of commodity. This is required for all international shipments except CBDS shipments. USPS, CBDS (PBI), FedEx, UPS
      weight Number The weight in the units specified in the unitOfMeasurement field. This field is required by the unitWeight object. USPS, CBDS (PBI), FedEx, UPS
      unitOfMeasurement String

The unit of measurement. This field is required by the unitWeight object. If USPS is the carrier, set this to OZ. This field can take the following values:

  • OZ: Ounces
  • GM: Grams
  • G: Grams. Available only for CBDS
  • LB: Pounds. Available only for CBDS
  • KG: Kilograms. Available only for CBDS
USPS, CBDS (PBI), FedEx, UPS
url String Recommended for CBDS (PBI). The commodity’s URL on the merchant’s site. Ensure the URL works. Providing a accurate URL helps Pitney Bowes assign the correct HS Code. The maximum length for this field is 1000 characters. CBDS (PBI)


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.

Response Elements: 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 ISO currency code (ISO 4217). For example: USD, CAD, EUR, GDP (U.K.)
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.
        itemId String The merchant’s unique identifier for the commodity. Maximum 50 characters.
        lineErrors Array[Error Object] Any errors on the quantity of the commodities on the line.
        lineId String The unique identifier for the line within the input basket. Maximum 50 characters.
        linePrice BigDecimal The unit price multiplied by quantity.
        lineRates Rates Object Each of the elements of the unitRates multiplied by quantity.
        quantity Number The number of items of this commodity.
        quoteLineId String The unique identifier for the line within the quoteLines object. Maximum 50 characters.
        unitErrors Array[Error Object] Any errors on the individual commodity.
        unitPrice BigDecimal The unit price of the commodity in the currency of the quote.
        unitRates Rates Object The international transportation and importation costs for one 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 olVCndjE5lFnQkXaNKHYwQajz8qB" \
-H "Content-Type: application/json" \
-d '
{
    "quoteCurrency": "USD",
    "basketCurrency": "USD",
    "fromAddress": {
        "name": "John Smith",
        "residential": false,
        "company": "Supplies",
        "addressLines": ["545 Market St"],
        "cityTown": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "countryCode": "US",
        "email": "john@example.com",
        "phone": "415-555-0000"
    },
    "toAddress": {
        "name": "Jan Jones",
        "residential": true,
        "addressLines": ["2168 King St N"],
        "cityTown": "Waterloo",
        "stateProvince": "ON",
        "postalCode": "N2J 4G8",
        "countryCode": "CA",
        "email": "jan@example.com",
        "phone": "519-555-0000"
    },
    "basketItems": [ {
        "brand": "",
        "categories": [ {
            "categoryCode": "UNKNOWN",
            "descriptions": [ {
                "locale": "en",
                "name": "Dress",
                "parentsNames": [
                    "Clothing",
                    "Women"
                ]
            } ],
            "parentCategoryCode": "6543",
            "url": "www.example.com"
        } ],
        "description": "Red Embroidered",
        "eccn": "EAR99",
        "hazmats": [
            "hazmat",
            "ormd"
        ],
        "hSTariffCode": "4203100001",
        "hSTariffCodeCountry": "AU",
        "identifiers": [ {
            "number": "123456",
            "source": "isbn"
        } ],
        "imageUrls": [
            "www.example.com"
        ],
        "itemDimension": {
            "length": 11,
            "height": 8.5,
            "width": 5,
            "unitOfMeasurement": "IN"
        },
        "itemId": "G_123456",
        "manufacturer": "",
        "originCountryCode": "CN",
        "pricing": {
            "price": 20,
            "codPrice": [ {
                "price": 20,
                "cod": "CA",
                "includesDuty": false,
                "includesTaxes": false
            } ],
            "dutiableValue": 20
        },
        "quantity": 2,
        "unitPrice": 19.99,
        "unitWeight": {
            "weight": 5,
            "unitOfMeasurement": "lb"
        },
        "url": "http://www.example.com/products/160921_030"
    } ],
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "789123"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_ELOVATIONS_KY"
    } ]
}

Sample CBDS Quotes Response

{
    "quote": [ {
        "quoteCurrency": "USD",
        "quoteLines": [ {
            "itemId": "G_123456",
            "lineId": "1",
            "quantity": 2,
            "quoteLineId": "1",
            "unitRates": {
                "unitPrice": 19.99,
                "totalTaxAmount": 3.12,
                "totalDutyAmount": 4,
                "serviceId": "PBXPS",
                "baseCharge": 23.62,
                "deliveryCommitment": {
                    "minEstimatedNumberOfDays": 3,
                    "maxEstimatedNumberOfDays": 6
                },
                "totalCarrierCharge": 30.74
            },
            "lineRates": {
                "linePrice": 39.98,
                "totalTaxAmount": 6.24,
                "totalDutyAmount": 8,
                "serviceId": "PBXPS",
                "baseCharge": 47.24,
                "deliveryCommitment": {
                    "minEstimatedNumberOfDays": 3,
                    "maxEstimatedNumberOfDays": 6
                },
                "totalCarrierCharge": 61.48
            }
        } ],
        "totalPrice": 39.98,
        "totalRates": {
            "serviceId": "PBXPS",
            "baseCharge": 47.24,
            "deliveryCommitment": {
                "minEstimatedNumberOfDays": 3,
                "maxEstimatedNumberOfDays": 6
            },
            "totalCarrierCharge": 61.48,
            "totalDutyAmount": 8,
            "totalTaxAmount": 6.24
        }
    } ]
}

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 errors using the standard error object and returns the following errors. For all error codes returned by the PB Shipping APIs, see Error Codes.

1005### - Quote Level Error Codes

Error Code
Error Description  
1005001 The address is invalid.  
1005002 The consignee information is invalid.  
1005003 The COP transportation information is invalid.  
1005004 The requested return currency is invalid.  
1005005 The request currency is not supported for the target country.  
1005006 The order cannot be shipped by the method selected.  
1005007 The order value has exceeded the allowed value.  
1005010 There are errors at the Quote Line Level  
1005011 There are errors at the Quote Item Level  
1005013 The address has missing fields  
1005014 Missing fields in basket  
1005015 Invalid fields in basket  
1005016 The consignee information is missing  
1005017 The COP transportation information is missing  
1005018 Shipping Speed or service unavailable  
1005019 Missing Basket  
1005020 Missing Parcel Fields  
1005021 Missing fields in the basket commodity source  
1005022 Seller has missing fields  
1005023 Seller has invalid fields  
1005555 Fedex Rating is not responding at this moment. Please try again later SOLUTION

1006### - Unit Errors

The following errors are returned in the quote.quoteLines.unitErrors array.

Error Code
Error Description  
1006001 The commodity is invalid  
1006002 The commodity is too large to ship (length, width or height)  
1006004 The commodity has a negative price  
1006005 The commodity’s price was too low and did not have a dutiable value.  
1006006 The item price exceeds maximum  
1006007 Item weight exceeds maximum  
1006009 The Commodity is restricted for this Country of Destination  
1006010 Commodity cannot be quoted.  
1006012 Categories associated with the commodity are not available for quoting  
1006013 Categories associated with the commodity are restricted for this country of destination  
1006014 Category associated with commodity is invalid  

1007### - Line Errors

The following errors are returned in the quote.quoteLines.lineErrors array.

Error Code
Error Description  
1007001 Order value exceeded on this line  
1007003 The quantity is invalid or missing  
1007006 Missing fields in basket line  
1007007 Invalid fields in basket line  

PB-APIM-ERR Errors

This operation can return PB-APIM-ERR-#### errors:

Error Code Error Description  
PB-APIM-ERR-0401 Invalid client ID or secret  
PB-APIM-ERR-0402 Invalid Subscription Id  
PB-APIM-ERR-0403 Developer App is not enriched with DOMAIN_INFO SOLUTION
  Developer App is not enriched with METER_POOL  
  Invalid ProductId Attribute value  
  Invalid SHIPPER_RATE_PLAN SOLUTION
  User exceeded configured monetization limits  
PB-APIM-ERR-0404 User not allowed to access the requested resource SOLUTION
PB-APIM-ERR-1000 GCS Domain Info: Invalid JSON  
  Internal Error Occurred SOLUTION
PB-APIM-ERR-1002 Invalid Access Token SOLUTION
PB-APIM-ERR-1003 Access Token Expired  
PB-APIM-ERR-1004 Invalid API Call SOLUTION
PB-APIM-ERR-1005 Invalid or Missing Client Credentials  
PB-APIM-ERR-1006 Spike arrest violation SOLUTION
  X-PB-IntegratorId Not Found  
PB-APIM-ERR-1008    
PB-APIM-ERR-1010 The Service is temporarily unavailable  
PB-APIM-ERR-1404 Invalid or missing resource  
PB-APIM-ERR-1500 Quota limit exceeded.  
PB-APIM-ERR-4001 X-PB-TransactionId Length cannot be greater than 25 chars  
PB-APIM-ERR-4002 X-PB-TransactionId is missing