Labels FAQs¶

On this page

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

See also:

Reference Fields FAQs
How do I differentiate merchants when generating labels? in the Merchant FAQs
How do I request a refund for a USPS prepaid label? in the Refund FAQs

What is an IMpb?¶

An IMpb (Intelligent Mail package barcode) is the part of a USPS label that provides tracking on a package. 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.

Example IMpb:

What is an IMb?¶

An IMb (Intelligent Mail barcode) is the part of a USPS label that provides tracking on a letter or flat. When tracking an IMb label with the Track a Package API, set the carrier query parameter to IMB, all caps.

Example IMb:

How do I print a letter or flat label with an IMb?¶

To print a letter or flat label with an IMb, issue the Create Shipment API call using the following options:

Set the following:

carrier

serviceId

size

parcelType

USPS

FCM

DOC_6X4
DOC_9X4

LETTER or FLAT
LETTER
Do not include the specialServices array. No extra services are supported with an IMb.
Do not include the PRINT_CUSTOM_MESSAGE_1 or PRINT_CUSTOM_MESSAGE_2 shipment options. They are not supported for FCM letters and flats.

The label displays the postage amount as human readable and displays the return address using the information in the fromAddress in the request.

Important

The label is not refundable. You cannot request refunds for FCM letters and flats.

To track the label through the Track a Package API, set the carrier query parameter to IMB, all caps.

How do I print a doc tab?¶

To print a 4X8 label with a 2-inch doc tab, enter the following when issuing the Create Shipment API for PB Expedited Delivery:

Set documents.size to DOC_4X8.

In the documents.docTab array, enter the fields and values to display on the doc tab. Each object in the array takes the name element and then either the displayName or value element:

Element

Data Type

Description

name

String

Required. The field to be printed. This can be an existing field returned by the Create Shipment API or a custom field that you define.

displayName

String

If name is set to a field returned by the Create Shipment API, this defines how the field’s name is displayed on the label. For example, if you enter the following object in the docTab array:

{
  "name": "parcelTrackingNumber",
  "displayName": "Tracking Number"
}

The label will display:

Tracking Number: <parcelTrackingNumber>

where <parcelTrackingNumber> is the value of the parcelTrackingNumber field.

If you don’t define a displayName, the actual field name is used.

value

String

To display a field and value that are not returned by the Create Shipment API, enter the field name in the name field and enter the value here. For example:

{
  "name": "DiscountCode",
  "value": "JUN40"
}

The following is a sample documents object in a request to create a label with a doc tab:

"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"
    } ]
} ]

The following is the documents object from a sample response:

"documents": [ {
    "type": "SHIPPING_LABEL",
    "contentType": "BASE64",
    "fileFormat": "ZPL2",
    "pages": [ {
        "contents":
            "XlhBCl5MSDE2LDEyCl5MTDEyMTIKXkZUIDU4MSwgNDAz..."
    } ]
} ]

The following is a sample label with a doc tab:

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

For carriers other than PB Standard, you can print a return address on the label that is different from the origin address of the parcel. To print a different return address, do one of the following:

Shipment type	Set the following
U.S. domestic shipment, other than PB Standard	`fromAddress`: Enter the return address you want printed on the label `rates.inductionPostalCode`: Enter the zip for the address from which the parcel is actually being shipped
International shipments, except CBDS Returns	`altReturnAddress`: Enter the return address you want printed on the label
CBDS Returns	`additionalAddresses.address`: Enter the return address you want printed on the label `additionalAddresses.addressType`: Set to `SELLER` For details, see Create a CBDS Return
CBDS Domestic shipments	`altReturnAddress`: Enter the return address you want printed on the 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 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 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.

What is the correct placement for a shipping label?¶

For PB Expedited, PB Standard, 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.

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 setting the SHIPPING_LABEL_RECEIPT shipment option in the shipmentOptions array. See Shipment Options.