USPS

Overview

The Pitney Bowes Complete Shipping APIs let you integrate USPS® (U.S. Postal Service) shipping services seamlessly into your platform.

Onboard a Merchant to use USPS

When you add a merchant to your developer account, the merchant has access to print USPS labels. To add merchants, see Merchant Accounts.


Shipping Operations

The PB Complete Shipping APIs provide full-featured integration with USPS® shipping services:


Services

The following are the supported services for USPS.

Domestic

ID Service
EM Priority Mail Express
PM Priority Mail
FCM First-Class Mail
PRCLSEL Parcel Select
STDPOST Standard Post
LIB Library Mail
MEDIA Media Mail
PMOD Priority Mail Open and Distribute

International

ID Shipping Service
EMI Priority Mail Express International
PMI Priority Mail International
FCMI First-Class Mail International
FCPIS First-Class Package International Service. For overseas tracking, see Do the APIs support E-USPS DELCON?


Special Services

Please read the following considerations before applying a special service when printing a USPS label:

  • Do not include a special service unless you intend to apply it.

  • Restrictions: Use of a special service might be subject to restrictions not shown in the table below. For example, the table does not show compatible parcel types or compatibility with other special services. To determine such restrictions, please use the Carrier Rules API.

  • Input Parameters: A special service might take input parameters. The available parameters depend on the carrier rules, as explained in How do I know the input parameters for a USPS special service?

  • Tracking: If the mail class does not automatically provide tracking, you can add the trackable Delivery Confirmation (DelCon) special service at no charge.

  • Omitting special services: If you use the FCM mail class, you can choose to omit special services. To do so either leave out the specialServices array or pass an empty array:

    specialServices": []

The following are the supported special services for USPS.

ID Special Service Services Supporting the Special Service [2]
ADSIG Adult Signature Required FCM, PM, EM, PRCLSEL
ADSIGRD Adult Signature with Restricted Delivery FCM, PM, EM, PRCLSEL
Cert Certified Mail FCM, PM
CERTAD Certified Mail with Adult Signature FCM, PM
CERTADRD Certified Mail with Adult Signature and Restricted Delivery FCM, PM
CertRD Certified Mail with Restricted Delivery FCM, PM
COD Collect On Delivery (COD) FCM, PM, EM, MEDIA, PRCLSEL, STDPOST, LIB
CODRD Collect On Delivery with Restricted Delivery FCM, PM, EM, MEDIA, PRCLSEL, STDPOST, LIB
DelCon Delivery Confirmation FCM, PM, MEDIA, PRCLSEL, STDPOST, LIB
ERR Electronic Return Receipt FCM, PM, MEDIA, PRCLSEL, STDPOST, LIB
hazmat Hazardous Materials FCM, PM, EM, PRCLSEL, STDPOST
holiday Holiday Delivery. EM
Ins Insured Mail FCM, PM, EM, MEDIA, PRCLSEL, STDPOST, LIB, PMI, EMI
InsRD Insured Mail with Restricted Delivery FCM, PM, EM, MEDIA, PRCLSEL, STDPOST, LIB
liveanimal Live Animal Surcharge FCM, PM, EM, PRCLSEL, STDPOST
liveanimal-poultry Live Animal-Day Old Poultry Surcharge FCM, PM, EM, PRCLSEL, STDPOST
PMOD_OPTIONS Priority Mail Open and Distribute PMOD
Reg Registered Mail FCM, PM
RegCOD Registered Mail with COD FCM, PM
RegIns Registered Mail with Insurance FCM, PM
RegInsRD Registered Mail with Insurance and Restricted Delivery FCM, PM
RegRD Registered Mail with Restricted Delivery FCM, PM
RR Return Receipt FCM, PM, EM, MEDIA, PRCLSEL, STDPOST, LIB
RRM Return Receipt for Merchandise FCM, PM, MEDIA, PRCLSEL, STDPOST, LIB
SH Special Handling - Fragile FCM, PM, EM, MEDIA, PRCLSEL, STDPOST, LIB
Sig Signature Confirmation FCM, PM, EM, MEDIA, PRCLSEL, STDPOST, LIB
SigRD Signature with Restricted Delivery FCM, PM, MEDIA, PRCLSEL, STDPOST, LIB
sunday Sunday Delivery EM
sunday-holiday Sunday holiday Delivery EM
[2]A given combination might be further restricted. For all possible restrictions, use the Carrier Rules API.


Parcel Types

