Request Parcel Protection Coverage

HTTP Request

POST /v1/parcel-protection/create

Summary

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

Prerequisites

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.

Things to Consider

  1. You must have the shipment’s tracking number to request PB Parcel Protection coverage for the shipment.
  2. 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
  3. Merchants are billed using the payment method on file. They are billed on the date of the regular billing cycle. Parcel Protection charges are not be deducted from a merchant’s USPS postage balance.
  4. Merchants cannot request coverage for packages that have already been shipped or delivered.
  5. 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.
  6. For more information on the Parcel Protection program, including FAQs, please see the Parcel Protection web page.

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

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 Address Object

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

  • addressLines
  • cityTown
  • StateProvince
  • countryCode
        companyName String The merchant’s company name.
        givenName String The merchant’s first name.
        middleName String The merchant’s middle hame.
        familyName String The merchant’s last name.
        email String The merchant’s email address.
        phoneNumbers Array[Object]

The merchant’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 Address Object

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

  • addressLines
  • cityTown
  • StateProvince
  • countryCode
        companyName String The buyer’s company name.
        givenName String The buyer’s first name.
        middleName String The buyer’s middle hame.
        familyName String The buyer’s last name.
        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.

Response Elements

Name Data Type Description
transactionID String A unique string that identifies the transaction. The string comprises the developer ID, the X-PB-TransactionId, and additional characters.
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 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: ABCD1234" \
-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/1084"
            } ]
        },
        "shipperInfo": {
            "shipperID": "9024324564",
            "address": {
                "addressLines": [ "545 Market St" ],
                "cityTown": "San Francisco",
                "stateProvince": "CA",
                "postalCode": "94105-2847",
                "countryCode": "US"
            },
            "companyName": "Supplies",
            "givenName": "John",
            "middleName": "James",
            "familyName": "Smith",
            "email": "john@example.com",
            "phoneNumbers": [ {
                "number": "1234567890",
                "type": "business phone"
            } ]
        },
        "consigneeInfo": {
            "address": {
                "addressLines": [ "284 W Fulton" ],
                "cityTown": "Garden City",
                "stateProvince": "KS",
                "postalCode": "67846",
                "countryCode": "US"
            },
            "companyName": "Shop",
            "givenName": "Mary",
            "middleName": "Anne",
            "familyName": "Jones",
            "email": "mary@example.com",
            "phoneNumbers": [ {
                "number": "6205551234",
                "type": "business phone"
            }, {
                "number": "6205554321",
                "type": "fax"
            } ]
        }
    }
}'

Sample Response

{
    "transactionID": "44397664_ABCD1234_28d6fb80-6b92-4e69-b5bb-6656a00ce435",
    "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.