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 Shipping APIs provide full-featured integration with USPS shipping services.

Operation
Method Endpoint

Validate Address

POST

/v1/addresses/verify
 

Suggest Addresses

POST

/v1/addresses/verify-suggest
 

Get USPS Rules

GET

/v1/information/rules/rating-services?carrier=USPS&originCountryCode={XX}&destinationCountryCode={YY}
 

Rate USPS Services

POST

/v1/rates
 

Create USPS Label

POST

/v1/shipments
 

Create USPS PMOD Label

POST

/v1/shipments
 

Reprint Label

GET

/v1/shipments/{shipmentId}?carrier={carrier}
 

Retry Label

GET

/v1/shipments?originalTransactionId={transaction_id}&carrier={carrier}
 

Void Label

DELETE

/v1/shipments/{shipmentId}
 

Create a USPS SCAN Form

POST

/v1/manifests
 

Get Tracking Information

GET

/v1/tracking/{trackingNumber}?packageIdentifierType=TrackingNumber&carrier=USPS
 


Services

The following USPS services are supported. To determine all restrictions on a USPS service, use the Carrier Rules API or the the USPS Domestic Mail Manual.

USPS Domestic Services

ID Service Parcel Types, not including restrictions [1]
EM Priority Mail Express FRE, LGENV, LGLFRENV, PKG, PFRENV
PM Priority Mail FRB, FRE, LGENV, LFRB, LGLFRENV, MLFRB, PKG, PFRENV, RBA, RBB, SOFTPACK, SFRB
FCM First-Class Mail FLAT, IRRPKG, LETTER, NMLETTER, PKG
PRCLSEL Parcel Select PKG
STDPOST Retail Ground (formerly Standard Post) PKG
LIB Library Mail LGENV, PKG
MEDIA Media Mail LGENV, PKG
PMOD Priority Mail Open and Distribute EMMTB, FTB, FTTB, HTB, SACK
[1]To determine further restrictions, such as compatibility with special services, use the Carrier Rules API.

USPS International Services

When a merchant uses a USPS international service, the returned label includes the customs form.

ID Shipping Service Parcel Types
EMI Priority Mail Express International FRE, LGLFRENV, PFRENV, PKG
PMI Priority Mail International FRE, LGLFRENV, PFRENV, DVDBOX, FRB, LFRB, PKG, SFRB, VIDEOBOX
FCMI First-Class Mail International LGENV, LTR, NMLTR
FCPIS First-Class Package International Service. For overseas tracking, see Do the APIs support E-DELCON? PKG


Special Services

This section describes supported USPS special services. Restrictions might apply beyond those listed here.

Important


 

  • The Special Services table below does not show compatibility with parcel types or with other special services. To determine these compatibilities, use the Carrier Rules API.
  • To determine a special service’s input parameters, use the Carrier Rules API, as explained in How do I know the input parameters for a USPS special service?
  • Use of a special service might be subject to other restrictions not shown in the table.
  • Do not include a special service unless you intend to apply it.
  • Some USPS services require that you add a trackable special service. For details, see this FAQ.
  • If you use the FCM service, no special service is required.

This table describe supported USPS special services. Restrictions might apply [2].

ID Special Service Services, not including restrictions [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 FCM, PM, EM, PRCLSEL, STDPOST
liveanimal-poultry Live Animal - Day Old Poultry 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 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](1, 2) To determine further restrictions and compatibilities, use the Carrier Rules API.


USPS Parcel Types

The following USPS parcel types are supported.

Letters and Flats

ID USPS Parcel Type Services Supporting the Parcel Type
FLAT

Large Envelope/Flat. Use only with service ID FCM and label size DOC_6X4 The generated label has an IMb. For additional considerations, see this IMb FAQ.

Note: To use a different service, use the LGENV parcel type instead.

Note: Advise shippers to ensure that none of the adhesive backing is exposed when attaching the label. Please see What is the correct placement for a shipping label?

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

Letter. Use only with service ID set to FCM and label size set to either DOC_6X4 or DOC_9X4. 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. Please see What is the correct placement for a shipping label?

FCM
LGENV Large Envelope/Flat

PM, EM, MEDIA, LIB, FCMI

Note: Do NOT use this parcel type with FCM. For FCM, use the FLAT parcel type.

LGLFRENV Legal Flat Rate Envelope PM, EM, PMI, EMI
LTR Letter. Use only with FCMI. FCMI
NMLETTER Sandbox only. Nonmachinable Letter. Use only with FCM. FCM
NMLTR Sandbox only. Nonmachinable Letter. Use only with FCMI. FCMI
PFRENV Padded Flat Rate Envelope PM, EM, PMI, EMI
SOFTPACK Soft Pack Envelope. For additional information, see this FAQ. PM

Packages

ID USPS 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
IRRPKG Sandbox only. Irregular Parcel FCM
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 USPS 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


USPS Labels

Please read the following considerations before printing a USPS label.

  • The Label Size values use an upper-case X. Using a lower-case x will result in an error.

  • 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.

  • When creating a First-Class Mail (FCM) shipment that uses the FLAT parcel type, set the label size to DOC_6X4. When creating an FCM shipment that uses the LETTER parcel type, set the label size to DOC_6X4 or DOC_9X4.

  • When creating an international shipment, set the label size DOC_4X6 or DOC_8X11. The returned label includes the customs form. The form is used as both the shipping label and the customs declaration.

  • To print a 4X8 label with a 2-inch Doc Tab, see How do I print a Doc Tab label?

  • USPS 4X6 labels use the following DPI settings. Set DPI in the resolution field in the Documents Object.

    File Format
    Content Type DPI
    PNG BASE64 DPI_203,
    DPI_300 (default)
    ZPL2 BASE64 DPI_203 (default),
    DPI_300 (domestic labels only)
  • Labels retrieved through URLs are available for 24 hours after label creation.

  • Advise shippers on correct label placement. Please see What is the correct placement for a shipping label?

     

USPS Label Options
Label Size
(size)
File Format
(fileFormat)
Content Type
(contentType)
DOC_4X6 PDF
PNG
ZPL2
URL
BASE64
BASE64
DOC_4X8 PDF
PNG
ZPL2
URL
BASE64
BASE64
DOC_6X4 PDF
PNG
ZPL2
URL
BASE64
BASE64
DOC_8X11 PDF
PNG
URL
BASE64
DOC_9X4 PDF
PNG
URL
BASE64


Surcharges

The following USPS surcharges can apply. If a surcharge applies, it is returned in the rates.surcharges array.

API Code Surcharge
irregular The parcel is an Irregular Parcel.
nonmachinable The parcel is a Nonmachinable Letter.
oversize The parcel is subject to oversize pricing.