Request a Parcel Protection Quote

HTTP Request

POST /v1/parcel-protection/quote

Summary

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

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/parcel-protection/quote
Production: https://api.pitneybowes.com/shippingservices/v1/parcel-protection/quote

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.
X-PB-TransactionId

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
X-PB-UnifiedErrorStructure 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.
    insuranceCoverageValueCurrency String

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:

https://example.com/computers/laptop_7490

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.
    consigneeInfo Object The buyer’s information.
        address Address Object The buyer’s address.
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-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": "https://example.com/computers/laptop_7490"
            } ]
        },
        "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.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.