Request Parcel Protection Coverage¶

HTTP Request¶

POST /v1/parcel-protection/create

Summary¶

This API lets merchants request Pitney Bowes Parcel Protection coverage for shipments. Merchants can request coverage for shipments created with the Shipping APIs as well as for shipments created with other platforms.

Things to Consider¶

The merchant must be enabled for PB Parcel Protection. See Onboard a Merchant for Parcel Protection.
You must have the shipment’s tracking number to request PB Parcel Protection coverage for the shipment.
Merchants can request coverage 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
Merchants are billed using the payment method on file on the date of the regular billing cycle. Parcel Protection charges are not be deducted from a merchant’s USPS postage balance.
Merchants cannot request coverage for packages that have already been shipped or delivered.
The merchant must keep track of parcelProtectionReferenceID value returned by this operation. The ID is needed if the merchant has any follow-up communications about the shipment coverage or if the merchant chooses to void the coverage (before shipment).

Request URIs¶

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

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.
trackingNumber	String	Required. The shipment’s tracking number.
carrier	String	Required. The carrier used to ship the parcel.
serviceId	String	Required. Notates the service the merchant is using. This field is for notation only and does not affect the amount charged for insurance.
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	Object. See Address Object below.	The shipper’s address.
companyName	String	The shipper’s company name.
familyName	String	The shipper’s last name.
givenName	String	The shipper’s first name.
middleName	String	The shipper’s middle hame.
email	String	The shipper’s email address.
phoneNumbers	Array[Object]	The shipper’s phone numbers. Each object in the array has two fields, `number`, which takes the phone number as a numeric value, and `type`, which takes a String that identifies the phone number. For example: { "number": 2125551212, "type": "company" }
consigneeInfo	Object	The buyer’s information.
address	Object. See Address Object below.	The buyer’s address.
companyName	String	The buyer’s company name.
familyName	String	The buyer’s last name.
givenName	String	The buyer’s first name.
middleName	String	The buyer’s middle hame.
email	String	The buyer’s email address.
phoneNumbers	Array[Object]	The buyer’s phone numbers. Each object in the array has two fields, `number`, which takes the phone number as a numeric value, and `type`, which takes a String that identifies the phone number. For example: { "number": 2125551212, "type": "company" }
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
transactionID	String	The ID sent in the `X-PB-TransactionId` request header.
parcelProtectionReferenceID	String	The unique identifier for the shipment’s PB Parcel Protection policy. Use this identifier when you want to reference this policy.
parcelProtectionDate	String	The date and time the Parcel Protection policy was created, returned in UTC/GMT time in the ISO 8601 Date Format.
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: ae4753-097518-8a4063" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "shipmentInfo": {
        "trackingNumber": "940509898641491871138",
        "carrier": "USPS",
        "serviceId": "PM",
        "insuranceCoverageValue": 1000,
        "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"
                ],
                "city": "San Francisco",
                "countyOrRegionOrState": "CA",
                "postalCode": "94105-2847",
                "country": "US"
            },
            "companyName": "Company",
            "familyName": "Smith",
            "givenName": "John",
            "middleName": "James",
            "email": "company@example.com",
            "phoneNumbers": [ {
                "number": "1234567890",
                "type": "business phone"
            } ]
        },
        "consigneeInfo": {
            "address": {
                "addressLines": [
                    "284 W Fulton"
                ],
                "city": "Garden City",
                "countyOrRegionOrState": "KS",
                "postalOrZipCode": "67846",
                "country": "US"
            },
            "companyName": "Shop",
            "familyName": "Jones",
            "givenName": "Mary",
            "middleName": "Anne",
            "email": "shop@example.com",
            "phoneNumbers": [ {
                "number": "1234567890",
                "type": "business phone"
            }, {
                "number": "1234567890",
                "type": "fax"
            } ]
        }
    }
}'

Sample Response¶

{
    "transactionID": "44397664_q146821_93c1541c-c8f3-4b35-af6a-9d560490f594",
    "parcelProtectionReferenceID": "IPPOL0000000012345678",
    "parcelProtectionDate": "2019-05-20 15:00:25.279+0000",
    "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.