Shipments FAQs

Subtopics:

Are dimension values required on all parcel types?

USPS requires dimensions on all services as a best practice, but the PB Shipping APIs currently require dimensions only for soft packs (SOFTPACK). You assign dimensions in the parcel object.

If you do not have dimensions to specify, for example, for flat-rate services, you can do either of the following:

  • Omit the dimensions
  • Send an empty payload for the dimension object

How are dimensions ordered?

Length is the longest dimension.
Height is the second-longest dimension.
Width is the shortest dimension.

If you assign values differently, the APIs will reassign them accordingly. Assign dimensions in the parcel object.

How is girth calculated?

Girth is twice the sum of the height and width:

girth = 2 * (height+width)

Note: The PB Shipping APIs configure length as the longest dimension, followed by height, followed by width.

What parcel type do I use for APO/FPO/DPO addresses?

Use the MLFRB parcel type for shipments to APO/FPO/DPO addresses, (i.e., military bases, diplomatic locations, and army post offices). MLFRB stands for Military Large Flat Rate Box.

How do I insure a parcel?

You can insure a parcel against damage or loss while in transit by selecting one of the following options. You can select only one option to insure a parcel:

  • PB Parcel Protection

    To insure a parcel through PB Parcel Protection, see What is PB Parcel Protection?.

  • USPS Insurance

    To insure a parcel through USPS, include the Ins special service in the in the rates.specialServices array when creating the shipment and specify the insured value. For example:

    {
        "specialServiceId": "Ins",
        "inputParameters": [ {
            "name": "INPUT_VALUE",
            "value": "50"
        } ]
    }
    

    For domestic shipments, see the domestic fees section of the USPS price list.

    For international shipments, USPS insurance is available for Priority Mail International (PMI) and Priority Mail Express International (EMI). For more information, see this section of the USPS Price List and see the USPS Priority Mail International Insurance page.

How do I file an insurance claim for a USPS shipment?

To file an insurance claim for a shipment, please visit the USPS Claims site. You must provide the following:

  • Tracking number
  • Proof of insurance
  • Proof of value (receipt, paid invoice). Note: You can print the shipment receipt at the time of print by using the SHIPPING_LABEL_RECEIPT shipment option when creating a label.

How do I file a claim for a PB Complete Delivery?

See Pitney Bowes Complete Delivery.

Which transactions require a trackable special service?

The PB Shipping APIs require almost all transactions (with very few exceptions) be trackable. While some services are automatically trackable, others are not and require the addition of a trackable special service. For the latter group, you can add a no-charge special service, such as Delivery Confirmation (DelCon).

To determine if a service-and-parcel-type combination will require the addition of a trackable special service, use the Carrier Rules API.

How do I know the input parameters for a special service?

The response returned by the Carrier Rules API lists the parameters for a special service. In the response, locate the service type and parcel type you are using and then locate the special service. The special service’s inputParameterRules array lists the available parameters and indicates if a parameter is required.

Note: The response returned by the Carrier Rules API is large. It is recommended that you make the API call only once a day and cache the returned data.

Specify the parameters when you create a shipment or rate a parcel. The following illustration shows how the response returned by the Carrier Rules API maps to the elements in a shipment or rate request. Only the relevant fields are shown:

Setting Special Service Input Parameters

Do all USPS services return transit times?

The PB Shipping APIs return transit times for USPS services if the includeDeliveryCommitment query parameter is set to true. The PB Shipping APIs return transit times for all USPS services, including all domestic and international services.

See also: Pitney Bowes Complete Delivery

Note the following:

  • Delivery transit time information is based on information provided by USPS. Domestic transit times are updated quarterly. International transit times are not updated on any particular schedule.
  • Delivery transit time information is based on the Origin and Destination Postal Codes, as well as the time of day the label is printed. Please keep in mind that one-day delivery commitments assume the package will be at the Post Office by a certain time.
  • As of this writing, USPS Priority Mail Express (a.k.a. Express Mail) is the only USPS Service which guarantees a particular delivery date and/or time, such as “10:30AM”, “12:00 Noon”, “3:00PM”, etc.

The following is an example of returned transit times for a domestic shipment:

{
    "minEstimatedNumberOfDays": "2",
    "maxEstimatedNumberOfDays": "2",
    "estimatedDeliveryDateTime": "2016-06-25",
    "guarantee": "NONE",
    "additionalDetails": "By end of Day"
}

The following is an example of returned transit times for an international shipment:

{
    "minEstimatedNumberOfDays": "6",
    "maxEstimatedNumberOfDays": "14",
    "estimatedDeliveryDateTime": "",
    "guarantee": "NONE",
    "additionalDetails": "6 - 14 business days to many major markets"
}

Do the APIs support COD Firm Book?

No, the PB Shipping APIs do not support COD Firm Book at this time.


Why does Express Mail return an error when other services do not?

See Error 1021119.