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¶
- 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. 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.
- 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. - 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
For example: |
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 | Address Object | The merchant’s address. |
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. |
String | The merchant’s email address. | |
phoneNumbers | Array[Object] | The merchant’s phone numbers. Each object in the array has two fields,
{
"number": 2125551212,
"type": "company"
}
|
consigneeInfo | Object | The buyer’s information. |
address | Address Object | The buyer’s address. |
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. |
String | The buyer’s email address. | |
phoneNumbers | Array[Object] | The buyer’s phone numbers. Each object in the array has two fields,
{
"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": "Company",
"givenName": "John",
"middleName": "James",
"familyName": "Smith",
"email": "smith@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": "jones@example.com",
"phoneNumbers": [ {
"number": "1234567890",
"type": "business phone"
}, {
"number": "1234567890",
"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.