Request Cross-Border Quotes for all Items in a Shopping Cart

HTTP Request

POST /v1/crossborder/checkout/quotes

Summary

This operation integrates with PB Cross-Border 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 oversized, the API returns an item-specific error for the ineligible item and still returns quotes for each eligible item.

PB Cross-Border 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.

Prerequisite

To help PB Cross-Border calculate duties and taxes more accurately, provide Pitney Bowes a category tree before using this API call. If you do not have a category tree, you can use categories from a Pitney Bowes generic catalog or a more general Google product taxonomy. For more information, contact PB Support at ShippingAPISupport@pb.com.

Things to Consider

  1. The toAddress requires only the countryCode field (unless the destination is in Canada). However, 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 Newgistics fulfillment or deliver customer, include the merchant’s ClientId in the shipmentOptions array.

  4. The Quotes API’s response object is different from request object. The API response does not return all the input elements in the request.

  5. The Quotes API can return a successful response even if there are errors with one or more items in the shopping cart. The items are not included in the resulting quotes. An item would return an error, for example, if it has restrictions or is missing mandatory information. The response body returns information on such errors in the unitErrors or LineErrors fields.

  6. If an item is found to be restricted, the API returns error 1006009 for that 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 field. Pitney Bowes recommends that you also include the addressLines, cityTown, and stateProvince fields 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.
shipmentOptions Array[Object] Each object in this array defines a shipment 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: Customs Items Object

The basketItems array stores the Customs Items object. Fields that apply to PB Cross-Border are marked PBI in the Carrier column.

Name
Data Type Carrier Description
description String USPS
PBI,
UPS
Required. The description of the commodity. For the Rate Parcel and Create Shipment APIs, the maximum is 50 characters. For the Cross-Border Quotes API, the maximum is 255 characters.
originCountryCode String USPS
PBI,
UPS
The country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.
quantity Integer USPS
PBI,
UPS

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.

unitPrice BigDecimal USPS
PBI,
UPS
Required. The price of one item of this type of commodity.
unitWeight Object USPS
PBI,
UPS

Conditional. The weight of one item of this type of commodity.

Required for international shipments, except PB Cross-Border. (Not required for PB Cross-Border.)

hSTariffCode String USPS
PBI,
UPS

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 PB Cross-Border operation, you must also enter information in the hSTariffCodeCountry field.

hSTariffCodeCountry String PBI

Conditional. The two-character code of the country that the hSTariffCode belongs to. This field applies only to PB Cross-Border.

Required for PB Cross-Border if the hSTariffCode field is used.

attributes Array[Object] PBI  
      name String    
      type String    
      value String    
brand String PBI The manufacturer’s brand name for the item. The maximum length is 255 characters.
categories Array[Categories Object] PBI Associated categories. The merchants category tree must have been provided to PB Cross-Border in advance. Do not use this array if the category tree has not been provided in advance.
childIdentifier String PBI The variation of the parent SKU (different Max Length or color). The maximum is 50 characters.
condition String PBI

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
eccn String PBI The ECCN code for the commodity. The maximum length is 10 characters.
enabled Boolean PBI
hazmats Array[String] PBI

The identification of a HAZMAT-flagged item. Valid values are:

  • hazmat: Item contains hazardous materials that are fully regulated by the D.O.T.
  • ormd: Other Regulated Materials for Domestic Transport only (ORM-D), meaning that the item contains hazardous material in a limited quantity that presents a limited hazard during transportation as defined by D.O.T. regulations.
  • chemicalindicator: Any product that contains a powder, gel, paste, or liquid that is not intended for human consumption.
  • pesticideindicator: Any chemical that is advertised or labeled to kill, repel or prevent growth of any living organism.
  • aerosolindicator: Any product that contains a compressed gas or propellant.
  • rppcindicator: Rigid plastic packaging container.
  • batterytype-{X}: The battery-type indicator, where {X} is one of the following:
    • alkaline
    • carbon zinc
    • lead acid
    • lithium
    • primary
    • lithium ion
    • magnesium mercury
    • nickel cadmium
    • silver
    • thermal
    • multiple types of nickel metal hydride
    • other
  • nonspillablebattery: Item contains a D.O.T. regulated battery that must be indicated on the shipping box with non-spillable battery text.
  • fuelrestriction: Product is an empty container that may be filled with fluids such as fuel, CO2, propane, etc.
identifiers Array[Object] PBI Additional identifiers for the item.
      number String   The value of the identifier. The maximum length is 50 characters. This field is required by the identifiers array.
      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.
imageURL Array[String] PBI URLs to images of the commodity.
itemId String PBI Required for PB Cross-Border. The merchant’s unique identifier for the commodity. The maximum length is 50 characters.
itemDimension Object PBI The dimensions for a single item.
      length BigDecimal   The longest dimension. This field is required by the itemDimension object.
      height BigDecimal   The second longest dimension. This field is required by the itemDimension object.
      width BigDecimal   The shortest dimension. This field is required by the itemDimension object.
      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
kit Boolean PBI If set to true, this item is a kit. Other items that make up the kit will use this item’s itemId as the kitIdentifier. The default value for this field is false.
kitIdentifier String PBI If present, the itemId of the kit that this item belongs to. The maximum length is 50 characters.
kitQuantity Integer PBI The number of units of this item in the kit.
manufacturer String PBI The manufacturer of the item. The maximum length is 255 characters.
parentIdentifier String PBI The parent SKU for a product that has variations. The maximum length is 50 characters.
pricing Object PBI The pricing information for the commodity. If the information is not in the shopping cart, then this information is used.
      codPrice Array[Object]   Currently not supported.
      dutiableValue BigDecimal   Currently not supported.
      price BigDecimal   List price of the item.
shipsAlone Boolean PBI  
      unitOfMeasurement String  

The unit of measurement. Required by the unitWeight object. If USPS is the carrier, set this to OZ.

Valid values:

      weight Number   The weight. Required by the unitWeight object.
url String PBI The commodity’s URL. The maximum length is 1000 characters.
netCostMethod String UPS  
originStateProvince String UPS  
preferenceCriterion String UPS  
producerAddress Address Object UPS  
producerDetermination String UPS  
producerId String UPS  
quantityUOM String UPS  


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.

Response Elements: 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 and Responses

See the following examples:

Sample Cross-Border 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": [ {
        "attributes": [ {
            "type": "material",
            "name": "fabric",
            "value": "cotton"
        } ],
        "brand": "",
        "categories": [ {
            "categoryCode": "UNKNOWN",
            "descriptions": [ {
                "locale": "en",
                "name": "Dress",
                "parentsNames": [
                    "Clothing",
                    "Women"
                ]
            } ],
            "parentCategoryCode": "6543",
            "url": "www.example.com"
        } ],
        "childIdentifier": "",
        "description": "Red Embroidered",
        "eccn": "EAR99",
        "enabled": true,
        "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",
        "kit": "",
        "kitIdentifier": "",
        "kitQuantity": "",
        "longDescription": "Red Embroidered Double-weave Sleeveless",
        "manufacturer": "",
        "originCountryCode": "CN",
        "parentIdentifier": "",
        "pricing": {
            "price": 20,
            "codPrice": [ {
                "price": 20,
                "cod": "CA",
                "includesDuty": false,
                "includesTaxes": false
            } ],
            "dutiableValue": 20
        },
        "quantity": 2,
        "shipsAlone": true,
        "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": "CBDS_0001"
    },{
        "name": "CLIENT_ID",
        "value": "CBDS_0001"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_ELOVATIONS_KY"
    } ]
}

Sample 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 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  

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 returns some of the following 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