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

HTTP Request

POST /v1/crossborder/checkout/quotes

Summary

This operation provides an estimate of the duties, taxes, and transportation costs for the items in a buyer’s online shopping cart. The API returns quotes for all eligible items and returns item-specific errors for any restricted items (for example, oversized items). If the cart has restricted items, the API still returns quotes for the eligible items.

The API estimates costs based on the destination address, service level, and 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 Pitney Bowes calculate duties and taxes more accurately, provide Pitney Bowes a category tree before using this API call. If you have a category tree on your platform, share it with Pitney Bowes in advance. 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.

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[Customs 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.

Customs Items Object

Note

The basketItems array stores the Customs Items Object. The table below describes all possible fields the object. If a field does not apply to this operation, it is marked as such.

Name
Data Type
Description
description String

Required. The description of the commodity.

In most cases, the maximum is 50 characters. However, for the Cross-Border Quotes API, this has a maximum of 255 characters.

quantity Integer

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

USPS: USPS limits the number of items of one commodity to 9999.

unitPrice BigDecimal Required. The price of one item of this type of commodity.
itemId
String
Required. The merchant’s unique identifier for the commodity. Maximum 50 characters.
categories
Array[Categories Object]
Associated categories. Categories must be provided to Pitney Bowes in advance. If the category information has not been provided to Pitney Bowes, do not use this array.
condition String

Condition of the commodity. If using an eBay-specific category tree, enter the eBay item conditionId. Otherwise use one of the following values:

  • new
  • used
  • refurbished
  • damaged
  • unknown
unitWeight
Object

The weight of one item of this type of commodity.

Required for international shipments.

Not required for PB Cross-Border.

      weight Number The weight. Required in the unitWeight object.
      unitOfMeasurement String

The unit of measurement. Required in the unitWeight object.

For USPS as the carrier, set this to OZ.

Valid values:

itemDimension
Object
The dimensions for a single item.
      length BigDecimal The longest dimension. Required in the itemDimension object.
      height BigDecimal The second longest dimension. Required in the itemDimension object.
      width BigDecimal The shortest dimension. Required in the itemDimension object.
      unitOfMeasurement String

The unit of measurement. Required in the itemDimension object. Valid values are:

  • IN: Inches
  • FT: Feet
  • YD: Yards
  • CM: Centimeters
  • M: Meters
hSTariffCode
String
The Harmonized System Tariff Code associated with the commodity. Maximum 14 characters.
originCountryCode String The country code of the shipment’s origin. Use ISO 3166-1 alpha-2 standard values.
hSTariffCodeCountry
String

Conditional. The two-character country the Harmonized Tariff refers to.

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

identifiers Array[Object] Additional identifiers for the item.
      source String The type of identifier, such as MPN, SKU, UPC, ISBN, or ISSN. Required in the identifiers array. Maximum 10 characters.
      number String The value of the identifier. Required in the identifiers array. Maximum 50 characters.
parentIdentifier
String
The parent SKU for a product that has variations. Maximum 50 characters.
childIdentifier String The variation of the parent SKU (different Max Length or color). Maximum 50 characters.
kit Boolean

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 If present, the itemId of the kit that this item belongs to. Maximum 50 characters.
kitQuantity Integer The number of units of this item in the kit.
manufacturer String The manufacturer of the item. Maximum 255 characters.
brand String The manufacturer’s brand name for the item. Maximum 255 characters.
eccn String The ECCN code for the commodity. Maximum 10 characters.
enabled Boolean  
pricing Object The pricing information for the commodity. If the information is not in the shopping cart, then this information is used.
      price BigDecimal List price of the item.
      codPrice Array[Object] Currently not supported.
      dutiableValue BigDecimal Currently not supported.
url String The commodity URL. Maximum 1000 characters.
imageURL Array[String] URLs to images of the commodity.
shipsAlone Boolean  
attributes Array[Object]  
      type String  
      name String  
      value String  
hazmats Array[String]

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

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

Categories Object

Name Data Type Description
categoryCode String The item’s category identifier based on the product categories agreed on with Pitney Bowes. Required if you include the categories array. Maximum 50 characters.
parentCategoryCode String Parent category of the item’s category identifier, based on the merchant product categories agreed on with Pitney Bowes. Maximum 50 characters.
descriptions Array[Object] Category description.
        locale String The category locale. For example, en_US. Required if you include the descriptions array. Maximum 10 characters.
        name String The category name. Required if you include the descriptions array. Maximum 255 characters.
        parentsNames Array[String(255)] The tree of parent names to reach this category. parentNames[0] must be the top-level name, and parentNames[Max Length-1] must be the name of the parent category containing this category. Maximum 255 characters.
categoryCodePath String

Hierarchical path to the category represented by the category ID of each level, concatenated with a colon delimiter. For example:

9785:8266:9798:9799:10203

categoryNamePath String

Hierarchical path to the category represented by the category name of each level, concatenated with a pipe (|) delimiter. For example:

CONSUMABLES AND GROCERY|BABY|BABY CARE|BABY CONSUMABLES|BABY FOOD

categorySiteId String The category site ID if the eBay category is referred.

Response Elements

Name
Data Type Description
quote Array[Object] The quotes. The array contains a quote for each available shipping method requested. Each object in the array is a separate quote.
      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.
              lineId String The unique identifier for the line within the input basket. Maximum 50 characters.
              itemId String The merchant’s unique identifier for the commodity. Maximum 50 characters.
              quoteLineId String The unique identifier for the line within the quoteLines object. Maximum 50 characters.
              quantity Number The number of items of this commodity.
              unitRates Rates Object The international transportation and importation costs for one commodity.
              unitPrice BigDecimal The unit price of the commodity in the currency of the quote.
              lineRates Rates Object Each of the elements of the unitRates multiplied by quantity.
              linePrice BigDecimal The unit price multiplied by quantity.
              unitErrors Array[Error Object] Any errors on the individual commodity.
              lineErrors Array[Error Object] Any errors on the quantity of the commodities on the line.
      totalRates Rates Object The rates for every requested service level.
      totalPrice BigDecimal The total value of the commodities, returned in the currency listed in quoteCurrency.
      errors Array[Error Object] Any quote-level errors.

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": [ {
        "itemId": "G_123456",
        "categories": [ {
            "categoryCode": "UNKNOWN",
            "descriptions": [ {
                "locale": "en",
                "name": "Dress",
                "parentsNames": [
                    "Clothing",
                    "Women"
                ]
            } ],
            "parentCategoryCode": "6543",
            "url": "www.example.com"
        } ],
        "description": "Red Embroidered",
        "longDescription": "Red Embroidered Double-weave Sleeveless",
        "unitWeight": {
            "weight": 5,
            "unitOfMeasurement": "lb"
        },
        "itemDimension": {
            "length": 11,
            "height": 8.5,
            "width": 5,
            "unitOfMeasurement": "IN"
        },
        "url": "http://www.example.com/products/160921_030",
        "quantity": 2,
        "unitPrice": 19.99,
        "originCountryCode": "CN",
        "parentIdentifier": "",
        "childIdentifier": "",
        "kit": "",
        "kitIdentifier": "",
        "kitQuantity": "",
        "manufacturer": "",
        "brand": "",
        "eccn": "EAR99",
        "enabled": true,
        "pricing": {
            "price": 20,
            "codPrice": [ {
                "price": 20,
                "cod": "CA",
                "includesDuty": false,
                "includesTaxes": false
            } ],
            "dutiableValue": 20
        },
        "hSTariffCode": "6403.20.00",
        "hSTariffCodeCountry": "US",
        "identifiers": [ {
            "number": "123456",
            "source": "isbn"
        } ],
        "imageUrls": [
            "www.example.com"
        ],
        "shipsAlone": true,
        "attributes": [ {
            "type": "material",
            "name": "fabric",
            "value": "cotton"
        } ],
        "hazmats": [
            "hazmat",
            "ormd"
        ]
    } ],
    "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": [ {
            "lineId": "1",
            "itemId": "G_123456",
            "quoteLineId": "1",
            "quantity": 2,
            "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