Release Notes¶
Coming January 24, 2021¶
The USPS 2021 price changes will go into effect January 24, 2021. For details, see:
https://www.pitneybowes.com/us/postal-information/usps-rate-change-overview.html
Released on 2021-01-09¶
- The Create SCAN Form API now ignores empty
Strings in the
parcelTrackingNumbers
array and prints the SCAN form without throwing an error. - The new USPS rounding rules went into effect January 9, 2021. USPS rounds dimensions to 2 decimal places (e.g. 0.12) instead of 3 decimal places (e.g. 0.123) when determining price and rates.
Released on 2021-01-04¶
- The Create a Container Label provides the
PACKAGE_COUNT
parameter for entering the number of parcels in the container.
Released on 2020-11-18¶
- Pitney Bowes has opened new PB Standard Facilities in: Atlanta, GA; Odenton, MD; Orlando, FL; and Stockton, CA.
Released on 2020-10-18¶
- The new HS Code API predicts the HS Code for a parcel being shipped internationally and gives the level of confidence in the prediction.
- The new Archived Transactions API obtains transaction data older than six months.
Released on 2020-10-14¶
- The Rates API returns rates for PB Standard Delivery parcels.
- PB Standard Returns labels can print custom logos, custom barcodes, and additional sizes and formats.
Released on 2020-09-20¶
- The
trackingStatus
query parameter in the Transaction Reports API can now take a value ofALL
to return all tracking statuses.
Released on 2020-09-10¶
- For a return label, Get Transaction Reports now return a
POSTAGE PRINT
transaction the same day. - The Get All Merchants API now returns the
company
field.
Released on 2020-08-30¶
- Get Transaction Reports now query on tracking status through the
trackingStatus
query parameter and now return the most recent tracking event within 30 days of the parcel’s ship date. Transaction Reports also now return the induction postal code.
Released on 2020-08-26¶
- USPS® has retired the Scan-Based Return (SBR) program. In its place, merchants can use PB Expedited Returns. Cubic rates and flat-rate packaging are now available for PB Expedited Returns.
- Pitney Bowes now provides the following SDKs for the Shipping APIs: C#, Java, Node.js, PHP, and Python
- Pitney Bowes also now provides an OpenAPI definition you can use to generate additional SDKs.
Released on 2020-08-24¶
- The CBDS California and
Kentucky hubs now ship Standard
DDP (
PBXPS
) to additional countries.
Released on 2020-08-08¶
- Void a Shipment no longer requires a request body. The API provides query parameters for passing all values. You can still pass values through a request body, but using query parameters is recommended.
Released on 2020-07-18¶
- The USPS Automated Package Verification system, which supports adjustments for
weight, dimensions, zone, and packaging, has expanded the coverage to include
“Duplicate” and “Used Refunded” labels. As a result, the
Get Transaction Reports API will return two new values in the
adjustmentReason
field:duplicate
andusedRefundedLabel
- USPS no longer supports E-DELCON to the countries listed here. For supported countries, see this list provided by USPS. For more information on E-DELCON, see this FAQ.
Released on 2020-07-01¶
- The Add Tracking Events API allows merchants, carriers, and other parcel handlers to record tracking events for shipments. The API supports adding multiple events to multiple shipments in a single request.
- USPS has deprecated the “Return Receipt for Merchandise” (RRM) special service as part of the July 1 rate change.
Released on 2020-06-30¶
- Merchants can generate container labels through the Merchant Portal.
Released on 2020-06-18¶
- The Transaction Reports API does not provide information for transactions that were created more than six months ago. To retrieve older transactions, use the Archived Transactions API.
Released on 2020-06-10¶
- The Create a Container Label API prints a label for the shipment of containerized parcels destined for a Pitney Bowes facility.
- The PB Cross-Border Delivery Service (CBDS) now provides a bulk-pickup solution for merchants who ship more than 200 parcels a day. See the Bulk Pickup option on the Delivery to the Consolidation Center page.
Released on 2020-05-19¶
- The Create Shipment API supports creating a PB Standard Returns label. The API also provides the option to create label QR code.
- The Carrier Facility API locates Post Offices and other facilities near a given address.
Released on 2020-05-16¶
- You can now create PB Standard Delivery Manifests by specifying parcel tracking numbers.
Released on 2020-04-15¶
- When you print an IMb label for an FCM letter or flat, Pitney Bowes now creates a “Label created” tracking event.
Released on 2020-04-11¶
- Support for USPS shipment of irregular parcels and nonmachinable letters.
Released on 2020-04-06¶
- The default date range for Transaction Reports is now 92 days prior to the current date.
Released on 2020-03-31¶
- Canadian destinations only: CBDS supports shipment to Canada of ID8000 commodities. For details, see this FAQ.
Released on 2020-03-07¶
- FedEx® integration. Merchants can integrate existing FedEx accounts with the Shipping APIs.
- PB Cross-Border Delivery Service (CBDS) now provides Client IDs to use when testing in Sandbox.
- The Rate and Shipment APIs now determine the best rate for a soft pack by looking at weight-based pricing and 2-dimensional cubic pricing. The APIs no longer look at 3-dimensional cubic pricing.
Released on 2020-02-23¶
- The Create CBDS Shipment API provides the option to print first-mile labels.
Released on 2020-02-15¶
- First-Class Mail letters and flats now display the postage amount as human readable.
- First-Class Mail flats now print return addresses in
the top left corner of the label (as was already the case for FCM letters).
The API uses the address listed in the
fromAddress
object.
Released on 2020-02-12¶
- The
X-PB-Shipper-Carrier-AccountId
request header is now conditional. The header is required only if the merchant has multiple accounts with a carrier. If the merchant has only one account with the carrier, the header is not required. For more information on carrier accounts, see Carrier Account Registration.
Released on 2020-01-18¶
- The USPS 2020 Price Changes are in effect for shipments with a ship date of January 26, 2020 or later.
Released on 2020-01-14¶
- The Tracking API tracks PB Standard parcels using the
carrier
query parameter. The API reports both PB Standard and USPS tracking events. - If you onboard merchants through Merchant Portal and retrieve account details
through the Merchant Authorization API,
you can now use the optional
paymentMethod
query parameter to specify which payment methods to make available.
Released on 2020-01-04¶
- Merchants can now print PB Presort Labels for U.S. territories, U.S. possessions, and Freely Associated States. This is in addition to previous support for APO/FPO/DPO. Customs forms are not required.
Released in 2019¶
Released on 2019-12-05
- PB Expedited Returns labels are now in Production.
Released on 2019-11-14
- If you use the APAC Services to print PB Standard Delivery labels as PDFs, the PDFs are returned as Base64-encoded strings, not as URLs.
- PB Cross-Border Delivery Service (CBDS) now provides
the Prepay Express (
PBXPE
) service.
Released on 2019-10-30
Pitney Bowes has changed the domain for retrieving PDF labels and manifests. If you whitelist Pitney Bowes domains, you must update your whitelist.
Environment Domains for Retrieving PDF Labels and Manifests Obsolete Domain Production https://web-prd3.gcs.pitneybowes.com
https://web-prd4.gcs.pitneybowes.comhttps://web.gcs.pitneybowes.com Sandbox https://web-sandbox.gcs.pitneybowes.com https://web-prt3.gcs.pitneybowes.com
Released on 2019-10-24
- PB Standard shipments can use 4X4 labels. See PB Standard Labels.
- USPS 4X6 domestic labels can use 300 DPI. See USPS Labels.
- A merchant’s PB Postage Account can have a negative account balance in certain circumstances (such as after an APV transaction). In such cases, the merchant will not be able to print a label until the postage account is refilled.
Released on 2019-10-04
- PB Cross-Border Delivery Service (CBDS) now provides the
Postpay Standard (
PBXUS
) service.
- PB Cross-Border Delivery Service (CBDS) now provides the
Postpay Standard (
Released on 2019-10-03
- The Transaction Reports API returns
CREDIT ADJUSTMENT
andDEBIT ADJUSTMENT
transactions to indicate manual adjustments to postage accounts.
- The Transaction Reports API returns
Released on 2019-10-01
- The Transaction Reports API reports the initiation and resolution of APV disputes.
- The Auto Refund service is no longer available.
Released on 2019-09-30
- If a merchant has multiple carriers, the Get All Merchants API now returns information on the merchant’s carrier accounts.
Released on 2019-09-07
- PB Presort labels for Standard Mail flats can now include human-readable tracking information. See the PRINT_IMBREADABLE_BARCODE shipment option.
- PB Presort labels for flats can now print an Electronic Service Requested endorsement. See the NON_DELIVERY_OPTION shipment option.
- PB Presort labels for flats can now print a custom message. See the PRINT_CUSTOM_MESSAGE_1 shipment option.
Released on 2019-07-27
- You can now set the DPI of a PB Standard Delivery label using the
documents.resolution
field. For details, see description ofresolution
in the Documents Object.
- You can now set the DPI of a PB Standard Delivery label using the
Released on 2019-07-25
- ACH is now available on request as a payment method for a merchant’s PB Postage Account.
Released on 2019-07-17
- To optimize performance for requests originating from the Asia-Pacific (APAC) Region, the following APIs provide Asia-Pacific URIs: Create PB Standard Delivery Shipment, Create PB Standard Manifest, Void a Shipment.
Released on 2019-07-11
- If you use the Authorize a Merchant API to enroll merchants, you can now use a referral code to identify who referred a merchant to your software.
Released on 2019-07-09
- The new CBDS Shopping Cart Quotes API retrieves estimates of the shipping costs, duties, and taxes for the items in a buyer’s shopping cart.
Released on 2019-06-15
- The USPS June 23, 2019 rule changes are in effect for shipments with a ship date of June 23, 2019 or later.
- The Create PMOD Shipments API includes two new PMOD options for specifying NASS code and destination entry facility.
Released on 2019-06-07
- Two new PB Parcel Protection APIs let you void Parcel Protection coverage and let you request Parcel Protection reports.
Released on 2019-06-06
- PB Cross-Border Delivery Service (CBDS) now integrates with the PB Shipping APIs.
- The Tracking API now returns tracking information on First-Class Mail letters and flats. FCM letters and flats use IMb labels.
Released on 2019-06-01
- UPS® (United Parcel Service) integration. You can now integrate a merchant’s existing UPS account with the PB Shipping APIs. Merchants use existing API operations to print and track UPS labels. The APIs provide the following new operations for integrating a merchant’s UPS account: Register an Existing Carrier Account, Get Carrier License Agreement.
- Shipping to APO/FPO/DPO destinations using the Bound Printed Matter (
BPM
) service is now supported. Parcels ship using thePKG
parcel type and the PB Presort carrier service.
Released on 2019-05-21
- The new PB Parcel Protection APIs let you obtain Parcel Protection quotes and request Parcel Protection coverage for shipments, including shipments created outside the PB Shipping APIs.
Released on 2019-05-13
- The v4.0 Transaction Reports API now
returns information within the hour for
POSTAGE FUND
transactions. - In the v4.0 Transaction Reports API, the new
shipDetails
query parameter lets you choose whether to return the following fields for each transaction:dimensionalWeightOz
valueOfGoods
specialServices
customMessage1
customMessage2
- The v4.0 Transaction Reports API now
returns information within the hour for
Released on 2019-04-20
The new version (v4.0) of the Transaction Reports API returns information within the hour for the following:
POSTAGE PRINT
transactionsPOSTAGE REFUND
requestsNote that the resolution of a refund request is returned the same day that USPS approves or denies the refund.
The API now also returns additional information about transactions. For more information, please see Transaction Reports.
Released on 2019-04-13
- An issue has been fixed so that now if you ship from an APO/FPO/DPO address to an international address (i.e., an address that is not in the United States), the Create Shipment API works as expected. Previously the API had thrown an error.
Released on 2019-04-05
- An issue with refund requests made between April 3 to 5, 2019, has been corrected. The issue had caused all refunds for those dates to be rejected. The issue is corrected, and all refunds requested on those dates have been resubmitted.
Released on 2019-03-16
For USPS shipments, the cutoff time to include the current day’s date on a label or SCAN form is now 8 p.m. local time. Local time is based on the shipment or manifest request’s induction postal code, if present, or otherwise on the state specified in the sender’s address. This change increases the accuracy of estimated delivery dates.
Note: Transaction Reports will continue to return time in UTC/GMT.
- For more information on this change, see:
What are the cutoff times for USPS shipments and manifests?
What is included in a USPS SCAN form?
Released on 2019-03-01
- The 2019-03-01 change to the Transaction Reports date range is superseded by a change on 2020-04-06. Please see 2020-04-06.
Released on 2019-02-19
Pitney Bowes automatically credits and debits prepaid postage accounts with APV adjustments made by USPS. Pitney Bowes applies adjustments made by USPS February 1st and later.
To view APV adjustments, use the Transaction Reports API.
Released on 2019-02-09
Improved error messages for address validation: In case of an incomplete or undeliverable address, the
additionalInfo
field in the error object now provides a reason for the address validation failure. This applies to the Address Validation and Create Shipment APIs. As an example, if an address contains an unrecognized street name, the APIs now return the following error:{ "errorCode": "1019003", "errorDescription": "Either Invalid or missing street or stateProvince or postalcode ", "additionalInfo": "E411 - The street cannot be found in this locality.", }
Released on 2019-02-01
- Merchants can now use the Refill API to add funds to their PB Postage Accounts. Previously, merchants could perform refills only through the Merchant Portal.
Released on 2019-01-29
- To bolster security of the Shipping APIs, Pitney Bowes made a change to deserialize incoming requests. This may introduce some request failures as the APIs now enforce a stricter validation when unexpected fields or values are present in the request body. In order to avoid failed requests, please follow specifications based on the PB Shipping APIs documentation.
Released on 2019-01-27
- The USPS 2019 rate changes are now in production.
- The Shipping APIs now provide the option to use a standard error format for
all errors encountered. To use the standard format, you must set the
X-PB-UnifiedErrorStructure
header totrue
with each API call. Without the header, the APIs use multiple formats. For more information, see Error Object.
Released in 2018¶
- Released on 2018-11-22
- CN 22 and CP 72 customs forms now accommodate more characters in the
To
andFrom
address blocks by allowing lower-case characters. Previously, Pitney Bowes had converted all characters in the blocks to CAPS. Now Pitney Bowes prints the characters as typed by the merchant, whether lower or upper case. Note that Pitney Bowes still converts state and country to caps, per USPS rules.
- CN 22 and CP 72 customs forms now accommodate more characters in the
- Released on 2018-11-03
- The PRINT_CUSTOM_MESSAGE_2 shipment option now prints up to 102 characters (three lines of 34 characters each) on 4X6 USPS domestic labels.
- Released on 2018-10-27
- You can specify the DPI for PNG shipping labels using the
documents.resolution
field. For details, see description ofresolution
in the Documents Object. - For PB Standard shipments, you can now print 4X5 labels, in addition to 4X6 labels.
- You can specify the DPI for PNG shipping labels using the
- Released on 2018-09-29
- You can now subscribe a PB Standard shipment to receive provisioned
notifications by including the
NOTIFICATIONS
special service in the Create PB Standard Delivery Shipment request. The merchant must be configured for PB Standard notifications. - You can now print custom messages on PB Standard labels using the PRINT_CUSTOM_MESSAGE_2 shipment option when creating a PB Standard Delivery shipment.
- You can now subscribe a PB Standard shipment to receive provisioned
notifications by including the
- Released on 2018-09-06
- As part of enhanced payment security, the Merchant Signup API (deprecated) now requires you to pass the an access token.
- Released on 2018-08-23
- The minimum supported security protocol for connection to the PB Shipping APIs is TLS v1.2.
- Released on 2018-08-17
- You can now map client-generated identifiers to fields in the PB Standard
package record. Use the new
references
field when creating PB Standard Delivery shipments. This applies only to PB Standard shipments. - The PB Shipping APIs now offer PB Parcel Protection.
- You can now map client-generated identifiers to fields in the PB Standard
package record. Use the new
- Released on 2018-07-29
- Support for USPS carrier route codes in address validation and create shipment
responses. See the
carrierRoute
definition in the Address Object.
- Support for USPS carrier route codes in address validation and create shipment
responses. See the
- Released on 2018-06-15
- Merchants can now use the PB Shipping APIs to print USPS-compliant PB Standard labels.
- Merchants can now print PB Presort Labels for
the following services: Bound Printed Matter (
BPM
), Standard Mail (STANDARD
).
- Released on 2018-05-26
- The Rates and Shipment APIs now determine the best rate for a soft pack by looking at weight-based pricing, 2-dimensional cubic pricing, and 3-dimensional cubic pricing. Note: 3-dimensional cubic pricing is deprecated.
- Released on 2018-05-11
- The Get Transaction Reports API supports the following new
query values:
- The transactionType query parameter can now use
APV-POSTAGE ALL
to return all APV adjustments, both overpaid and underpaid. - The printStatus query parameter can return all SBR labels (deprecated). Note: USPS has retired the SBR program.
- The transactionType query parameter can now use
- The Get Transaction Reports API supports the following new
query values:
- Released on 2018-04-19
- Additional validations are now made on the merchant contact information sent through the Merchant Signup API (deprecated) and Register a Merchant API. A merchant’s address cannot contain a P.O. Box, and a merchant’s phone number must be valid. The validation changes meet USPS compliance requirements.
- Released on 2018-03-09
- The new Get Account Balances API retrieves the current balances for a PB Postage Account and PB Line of Credit.
- Released on 2018-02-20
- Support for 2-inch Doc Tab labels through the Create Shipment API’s
documents.docTab
array. For more information, see How do I print a Doc Tab label?
- Support for 2-inch Doc Tab labels through the Create Shipment API’s
- Released on 2018-01-21
- The USPS January 2018 Rate Changes have been deployed to the production environment. The rate changes reflect an average 3.9 percent increase across all shipping services. The changes affect both domestic and international shipping products, including Priority Mail, Priority Mail Express, and Priority Mail International.
- Registered Mail (
Reg
) and Registered Mail with Insurance (RegIns
) are no longer available with Priority Mail Padded Flat Rate Envelopes (PFRENV
). - In accordance with the January 2018 USPS changes, First-Class Mail
International (
FCMI
) shipments may contain only documents, not goods. When using FCMI, you must set the customs object’sreasonForExport
field toDOCUMENTS
. Goods that were formerly shipped via FCMI are eligible to be shipped via First-Class Package International Service (FCPIS
) and other services.
- Released on 2018-01-07
- You can create PB Presort labels and PB Presort pickup slips.
Released in 2017¶
Released on 2017-09-16
- You can create Priority Mail Open and Distribute (PMOD) shipments and their required manifests. Specifically, you can print PMOD labels and print PMOD manifests.
- The Address Validation API returns the 2-digit delivery point, when available.
Released on 2017-08-26
- The Merchant Signup API (deprecated) allows merchants to sign up for their own PB Postage Accounts directly within your application.
- The Create Shipment API now generates a single-ply customs declaration form for shipments to APO/FPO/DPO destinations and to participating countries. As of this writing, the following countries participate: Australia, Canada, and Costa Rica. For more information on customs forms, see this FAQ.
- This feature is no longer supported. Pitney Bowes offers an Auto Refund service that submits unused, prepaid labels for electronic refund on your behalf.
Released on 2017-07-22
- The new Pickups API allows merchants to schedule carrier pickups and, when necessary, to cancel previously scheduled pickups.
- The Rate Parcel and Create Shipment APIs now support printing a First-Class Letter with an Intelligent Mail barcode (IMb). For details, see this FAQ on IMb.
- The Rate Parcel and Create Shipment APIs now support the Soft Pack (
SOFTPACK
) parcel type. Soft packs are flexible packages that adhere and conform to the contents being packaged, in order to take up minimum cubic space.
Released on 2017-07-09
USPS Scan-Based Return (SBR) labels (deprecated). Note: USPS has retired the SBR program.
The new Suggest Addresses API provides address suggestions, when they’re available. The response can contain up to 20 suggestions. Results are not sorted by priority.
Note: The Validate an Address API has not changed.
The new Get Carrier Rules API retrieves USPS rules for domestic and international shipments. The rules provide information on weight/dimension constraints and on service compatibility.
When using the Rate Parcel API, you can now leave out the
parcelType
,serviceId
, or both, allowing merchants to find rates for multiple parcel types and services with one call. You can also specify special services in the rate request and obtain the special service fee in the response.The Rate Parcel and Create Shipment APIs support two new parcel types with Priority Mail International (PMI):
- DVD Flat Rate Box (DVDBOX)
- Large Video Flat Rate Box (VIDEOBOX)
Released on 2017-06-10
The Parcel Object, which is used in the Create Shipment and Rate Parcel APIs, now includes two new fields for specifying the value of the parcel:
valueOfGoods
andcurrencyCode
.Note:
valueOfGoods
is independent of the insured, COD, and customs values. If you add insurance or COD as a special service, you still must define the associatedINPUT_VALUE
in the rates.specialServices array. If you create an international shipment, you still must declare the customs value in the customsInfo.customsDeclaredValue field.The Create Shipment API now automatically reassigns values in the parcel.dimension object to ensure length is the longest dimension, followed by height, followed by width.
The Create Shipment API now generates customs forms for U.S. territories, possessions, and Freely Associated States. Hence, Create Shipment now requires customs data for shipments to U.S. territories (except VI & PR), U.S. possessions, and Freely Associated States, in accordance with USPS rules.
The Create Shipment API now returns an error if the declared value for customs exceeds $400 for either of the following two services: First-Class Mail International, First-Class Package International Service. This follows USPS rules.
Released on 2017-05-31
- Adult Signature Required and Adult Signature Restricted Delivery are now supported with the Rate Parcel and Create Shipment APIs.
- The Create Manifest API now allows you to both list shipments and specify a Shipper ID. If a listed shipment does not belong to the specified Shipper ID, the API returns an error. See Create a Manifest.
- Support has been removed for deprecated USPS STCs (Service Type Codes).
Released on 2017-05-12
- The Create Manifest API now lets you filter shipments
based on their
inductionPostalCode
. See Create a Manifest.
- The Create Manifest API now lets you filter shipments
based on their