Request a Parcel Protection Quote

HTTP Request

POST /v1/parcel-protection/quote


This API provides a quote for covering a shipment through Pitney Bowes Parcel Protection. Merchants can request quotes for:

  • Shipment labels printed on any platform, including both PB Shipping APIs and other platforms.
  • Shipments with all major U.S. carriers.
  • Both domestic and international shipments. Shipments must originate in the U.S.


To use this API, both your developer account and the merchant’s account must be enabled for Parcel Protection. For instructions, see Enabling Parcel Protection Coverage.

Request URIs


Request Headers

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.
X-PB-TransactionId Required. A unique identifier for the transaction, up to 25 characters. Ensure this is a unique ID.
Accept-Language Language and country code. Default: en-US
X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

Request Elements

Data Type Description
shipmentInfo Object Required. Information about the covered parcel.
    carrier String Required. The carrier used to ship the parcel.
    serviceId String Required. Notates the service the merchant is using.
    insuranceCoverageValue Number with up to 3 decimal places Required. The declared value of the parcel.
    insuranceCoverageValueCurrency String Required. The ISO currency code of the currency referenced in the insuranceCoverageValue field. Use three uppercase letters, per ISO 4217. For example, use USD for US Dollars, CAD for Canadian Dollars, and EUR for Euros. For all currency codes, see
    parcelInfo Object Commodity information about the parcel.
        commodityList Array[Object] An array containing a separate document for each item in the parcel.
            categoryPath String The item’s product category path.
            itemCode String

The item’s SKU code.

Max Length: 10 characters

            name String

The item’s product name.

Max Length: 200 characters

            url String

The item’s URL. For example:

Max Length: 200 characters

    shipperInfo Object Merchant information.
        shipperID String Required. The merchant’s Shipper ID. The Shipper ID is found in the postalReportingNumber field in the Merchant Object.
        address Address Object

The shipper’s address. The following address fields are required:

  • addressLines
  • cityTown
  • StateProvince
  • countryCode
    consigneeInfo Object The buyer’s information.
        address Address Object

The buyer’s address. The following address fields are required:

  • addressLines
  • cityTown
  • StateProvince
  • countryCode
parcelProtectionAccountID String Parcel Protection account ID, if applicable.
parcelProtectionProgramID String Parcel Protection program ID, if applicable.

Response Elements

Name Data Type Description
parcelProtectionFees Number The charge for Parcel Protection.
parcelProtectionFeesCurrencyCode String The ISO currency code for the Parcel Protection fees.
parcelProtectionFeesBreakup Object Breaks down the Parcel Protection fees.
    basePremium Number The base premium value.
    technologyFee Number The technology fee.

Sample Request

curl -X POST .../v1/parcel-protection/quote \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type:application/json" \
-H "Accept: application/json" \
-H "X-PB-TransactionId: 674109a5-50738a843e" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
    "shipmentInfo": {
        "carrier": "USPS",
        "serviceId": "PM",
        "insuranceCoverageValue": 1000,
        "insuranceCoverageValueCurrency": "USD",
        "parcelInfo": {
            "commodityList": [ {
                "categoryPath": "electronics",
                "itemCode": "SKU1084",
                "name": "Laptop",
                "url": ""
            } ]
        "shipperInfo": {
            "shipperID": "9024324564",
            "address": {
                "addressLines": [ "545 Market St" ],
                "cityTown": "San Francisco",
                "stateProvince": "CA",
                "postalCode": "94105-2847",
                "countryCode": "US"
        "consigneeInfo": {
            "address": {
                "addressLines": [ "284 W Fulton" ],
                "cityTown": "Garden City",
                "stateProvince": "KS",
                "postalCode": "67846",
                "countryCode": "US"

Sample Response

    "parcelProtectionFees": 7.50,
    "parcelProtectionFeesCurrencyCode": "USD",
    "parcelProtectionFeesBreakup": {
        "basePremium": 7.25,
        "technologyFee": 0.25

Error Codes

For a list of all PB Shipping APIs error codes, please see Error Codes.