Pitney Bowes¶
Overview
Pitney Bowes provides delivery and return shipping through PB Expedited and PB Standard services:
- PB Expedited provides domestic and international shipping through USPS®. PB Expedited offers both delivery and return labels. By default, all developer and merchant accounts have access to ship with PB Expedited.
- PB Standard provides postpaid shipping. Labels incur no charges at the time of print. PB Standard offers both delivery and return labels. When printing delivery labels, shippers must containerize their parcels. To ship with PB Standard, a merchant must first onboard.
Pitney Bowes recommends integrating your platform with both PB Expedited and PB Standard to provide shippers a full range of options.
This page lists the API Operations to use when integrating with Pitney Bowes, as well as the available services, parcel types, and other options. If you have not yet read the API Overview and tried the Getting Started steps, we recommend doing so.
On this page
API Operations¶
The following operations are used with PB Expedited and PB Standard. For PB Standard requests that originate in the Asia-Pacific Region, Pitney Bowes also provides APAC Services to localize operations. See APAC Services.
| Operation
|
Method | Endpoint
|
|---|---|---|
Validate an Address |
POST |
/v1/addresses/verify |
Suggest Addresses |
POST |
/v1/addresses/verify-suggest |
Get Carrier Rules |
GET |
/v1/information/rules/rating-services?carrier=USPS&originCountryCode={XX}&destinationCountryCode={YY} |
Rate a Service |
POST |
/v1/rates |
Create a Pitney Bowes Delivery Shipment (PB Expedited Delivery or PB Standard Delivery) |
POST |
/v1/shipments |
Create a PB Expedited Returns Label |
POST |
/v1/shipments |
Create a PB Standard Returns Label |
POST |
/v1/shipments |
Reprint a Label |
GET |
/v1/shipments/{shipmentId}?carrier={carrier} |
Retry a Label |
GET |
/v1/shipments?originalTransactionId={transaction_id}&carrier={carrier} |
Void a Label |
DELETE |
/v1/shipments/{shipmentId}?carrier={carrier}&cancelInitiator=SHIPPER |
Create a USPS SCAN Form |
POST |
/v1/manifests |
Create a PB Standard Closeout |
POST |
/v1/manifests |
Create a Container Label |
POST |
/v1/container-manifest |
Get Tracking Information |
GET |
/v1/tracking/{trackingNumber}?packageIdentifierType=TrackingNumber&carrier=USPS |
Find Carrier Facilities |
POST |
/v1/carrier-facility |
Get Carrier Countries |
GET |
/v1/countries?carrier={carrier}&originCountryCode={two-character-ISO-code} |
Accounts APIs |
—— |
See the Accounts APIs table on the Merchant Accounts page. |
Services¶
The following table shows supported services and their available parcel types. The table does not show restrictions such as which special service is compatible with a chosen combination of service and parcel type. For shipments that use PB Expedited, use the Rules API or USPS Domestic Mail Manual to determine which supported special services are compatible with a chosen combination of service and parcel type.
For PB Expedited international services, the returned label includes the customs form. Some domestic services might also include a customs form, as described in this FAQ.
| Mail Class
|
ID | PB Expedited
|
PB Standard
|
Parcel Types [1]
|
|---|---|---|---|---|
| Bound Printed Matter | BPM | ✓ | PKG | |
| First-Class Mail | FCM | ✓ | ✓ | Expedited: FLAT, IRRPKG, LETTER, NMLETTER, PKG
Standard: PKG |
| First-Class Mail International | FCMI | ✓ | LGENV, LTR, NMLTR | |
| First-Class Package International Service
(Supports E-DELCON) |
FCPIS | ✓ | PKG | |
| First-Class Package Return Service | FCM | ✓ | PKG | |
| Ground Return Service | PRCLSEL | ✓ | PKG | |
| Library Mail | LIB | ✓ | LGENV, PKG | |
| Media Mail | MEDIA | ✓ | LGENV, PKG | |
| Parcel Select | PRCLSEL | ✓ | PKG | |
| Parcel Select—Ground | PRCLSEL | ✓ | PKG | |
| Parcel Select Lightweight | PSLW | ✓ | PKG | |
| Parcel Select Return | PRCLSEL | ✓ | PKG | |
| Priority Mail | PM | ✓ | ✓ | Expedited: FRB, FRE, LGENV, LFRB, LGLFRENV, MLFRB, PKG, PFRENV, RBA, RBB, SOFTPACK, SFRB
Standard: PKG |
| Priority Mail Return Service | PM | ✓ | PKG, FRE, LGLFRENV, PFRENV | |
| Priority Mail Express | EM | ✓ | FRE, LGENV, LGLFRENV, PKG, PFRENV | |
| Priority Mail Express International | EMI | ✓ | FRE, LGENV, LGLFRENV, PFRENV, PKG | |
| Priority Mail International | PMI | ✓ | DVDBOX, FRB, FRE, LFRB, LGENV, LGLFRENV, PFRENV, PKG, SFRB, VIDEOBOX | |
| Retail Ground (formerly Standard Post) | STDPOST | ✓ | PKG |
|
Special Services¶
For special services, see the following:
PB Expedited Special Services¶
PB Expedited supports the following special services. Before using a special service, you must use the Rules API to determine:
- Compatibility with the chosen combination of service and parcel type.
- Compatibility with any other selected special services.
- The input parameters for the special service. For help determining input parameters, see this FAQ.
- Whether the combination of service and parcel type requires a trackable special
service. If it does, you can add a no-charge special service, such as
DelCon.
Important
- The table below shows which services use a special service. The table does not show compatibility with parcel types or other special services. To check compatibilities, use the Rules API.
- 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.
Note that if you use the FCM service, no special service is required.
| Special Service
|
ID | Services [2]
|
|---|---|---|
| Adult Signature Required | ADSIG | EM, FCM, PM, PRCLSEL |
| Adult Signature with Restricted Delivery | ADSIGRD | EM, FCM, PM, PRCLSEL |
| Certified Mail | Cert | FCM, PM |
| Certified Mail with Adult Signature | CERTAD | FCM, PM |
| Certified Mail with Adult Signature and Restricted Delivery | CERTADRD | FCM, PM |
| Certified Mail with Restricted Delivery | CertRD | FCM, PM |
| Collect On Delivery (COD) | COD | EM, FCM, LIB, MEDIA, PM, PRCLSEL, STDPOST |
| Collect On Delivery with Restricted Delivery | CODRD | EM, FCM, LIB, MEDIA, PM, PRCLSEL, STDPOST |
| Delivery Confirmation | DelCon | FCM, LIB, MEDIA, PM, PRCLSEL, STDPOST |
| Electronic Return Receipt | ERR | FCM, LIB, MEDIA, PM, PRCLSEL, STDPOST |
| Hazardous Materials | hazmat | EM, FCM, PM, PRCLSEL, STDPOST |
| Holiday Delivery. | holiday | EM |
| Insured Mail | Ins | EM, EMI, FCM, LIB, MEDIA, PM, PMI, PRCLSEL, STDPOST |
| Insured Mail with Restricted Delivery | InsRD | EM, FCM, LIB, MEDIA, PM, PRCLSEL, STDPOST |
| Live Animal | liveanimal | EM, FCM, PM, PRCLSEL, STDPOST |
| Live Animal - Day Old Poultry | liveanimal-poultry | EM, FCM, PM, PRCLSEL, STDPOST |
| Registered Mail | Reg | FCM, PM |
| Registered Mail with COD | RegCOD | FCM, PM |
| Registered Mail with Insurance | RegIns | FCM, PM |
| Registered Mail with Insurance and Restricted Delivery | RegInsRD | FCM, PM |
| Registered Mail with Restricted Delivery | RegRD | FCM, PM |
| Return Receipt | RR | EM, FCM, LIB, MEDIA, PM, PRCLSEL, STDPOST |
| Special Handling - Fragile | SH | EM, FCM, LIB, MEDIA, PM, PRCLSEL, STDPOST |
| Signature Confirmation | Sig | EM, FCM, LIB, MEDIA, PM, PRCLSEL, STDPOST |
| Signature with Restricted Delivery | SigRD | FCM, LIB, MEDIA, PM, PRCLSEL, STDPOST |
| Sunday Delivery | sunday | EM |
| Sunday holiday Delivery | sunday-holiday | EM |
|
PB Standard Special Services¶
The following special services are supported for PB Standard shipments created through the Shipping APIs. Do not include a special service unless you intend to apply it.
| ID | Special Service
|
Input Parameters |
|---|---|---|
| DelCon | Delivery Confirmation | Input parameters are not required for DelCon. To use DelCon, add the
following to the { "specialServiceId": "DelCon" }
|
| Sig | Signature Confirmation | Input parameters are not required for Sig. To use Sig, add the following to
the { "specialServiceId": "Sig" }
|
| NOTIFICATIONS | Subscribes the shipment to provisioned notifications. To use this special service, the merchant must be configured for PB Standard notifications. |
To set input parameters, see PB Standard Notifications. |
Parcel Types¶
For parcel types, see the following:
PB Expedited Letters and Flats¶
| ID | Parcel Type
|
Services that use the Parcel Type [3] |
|---|---|---|
| FLAT | Large Envelope/Flat. Use this parcel type only with First-Class Mail (FCM) and a label size of DOC_6X4. This parcel type does not support special services. If your large envelope or flat uses a mail class other than FCM, use the LGENV parcel type instead. The generated label for the FLAT has an IMb. For considerations when printing on IMb label, see this FAQ. Advise shippers to ensure that none of the adhesive backing is exposed when attaching the label. See What is the correct placement for a shipping label? |
FCM |
| FRE | Flat Rate Envelope | EM, EMI, PM, PMI |
| LETTER | Letter. Use this parcel type only with First-Class Mail (FCM) and a label size of either DOC_6X4 or DOC_9X4. This parcel type does not support special services. The generated label has an IMb. For considerations when printing on IMb label, see this FAQ. Advise shippers to affix the label to the upper right of the envelope and to ensure that none of the adhesive backing is exposed. See What is the correct placement for a shipping label? |
FCM |
| LGENV | Large Envelope/Flat Note: Do NOT use this parcel type with FCM. |
EM, EMI, FCMI, LIB, MEDIA, PM, PMI |
| LGLFRENV | Legal Flat Rate Envelope | EM, EMI, PM, PMI |
| LTR | Letter. Use this parcel type only with First-Class Mail International (FCMI). | FCMI |
| NMLETTER | Nonmachinable Letter. Use this parcel type only with First-Class Mail (FCM). For steps to ship non-machinable letters, please see this FAQ. |
FCM |
| NMLTR | Nonmachinable Letter. Use this parcel type only with First-Class Mail International (FCMI). For steps to ship non-machinable letters, please see this FAQ. |
FCMI |
| PFRENV | Padded Flat Rate Envelope | EM, EMI, PM, PMI |
| SOFTPACK | Soft Pack Envelope. For additional information, see this FAQ. | PM |
|
PB Expedited Packages¶
| ID | Parcel Type
|
Services that use the Parcel Type [4] |
|---|---|---|
| DVDBOX | DVD Flat Rate Box | PMI |
| FRB | Medium Flat Rate Box 1, Medium Flat Rate Box 2 | PM, PMI |
| IRRPKG |
For steps to ship irregular parcels, please see this FAQ. |
FCM |
| LFRB | Large Flat Rate Box | PM, PMI |
| MLFRB | Military Large Flat Rate Box | PM |
| PKG | Package | EM, EMI, FCM, FCPIS, LIB, MEDIA, PM, PMI, PRCLSEL, STDPOST |
| RBA | Regional Box A | PM |
| RBB | Regional Box B | PM |
| SFRB | Small Flat Rate Box | PM, PMI |
| VIDEOBOX | Large Video Flat Rate Box | PMI |
|
PB Standard Packages¶
The following parcel type is supported for PB Standard:
| ID | Parcel Type
|
Services Supporting the Parcel Type |
|---|---|---|
| PKG | Package | BPM, PRCLSEL, PSLW, FCM, PM |
Labels¶
Please read the following considerations before printing a label:
- The value for the label size uses an upper-case
X. Do not use a lower-case x. - Labels retrieved through URLs are available for 24 hours after creation.
- For APAC Services, this table does not apply. See APAC Label Settings.
- For ZPL2 labels, if your printer does not support Unicode, see this topic.
- For
FCM/FLATshipments, set the label size toDOC_6X4. - For
FCM/LETTERshipments, set the label size toDOC_6X4orDOC_9X4. - For international shipments, set the label size to
DOC_4X6orDOC_8X11. The returned label includes the customs form. The form serves as both shipping label and customs declaration. - To print Doc Tabs, see this FAQ.
- Default DPI is 203 for Standard Delivery; 300 for Standard Returns; and varies for Expedited, depending on the label size and format. For questions, contact ClientServicesTechSupport@pb.com.
- Advise shippers on correct label placement.
The following table describes the options available for Pitney Bowes labels:
| Label size
|
Carrier
|
PDF /
URL |
PNG /
BASE64 |
ZPL2 /
BASE64 |
|---|---|---|---|---|
| DOC_4X4 | Standard Delivery | ✓ | ✓ | ✓ |
| DOC_4X5 | Standard Delivery | ✓ | ✓ | ✓ |
| DOC_4X6 | Expedited Standard Delivery Standard Returns |
✓ ✓ ✓ |
✓ ✓ ✓ |
✓ ✓ ✓ |
| DOC_4X8 | Expedited | ✓ | ✓ | ✓ |
| DOC_6X4 | Expedited Standard Returns |
✓ ✓ |
✓ ✓ |
✓ ✓ |
| DOC_8X11 | Expedited Standard Returns |
✓ ✓ |
✓
|
|
| DOC_9X4 | Expedited | ✓ | ✓ |
Surcharges¶
For PB Expedited, 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. |
Onboard with PB Standard¶
To onboard a merchant to use PB Standard:
Contact your Pitney Bowes representative to register the merchant at one or more PB Standard facilities. Pitney Bowes will provide the merchant with a set of PB Standard IDs for use when shipping with PB Standard.
You can test PB Standard in the Sandbox environment by setting the IDs to the Sandbox values listed in the table below.
Email a request to ClientServicesTechSupport@pb.com asking Pitney Bowes to enable the merchant to use PB Standard. In the request, include the merchant’s Shipper ID and PB Standard IDs
PB Standard IDs¶
The following IDs apply when shipping and manifesting with PB Standard. To test PB Standard in the sandbox environment, use the ID values listed in the table’s Sandbox Value column.
| ID
|
Description
|
Sandbox Value
|
|---|---|---|
| CARRIER_FACILITY_ID | The PB Standard facility assigned to the merchant. A merchant can be assigned multiple PB Standard facilities. | 1585 |
| CLIENT_FACILITY_ID | The merchant’s facility. A merchant can have multiple client facility IDs. | 0093 |
| CLIENT_ID | The unique ID assigned to the merchant for use with PB Standard. | NGST |
PB Standard Facilities¶
The following are the Pitney Bowes Standard facilities.
| Facility Name
|
Facility Code (ID)
|
Facility Address
|
|---|---|---|
| ATL | 0224 | 3630 Royal South Pkwy #210, Atlanta, GA 30349 |
| ATL4 | 2035 | 3725 Royal South Pkwy, Atlanta, GA 30349 |
| BWI | 2109 | 1781 Crossroads Drive, Odenton, MD, 21113 |
| COM | 1304 | 6017 Randolph St., Commerce, CA 90040 |
| CVG | 0921 | 1200 Worldwide Blvd, Hebron, KY 41019 |
| DFW | 1361 | 1250 Mustang Drive, Grapevine, TX 76051 |
| EWR | 1779 | 117 Interstate Blvd, Monroe, NJ 08831 |
| IND | 1585 | 1415 Collins Rd, Greenwood, IN 46143 |
| MCO | 2121 | 2622 Consulate Drive Suite 100, Orlando, FL, 32819 |
| ONT | 1787 | 11260 Cedar Ave, Bloomington, CA 92316 |
| ORD | 1094 | 882 Carol Ct. Carol Stream, IL 60188 |
| PHL | 1532 | 305 Butterfly Commons, York, PA 17402 |
| RNO | 1328 | 38 Isidor Ct Suite 130, Sparks, NV 89441 |
| SCK | 2124 | 4733 Newcastle Rd. Building 3, Stockton, CA, 95215 |
| SEA | 1571 | 19005 64th Avenue South Ste 175, Kent, WA 98032 |
| SFO | 1548 | 125 Valley Drive, Brisbane, CA 94005 |
| SLC | 1712 | 2449 S 6755 W, Ste E, West Valley City, UT 84128 |