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 Shipping Lanes.

Prerequisites

  1. You must contact Pitney Bowes and request to be enabled to use this API. Contact Client Support at ClientSupportTechServices@pb.com.

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

  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 merchant’s PB Standard Client 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 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.

  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 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. Pitney Bowes recommends that you include this information to get more accurate quotes. The object requires following fields, as noted above in Considerations:

  • addressLines

  • cityTown

  • postalCode

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

customsInfo

Customs Info Object

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. The array takes the Customs Items Object. Note that some fields in the object do not apply to this operation and are marked as such in the object description.

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.

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 (Response Only)

The quote array returns the 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"
        ],
        "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.

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.