The following are the supported parcel types for USPS.

Letters and Flats

ID Parcel Type Services Supporting the Parcel Type
FLAT

Large Envelope/Flat. Use with FCM only. For other services, see the LGENV parcel type.

When you use the FLAT parcel type, you must set label size to DOC_6X4 and service ID to FCM. The generated label has an IMb (Intelligent Mail barcode). The label does not display the return address. For additional considerations, please see this IMb FAQ.

Note: Advise shippers to ensure that none of the adhesive backing is exposed when attaching the label. Exposed backings can interfere with mail-processing equipment. Please see What is the correct placement for a shipping label?

FCM
FRE Flat Rate Envelope PM, EM, PMI, EMI
LETTER

Letter. If you specify LETTER, you must set label size to DOC_6X4 and service ID to FCM. The generated label has an IMb. For additional considerations, see this IMb FAQ.

Note: Advise shippers to affix the label to the upper right of the envelope and to ensure that none of the adhesive backing is exposed. Exposed backings can interfere with mail processing equipment. Please see What is the correct placement for a shipping label?

FCM
LGENV

Large Envelope/Flat.

Note: Do not use this parcel type with the FCM service. For FCM, use the FLAT parcel type instead.

PM, EM, MEDIA, LIB, FCMI
LGLFRENV Legal Flat Rate Envelope PM, EM, PMI, EMI
PFRENV Padded Flat Rate Envelope PM, EM, PMI, EMI
SOFTPACK Soft Pack Envelope. For additional information, see this FAQ. PM

Packages

ID Parcel Type Services Supporting the Parcel Type
DVDBOX DVD Flat Rate Box PMI
FRB Medium Flat Rate Box 1, Medium Flat Rate Box 2 PM, PMI
LFRB Large Flat Rate Box PM, PMI
LP (deprecated) Large Package (deprecated) Support for the LP parcel type is deprecated.
MLFRB Military Large Flat Rate Box PM
PKG Package FCM, PM, EM, STDPOST, PRCLSEL, MEDIA, LIB, FCPIS, PMI, EMI
RBA Regional Box A PM
RBB Regional Box B PM
SFRB Small Flat Rate Box PM, PMI
VIDEOBOX Large Video Flat Rate Box PMI

PMOD Shipments

ID Parcel Type Services Supporting the Parcel Type
EMMTB Extended Managed Mail Tray Box PMOD
FTB Full Tray Box PMOD
FTTB Flat Tub Tray PMOD
HTB Half Tray Box PMOD
SACK Sack PMOD


Surcharges

The following surcharge can apply to a USPS shipment.

API Code Surcharge or Fee
oversize Package is subject to oversize pricing


Label Sizes and Formats

Please read the following considerations before printing a USPS label:

  • The label size, as specified in the documents.size field, uses an upper-case X. Using a lower-case x will result in an error.
  • When creating an international shipment, set the documents.size field to DOC_4X6 or DOC_8X11. The returned label will be a customs form. The form is used as both the shipping label and the customs declaration.
  • If you choose to retrieve the label through a URL, the URL is available for 24 hours after the shipment is created.
  • By default, the APIs print ZPL2 labels using the Unicode character set. If you have an older printer that does not support Unicode, see this Troubleshooting topic.
  • Advise shippers on correct label placement. Please see What is the correct placement for a shipping label?
Label Size File Format Content Type
DOC_4X6 PDF

PNG

ZPL2 [1]
URL

BASE64

BASE64
DOC_4X8 PDF

PNG

ZPL2 [1]
URL

BASE64

BASE64
DOC_6X4 PDF

PNG

ZPL2 [1]
URL

BASE64

BASE64
DOC_8X11 PDF

PNG
URL

BASE64
[1](1, 2, 3) By default, the APIs print ZPL2 labels using the Unicode character set.
If you have an older printer that does not support Unicode, see
this troubleshooting topic.

Example documents array, as sent in the request:

"documents": [ {
    "type": "SHIPPING_LABEL",
    "size": "DOC_4X6",
    "fileFormat": "PDF",
    "contentType": "URL",
    "printDialogOption": "EMBED_PRINT_DIALOG"
} ]

Example documents array, as returned in the response:

"documents": [ {
    "type": "SHIPPING_LABEL",
    "size": "DOC_4X6",
    "fileFormat": "PDF",
    "contentType": "URL",
    "contents": "https://.../usps/872060188/outbound/label/35c72f3443824415bf46ed4177118451.pdf"
} ]