This document contains a Reference Guide to the USPS Returns Label API. See the Developers 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.

Note: 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.

1.1 Before you get started:

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.

Note: The Web Tools user ID (i.e.“123ABCD456”) you receive upon registration will not work at www.usps.com (also reference: https://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 Returnsservice 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://www.usps.com/business/return-services.htm

2.0 USPS Returns Label API

2.1 Overview

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 Returnsservice 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 Returnsservice labels for items that can be mailed using First-Class Package ReturnService, 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:

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

· Mailer ID (MID) enrollment

· Customer Registration ID (CRID) enrollment

· Configuration of Destination Delivery Address (where applicable)

Note: The “USPSReturnsLabelCertify” API is for testing purposes and will not generate usable labels and barcodes.

2.1.1 API Signature

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)

2.2 Request Descriptions

Tag Name

Occurs

Description

Type

Validation

USPSReturnsLabelRequest

Required

Used with API=USPSReturnsLabel

(Alias)

USPSReturnsLabelRequest / USERID

Required

This attribute specifies your WebTools user ID. See the Developers Guide for information on obtaining your USERID

For example:

NMTOKEN

USPSReturnsLabelRequest / Option

Optional

For future use.

String

USPSReturnsLabelRequest / Revision

Optional

For future use. Used to indicate API version.

String

minLength=0
pattern=\d{1}
pattern=

USPSReturnsLabelRequest / ImageParameters

Required

Group containing all request parameters pertaining to the Label Image generation.

(Group)

USPSReturnsLabelRequest / ImageParameters / ImageType

Required

Label Image Type.

For example: <ImageType>PDF</ImageType>

String

Enumeration=

· PDF

· TIF

· NONE

USPSReturnsLabelRequest / ImageParameters / SeparateReceiptPage

Optional

Flag to request a Separate Receipt Image. Enter “true” if you want receipt returned on a separate page – this will return label in <LabelImage> tag and receipt in <ReceiptImage> tag.

For example: <SeparateReceiptPage>true</SeparateReceiptPage>

Note: If not specified, receipt will return on same page as returns label. Response will contain a single <LabelImage> tag containing label and receipt on the same page.

Boolean

Default=false

· true

· false

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.

Note: <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
maxLength=50

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.

String

minLength=1
maxLength=50

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.

Note: <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
maxLength=50

USPSReturnsLabelRequest / CustomerAddress1

Conditionally required (if address needs secondary info)

Secondary address unit designator and number (such as an apartment or suite number). For example: “APT 202” or “STE 100” etc.

Note: 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
maxLength=50

USPSReturnsLabelRequest / CustomerAddress2

Required

Address of customer returning the package. (Primary Street address). For example: <CustomerAddress2>123 Main St.</CustomerAddress2>

String

minLength=1
maxLength=50

USPSReturnsLabelRequest / CustomerCity

Required

City of customer returning the package.

String

minLength=1
maxLength=28

USPSReturnsLabelRequest / CustomerState

Required

State of customer returning the package. Value should be passed as two-letter state abbreviation. For example: <CustomerState>DC</CustomerState>

String

pattern=\w{2}
pattern=

minLength=2
maxLength=2

USPSReturnsLabelRequest / CustomerZip5

Required

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}
pattern=

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.

For example: <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.

Note: 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

USPSReturnsLabelRequest / WeightInOunces

Optional

Package weight used to calculate postage. Items must weigh 70 pounds (1120 ounces) or less.

For example: <WeightInOunces>80</ WeightInOunces>

Note: If weight not supplied, 4oz used.

Integer

Default=4

minInclusive=0
maxInclusive=1120

USPSReturnsLabelRequest / ServiceType

Required

Enter one of the valid Mail Service entries:

“PRIORITY” for Priority Mail Return Service.

“FIRST CLASS” for First-Class Package Return Service.

“GROUND” for Ground Return Service.

String

Enumeration=

· PRIORITY

· FIRST CLASS

· GROUND

USPSReturnsLabelRequest / Width

Optional

Value must be numeric. Units are inches.
For example: <Width>5.5</ Width>

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
totalDigits=10

USPSReturnsLabelRequest / Length

Optional

Value must be numeric. Units are inches. Length should be longest dimension when compared to Width and Height values supplied.

For example: <Length>11</Length>

Decimal

minExclusive=0.0
totalDigits=10

USPSReturnsLabelRequest / Height

Optional

Value must be numeric. Units are inches.
For example: <Height>7</Height>

Decimal

minExclusive=0.0
totalDigits=10

USPSReturnsLabelRequest / Girth

Conditionally required (if package is non-rectangular)

Note: 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.

For example: <Girth>25</Girth>

