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

  1. The merchant must be enabled for PB Parcel Protection. See Enable a Merchant for Parcel Protection.
  2. You must have the shipment’s tracking number to request PB Parcel Protection coverage for the shipment.
  3. 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
  4. 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.
  5. Merchants cannot request coverage for packages that have already been shipped or delivered.
  6. 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 Address Object 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 Address Object 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.

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"
                ],
                "cityTown": "San Francisco",
                "stateProvince": "CA",
                "postalCode": "94105-2847",
                "countryCode": "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"
                ],
                "cityTown": "Garden City",
                "stateProvince": "KS",
                "postalCode": "67846",
                "countryCode": "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.