web tools release notes · 2021. 1. 12. · release notes web tools apis united states postal...
TRANSCRIPT
Web Tools Release Notes
Version 1.17
Application: Web Tools APIs Package Name: 2020 Updates Package Version: 1.17
Table of Contents
1 Revision History ..................................................................................................................................................1 2 Implementation Summary ...................................................................................................................................3
2.1 Production Release: January 23, 2020 ......................................................................................................3 2.2 Production Release: February 20, 2020 .....................................................................................................5 2.3 Production Release: March 19, 2020 .........................................................................................................6 2.4 Production Release: April 23, 2020 - Canceled .........................................................................................6 2.5 Production Release: May 21, 2020 ............................................................................................................6 2.6 Production Release: June 25, 2020 ...........................................................................................................7 2.7 Production Release: July 23, 2020 - Canceled ..........................................................................................8 2.8 Production Release: August 27, 2020 ........................................................................................................8 2.9 Production Release: September 24, 2020 ..................................................................................................9 2.10 Production Release: October 22, 2020 ................................................................................................... 11 2.11 Production Release: To Be Determined .................................................................................................. 12
3 Appendices ...................................................................................................................................................... 14 3.1 Appendix A – Price Calculator and Label APIs ....................................................................................... 14 3.2 Appendix B – Sample API Requests, Responses, and Labels ............................................................... 15 3.3 Appendix C – HTTPS/Secure Web Tools APIs ....................................................................................... 24
1 Revision History Date Author File
Version Change Description
1/9/2020 Maggie Tillar V1.1 Initial external version
2/13/2020 Maggie Tillar V1.3 - Feb Release sections: 2.2.1 and 2.2.3 updated - Mar Release section 2.3 updated - Appendix B updated - Appendix C updated
5/11/2020 Maggie Tillar V1.5 - April Release section - canceled - May Release sections: 2.5.1-2.5.2 added - June Release sections: 2.6.1-2.6.5 added - August Release section 2.8.1 added - Sept Release sections: 2.9.1-2.9.2 added
Release Notes Web Tools APIs
United States Postal Service
Page 2 of 25
- TBD section 2.11 updated - Appendix B updated - Appendix C updated
6/15/20 Maggie Tillar V1.7 - June Release sections: 2.6.5 updated; 2.6.6-2.6.7 added - July Release section - canceled - August Release sections: 2.8.2 added - Sept Release section 2.9.2 updated - TBD section 2.11 updated
8/10/20 Maggie Tillar V1.9 - August Release date moved from 8/20/27 to 8/27/20 - August Release section 2.8 updated - Sept Release section 2.9 updated - Appendix B section 3.2.1 updated
9/14/20 Maggie Tillar V1.11 - Sept Release sections: 2.9.4 and 2.9.5 updated; section 2.9.6 added - Oct Release section 2.10 added - TBD section 2.11 updated - Appendix B section 3.2.1 updated
9/24/20 Maggie Tillar V1.13 - Sept Release section: 2.9.4 section deferred to Oct Release - Oct Release section: 2.10.3 added - Appendix B section 3.2.1 updated
10/8/20 Maggie Tillar V1.15 - Oct Release sections: 2.10.1, 2.10.2, and 2.10.3 updated - TBD section 2.11 updated - Appendix A section 3.1.3 updated - Appendix B section 3.2.1 updated - Appendix C section 3.3.2 updated
10/13/20 Maggie Tillar V1.17 - Oct Release section 2.10.1 updated
Release Notes Web Tools APIs
United States Postal Service
Page 3 of 25
2 Implementation Summary External testing availability via the Web Tools CAT / stg- environment for each release can be found in the respective section below. The external test environment can be accessed, using your production UserID, via the following URL scheme, host and path:
• Secure APIs: https://stg-secure.shippingapis.com/ShippingApi.dll
• Non-secure APIs: http://stg-production.shippingapis.com/ShippingApi.dll If you receive an authorization error, please contact [email protected] and include your UserID. Note: Gray coloring indicates production release changes have been implemented.
2.1 Production Release: January 23, 2020
External testing: January 7, 2020
The API changes noted below will be released to production in the late-night hours of January 23. USPS is enacting a Price Change on January 26, 2020, which will be available on January 23 when using a ship date of January 26 or beyond. All domestic and international price calculator and shipping label APIs will reflect updated pricing in XML responses, on shipping label images, and in the Shipping Services Files (see Appendix A for full list of price calculator and label APIs). For information on specific prices being updated, please go to https://about.usps.com/newsroom/national-releases/2019/1009-usps-announces-new-prices-for-2020.htm.
Changes beyond basic price updates are explained below, per API.
2.1.1 International Price Calculator (API=IntlRateV2, IntlRate) and Label API Updates
1. The following country name updates are applicable to the international APIs noted in Appendix 3.1.2 and 3.1.4:
o “Republic of Macedonia” updated to “Republic of North Macedonia”
• “Republic of Macedonia” will return an invalid country name error. Integrators should use Republic of North Macedonia ("North Macedonia, Republic of", "North Macedonia") in the applicable country name fields (i.e. <Country>, <ToCountry> etc.)
o “Republic of South Sudan” added as a new country
• Integrators should use Republic of South Sudan ("South Sudan, Republic of", "South Sudan") in the applicable country name fields (i.e. <Country>, <ToCountry> etc.)
• Note: Republic of South Sudan will be available in addition to current country of Sudan. o Reference Appendix B for examples.
2.1.2 Dimensional Weight Retail Ground Domestic Price Calculator Updates (API=RateV4)
1. The RateV4 API will be updated to reflect dimensional weighting being applied to USPS Retail Ground effective January 26th, 2020. For USPS Retail Ground pricing requests, Web Tools will support dimensional weighting:
o When any dimension (i.e. Length, Width, or Height) exceeds 12 inches
• <Girth> value will indicate rectangular or nonrectangular package shape o Applicable to <ServiceType>= “Retail Ground” o Applicable to return when <ReturnDimesionalWeight>= “true” o Limited Overland Routes (LOR) applicable in Alaska will NOT implement dimensional weight for
USPS Retail Ground. o USPS Retail Ground balloon pricing will be removed. o USPS Retail Ground oversized pricing (and structure) will remain. o For dimensional weight calculation details, reference: https://www.govinfo.gov/content/pkg/FR-
2019-10-17/html/2019-22640.htm and https://pe.usps.com/cpim/ftp/manuals/dmm300/123.pdf
Release Notes Web Tools APIs
United States Postal Service
Page 4 of 25
2.1.3 Dimensional Weight Retail Ground Domestic Label API Updates
1. Impacted Domestic Label APIs: Reference Appendix A section 3.1.3 2. Domestic Label APIs will be updated to reflect dimensional weighting being applied to USPS Retail
Ground effective January 26th, 2020. For USPS Retail Ground labels, Web Tools will support dimensional weighting:
o When any dimension (i.e. Length, Width, or Height) exceeds 12 inches
• <Girth> value will indicate rectangular or nonrectangular package shape o Limited Overland Routes (LOR) applicable in Alaska will NOT implement dimensional weight for
USPS Retail Ground. o USPS Retail Ground balloon pricing will be removed. o USPS Retail Ground oversized pricing (and structure) will remain. o For dimensional weight calculation details, reference: https://www.govinfo.gov/content/pkg/FR-
2019-10-17/html/2019-22640.htm and https://pe.usps.com/cpim/ftp/manuals/dmm300/123.pdf
2.1.4 Premium Tracking – Domestic Price Calculator Updates (API=RateV4)
1. USPS will offer new Premium Tracking option to allow a customer to purchase extended retention of tracking data on their mail piece for varying lengths of time up to 10 years when available.
2. RateV4 Updates: o Two new extra service code (i.e. <SpecialService>) enumerations added to request Premium
Tracking options:
• Non-signature products (“Scan Retention”): ServiceID= "181"
• Signature products (“Scan + Signature Retention”): ServiceID= "182" o New optional request tag <TrackingRetentionPeriod> added to indicate Premium Tracking length
of time in years. i.e. <TrackingRetentionPeriod>="0.5" indicates 6 months. o When <Service>= “ALL” indicated in XML request, the <TrackingRetentionPeriod> value will be
ignored and available Premium Tracking options will return with lowest tracking retention period values used as default. (i.e. ServiceIDs = “181”/6 months and “182”/3 years).
o New Premium Tracking extra service options shown in table below:
ServiceID Special Service Name <TrackingRetentionPeriod> Price
181 Scan Retention “0.5” (6 Months) $2.10
181 Scan Retention “1” (1 Year) $2.59
181 Scan Retention “3” (3 Years) $3.59
181 Scan Retention “5” (5 Years) $4.59
181 Scan Retention “7” (7 Years) $5.59
181 Scan Retention “10” (10 Years) $9.99
182 Scan + Signature Retention “3” (3 Years) $4.59
182 Scan + Signature Retention “5” (5 Years) $5.59
182 Scan + Signature Retention “7” (7 Years) $6.99
182 Scan + Signature Retention “10” (10 Years) $12.99
o Reference Appendix B for examples o Contact [email protected] for any questions and detailed specifications.
2.1.5 Premium Tracking – eVS Domestic Label API Updates (API=eVS)
1. USPS will offer new Premium Tracking option to allow a customer to purchase extended retention of tracking data on their mail piece for varying lengths of time up to 10 years when available.
2. eVS Updates: o Two new extra service code (i.e. <ExtraService>) enumerations added to request Premium
Tracking options:
• Non-signature products (“Scan Retention”): ServiceID= "181"
• Signature products (“Scan + Signature Retention”): ServiceID= "182" o New optional request tag <TrackingRetentionPeriod> added to indicate Premium Tracking length
of time in years. i.e. <TrackingRetentionPeriod>="0.5" indicates 6 months.
Release Notes Web Tools APIs
United States Postal Service
Page 5 of 25
• When <ExtraService>= “181” or “182” provided in XML request, <TrackingRetentionPeriod> is required.
o New Premium Tracking extra service options shown in table below:
ServiceID Service Name <TrackingRetentionPeriod> Price
181 Scan Retention “0.5” (6 Months) $2.10
181 Scan Retention “1” (1 Year) $2.59
181 Scan Retention “3” (3 Years) $3.59
181 Scan Retention “5” (5 Years) $4.59
181 Scan Retention “7” (7 Years) $5.59
181 Scan Retention “10” (10 Years) $9.99
182 Scan + Signature Retention “3” (3 Years) $4.59
182 Scan + Signature Retention “5” (5 Years) $5.59
182 Scan + Signature Retention “7” (7 Years) $6.99
182 Scan + Signature Retention “10” (10 Years) $12.99
o Web Tools will update the Shipping Services File to include correct Extra Service Code (SSFv2.0 D1, pos 44) and Extra Service Fee SSFv2.0 D1, pos 45) as specified in USPS Pub 199.
• Reference above section 2.1.4 for table of ESC values o Reference Appendix B for examples o Contact [email protected] for any questions and detailed specifications.
2.1.6 Miscellaneous Maintenance API Updates
1. Domestic Price Calculator API (API=RateV4) updated with new <Service> tag enumeration of "Parcel Select Ground" to support returning Parcel Select Ground (CLASSID = "77")
o i.e. <Service>Parcel Select Ground</Service> returns <Postage CLASSID="77"> <MailService>Parcel Select Ground<sup>™</sup></MailService>
o New service option applicable for Commercial Base and Commercial Plus RateV4 pricing requests.
o Parcel Select Ground will still be eligible to return when XML request contains <Service>= “ONLINE” or “PLUS.”
o Contact [email protected] for any questions and detailed specifications.
2.2 Production Release: February 20, 2020
External testing: February 10, 2020
2.2.1 eVS Domestic Label API Updates (API=eVS)
1. Web Tools will remove the DPO and trademark verbiage in the indicia section for eVS customs forms labels destined to Diplomatic Post Offices:
o Applicable to Priority Mail and Parcel Select Ground mail classes o eVS Customs forms to DPO destinations will only display mail class on top line of indicia
• i.e. "PRIORITY MAIL DPO™" will be updated to "PRIORITY MAIL" o Reference Appendix B for example
2. Web Tools will remove the Trademark symbol in the indicia section for eVS customs forms labels destined to APO/FPO/PTFAS locations:
o Applicable to Priority Mail and Parcel Select Ground mail classes o eVS Customs forms to APO, FPO, and PTFAS destinations will only display mail class on top line
of indicia
• i.e. "PRIORITY MAIL™" will be updated to "PRIORITY MAIL" o Reference Appendix B for example
Release Notes Web Tools APIs
United States Postal Service
Page 6 of 25
2.2.2 Redelivery APIs Retirement
1. The Web Tools 2.0 Redelivery/Delivery Instructions APIs will be retired effective February 20, 2020. o Impacted APIs:
• DI and Redelivery Availability (API=getDIRedeliveryAvailability)
• DI and Redelivery Status (API=getDIRedeliveryStatus)
• Create Delivery Instructions (API=createDeliveryInstructions)
• Create Redelivery (API=createRedelivery) o Contact [email protected] for any questions and detailed specifications.
2.2.3 Miscellaneous Maintenance API Updates
1. Web Tools will make updates to correctly populate the D1 Destination ZIP (pos 6) field in the Shipping Services File when destination is APO/FPO/DPO+PTFAS.
o Impacted APIs:
• Customs Form CN22 (API=CustomsCN22V2)
• Customs Form CP72 (API=CustomsCP72V3) 2. Web Tools will make fixes to Customs forms Invoice/License/Certificate No(s) field to prevent longer
values running outside the length of field. o Reference Appendix A section 3.1.4 for list of impacted APIs.
3. Web Tools will make backend API updates to better optimize performance. Integrators should see no changes in XML responses, but testing is encouraged. Reference Appendix A for list of impacted APIs.
2.3 Production Release: March 19, 2020
External testing: March 9, 2020
2.3.1 International Price Calculator and Label API Updates (Deferred)
1. Web Tools will update the International Price Calculator (API=IntlRateV2) and Label APIs to reflect the most accurate USPS international mailing prices and availability. Integrators will not be impacted since current XML request/response for impacted APIs will not change.
o Impacted APIs: Reference Appendix A sections 3.1.2 and 3.1.4. o International Price Calculator APIs and International Label APIs will continue returning the
following error response when prices and availability are not available for supplied XML request inputs:
• “Unable to calculate international postage. No services available.”
2.4 Production Release: April 23, 2020 - Canceled
External testing: April 13, 2020
Items will be moved to this release when scheduled and included in future versions of the release notes
2.5 Production Release: May 21, 2020
External testing: May 11, 2020
2.5.1 Security Certificate Updates – HTTPS URLs (effective May 10th, 2020)
1. Web Tools will install Sectigo (formerly COMODO) certificates May 10th, 2020 for all secure HTTPS APIs. The new certificates include new Sectigo Root and Intermediate certificates within the cert chain. Integrating systems will need to have these Sectigo Root and Intermediate certificates installed in their Trust store in order to continue to communicate with Web Tools.
o Reference Appendix C for complete schedule and list of impacted HTTPS URLs and APIs. o Contact [email protected] for any questions.
Release Notes Web Tools APIs
United States Postal Service
Page 7 of 25
2.5.2 Miscellaneous Maintenance API Updates
1. Updates to Package Pickup APIs to improve error handling when non-cleansed/standardized address information is provided in a Cancel (API=CarrierPickupCancel), Change (API=CarrierPickupChange), or Inquiry (API=CarrierPickupInquiry) request. Integrators should always use the returned cleansed/standardized address information (i.e. address returned in an Availability (API=CarrierPickupAvailability) or Schedule (API=CarrierPickupSchedule) request) when using Web Tools Package Pickup APIs to take action on an existing package pickup.
o For more details reference https://www.usps.com/business/web-tools-apis/package-pickup-api.pdf
2. Fixes to RateV4 API to resolve dimension errors seen when multiple packages are included in a single RateV4 XML request.
o Error message returned: “Dimensions, when specified, must be a valid decimal value such as 8 or 8.25 Please do not use symbols or fractions such as 9" or 8 5/8.”
2.6 Production Release: June 25, 2020
External testing: June 16, 2020
2.6.1 Post Office Locator API – Special Hours Updates (API=POLocatorV2Ext)
1. Web Tools will update the External POLocatorV2Ext API to support optionally returning multiple weeks of special hours when available for a facility.
o External testing available: 6/12/20 2. POLocatorV2Ext API Updates:
o New optional request tag <MaxSpecialWeeks> added to control number of weeks of special hours returned
• Values are number of weeks. (i.e. “1”, “2”, “3”, etc.). Ex. <MaxSpecialWeeks>=“3”.
• Default value is “1” week. o When provided in XML request, the <MaxSpecialWeeks> tag returns the requested number of
weeks for Special Business “SPCBUSINESS” hours if available for a facility.
• Note: Last Collection Hours “LASTCOLLECTION” and Special Last Collection “SPCLASTCOLLECTION” hours are not supported within POLocatorV2Ext API.
o When multiple weeks of special hours are requested (i.e. <MaxSpecialWeeks>=“2”), each week of hours will be grouped by the applicable <Starting> and <Ending> dates and returned as a separate set (i.e. <Set name="SPCBUSINESS">)
o Web Tools will add the ability to filter on hours in the XML request (i.e. POLocatorV2ExtRequest / Filters / Hours) with following enumerations:
• “ALL”, “24HR”, “SATURDAY”, “SUNDAY”, and “AFTER5PM.” Example: <Hours>SATURDAY</Hours>
o Reference Appendix B for example XML request/response o Contact [email protected] for access, questions, and detailed specifications.
2.6.2 Domestic Price Calculator Updates (API=RateV4)
1. Web Tools will update the RateV4 API to reflect USPS elimination of Return Receipt for Merchandise. o Return Receipt for Merchandise extra service/special service (ServiceID=107) will not return o RateV4 XML requests containing “107” indicated as extra service will return an error; i.e.
<SpecialService>107</SpecialService>.
2.6.3 International Price Calculator and Label API Updates
1. Web Tools will update the International Price Calculator (API=IntlRateV2) and Label APIs to reflect the most accurate USPS international mailing prices and availability. Integrators will not be impacted since current XML request/response schema for impacted APIs will not change.
o Impacted APIs: Reference Appendix A sections 3.1.2 and 3.1.4.
Release Notes Web Tools APIs
United States Postal Service
Page 8 of 25
o International Price Calculator APIs and International Label APIs will continue returning the following error response when prices and availability are not available for supplied XML request inputs:
• “Unable to calculate international postage. No services available.”
2.6.4 eVS International Label APIs – ZPL Updates
1. Web Tools will update the eVS International Label APIs to support label images in ZPL (Zebra Programming Language) format. ZPL format will support 203 DPI resolution.
o Impacted APIs: International eVS Label APIs.
• Reference Appendix A section 3.1.4 o Web Tools will add new <ImageParameter> enumerations for ZPL:
• “4X6ZPL203DPI”
• “4X6ZPL300DPI” (for future use – reference section 2.8.1) o Integrators interested in supporting customer acceptance testing should contact
2.6.5 Service Standards & Commitments APIs – Transportation Messaging Updates
1. Updates to enable returning new transportation exception messaging. o Impacted APIs: SDCGetLocations, StandardB, FirstClassMail, ExpressMailCommitment,
PriorityMail o When applicable, new message code “TM103” and message (see below example) will return
within the API response to indicate a transportation delay:
• <MsgCode>=“TM103”
• <Msg>= “Your shipment may be delayed due to transportation issues.” o Contact [email protected] for any questions.
2.6.6 Miscellaneous Maintenance API Updates
1. Fixes to Package Pickup APIs to resolve errors returned for specific addresses incorrectly flagged as profanity. Changes effective 6/16/20.
2. Fix to the Domestic Price Calculator (API=RateV4) to resolve errors returned when XML request contains <Service>= “PARCEL SELECT GROUND.”
2.6.7 eVS Label APIs - Miscellaneous Maintenance Updates
1. Fixes to the eVS domestic label API (API=eVS) to resolve issues with the processing category not being populated in Shipping Services File for eVS Priority Mail Cubic labels destined to APO/FPO/DPO+PTFAS locations requiring a Customs Form.
2. Fixes to eVS domestic label API (API=eVS) to resolve issue with invalid Service Type Code used for First-Class Package Service with Signature Confirmation Restricted Delivery. Invalid STC 937 will be replaced with correct STC 894 per PUB199 specifications
3. Fixes to eVS domestic label API image generation process to resolve issues reported with decoding labels generated by the eVS API.
2.7 Production Release: July 23, 2020 - Canceled
2.8 Production Release: August 27, 2020
External testing: August 10, 2020
2.8.1 Post Office Locator API – Temporarily Closed Locations Updates (API= POLocatorV2Ext)
1. Web Tools will make updates to the External Post Office Locator API (API=POLocatorV2Ext) to indicate which USPS facilities are temporarily closed.
Release Notes Web Tools APIs
United States Postal Service
Page 9 of 25
o Web Tools will return the below two new XML response tags when a USPS facility is temporarily closed:
• <TemporarilyClosed>Y</TemporarilyClosed> (indicates facility is temporarily closed)
• <TemporarilyClosedDate>2020-08-17</TemporarilyClosedDate> (indicates temporarily closed effective date)
o If a USPS facility is not temporarily closed (i.e. when indicator <TemporarilyClosed>=“N”), Web Tools will not return these new tags in the XML response.
o Reference Appendix B for example o Contact [email protected] for access, questions, and detailed specifications.
2.8.2 Miscellaneous Maintenance API Updates/Fixes
1. Fixes to eVS Domestic Label API to resolve inaccurate error messages returned when <ContentType> values of “Perishable”, “Pharmaceuticals”, or “MedicalSupplies” are included in the XML request but not available for service indicated.
o Fix will update inaccurate “HAZMAT” verbiage to reflect actual content type passed in request. o Example: When <ContentType> = “Perishable”, the following error messages will return:
• OLD: “ContentType of HAZMAT not available for Media, BPM or Standard Mail Marketing Parcel.”
• NEW: “ContentType of Perishable not available for Media, BPM or Standard Mail Marketing Parcel.”
2. Fixes to International Label APIs to resolve long addresses exceeding field boundaries when printed on a Customs Form.
o Impacted APIs: ExpressMailIntl, eVSExpressMailIntl
• Note: Access to ExpressMailIntl API restricted; contact [email protected] for questions.
o Example address: <ToAddress1>Aeropuerto Internacional de Corisco</ToAddress1> <ToCity>Corisco</ToCity> <ToCountry>Corisco Island (Equatorial Guinea)</ToCountry>
3. Backend address standardization and validation updates: o No changes expected to Web Tools Address and Label APIs, but integrators are encouraged to
test to ensure no interruptions to their current integration with Web Tools. o Contact [email protected] for any questions.
4. International Price Calculator and Label API fixes to return correct service availability for country indicated in XML request – reference Appendix A sections: 3.1.2 and 3.1.4 for list of impacted APIs.
o Current logic always returns availability of a parent country even when a child territory is included in XML request. Web Tools will update to use country provided in the request to resolve inaccurate availability being returned when service availability differs between the parent country and child territory.
o Example: Norfolk Island (Australia) – Australia is the Parent country of child territory Norfolk Island. Norfolk Island does not have GXG service, but Australia does. Web Tools updates will return the correct availability for the country passed and update any error messages to reference the country passed in the XML request. Note: USPS country service availability is subject to frequent updates – please reference https://postcalc.usps.com/Calculator/Index?country=10440 for latest country availability.
o Updates will not result in any XML request/response structural changes, but integrators should test to confirm they see correct availability returned when child territory is indicated in XML request.
o Contact [email protected] for any questions. (Deferred from Aug 27th release)
2.9 Production Release: September 24, 2020
External testing: September 14, 2020
Release Notes Web Tools APIs
United States Postal Service
Page 10 of 25
2.9.1 Domestic Label APIs Retirements
1. Web Tools will retire several legacy domestic label APIs which have been restricted since February 2018 and are planned for full retirement September 24, 2020. Reference https://www.usps.com/business/web-tools-apis/ for all available USPS Web Tools APIs, announcements, and documentation.
o Impacted APIs:
• SigConfirmCertifyV3.0
• SignatureConfirmationCertifyV4
• SignatureConfirmationV3.0
• SignatureConfirmationV4.0
• DelivConfirmCertifyV2
• DelivConfirmCertifyV3.0
• DeliveryConfirmationV2
• DeliveryConfirmationV3 o Note: the “Certify” APIs are intended for testing purposes only; these APIs do not generate valid
shipping labels. o Contact [email protected] for any questions.
2.9.2 TLS 1.2 Protocol Compliance Updates (effective Sept. 27, 2020)
1. Effective September 27, 2020, unless otherwise noted in the table below, Web Tools will BLOCK any traffic requests not using TLS 1.2 or above.
o Reference https://www.usps.com/business/web-tools-apis/web-tools-notice-tls-1.2-protocol-compliance.pdf
o After this change, connections not using TLS 1.2 or above will fail when attempting to access the APIs. Integrators may also see an error message return with language such as "handshake failure", "service unavailable", or "protocol type TLS 1.0/1.1 not available."
o It is possible that no changes are necessary to retain Web Tools services. Please review the entire message carefully and share with your web developer, software vendor, or IT service provider to determine if your use of the Web Tools APIs will be affected.
o In advance of the changes to production, connections not using TLS 1.2 or above will be blocked in the lower Web Tools environments and available for testing per the schedule and impacted secure (HTTPS) APIs listed below.
o Integrators using our unsecure (HTTP) APIs (URL: http://production.shippingapis.com/ShippingAPI.dll) are encouraged switch to our secure (HTTPS) APIs (URL: https://secure.shippingapis.com/ShippingAPI.dll) in advance of future plans to remove HTTP API support – details will be provided in future versions of the release notes.
Schedule
2.9.3 eVS Domestic and International Label APIs – ZPL Updates
1. Web Tools will update the Domestic and International eVS Label APIs to support ZPL label images (Zebra Programming Language) with a resolution of 300 DPI.
Environment URLs Impacted APIs Deployment
Date
Status
TEST
https://cat-webtools.usps.com
https://staging-
whitelabel.shippindapis.com
Ref. Appendix C section 3.3.4
3/30/2020 Complete
PROD https://webtools.usps.com
https://whitelabel.shippingapis.com
Ref. Appendix C section 3.3.4
4/13/2020 Complete
TEST https://stg-secure.shippingapis.com/ All HTTPS/Secure Web Tools APIs - Ref. Appendix C section 3.3.2
6/7/2020 Complete
PROD https://secure.shippingapis.com/ All HTTPS/Secure Web Tools APIs - Ref. Appendix C section 3.3.2
9/27/2020 Scheduled
Release Notes Web Tools APIs
United States Postal Service
Page 11 of 25
o Impacted APIs: Domestic and International eVS Label APIs.
• Reference Appendix A sections 3.1.3 and 3.1.4. o Web Tools will update current ZPL <ImageParameter> enumeration "4X6LABELZPL" to
"4X6ZPL203DPI"
• Integrators should use new “4X6ZPL203DPI” for eVS (domestic) Label APIs to return ZPL images with 203 DPI resolution.
• Current enumeration "4X6LABELZPL" will remain backwards compatible. o Web Tools will add/enable new ZPL <ImageParameter> enumeration “4X6ZPL300DPI.” o Integrators interested in supporting customer acceptance testing should contact
2.9.4 Post Office Locator API – Updates (API=POLocatorV2Ext) (Deferred to Oct Release)
1. Web Tools will make updates to the External Post Office Locator API (API=POLocatorV2Ext) to indicate when a USPS facility supports Label Broker (LBRO) printing.
o Web Tools will no longer return the <LBRORetail> response tag to indicate which USPS facilities support LBRO printing at retail.
• Label broker printing at retail will be indicated in POLocatorV2Ext API by new <Service> enumeration returned for available USPS facilities. See below.
o Web Tools will add a new service (i.e. <Service>) enumeration for label broker retail printing – name: “LBRORETAIL”.
o Web Tools will add a new service (i.e. <Service>) enumeration for label broker printing at Self-Service Kiosks (SSKs) – name: “LBROSSK”.
o Web Tools will add <Service> request tag with enumerations of “LBRORETAIL” and “LBROSSK” to <Filter> grouping in XML request to allow ability to sort on new services.
o Reference Appendix B for sample XML request/response. o Contact [email protected] for access, questions, and detailed specifications.
2.9.5 Miscellaneous Maintenance API Updates/Fixes
1. SCAN API Fixes – fixes to resolve errors seen when shortened IMpb barcodes destined to an APO/FPO/DPO+PTFAS location are included in a SCAN API XML request.
2.9.6 Time-Limited Price Change
1. USPS is enacting a time-limited Price Change on October 18, 2020 through December 26,2020. Updated prices via Web Tools APIs will be available on September 24 when using a ship date of October 18 or beyond through December 26. All domestic price calculator and shipping label APIs will reflect updated pricing in XML responses, on shipping label images, and in the Shipping Services Files (see Appendix A sections 3.1.1 and 3.1.3 for full list of domestic price calculator and label APIs).
o For information on specific prices being updated, please go to https://about.usps.com/newsroom/national-releases/2020/0814-usps-announces-temporary-price-increase.htm and https://pe.usps.com/pricechange/index
2.10 Production Release: October 22, 2020
External testing: October 13, 2020
2.10.1 USPS Returns – New USPS Returns Label API
1. Web Tools will create a new USPS Returns API to enable generation of USPS Returns labels. o New API will support the following services:
• GROUND RETURN SERVICE
• PRIORITY MAIL® RETURN SERVICE
• FIRST-CLASS™ PACKAGE RETURN SERVICE o New API will support the following extra services:
• Signature Confirmation
Release Notes Web Tools APIs
United States Postal Service
Page 12 of 25
o New API will support creation of returns labels to a single destination delivery address configured per Web Tools USERID, MID, and CRID. Please contact the USPS Mailing & Shipping Solutions Center (MSSC) for initial migration and onboarding.
o Cubic pricing will be supported via the Package Platform which will handle weighing and rating of labels generated through the Web Tools USPS Returns Label API.
• Note: Web Tools USPS Returns Label API will not display Cubic markings or prices on the label.
o Retirement of the Web Tools Merchandise Return Service Label APIs (API=MRS, MRSBulk) originally scheduled for September 2020 has been rescheduled to January 24th, 2021 – see full schedule below. Current Merchandise Return Service (MRS) API integrators should contact the USPS Mailing & Shipping Solutions Center (MSSC) at 1-877-672-0007 to transition off the MRS API immediately. Business hours for the MSSC are Monday-Friday from 7:00 AM-7:00 PM Central.
o Web Tools MRS API integrators should note the following USPS MRS Retirement schedule:
• Merchandise Return Service was retired August 28th, 2020.
• The Postal Service will retire the Web Tools MRS APIs on January 24th, 2021.
• Legacy label grace period will end June 20th, 2021. o For detailed API specifications contact [email protected].
2.10.2 Miscellaneous Maintenance API Updates/Fixes
1. Updates to eVSFirstClassMailIntl APIs to resolve errors with printing <FromFirm> on label. o Web Tools will truncate <FromFirm> value displayed on the label to 29 characters due to space
limitations. The API request tag will still accept <FromFirm> values up to 50 characters; truncation will only occur on the label image.
2.10.3 External Post Office Locator API Updates (API=POLocatorV2Ext)
1. Web Tools will make updates to the External Post Office Locator API (API=POLocatorV2Ext) to indicate when a USPS facility supports Label Broker (LBRO) printing.
o Web Tools will still return the <LBRORetail> response tag to indicate which USPS facilities support LBRO printing at retail for backwards compatibility.
• The current <LBRORetail> tag is planned for future deprecation. Integrators currently using this tag are encouraged to transition to using the new <Service> enumeration “LBRORETAIL” which will also be returned in the POLocatorV2Ext XML response to indicate facilities that support Label Broker (LBRO) printing at retail.
o Web Tools will add a new service (i.e. <Service>) enumeration for label broker retail printing – name: “LBRORETAIL” which will return in XML response as new tags when applicable for a facility.
o Web Tools will add a new service (i.e. <Service>) enumeration for label broker printing at Self-Service Kiosks (SSKs) – name: “LBROSSK” which will return in XML response as new tags when applicable for a facility.
o Web Tools will add <Service> request tag with enumerations of “LBRORETAIL” and “LBROSSK” to <Filter> grouping in XML request to allow ability to sort on new services.
o Reference Appendix B for sample XML request/response. o Contact [email protected] for access, questions, and detailed specifications.
2. Fixes to inconsistent error messages returned when invalid ZIP codes passed in the XML request. o When invalid ZIP code included in XML request (ex. “00001”) error message “GEO vendor cannot
interpret the given address” will return instead of the current vague message “no locations found in the search criteria.”
o Reference Appendix B for sample XML request/response.
2.11 Production Release: To Be Determined
Items will be moved to release dates as scheduled and included in future versions of the release notes
1. Customs Forms API Restrictions – Web Tools will prohibit external use of the Customs Form CN22 (API=CustomsCN22V2) and Customs Form CP72 (API=CustomsCP72V3) APIs.
Release Notes Web Tools APIs
United States Postal Service
Page 13 of 25
2. Web Tools will remove support for unsecure (HTTP) APIs. Integrators using our unsecure (HTTP) APIs (URL: http://production.shippingapis.com/ShippingAPI.dll) are encouraged switch to our secure (HTTPS) APIs (URL: https://secure.shippingapis.com/ShippingAPI.dll).
3. Enhancements to monitor, optimize, and prevent duplicate barcodes being generated for Domestic eVS Label API.
4. Fixes to International Price Calculator API, Label APIs, and GXG APIs to return correct service availability for country indicated in XML request – reference Appendix A sections: 3.1.2 and 3.1.4 for list of impacted APIs.
o Current logic always returns availability of a parent country even when a child territory is included in XML request. Web Tools will update to use country provided in the request to resolve inaccurate availability being returned when service availability differs between the parent country and child territory.
o Example: Norfolk Island (Australia) – Australia is the Parent country of child territory Norfolk Island. Norfolk Island does not have GXG service, but Australia does. Web Tools updates will return the correct availability for the country passed and update any error messages to reference the country passed in the XML request. Note: USPS country service availability is subject to frequent updates – please reference https://postcalc.usps.com/Calculator/Index?country=10440 for latest country availability.
o Updates will not result in any XML request/response structural changes, but integrators should test to confirm they see correct availability returned when child territory is indicated in XML request.
o Contact [email protected] for any questions.
Release Notes Web Tools APIs
United States Postal Service
Page 14 of 25
3 Appendices
3.1 Appendix A – Price Calculator and Label APIs
3.1.1 Domestic Price Calculator APIs
Description API Name
Domestic Price Calculator RateV4
3.1.2 International Price Calculator APIs
Description API Name
International Price Calculator IntlRateV2, IntlRate (deprecated)
3.1.3 Domestic Label APIs
Description API Name
Merchandise Return Service MerchandiseReturnV4 (deprecated effective 1/24/21)
Merchandise Return Service Bulk MerchReturnV4Bulk (deprecated effective 1/24/21)
USPS Returns Label USPSReturnsLabel (available 10/22/20)
eVS Domestic eVS
SCAN Form SCAN
3.1.4 International Label APIs
Description API Name
Express Mail International – eVS eVSExpressMailIntl
Priority Mail International – eVS eVSPriorityMailIntl
First Class Mail International - eVS eVSFirstClassMailIntl
GXG Get Label – eVS eVSGXGGetLabel
Customs Form CN22 CustomsCN22V2 (deprecated)
Customs Form CP72 CustomsCP72V3 (deprecated)
Release Notes Web Tools APIs
United States Postal Service
Page 15 of 25
3.2 Appendix B – Sample API Requests, Responses, and Labels
3.2.1 Sample XML Requests
This section provides sample XML requests to the CAT/staging environment that demonstrate some of the changes implemented to our APIs in this release. These requests are provided as a reference to aid in your understanding of the changes and in your integration with our updated APIs. You should still complete all your usual testing and verification processes to ensure that your system is communicating properly with the most updated version of Web Tools. Please note that you must place your valid USERID into the request. Sample responses are provided below the sample requests to illustrate the changes that will occur to the XML schema. Please note that the data within the tags may differ depending on inputs provided. Areas of note are highlighted.
IntlRateV2 Sample Request
January 2020 Release reference 2.1.1: New country South Sudan supported
<IntlRateV2Request USERID="XXXXXXXXX"> <Revision>2</Revision> <Package ID="0"> <Pounds>1</Pounds> <Ounces>0</Ounces> <MailType>ALL</MailType> <ValueOfContents>20</ValueOfContents> <Country>SOUTH SUDAN</Country> <Container>VARIABLE</Container> <Width>3</Width> <Length>3</Length> <Height>3</Height> <Girth>0</Girth> <OriginZip>44026</OriginZip> <CommercialFlag>Y</CommercialFlag> </Package> </IntlRateV2Request>
IntlRateV2 Sample Response
January 2020 Release reference 2.1.1: New country South Sudan supported <IntlRateV2Response> <Package ID="0"> <Prohibitions> Arms, including spare parts and ammunition. Infectious Substances, including exempt patient specimens (human or animal) and Category B infectious substances under 135.1 Gambling items, such as playing cards, poker chips and games of chance. Narcotics, including those prescribed by a doctor. Radioactive materials, including radioactive materials under 135.5. </Prohibitions> <Restrictions>No Restrictions Data found.</Restrictions> <Observations> All goods sent to South Sudan are subject to a customs clearance fee of 450 South Sudan Pounds (SSP) and an administration fee of 550 SSP. </Observations> <CustomsForms> All Priority Mail International items: PS Form 2976-A inside PS Form 2976-E (envelope) First-Class Mail International: PS Form 2976 as required (see 123.61) First-Class Package International Service and Airmail M-bags: PS Form 2976 </CustomsForms> <ExpressMail>No Express Mail Regulations Data found.</ExpressMail> <AreasServed>Please reference Express Mail for Areas Served.</AreasServed> <AdditionalRestrictions>No Additional Restrictions Data found.</AdditionalRestrictions> <Service ID="2"> <Pounds>1</Pounds> <Ounces>0</Ounces> <MailType>ALL</MailType> <Width>3</Width> <Length>3</Length> <Height>3</Height> <Girth>0</Girth> <Country>SOUTH SUDAN</Country>
Release Notes Web Tools APIs
United States Postal Service
Page 16 of 25
… </Service> </Package> </IntlRateV2Response>
RateV4 API Sample Request
January 2020 Release reference 2.1.4: New Premium Tracking extra services
<RateV4Request USERID="XXXXXXXXXX"> <Revision>2</Revision> <Package ID="1"> <Service>Priority</Service> <ZipOrigination>20770</ZipOrigination> <ZipDestination>54324</ZipDestination> <Pounds>2</Pounds> <Ounces>0</Ounces> <Container></Container> <Size>Regular</Size> <AmountToCollect></AmountToCollect> <SpecialServices> <SpecialService></SpecialService> <SpecialService>181</SpecialService> </SpecialServices> <Machinable>True</Machinable> <TrackingRetentionPeriod>3</TrackingRetentionPeriod> </Package> </RateV4Request>
RateV4 API Sample Response
January 2020 Release reference 2.1.4: New Premium Tracking extra services
<RateV4Response> <Package ID="1"> <ZipOrigination>20770</ZipOrigination> <ZipDestination>54324</ZipDestination> <Pounds>2</Pounds> <Ounces>0</Ounces> <Container>VARIABLE</Container> <Zone>5</Zone> <Postage CLASSID="1"> <MailService>Priority Mail 2-Day<sup>™</sup></MailService> <Rate>10.90</Rate> <CommitmentDate>2020-01-13</CommitmentDate> <CommitmentName>2-Day</CommitmentName> <SpecialServices> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService> <ServiceID>181</ServiceID> <ServiceName>Scan Retention</ServiceName> <Available>true</Available> <Price>3.59</Price> <DeclaredValueRequired>false</DeclaredValueRequired> <DueSenderRequired>false</DueSenderRequired> </SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> <SpecialService>...</SpecialService> </SpecialServices> </Postage> </Package>
Release Notes Web Tools APIs
United States Postal Service
Page 17 of 25
</RateV4Response>
eVS API Sample Request
January 2020 Release reference 2.1.5: New Premium Tracking extra services
<eVSRequest USERID="XXXXXXXXX"> <Option/> <Revision/> <ImageParameters> <ImageParameter>6X4LABEL</ImageParameter> </ImageParameters> <FromName>Lina Smith</FromName> <FromFirm>Horizon</FromFirm> <FromAddress1/> <FromAddress2>6 Plumbrook Court</FromAddress2> <FromCity>Reisterstown</FromCity> <FromState>MD</FromState> <FromZip5>21136</FromZip5> <FromZip4/> <FromPhone>1234567890</FromPhone> <POZipCode/> <AllowNonCleansedOriginAddr>False</AllowNonCleansedOriginAddr> <ToName>Tom Smith</ToName> <ToFirm>ABC Corp.</ToFirm> <ToAddress1>Suite 101</ToAddress1> <ToAddress2> 901 D St. SW</ToAddress2> <ToCity>Washington</ToCity> <ToState>DC</ToState> <ToZip5>20024</ToZip5> <ToZip4/> <ToPhone>2022242345</ToPhone> <POBox/> <AllowNonCleansedDestAddr/> <WeightInOunces>2</WeightInOunces> <ServiceType>Priority</ServiceType> <Container>Rectangular</Container> <Width>2</Width> <Length>2</Length> <Height>2</Height> <Machinable>True</Machinable> <ProcessingCategory/> <PriceOptions/> <InsuredAmount></InsuredAmount> <AddressServiceRequested>true</AddressServiceRequested> <ExpressMailOptions> <DeliveryOption/> <WaiverOfSignature/> </ExpressMailOptions> <ShipDate/> <CustomerRefNo>123</CustomerRefNo> <CustomerRefNo2>123456</CustomerRefNo2> <ExtraServices> <ExtraService>181</ExtraService> </ExtraServices> <HoldForPickup/> <OpenDistribute/> <PermitNumber/> <PermitZIPCode/> <PermitHolderName/> <CRID/> <SenderEMail>[email protected]</SenderEMail> <RecipientName></RecipientName> <RecipientEMail/> <ReceiptOption/> <ImageType>PDF</ImageType> <HoldForManifest/> <RateClientType>011</RateClientType> <RatePriceType>B</RatePriceType> <RatePaymentType>6</RatePaymentType> <TrackingRetentionPeriod>3</TrackingRetentionPeriod>
Release Notes Web Tools APIs
United States Postal Service
Page 18 of 25
</eVSRequest>
eVS API Sample Response
January 2020 Release reference 2.1.5: New Premium Tracking extra services
eVSResponse> <BarcodeNumber>XXXXXXXXXXXXXXXXXXXXX</BarcodeNumber> <LabelImage>...</LabelImage> <ToName>TOM SMITH</ToName> <ToFirm>ABC CORP.</ToFirm> <ToAddress1>STE 101</ToAddress1> <ToAddress2>901 D ST SW</ToAddress2> <ToCity>WASHINGTON</ToCity> <ToState>DC</ToState> <ToZip5>20024</ToZip5> <ToZip4>2198</ToZip4> <Postnet>200242198264</Postnet> <RDC>0024</RDC> <Postage>7.02</Postage> <ExtraServices> <ExtraService> <ServiceID>181</ServiceID> <ServiceName>Scan Retention</ServiceName> <Price>3.59</Price> </ExtraService> <ExtraService> <ServiceID>155</ServiceID> <ServiceName>USPS Tracking Electronic</ServiceName> <Price>0.00</Price> </ExtraService> </ExtraServices> <Zone>01</Zone> <CarrierRoute>C001</CarrierRoute> <PermitHolderName>Not Valid Test Label</PermitHolderName> <InductionType>ePostage</InductionType> <LogMessage/> <RateClientType>011</RateClientType> <RatePriceType>B</RatePriceType> <RatePaymentType>6</RatePaymentType> </eVSResponse>
POLocatorV2Ext API Sample Request
June 25, 2020 Release reference 2.6.1: Post Office Locator APIs – Special Hours Updates. New tag requesting multiple weeks of special hours to return. New option to filter hours.
<POLocatorV2ExtRequest USERID="xxxxx"> <ZIP5>14621</ZIP5> <Radius>20</Radius> <MaxLocations>1</MaxLocations> <MaxSpecialWeeks>3</MaxSpecialWeeks> <Filters> <FacilityType>PO</FacilityType> <Hours></Hours> </Filters> </POLocatorV2ExtRequest>
POLocatorV2Ext API Sample Response
June 25, 2020 Release reference 2.6.1: Post Office Locator APIs – Special Hours Updates. Response returns 3 weeks for SPCBUSINESS.
<POLocatorV2ExtResponse> <Locations> <Location> <LocationName>IRONDEQUOIT</LocationName> <Address2>425 E RIDGE RD</Address2> <City>ROCHESTER</City> <State>NY</State> <ZIP5>14621</ZIP5> <Hours>
Release Notes Web Tools APIs
United States Postal Service
Page 19 of 25
<Set name="BUSINESS"> <MO> <Open>07:30:00</Open> <Close>18:00:00</Close> </MO> <TU> <Open>07:30:00</Open> <Close>18:00:00</Close> </TU> <WE> <Open>07:30:00</Open> <Close>18:00:00</Close> </WE> <TH> <Open>07:30:00</Open> <Close>18:00:00</Close> </TH> <FR> <Open>07:30:00</Open> <Close>18:00:00</Close> </FR> <SA> <Open>09:00:00</Open> <Close>14:00:00</Close> </SA> <SU /> </Set> <Set name="SPCBUSINESS"> <MO /> <TU /> <WE /> <TH /> <FR /> <SA> <Open>08:30:00</Open> <Close>13:00:00</Close> </SA> <SU /> <Starting>2020-04-05</Starting> <Ending>2020-04-11</Ending> </Set> <Set name="SPCBUSINESS"> <MO /> <TU /> <WE /> <TH /> <FR /> <SA> <Open>08:30:00</Open> <Close>13:00:00</Close> </SA> <SU /> <Starting>2020-04-12</Starting> <Ending>2020-04-18</Ending> </Set> <Set name="SPCBUSINESS"> <MO /> <TU /> <WE /> <TH /> <FR /> <SA> <Open>08:30:00</Open> <Close>13:00:00</Close> </SA> <SU /> <Starting>2020-04-19</Starting> <Ending>2020-04-25</Ending> </Set> <Set name="WINDOWSSERVICE">
Release Notes Web Tools APIs
United States Postal Service
Page 20 of 25
<MO> <Open>07:30:00</Open> <Close>18:00:00</Close> </MO> <TU> <Open>07:30:00</Open> <Close>18:00:00</Close> </TU> <WE> <Open>07:30:00</Open> <Close>18:00:00</Close> </WE> <TH> <Open>07:30:00</Open> <Close>18:00:00</Close> </TH> <FR> <Open>07:30:00</Open> <Close>18:00:00</Close> </FR> <SA> <Open>09:00:00</Open> <Close>14:00:00</Close> </SA> <SU /> </Set> </Hours> <Parking>LOT</Parking> <LBRORetail>Y</LBRORetail> </Location> </Locations> </POLocatorV2ExtResponse>
POLocatorV2Ext API Sample Response
August 20, 2020 Release reference 2.8.1: POLocatorV2Ext temporarily closed facility updates. New tags returned to indicate a facility is temporarily closed and effective date.
<POLocatorV2ExtResponse> <Locations> <Location> <LocationName>GODWIN</LocationName> <Address2>8817 MAIN ST</Address2> <City>GODWIN</City> <State>NC</State> <ZIP5>28344</ZIP5> <Hours> ... </Hours> <TemporarilyClosed>Y</TemporarilyClosed> <TemporarilyClosedDate>2019-11-22</TemporarilyClosedDate> <Parking>LOT</Parking> <LBRORetail>N</LBRORetail> </Location> </Locations> </POLocatorV2ExtResponse>
POLocatorV2Ext API Sample Request
October 22, 2020 Release reference 2.10.3: POLocatorV2Ext External API LBRO service updates. New <Service> tags returned to indicate a facility supports label broker printing at retail and SSKs and existing <LBRORetail> tag returned for backwards compatibility.
<POLocatorV2ExtRequest USERID="XXXXXXXX"> <Revision>1</Revision> <FirmName>ALABAMA CITY</FirmName> <Address1>500 N RANDALL RD</Address1> <Address2/> <City>BATAVIA</City> <State>IL</State> <Radius>50</Radius>
Release Notes Web Tools APIs
United States Postal Service
Page 21 of 25
<MaxLocations>10</MaxLocations> <Filters> <FacilityType>PO</FacilityType> <Service/> <Hours/> </Filters> </POLocatorV2ExtRequest>
POLocatorV2Ext API Sample Response
October 22, 2020 Release reference 2.10.3: POLocatorV2Ext External API LBRO service updates. New <Service> tags returned to indicate a facility supports label broker printing at retail and SSKs and existing <LBRORetail> tag returned for backwards compatibility.
<POLocatorV2ExtResponse> <Locations> <Location> <LocationName>BATAVIA</LocationName> <Address2>500 N RANDALL RD</Address2> <City>BATAVIA</City> <State>IL</State> <ZIP5>60510</ZIP5> <Services> <Service name="LBRORETAIL"/> <Service name="LBROSSK"/> </Services> <Hours> … <Parking>LOT</Parking> <LBRORetail>Y</LBRORetail> </Location> </Locations> </POLocatorV2ExtResponse>
External POLocatorV2Ext API Sample Request
October 22, 2020 Release reference 2.10.3: POLocatorV2Ext External API invalid ZIP code error message fix.
<POLocatorV2ExtRequest USERID=”XXXXXXXXX”> <Revision>1</Revision> <ZIP5>00001</ZIP5> <Radius>20</Radius> <MaxLocations>10</MaxLocations> <Filters> <FacilityType>PO</FacilityType> </Filters> </POLocatorV2ExtRequest>
External POLocatorV2Ext API Sample Response
October 22, 2020 Release reference 2.10.3: POLocatorV2Ext External API invalid ZIP code error message fix.
<Error> <Number>800412fd</Number> <Source>POLocator</Source> <Description>GEO vendor cannot interpret the given address</Description> </Error>
Release Notes Web Tools APIs
United States Postal Service
Page 22 of 25
3.2.2 Sample Labels/Receipts
This section provides sample label and receipt images to the CAT/staging environment that demonstrate some of the changes implemented to our APIs in this release. These samples are provided as a reference to aid in your understanding of the changes and in your integration with our updated APIs. You should still complete all your usual testing and verification processes to ensure that your system is communicating properly with the most updated version of Web Tools.
3.2.2.1 February 20, 2020 Release
eVS Domestic Label API Updates – reference section 2.2.1
Figure 1: SAMPLE Priority eVS DPO Customs form - "DPO", Trademark removed
Release Notes Web Tools APIs
United States Postal Service
Page 23 of 25
Figure 2: SAMPLE Priority Mail eVS APO Customs form - Trademark removed
Release Notes Web Tools APIs
United States Postal Service
Page 24 of 25
3.3 Appendix C – HTTPS/Secure Web Tools APIs
3.3.1 Security Certificate Updates (HTTPS APIs)
Status Common Name (CN) Envir. URLS Current Expiration Date
Deployment Date
2021 Expiration Date
Complete stg-secure.shippingapis.com
TEST https://stg-secure.shippingapis.com/ 3/26/2020 3/10/2020
3/2/2021
Complete secure.shippingapis.com PROD https://secure.shippingapis.com/ 5/23/2020 5/10/2020 4/10/2021
3.3.2 Web Tools Secure/HTTPS APIs
API API Name
Carrier Pickup Availability CarrierPickupAvailability
Carrier Pickup Cancel CarrierPickupCancel
Carrier Pickup Change CarrierPickupChange
Carrier Pickup Inquiry CarrierPickupInquiry
Carrier Pickup Schedule CarrierPickupSchedule
City+State Lookup CityStateLookup
Customs Form CN22 CustomsCN22V2
Customs Form CP72 CustomsCP72V3
eVS Domestic eVS
eVS Domestic Cancel eVSCancel
eVS Express Mail International eVSExpressMailIntl
eVS First Class Mail International eVSFirstClassMailIntl
eVS GXG Public Label generation eVSGXGGetLabel
eVS International Cancel eVSICancel
eVS Priority Mail International eVSPriorityMailIntl
GXG Get Commodity Information GXGGetCommodityInfo
GXG - Guarantee GXGGetGuarantee
Hold For Pickup Facility Information HFPFacilityInfo
International Price Calculator IntlRateV2, IntlRate (deprecated)
Merchandise Return Service MerchandiseReturnV4 (deprecated effective 1/24/21)
Merchandise Return Service Bulk MerchReturnV4Bulk (deprecated effective 1/24/21)
Priority Mail Service Standards PriorityMail
Track and Confirm - Email PTSEmail
Track and Confirm - Pod PTSPod
Track and Confirm - Tpod PTSTpod
Track and Confirm - Rre PTSRre
Domestic Price Calculator RateV4
SCAN SCAN
Package Services Service Standards StandardB
Track and Confirm TrackV2
Release Notes Web Tools APIs
United States Postal Service
Page 25 of 25
USPS Returns Label USPSReturnsLabel (available 10/22/20)
Address Validation Verify
ZipCode Lookup ZipCodeLookup
3.3.3 Security Certificate Update (HTTPS Web Tools 2.0 APIs):
Status Common Name (CN)
Envir. URLS Current Expiration Date
Deployment Date
2021 Expiration Date
Complete Web Tools 2.0 APIs TEST https://cat-webtools.usps.com/ 7/4/2020 5/10/2020 4/16/2021
Complete White Label APIs TEST https://staging-whitelabel.shippingapis.com/ 3/26/2020 3/10/2020
2/27/2021
Complete Web Tools 2.0 APIs PROD https://webtools.usps.com/ 6/20/2020 5/10/2020 4/14/2021
Complete White Label APIs PROD https://whitelabel.shippingapis.com/ 7/2/2020 5/10/2020 4/13/2021
3.3.4 Secure HTTPS Web Tools 2.0 APIs
API API Name
Package Intercept Status status
Package Intercept Hold For Pickup holdForPickup
Package Intercept Redirect createRedirect
Package Intercept Return to Sender createRTS
Create Delivery Instructions createDeliveryInstructions
EDDMR EDDMR
ForeverPrepaidLabel ForeverPrepaidLabel
DI and Redelivery Availability getDIRedeliveryAvailability
DI and Redelivery Status getDIRedeliveryStatus
Create Redelivery createRedelivery