Note: 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
totalDigits=10

USPSReturnsLabelRequest / Machinable

Optional

Indicates if packaging is Machinable. Used to calculate postage.

For example: <Machinable>true</Machinable>

Boolean

Default=false

Enumerations=

· true

· false

USPSReturnsLabelRequest / ShipDate

Optional

Date Package Will Be Mailed. Ship date may be today plus 0 to 3 days in advance. Enter the date in either format: dd-mmm-yyyy, such as 14-Feb-2020, or mm/dd/ yyyy, such as 02/14/2020. If not provided,
current day will be used as a basis for delivery date calculations.

For example: <ShipDate>02/14/2011</ShipDate>

String

Default=current day

minLength=0
pattern=\d{1,2}/ \d{1,2}/ \d\d(\d\d)?

USPSReturnsLabelRequest / SenderName

Optional

Used for the USPS Tracking email. Indicates the name of the person or company sending the USPS tracking email notification.

Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.

String

minLength=0
maxLength=50

USPSReturnsLabelRequest / SenderEMail

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.

Note: <RecipientEMail> must be populated to generate USPS tracking email notification. If <SenderEMail> provided without <RecipientEMail>, USPS tracking email notification will not be generated.

Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.

String

pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}
pattern=

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.

Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.

String

minLength=0
maxLength=50

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. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.

String

pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}
pattern=

USPSReturnsLabelRequest / ExtraServices

Optional

Groups extra services elements

(Group)

USPSReturnsLabelRequest / ExtraServices/ ExtraService

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:

Service Name	Service ID
Signature Confirmation Electronic	156

String

whiteSpace=collapse

Enumeration=

· 156

USPSReturnsLabelRequest

Required

Used with API=USPSReturnsLabel

(Alias)

2.2.1 Sample Request

XML Request:

<SeparateReceiptPage>false</SeparateReceiptPage>

</ImageParameters>

<CustomerFirstName>Cust First Name</CustomerFirstName>

<CustomerFirm>Customer Firm</CustomerFirm>

<CustomerCity>Washington</CustomerCity>

<AllowNonCleansedOriginAddr>false</AllowNonCleansedOriginAddr>

<ServiceType>PRIORITY</ServiceType>

<SenderName>Sender Name for Email </SenderName>

<SenderEMail>senderemail@email.com</SenderEMail>

<RecipientName>Recipient of Email</RecipientName>

<RecipientEMail>recipientemail@email.com</RecipientEMail>

</ExtraServices>

</USPSReturnsLabelRequest>

2.3 Response Descriptions

Tag Name

Occurs

Description

Type

Validation

USPSReturnsLabelResponse

Required

(Alias)

USPSReturnsLabelResponse / BarcodeNumber

Required

Tracking / Confirmation number for the package.

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.

Note: 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).

Note: Only returned when <SeparateReceiptPage>= “true” is specified in request.

base64Binary

USPSReturnsLabelResponse / ToFirm

Optional

Firm Name of Retailer receiving the return package. Configured “Delivery Destination Company” used. Future enhancements will also use <RetailerFirm>.

Note: <ToFirm> 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 / ToAddress1

Optional

Address of Retailer receiving the return package. Secondary address unit designator and number (such as an apartment or suite number). For example: “APT 202” or “STE 100” etc. Configured “Delivery Destination Address2” used.

String

USPSReturnsLabelResponse / ToAddress2

Required

Address of Retailer receiving the return package. Configured “Delivery Destination Address” used.

String

USPSReturnsLabelResponse / ToCity

Required

City of Retailer receiving the return package. Configured “Delivery Destination City” used.

String

USPSReturnsLabelResponse /
ToState

Required

State of Retailer receiving the return package. Configured “Delivery Destination State” used.

String

USPSReturnsLabelResponse / ToZip5

Required

Zip5 of Retailer receiving the return package. Configured “Delivery Destination Zip Code” used.

String

pattern=\d{5}

USPSReturnsLabelResponse / ToZip4

Required

Zip4 of Retailer receiving the return package. Configured “Delivery Destination Zip Code” used.

String

USPSReturnsLabelResponse / Postnet

Required

Customer text representation of Postnet barcode.

Note: The Postnet barcode is not displayed on the label.

String

minLength=0

USPSReturnsLabelResponse / RDC

Required

Retail Distribution Code printed on label for USPS processing purposes.

Note: The following MCSetCodes are used for Returns API to determine RDC:

Service	MCSetCode
Ground Return Service	006
First-Class Package Return Service	005
Priority Mail Return Service	003

String

USPSReturnsLabelResponse / Postage

Required

Postage amount for the Returns package.

Note: 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

Required

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

Required

Carrier Route

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

Required

(Alias)