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.

Things to Consider

  1. The merchant must be enabled for PB Parcel Protection. See Onboard a Merchant for Parcel Protection.
  2. Merchants can request quotes for the following:
    • U.S. Domestic shipments
    • International shipments (U.S. origin)
    • Shipments with all major U.S. carriers
    • Shipments printed on the Pitney Bowes Shipping APIs and shipments printed on other platforms

Request URIs


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.

Required. A unique identifier for the transaction, up to 25 characters.

Important: You must ensure this is a unique id.
Accept-Language Language and country code. Default: en-US
Recommended. Set this to true to use the standard error object if an error occurs.

Request Elements

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



Required. The ISO currency code of the currency referenced in the insuranceCoverageValue field. Use three uppercase letters, per ISO 4217.

For example: USD, CAD, or EUR

    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 Object. See Address Object below. The shipper’s address.
    consigneeInfo Object The buyer’s information.
        address Object. See Address Object below. The buyer’s address.
parcelProtectionAccountID String Parcel Protection account ID, if applicable.
parcelProtectionProgramID String Parcel Protection program ID, if applicable.

Address Object for Parcel Protection

addressLines Array[String] Street address or P.O. Box. Include apartment number if applicable. You can specify up to 3 address lines.
city String The city or town.
countyOrRegionOrState String The state or province. For US address, use the 2-letter state code.
postalCode String Postal/ZIP code. For US addresses, either the 5-digit or 9-digit ZIP code.
country String Required. Two-character country code from the ISO country list.

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-50738a84-3e" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
    "shipmentInfo": {
        "carrier": "USPS",
        "serviceId": "PM",
        "insuranceCoverageValue": 10,
        "insuranceCoverageValueCurrency": "USD",
        "parcelInfo": {
            "commodityList": [ {
                "categoryPath": "electronics",
                "itemCode": "SKU1084",
                "name": "Laptop",
                "url": ""
            } ]
        "shipperInfo": {
            "shipperID": "9024324564",
            "address": {
                "addressLines": [
                    "545 Market St"
                "city": "San Francisco",
                "countyOrRegionOrState": "CA",
                "postalCode": "94105-2847",
                "country": "US"
        "consigneeInfo": {
            "address": {
                "addressLines": [
                    "284 W Fulton"
                "city": "Garden City",
                "countyOrRegionOrState": "KS",
                "postalOrZipCode": "67846",
                "country": "US"

Sample Response

    "parcelProtectionFees": 7.5,
    "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.