Labels FAQs¶

On this page

What is the correct placement for a shipping label?
How do I print an IMb label?
What is an IMpb?
How do I print a Doc Tab label?
Can I get only the USPS postage indicia to use on a label?
How do I print a return address that is different from the origin address?
How long is a USPS shipment label valid?
Can I get the transaction receipt for a label that has already been printed?

What is the correct placement for a shipping label?¶

For USPS®, Newgistics®, and PB Presort labels, advise shippers to follow these guidelines:

Place the label such that none of the adhesive backing is exposed. Exposed backings can interfere with mail-processing equipment.
Place the label fully on the address side of the parcel, without overlapping the side or overlapping any other labels.
When affixing an IMb label, place the label in the top right corner of the package.
Do not cover a label’s barcode with tape or plastic wrap. These can affect readability.
When placing a barcode label on a rounded package, such as a mailing tube, place the label such that the bars of the barcode are perpendicular to the curve of the package, as shown in the illustration below from the Label Placement appendix of the USPS Parcel Labeling Guide. If a package curves in more than one direction, consider placing the parcel in a box or other flat-sided container.

How do I print an IMb label?¶

An IMb (Intelligent Mail barcode) is a barcode used by USPS to sort and track letters and flats. You can print IMb labels for letters and flats that use First-Class Mail. To do so, set the following when invoking the Create Shipment API:

serviceId to FCM
parcelType to either LETTER or FLAT.

Note: If you select FLAT, the label does not display the return address.
size to DOC_6X4

When creating the shipment, consider the following:

No extra services are supported with an IMb. Do not pass the specialServices array.
The PRINT_CUSTOM_MESSAGE_1 and PRINT_CUSTOM_MESSAGE_2 shipment options are not supported for FCM 6X4 labels with IMb.
Refunds are not supported at this time.

The output of the request is a 6X4 label with an IMb. The following example shows a label created for a letter:

Coming soon to the Sandbox environment: To track an IMb label, set the carrier query parameter to IMB when invoking the Tracking API. IMB must be all caps.

What is an IMpb?¶

An IMpb (Intelligent Mail package barcode) is the part of a shipping label that provides tracking on a package. An example IMpb is shown below. For detailed information on IMpb tracking and its benefits, please see the blog entry A Crash Course on the USPS IMpb on the Pitney Bowes shipping blog. See also the USPS PostalPro page on IMpb.

How do I print a Doc Tab label?¶

To print a 4X8 label with a 2-inch Doc Tab issue the Create Shipment API call with the following values:

Set the documents.size field to DOC_4X8.
Enter the information to be printed on the Doc Tab in the documents.docTab array. For details on the array, see Documents Object.

The following is a sample request:

curl -X POST .../v1/shipments \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": { ... },
    "rates": [ { ... } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "BASE64",
        "size": "DOC_4X8",
        "fileFormat": "ZPL2",
        "printDialogOption": "NO_PRINT_DIALOG",
        "docTab": [ {
            "name": "parcelTrackingNumber",
            "displayName": "Tracking Number"
        }, {
            "name": "Order#",
            "value": "FG3876"
        }, {
            "name": "Discount code",
            "value": "Mar20"
        } ]
    } ],
    "shipmentOptions": [ ... ]
}'

The following is a sample response:

{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": { ... },
    "rates": [ { ... } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "BASE64",
        "fileFormat": "ZPL2",
        "pages": [ {
            "contents":
                "XlhBCl5MSDE2LDEyCl5MTDEyMTIKXkZUIDU4MSwgNDAzIF5BVU4gIF5GRDAwMDReRlMgXkZYIENvbmZpZ3VyYWJsZSB
                ...
                gXkdCIDExMSw1MSwxLEIgXkZTCl5GTyAgIDAsICAgMCBeR0IgNzc2LDExOTgsMixCIF5GUwpeTEgwCl5MUk4KXlha"
        } ]
    } ],
    "shipmentOptions": [ ... ],
    "shipmentId": "USPS2200097907656638",
    "parcelTrackingNumber": "9405509898641491248893"
}

The following is a sample Doc Tab label:

Can I get only the USPS postage indicia to use on a label?¶

Pitney Bowes is not authorized by the US Postal Service (USPS) as a USPS PC Postage Vendor to supply only the indicium. We must supply a complete shipping label. USPS requires that shipping labels that contain indicia are certified by them. The labels the PB Complete Shipping APIs produce have been certified by the USPS and must be provided as a complete label. We must print the entire label, and the label must go through a certification process.

How do I print a return address that is different from the origin address?¶

For USPS shipments, you can print a return address on the label that is different from the origin address of the parcel. Do one of the following:

For a domestic shipment, set the following when creating the label:

In the fromAddress field, enter the return address you want printed on the label.
In the rates.inductionPostalCode field, enter the zip for the address from which the parcel is actually being shipped.

For an international shipment, set the altReturnAddress field to the return address you want printed on the label. Note that the altReturnAddress field applies only to international shipments.

How long is a USPS shipment label valid?¶

Once the label has been generated and physically printed, it should be shipped that day, but generally USPS does not stop shipments if they are shipped within a couple of days.

Labels can be postdated up to 7 days for regular shipments and 3 days for Priority Mail or International shipments.

Can I get the transaction receipt for a label that has already been printed?¶

No. The API does not support printing a label receipt after the label has been printed. You can, however, print a receipt when creating the label by using the SHIPPING_LABEL_RECEIPT shipment option. See Shipment Options.