USPS Returns Label API
USPS Web Tools™
Application Programming Interface
Guía del usuario
Version 1.8 (8/2/2023)
Índice
3.0 Appendix A – Image Parameter Options
4.0 Appendix B – Label Samples
4.1 USPS Returns Label Sample – Priority Mail Return Service
4.2 USPS Returns Label Sample – Priority Mail Express Return Service
4.3 USPS Returns Label Sample – Ground Advantage Return Service
This document contains a Reference Guide to the USPS Returns Label API. See the Developer’s Guide to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The Developer’s Guide also contains information on testing and troubleshooting.
Nota: The Request Parameter sections present the XML input tags for generating live requests along with the restrictions on the values allowed. An error message will be returned if an incorrect value is entered. Also, be aware of the maximum character amounts allowed for some tags - an error will return if values passed exceed these limits. Where a parsing expression or character limit is not documented for tags defined as a String, Web Tools will simply pass in the characters up to the maximum amount allowed and disregard the rest. This is important since the resulting value could prevent a correct response. We recommend integrators check the character length of all values passed in the API request to avoid any truncation or unsuccessful responses.
When building the XML request, pay particular attention to the order and case for tags. An error message will be returned if an incorrect value is entered. Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values.
For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Web Tools Technical Documentation Page.
Nota: The Web Tools user ID (i.e.“123ABCD456”) you receive upon registration will not work at www.usps.com (also reference: https://es-reg.usps.com); USPS Web Tools API user ID credentials are separate and required for API use.
Additional onboarding is required before integrators can begin using the Web Tools USPSReturnsLabel API to generate USPS Returns service labels. Integrators should contact the USPS Mailing & Shipping Solutions Center (MSSC) at 1-877-672-0007 for assistance. Business hours for the MSSC are Monday-Friday from 7:00 AM-7:00 PM Central. The USPS Returns web page can also be referenced: https://es.usps.com/business/return-services.htm
The Web Tools USPS Returns Label API enables customers to receive USPS Returns service labels which are processed using the new automated returns process via Package Platform. USPS Returns service account holders will pay postage and fees through an Enterprise Payment System (EPS) account so that items can be returned by their customers (at no charge to their customers) using merchant provided USPS Returns service labels. The API allows integrators to request USPS Returns service labels for items that can be mailed using First-Class Package Return Service, Priority Mail Return Service, and Ground Return Service. For additional USPS Returns service details, reference: https://www.federalregister.gov/documents/2020/02/25/2020-03170/usps-returns-service.
Initial onboarding will include:
Part I: Technical Integration Specialist (TIS)
· Package Platform enrollment
· USPS Returns enrollment
· EPS account enrollment for electronic funds transfer for payment of USPS Returns service postage.
· USPS Web Tools API registration resulting in generation of Web Tools user ID and access configuration
· Mailer ID (MID) enrollment
· Customer Registration ID (CRID) enrollment
· Configuration of Destination Delivery Address (where applicable)
Customer Types:
The USPS Returns Label API will support the following configuration options determined during initial customer onboarding:
· Non-manifesting (SSF) Option: Supports creation of returns label to a single delivery destination address configured per Web Tools UserID. Unique ZIP4 for returns supported. Nota: The ability to generate returns labels to multiple delivery destinations requires separate Web Tools UserIDs for each destination address.
· Manifesting (SSF) Option (not eFulFillment): Supports creation of returns label to a configured delivery destination address with options for Insurance extra services. Unique ZIP4 for returns supported. A Shipping Services File will be submitted by Web Tools for returns labels on behalf of the integrator.
· Manifesting (SSF) eFulfillement for Returns Option: Supports creation of returns label for eFulfillment returns customers to a delivery destination address collected in the API request with options for Insurance extra services. A Shipping Services File will be submitted by Web Tools for returns labels on behalf of the integrator. Nota: The USPSReturnsLabel API will AMS-validate the destination addresses provided by eFulFillment customers or an error will return. Unique ZIP4s are not applicable to these customers.
USPS Returns Label API Feature |
Non-manifesting Option |
Manifesting Option (not eFulfillment) |
Manifesting Option (eFulfillment) |
USPS Returns Services: |
- |
- |
- |
· PRIORITY MAIL RETURN SERVICE |
Disponible |
Disponible |
Disponible |
· PRIORITY MAIL EXPRESS RETURN SERVICE |
Disponible |
Disponible |
Disponible |
· GROUND ADVANTAGE RETURN SERVICE |
Disponible |
Disponible |
Disponible |
Servicios Adicionales: |
- |
- |
- |
· Insurance |
N/A |
Disponible |
Disponible |
· HAZMAT Extra Services |
Disponible |
Disponible |
Disponible |
Ability to use multiple delivery destination addresses per Web Tools UserID. (Address collected in XML request and submitted in fSSF) |
N/A |
N/A |
Disponible |
Ability to specify Customer Reference Number(s) on label |
Disponible |
Disponible |
Disponible |
Ability to specify attention line on label for Delivery Destination Address |
Disponible |
Disponible |
Disponible |
Support Puerto Rican Origin Addresses |
Disponible |
Disponible |
Disponible |
Support Priority Mail Cubic Returns Pricing |
A confirmar |
A confirmar |
A confirmar |
Label Sizes/types: |
- |
- |
- |
Default (6x4 label and receipt printed on same 8.5x11 page) Enumeration: “6X4 PAGE” |
Disponible |
Disponible |
Disponible |
· ZPL (203 and 300 dpi) Enumerations: “4X6ZPL203DPI” and “4X6ZPL300DPI” |
Disponible |
Disponible |
|
· True 4x6 portrait Enumeration: “4X6” |
Disponible |
Disponible |
Disponible |
· True 6x4 landscape Enumeration: “6X4” |
Disponible |
Disponible |
Disponible |
· True 4x4 (restricted) |
A confirmar |
A confirmar |
A confirmar |
USPS Tracking Email |
Disponible |
Disponible |
Disponible |
USPS Tracking Email with PDF returns label attachment |
Disponible |
Disponible |
Disponible |
Support unique Returns ZIP4 |
Disponible |
Disponible |
N/A |
Generate Shipping Services File |
N/A |
Disponible |
Disponible |
Label volume reporting |
Disponible |
Disponible |
Disponible |
2D IMpb Barcode |
Disponible |
Disponible |
Disponible |
Optional Fees and Attributes (i.e., dim wt.) Breakdown |
Disponible |
Disponible |
Disponible |
Scheme |
Host |
Path |
API |
XML |
||||
https:// |
secure.shippingapis.com |
/ShippingAPI.dll? |
API=USPSReturnsLabel |
&XML=(see below) |
||||
https:// |
secure.shippingapis.com |
/ShippingAPI.dll? |
API=USPSReturnsLabelCertify |
&XML=(see below) |
||||
Nota: The “USPSReturnsLabelCertify” API is for testing purposes and will not generate usable labels and barcodes.
Tag Name |
Occurs |
Descripción |
Tipo |
Validation |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest |
Obligatorio |
Used with API=USPSReturnsLabel |
(Alias) |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / USERID |
Obligatorio |
This attribute specifies your Web Tools user ID. See the Developer's Guide for information on obtaining your USERID. Por Ejemplo: USERID="XXXXXXX" |
NMTOKEN |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / PASSWORD |
Obligatorio |
This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. Por Ejemplo: PASSWORD="XXXXXXX" |
NMTOKEN |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / Option |
Optional |
For future use. |
String |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / Revision |
Optional |
Used to indicate API version. Use a value of “2” to return a shortened IMpb barcode in the <TrackingNumber> tag. Por ejemplo: <Revision>2</Revision> |
String |
minLength=0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / ImageParameters |
Obligatorio |
Group containing all request parameters pertaining to the Label Image generation. |
(Group) |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / ImageParameters / ImageType |
Obligatorio |
Label Image Type. See Appendix A for Image parameter options. Por ejemplo: <ImageType>PDF</ImageType> |
String |
Enumeration= · PDF · TIF · NONE · ZPL |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Optional |
Returns alternate label image. See Appendix A for Image parameter options. Por ejemplo: <ImageParameter>4X6</ImageParameter> |
String |
Default=6X4PAGE Enumerations= · 4X6 · 6X4 · 6X4PAGE · 4X6ZPL203DPI · 4X6ZPL300DPI · SEPARATERECEIPTPAGE |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerFirstName |
Conditionally required (only if CustomerFirm not provided) |
First Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Nota: <CustomerFirstName> and <CustomerLastName> values have a combined 32-character limit when printed on label. Combined values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters. |
String |
minLength=1 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerLastName |
Conditionally required (only if CustomerFirm not provided) |
Last Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Nota: <CustomerFirstName> and <CustomerLastName> values have a combined 32-character limit when printed on label. Combined values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters. |
String |
minLength=1 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerFirm |
Conditionally required (only if Customer First/Last Name not provided) |
Firm Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Nota: <CustomerFirm> has a 32-character limit when printed on label. Values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters. |
String |
minLength=1 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerAddress1 |
Conditionally required (if address needs secondary info) |
Secondary address unit designator and number (such as an apartment or suite number). Por ejemplo: “APT 202” or “STE 100” etc. Nota: This tag must be included in the request, even if the value is null, to return a successful response. For addresses that do not require secondary information, integrators should include “<CustomerAddress1/>” in the request. |
String |
minLength=0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerAddress2 |
Obligatorio |
Address of customer returning the package. (Primary Street address). Por ejemplo: <CustomerAddress2>123 Main St.</CustomerAddress2> |
String |
minLength=1 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Conditionally required (if address is in Puerto Rico) |
Urbanization of customer returning the package. |
String |
minLength=0 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerCity |
Obligatorio |
City of customer returning the package. |
String |
minLength=1 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerState |
Obligatorio |
State of customer returning the package. Value should be passed as two-letter state abbreviation. Por ejemplo: <CustomerState>DC</CustomerState> |
String |
pattern=\w{2} minLength=2 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerZip5 |
Obligatorio |
ZIP Code of customer returning the package. |
String |
pattern=\d{5} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerZip4 |
Optional |
ZIP+4 Code of customer returning the package. |
String |
pattern=\d{4} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / POZipCode |
Conditionally required (if mail entry ZIP Code different than CustomerZip5) |
ZIP Code of Post Office or collection box where item is mailed. May be different than CustomerZip5. This tag will take precedence over CustomerZip5 when provided. Will be used to populate the SSFv2.0 H1 pos. 7 Entry Facility ZIP Code field. Por ejemplo: <POZipCode>20770</ POZipCode> |
String |
pattern=\d{5} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / AllowNonCleansedOriginAddr |
Optional |
Allows Non-Validated Origin Street Address. Enter “true” to bypass street address validation failures/errors or “false” if only validated addresses should be allowed. Nota: Integrators are recommended to always use “false” to ensure no delivery issues. In the event USPS cannot validate the street address, this tag will “bypass” address validation error when “true” is indicated to allow label creation which could impact delivery. The <AllowNonCleansedOriginAddr> excludes City, State, and ZIP Code which must be valid for a successful response. Reference https://pe.usps.com/text/pub28/28c2_001.htm. |
Boolean |
Default=false Enumerations= · true · false |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Optional (May be specified when <ReturnsPostageType>=5) |
Attention line for Retailer Address. If supplied, this optional value will override the value stored in the Retailers WebTools Profile. Nota: <RetailerATTN> has a 32-character limit when printed on label. Values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters. |
String |
minLength=0 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Conditionally required (When <ReturnsPostageType>=5) |
Firm Name of Retailer Address for return package. Printed on label and receipt. <RetailerFirm> is required for Efulfillment customers using <ReturnsPostageType>=5. Minimum of 1 character required. Nota: <CustomerFirm> has a 32-character limit when printed on label. Values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters. |
String |
minLength=0 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RetailerAddress1 |
Optional (May be specified when <ReturnsPostageType>=5) |
Secondary address unit designator and number (such as an apartment or suite number). Por ejemplo: “APT 202” or “STE 100” etc. Nota: <RetailerAddress1> may be specified by Efulfillment customers using <ReturnsPostageType>=5. The value supplied will override the value stored in the Retailers WebTools Profile. Efulfillment customers supplying an empty tag or not supplying this tag will also override the value stored in the Retailers WebTools Profile resulting in no RetailerAddress1 line being displayed. |
String |
minLength=0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RetailerAddress2 |
Conditionally required (When <ReturnsPostageType>=5) |
Address of Retailer where the package will be returned. (Primary Street address). Por ejemplo: <RetailerAddress2>123 Main St.</ RetailerAddress2> Nota: <RetailerAddress2> is required for Efulfillment customers using <ReturnsPostageType>=5. Minimum of 1 character required. |
String |
minLength=1 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RetailerCity |
Conditionally required (When <ReturnsPostageType>=5) |
City of Retailer where the package will be returned. Nota: <RetailerCity> is required for Efulfillment customers using <ReturnsPostageType>=5. |
String |
minLength=1 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RetailerState |
Conditionally required (When <ReturnsPostageType>=5) |
State of Retailer where the package will be returned. Value should be passed as two-letter state abbreviation. Por ejemplo: <RetailerState >DC</ RetailerState > Nota: <RetailerState> is required for Efulfillment customers using <ReturnsPostageType>=5. |
String |
pattern=\w{2} minLength=2 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RetailerZip5 |
Conditionally required (When <ReturnsPostageType>=5) |
ZIP Code of Retailer where the package will be returned. Nota: <RetailerZip5> is required for Efulfillment customers using <ReturnsPostageType>=5. |
String |
pattern=\d{5} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RetailerZip4 |
Conditionally required (When <ReturnsPostageType>=5) |
ZIP+4 Code of Retailer where the package will be returned. Nota: <RetailerZip4> is required for Efulfillment customers using <ReturnsPostageType>=5. |
String |
pattern=\d{4} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RetailerEmail |
Conditionally required (When <ReturnsPostageType>=5) |
Email for Retailer of the return package. Nota: Either <RetailerEmail> OR <RetailerPhone> is required for Efulfillment customers using <ReturnsPostageType>=5. |
String |
pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RetailerPhone |
Conditionally required (When <ReturnsPostageType>=5) |
Phone number for Retailer of the return package. Nota: Either <RetailerEmail> OR <RetailerPhone> is required for Efulfillment customers using <ReturnsPostageType>=5. |
String |
pattern= \s*|[0-9]{10})? |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / WeightInOunces |
Optional |
Package weight used to calculate postage. Items must weigh 70 pounds (1120 ounces) or less. Por ejemplo: <WeightInOunces>80</ WeightInOunces> Nota: If weight not supplied, 4oz used. |
Integer |
Default=4 minInclusive=0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / ServiceType |
Obligatorio |
Enter one of the valid Mail Service entries: “PRIORITY” for Priority Mail Return Service. “EXPRESS” for Priority Mail Express Return Service. “GROUND” for Ground Advantage Return Service. |
String |
Enumeration= · PRIORITY · EXPRESS · GROUND |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Conditionally required (Required for Efulfillment users) |
The Postage Type for the Returns Label. Nota: Required for USPSReturns callers registered as Efulfillment users. Non-Efulfillment users may omit this tag or supply it with an empty value. |
String |
Enumeration= · 5 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / Width |
Optional |
Value must be numeric. Units are inches. Nota: If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm |
Decimal |
minExclusive=0.0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / Length |
Optional |
Value must be numeric. Units are inches. Length should be longest dimension when compared to Width and Height values supplied. Por ejemplo: <Length>11</Length> Nota: If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm |
Decimal |
minExclusive=0.0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / Height |
Optional |
Value must be numeric. Units are inches. Nota: If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm |
Decimal |
minExclusive=0.0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / Girth |
Conditionally required (if package is non-rectangular) |
Nota: Girth is required only for a non-rectangular package. For rectangular packages, girth must be left blank. Value must be numeric. Units are inches. Girth is distance around the thickest part of package (perpendicular to the length). For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail https://pe.usps.com/text/dmm300/index.htm. Por ejemplo: <Girth>25</Girth> Nota: If partial dimensions are provided, an error response will return. (i.e. Length, Width, and Height must all be supplied with Girth). |
Decimal |
minExclusive=0.0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / Machinable |
Optional |
Machinable parcels are defined as parcels less than or equal to 15”x18”x22” inches and less than or equal 25 pounds. Any parcel that exceeds either threshold (dimensions or weight) will be considered nonmachinable. Nota: The API will validate provided dimensions and/or weight to determine machinability. In this case the <Machinable> tag will be ignored. If these are not provided, then the <Machinable> tag will be used to designate if shipment is Machinable (true) or Nonmachinable (false). Por ejemplo: <Machinable>verdadero</Machinable> |
Boolean |
Default=true Enumerations= · true · false |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Optional |
|
String |
minLength=0 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / VendorProductVersionNumber |
Optional |
|
String |
minLength=0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / MailOwnerMID |
Optional |
|
String |
minLength =0 maxLength =9 pattern =\d{9} pattern =\d{6} pattern =\d{0} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerRefNo |
Optional |
Used to collect RMA number. The <CustomerRefNo> value will be used to populate the SSFv2.0 D1 pos. 21 Customer Reference Number field. |
String |
minLength=0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / PrintCustomerRefNo |
Optional |
Used to print <CustomerRefNo> value on the label. The <PrintCustomerRefNo> must be set to “true” in order to display <CustomerRefNo> on the label. |
Boolean |
Default=false Enumerations= · true · false |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / CustomerRefNo2 |
Conditionally required (When <ReturnsPostageType>=5) |
Used to collect merchant ID. Nota: <CustomerRefNo2> is required for Efulfillment customers using <ReturnsPostageType>=5. |
String |
minLength=0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / PrintCustomerRefNo2 |
Optional |
Used to print <CustomerRefNo2> data on the label. The <PrintCustomerRefNo2> must be set to “true” in order to display <CustomerRefNo2> value on the label. |
Boolean |
Default=false Enumerations= · true · false |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / SenderName |
Optional |
Used for the USPS Tracking email. Indicates the name of the person or company sending the USPS tracking email notification. Nota: No email is returned when generating a Sample (i.e., API=USPSReturnsLabelCertify) request. |
String |
minLength=0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Optional |
Used for the USPS Tracking email. Indicates the email address of sender used for USPS tracking email notification. Valid email addresses must be used. Nota: <RecipientEmail> must be populated to generate USPS tracking email notification. If <SenderEmail> provided without <RecipientEmail>, USPS tracking email notification will not be generated. Nota: No email is returned when generating a Sample (i.e., API=USPSReturnsLabelCertify) request. |
String |
pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4} |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RecipientName |
Optional |
Used for the USPS Tracking email. Indicates the name of the person or company receiving the USPS tracking email notification. If recipient name not provided, email will be addressed to <RecipientEmail> value provided. Nota: No email is returned when generating a Sample (i.e., API=USPSReturnsLabelCertify) request. |
String |
minLength=0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / RecipientEmail |
Optional |
Required to generate the USPS Tracking email. Indicates email address of recipient receiving the USPS tracking email notification. Valid email addresses must be used. Nota: No email is returned when generating a Sample (i.e., API=USPSReturnsLabelCertify) request. |
String |
pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / TrackingEmailPDF |
Optional |
Used to indicate if a PDF returns label will be attached (true) or not (false) to the USPS Tracking email. |
Boolean |
Default=false Enumerations= · true · false |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest / ExtraServices |
Optional |
Groups extra services elements |
(Group) |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Optional, repeating up to unbounded times |
Use to specify extra services. If no Extra Service is specified, USPS Tracking will be the default, base service. Currently available services are:
Nota: When <ExtraService>=“125” and <InsuredAmount> is less than or equal to $100, the insurance price returned will be zero (“$0.00”) to reflect baked-in insurance. If <InsuredAmount> is greater than $100, the insurance price returned will reflect an extra cost since baked-in insurance was exceeded. Nota: If HAZMAT extra services “813” and “826” are indicated when a domestic integrated customs form returns, a <CustomsContentType> of "DANGEROUSGOODS" will be required. |
String |
whiteSpace=collapse Enumeration= · 100 · 101 · 125 HAZMAT Services: · 810 · 811 · 812 · 813 · 814 · 815 · 816 · 817 · 818 · 819 · 820 · 821 · 822 · 823 · 824 · 825 · 826 · 827 · 828 · 829 · 830 · 831 · 832 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Conditionally required (When insurance extra service is also indicated) |
Use this tag for entering an insurance amount, if applicable. Por ejemplo: <InsuredAmount>100.00</InsuredAmount> Nota: The maximum insurance available may vary by the Returns Mail Service type requested. |
Decimal |
minInclusive=0.0 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest /ReturnFees |
Optional |
This tag must be set to “true” for <Fees> to be returned. This tag is used so customers can see what fees apply to their postage. |
Boolean |
Default=false Enumerations= · true · false |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
USPSReturnsLabelRequest |
Obligatorio |
Used with API=USPSReturnsLabel |
(Alias) |
|
Non-manifesting (SSF) XML Request: <USPSReturnsLabelRequest USERID="XXXXXXXXX" PASSWORD="XXXXXXXXX"> <Option/> <Revision></Revision> <ImageParameters> <ImageType>PDF</ImageType> </ImageParameters> <CustomerFirstName>Cust First Name</CustomerFirstName> <CustomerLastName>Cust Last Name</CustomerLastName> <CustomerFirm>Customer Firm</CustomerFirm> <CustomerAddress1/> <CustomerAddress2>Po Box 100</CustomerAddress2> <CustomerUrbanization/> <CustomerCity>Washington</CustomerCity> <CustomerState>DC</CustomerState> <CustomerZip5>20260</CustomerZip5> <CustomerZip4>1122</CustomerZip4> <POZipCode>20260</POZipCode> <AllowNonCleansedOriginAddr>false</AllowNonCleansedOriginAddr> <RetailerATTN>ATTN: Retailer Returns Department</RetailerATTN> <RetailerFirm>Retailer Firm</RetailerFirm> <WeightInOunces>80</WeightInOunces> <ServiceType>PRIORITY</ServiceType> <Width>4</Width> <Length>10</Length> <Height>7</Height> <Girth>2</Girth> <Machinable>verdadero</Machinable> <CustomerRefNo>RMA%23: EE66GG87</CustomerRefNo> <PrintCustomerRefNo>true</PrintCustomerRefNo> <CustomerRefNo2> EF789UJK </CustomerRefNo2> <PrintCustomerRefNo2>verdadero</PrintCustomerRefNo2> <SenderName>Sender Name for Email</SenderName> <SenderEmail>senderemail@email.com</SenderEmail> <RecipientName>Recipient of Email</RecipientName> <RecipientEmail>recipientemail@email.com</RecipientEmail> <TrackingEmailPDF>true</TrackingEmailPDF> <ExtraServices> <ExtraService></ExtraService> </ExtraServices> </USPSReturnsLabelRequest> Manifesting (SSF) XML Request: <USPSReturnsLabelRequest USERID="XXXXXXXXX" PASSWORD="XXXXXXXXX"> <Option/> <Revision>2</Revision> <ImageParameters> <ImageType>PDF</ImageType> <ImageParameter>4X6</ImageParameter> <ImageParameter>SEPARATERECEIPTPAGE</ImageParameter> </ImageParameters> <CustomerFirstName>Cust First Name</CustomerFirstName> <CustomerLastName>Cust Last Name</CustomerLastName> <CustomerFirm>Customer Firm</CustomerFirm> <CustomerAddress1/> <CustomerAddress2>150 CALLE A</CustomerAddress2> <CustomerUrbanization>URB REPTO VETERANO</CustomerUrbanization> <CustomerCity>San Juan</CustomerCity> <CustomerState>PR</CustomerState> <CustomerZip5>00926</CustomerZip5> <CustomerZip4>0221</CustomerZip4> <POZipCode>20260</POZipCode> <AllowNonCleansedOriginAddr>true</AllowNonCleansedOriginAddr> <RetailerATTN>ATTN: Retailer Returns Department</RetailerATTN> <RetailerFirm>Retailer Firm</RetailerFirm> <WeightInOunces>10</WeightInOunces> <ServiceType>EXPRESS</ServiceType> <Width>4</Width> <Length>10</Length> <Height>7</Height> <Girth>2</Girth> <Machinable>verdadero</Machinable> <CustomerRefNo>RMA%23: EE66GG87</CustomerRefNo> <PrintCustomerRefNo>true</PrintCustomerRefNo> <CustomerRefNo2> EF789UJK </CustomerRefNo2> <PrintCustomerRefNo2>verdadero</PrintCustomerRefNo2> <SenderName>Sender Name for Email</SenderName> <SenderEmail>senderemail@email.com</SenderEmail> <RecipientName>Recipient of Email</RecipientName> <RecipientEmail>recipientemail@email.com</RecipientEmail> <TrackingEmailPDF>true</TrackingEmailPDF> <ExtraServices> <ExtraService>101</ExtraService> </ExtraServices> <InsuredAmount>100</InsuredAmount> </USPSReturnsLabelRequest> Manifesting (SSF) eFulfillement for Returns XML Request: <USPSReturnsLabelRequest USERID="XXXXXXXXX" PASSWORD="XXXXXXXXX"> <Option/> <Revision>2</Revision> <ImageParameters> <ImageType>PDF</ImageType> <ImageParameter>6X4PAGE</ImageParameter> </ImageParameters> <CustomerFirstName>Cust First Name</CustomerFirstName> <CustomerLastName>Cust Last Name</CustomerLastName> <CustomerFirm>Customer Firm</CustomerFirm> <CustomerAddress1>232</CustomerAddress1> <CustomerAddress2>Po Box 100</CustomerAddress2> <CustomerUrbanization/> <CustomerCity>Washington</CustomerCity> <CustomerState>DC</CustomerState> <CustomerZip5>20260</CustomerZip5> <CustomerZip4>1236</CustomerZip4> <POZipCode>20260</POZipCode> <AllowNonCleansedOriginAddr>true</AllowNonCleansedOriginAddr> <RetailerATTN>ATTN: Retailer Returns Department</RetailerATTN> <RetailerFirm>Retailer Firm</RetailerFirm> <RetailerAddress1>Ste 100</RetailerAddress1> <RetailerAddress2>2 Massachusetts Ave NE</RetailerAddress2> <RetailerCity>Washington</RetailerCity> <RetailerState>DC</RetailerState> <RetailerZip5>20212</RetailerZip5> <RetailerZip4>1726</RetailerZip4> <RetailerEmail>Returns@Retailer.com</RetailerEmail> <RetailerPhone>2125551234</RetailerPhone> <WeightInOunces>10</WeightInOunces> <ServiceType>GROUND</ServiceType> <ReturnsPostageType>5</ReturnsPostageType> <Width>12</Width> <Length>24</Length> <Height>16</Height> <Girth>0</Girth> <Machinable>verdadero</Machinable> <VendorCode>1000</VendorCode> <VendorProductVersionNumber>102</VendorProductVersionNumber> <MailOwnerMID>817463</MailOwnerMID> <CustomerRefNo>RMA%23: EE66GG87</CustomerRefNo> <PrintCustomerRefNo>true</PrintCustomerRefNo> <CustomerRefNo2>EF789UJK</CustomerRefNo2> <PrintCustomerRefNo2>verdadero</PrintCustomerRefNo2> <SenderName>Sender Name for Email</SenderName> <SenderEmail>senderemail@email.com</SenderEmail> <RecipientName>Recipient of Email</RecipientName> <RecipientEmail>recipientemail@email.com</RecipientEmail> <TrackingEmailPDF>true</TrackingEmailPDF> <ExtraServices> <ExtraService>100</ExtraService> </ExtraServices> <InsuredAmount>100</InsuredAmount> <ReturnFees>true</ReturnFees> </USPSReturnsLabelRequest> |
Tag Name |
Occurs |
Descripción |
Tipo |
Validation |
||||||||
Obligatorio |
|
(Alias) |
|
|||||||||
USPSReturnsLabelResponse / BarcodeNumber |
Obligatorio |
Tracking / Confirmation number for the package. This tag returns a long form IMpb that includes routing information: 42020904198592019xxxxxxxxxxxxxxxxx |
String |
|
||||||||
USPSReturnsLabelResponse / TrackingNumber |
Obligatorio |
Tracking / Confirmation number for the package. This tag returns a shortened IMpb that begins with the Channel Application ID: 92019xxxxxxxxxxxxxxxxx TrackingNumber is available when <Revision> is greater than or equal to “2” |
String |
|
||||||||
USPSReturnsLabelResponse / LabelImage |
Optional |
Binary representation of the label in the form selected (PDF, TIF). Default response will contain a single <LabelImage> tag containing label and receipt on the same page. Nota: Not returned when <ImageType>=“NONE” is specified in request. |
base64Binary |
Default= <LabelImage> contains label and receipt on same page |
||||||||
USPSReturnsLabelResponse / ReceiptImage |
Optional |
Binary representation of the Receipt in the form selected (PDF, TIF). Nota: Only returned when SEPARATERECEIPTPAGE is specified in the request. |
base64Binary |
|
||||||||
USPSReturnsLabelResponse / RetailerATTN |
Optional |
Attention line of Retailer receiving the return package. |
String |
maxLength=50 |
||||||||
USPSReturnsLabelResponse / RetailerFirm |
Optional |
Firm Name of Retailer receiving the return package. Configured “Delivery Destination Company” used. Future enhancements will also use <RetailerFirm>. Nota: <RetailerFirm> value truncated after 32-characters when printed on label due to space limitations. API response eligible to return up to 50 characters. |
String |
MaxLength=50 |
||||||||
USPSReturnsLabelResponse / RetailerAddress1 |
Optional |
Address of Retailer receiving the return package. Secondary address unit designator and number (such as an apartment or suite number). Por ejemplo: “APT 202” or “STE 100” etc. Configured “Delivery Destination Address2” used. |
String |
|
||||||||
USPSReturnsLabelResponse / RetailerAddress2 |
Obligatorio |
Address of Retailer receiving the return package. Configured “Delivery Destination Address” used. |
String |
|
||||||||
USPSReturnsLabelResponse / RetailerCity |
Obligatorio |
City of Retailer receiving the return package. Configured “Delivery Destination City” used. |
String |
|
||||||||
USPSReturnsLabelResponse / |
Obligatorio |
State of Retailer receiving the return package. Configured “Delivery Destination State” used. |
String |
|
||||||||
USPSReturnsLabelResponse / RetailerZip5 |
Obligatorio |
Zip5 of Retailer receiving the return package. Configured “Delivery Destination Zip Code” used. |
String |
pattern=\d{5} |
||||||||
USPSReturnsLabelResponse / RetailerZip4 |
Obligatorio |
Zip4 of Retailer receiving the return package. Configured “Delivery Destination Zip Code” used. |
String |
|
||||||||
USPSReturnsLabelResponse / RDC |
Obligatorio |
Retail Distribution Code printed on label for USPS processing purposes. Nota: The following MCSetCodes are used for Returns API to determine RDC:
|
String |
|
||||||||
USPSReturnsLabelResponse / Postage |
Obligatorio |
Postage amount for the Returns package. Nota: Does not include any extra service fees or surcharges. |
String |
minLength=0 |
||||||||
USPSReturnsLabelResponse / ExtraServices |
Optional |
Groups extra service information specified in request. |
(Group) |
|
||||||||
USPSReturnsLabelResponse / ExtraServices / ExtraService |
Optional, repeating up to unbounded times |
Groups extra service information specified in request. |
(Group) |
|
||||||||
USPSReturnsLabelResponse / ExtraServices / ExtraService / ServiceID |
Optional |
Extra Service ID included in request |
String |
|
||||||||
USPSReturnsLabelResponse / ExtraServices / ExtraService / ServiceName |
Optional |
Extra Service name |
String |
|
||||||||
USPSReturnsLabelResponse / ExtraServices / ExtraService / Price |
Optional |
Extra Service fee |
Decimal |
|
||||||||
USPSReturnsLabelResponse / Zone |
Obligatorio |
Postal Zone. USPS defined distance codes assigned to each origin and destination ZIP Code pairing for every ZIP Code number in the nation. These distance codes, referred to as zones, are designated as “1 through 9." |
String |
|
||||||||
USPSReturnsLabelResponse / DimensionalWeight |
Optional |
Dimensional Weight of package used to determine postage. Postage based on actual weight (specified in <WeightInOunces>) or the dimensional weight, whichever is greater. For example, <DimensionalWeight>14.0</DimensionalWeight> For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm |
String |
|
||||||||
USPSReturnsLabelResponse / CarrierRoute |
Obligatorio |
Ruta del cartero |
String |
|
||||||||
USPSReturnsLabelResponse / LogMessage |
Optional |
Messaging for integrators of this API. It may contain additional information about this particular request / response, or general information about the API or Web Tools. In typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis. |
String |
|
||||||||
USPSReturnsLabelResponse / Fees |
Optional |
Returned when “Fees” is True Dimensional weight pricing will include length and volume fees to account for cost of processing oversized parcels |
|
|
||||||||
USPSReturnsLabelResponse / Fee |
Obligatorio |
|
String |
|
||||||||
USPSReturnsLabelResponse / Fee / FeeType |
Obligatorio |
Indicates type of fee applied to package: - Non Standard Length Fee - Non Standard Volume Fee |
String |
|
||||||||
USPSReturnsLabelResponse / Fee / FeeType / FeePrice
|
Obligatorio |
Non Standard Length Fee(s) a. 15" < x < 22" = $0 (for all packages) b. 22" < x < 30" = $2 (for DDU entered packages) c. 22" < x < 30" = $3 (for DNDC/DSCF entered packages) d. 22" < x < 30" = $4 (for all other packages) e. x > 30" = $7.50 (for DDU entered packages) f. x > 30" = $11.25 (for DNDC/DSCF entered packages) g. x > 30" = $15 (for all other packages) - Non Standard Volume Fee(s) a. x > 2 cubic feet (3546 cubic inches) = $15 (for all packages) Live Animal Transportation Fee(s) a. $0.20 for all packages |
String |
|
||||||||
USPSReturnsLabelResponse / Fees / Fee / FeeType / FeePrice / FeeInformation |
Obligatorio |
Fee Information indicates the fee is <Rate> |
String |
|
||||||||
USPSReturnsLabelResponse / Fees / Fee / FeeType / FeePrice / FeeInformation / FeeInfo FeeInfoType=”PriceType” |
Obligatorio |
Fee Information indicates the fee is <Rate> |
String |
|
||||||||
USPSReturnsLabelResponse / Attributes |
Obligatorio |
When <ReturnFees> = True, the new Attributes tag will return to show Oversize fees and/or Dimensional Weight fees. Any future package attributes that impact a price returned will be included in the attributes tag. |
String |
|
||||||||
USPSReturnsLabelResponse / Attributes / AttributeKey |
Obligatorio |
Attribute Key: · DimensionalWeightR = RetailRate · DimensionalWeightCB = Commercial Rate · DimensionalWeightCP = Commerical Plus Rate · Oversized |
String |
|
||||||||
USPSReturnsLabelResponse |
Obligatorio |
|
(Alias) |
|
XML Response: <USPSReturnsLabelCertifyResponse> <BarcodeNumber>420202121726925989XXXXXXXXXXXXXXXX</BarcodeNumber> <TrackingNumber>925989XXXXXXXXXXXXXXXX</TrackingNumber> <LabelImage>--- Base 64 Binary stream Suppressed for documentation---</LabelImage> <RetailerATTN>ATTN: Retailer Returns Department</RetailerATTN> <RetailerFirm>RETAILER FIRM</RetailerFirm> <RetailerAddress1>STE 100</RetailerAddress1> <RetailerAddress2>2 MASSACHUSETTS AVE NE</RetailerAddress2> <RetailerCity>WASHINGTON</RetailerCity> <RetailerState>DC</RetailerState> <RetailerZip5>20212</RetailerZip5> <RetailerZip4>1726</RetailerZip4> <RDC>0001</RDC> <Postage>43.71</Postage> <ExtraServices> <ExtraService> <ServiceID>100</ServiceID> <ServiceName>Insurance</ServiceName> <Price>3.40</Price> </ExtraService> </ExtraServices> <Zone>01</Zone> <DimensionalWeight>28</DimensionalWeight> <CarrierRoute>C000</CarrierRoute> <Fees> <Fee> <FeeType>Nonstandard Length fee > 22 in.</FeeType> <FeePrice>4.00</FeePrice> </Fee> <Fee> <FeeType>Nonstandard Volume fee > 2 cu. ft.</FeeType> <FeePrice>15.00</FeePrice> </Fee> </Fees> <Attributes> <Attribute Key="DimensionalWeight">28</Attribute> </Attributes> </USPSReturnsLabelCertifyResponse> |
Image Parameter(s) |
Descripción |
Receipt |
Image Type |
6X4 PAGE |
1 image returned: Full Page 8.5x11 with 6x4 label and receipt (current default). |
Yes, included in single image |
PDF, TIF |
6X4 PAGE SEPARATERECEIPTPAGE |
2 images returned: 1) Full Page 8.5x11 with 6x4 label 2) Receipt on Full Page 8.5x11 |
Yes, but on separate full page |
PDF, TIF |
4X6 |
1 image returned: True 4x6 |
No |
PDF, TIF |
4X6 SEPARATERECEIPTPAGE |
2 images returned: 1) True 4x6 label 2) Receipt on Full Page 8.5x11 |
Yes, but on separate full page |
|
6 X 4 |
1 image returned: True 6x4 |
No |
PDF, TIF |
6 X 4 SEPARATERECEIPTPAGE |
2 images returned: 1) True 6x4 label True 2) Receipt on Full Page 8.5x11 |
Sí |
PDF, TIF |
4X6ZPL203DPI |
1 image returned: 4x6 ZPL 203 |
No |
ZPL |
4X6ZPL300DPI |
1 image returned: 4x6 ZPL 300 |
No |
ZPL |
Figure 1: USPS Priority Mail Return service label
Figure 2: Priority Mail Express Return Service label
Figure 3: USPS Ground Advantage Return Service label
Web Tools USPSReturnsLabel allows a unique returns ZIP4 which can be used instead of the ZIP4 returned from AMS in the XML response <RetailerZip4>, barcode, label, receipt, and SSF.
Context: Today local AMS generates a unique returns destination ZIP4 for larger volume returns shippers, but doesn't share this data outside of AMS DB with other internal systems. As a result, unique returns ZIP4 will fail AMS validation and standardize to ZIP4 of the physical address. For the Web Tools USPS Returns API, a configured unique ZIP4 allows customers to bypass the AMS ZIP4.
Ex. Destination Address: “16840 BUCCANEER LN HOUSTON, TX 77058 + XX50* – the unique ZIP4 is “XX50”, AMS standardizes to “2563” – when the unique ZIP4 option is configured in Web Tools, the unique returns ZIP4 of "XX50" is used.