Merchandise Return V4.0 Label API

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 3.0 (5/31/2015)

 

 

 

 

 

 

 

United States Postal Service Logo
 

 


 

 


Contents

Introduction to Web Tools. 3

Before you get started: 3

USPS Merchandise Return V4.0 Label API. 3

Overview.. 3

API Signature. 3

Request Description. 4

Request Example. 7

Response Description. 8

Error Responses. 10

 


Introduction to Web Tools

This document contains a Reference Guide to the Merchandise Return Bulk 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 trouble-shooting.

 

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.  If the user enters more than those amounts, an error will not be generated. The Web Tool 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.

 

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.

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 Technical Documentation section of the Web Tools page on usps.com/webtools. 

Use of Merchandise Return Service requires that a USPS permit account be set up on site at a local USPS facility. For more information, see https://www.usps.com/business/return-services.htm.

USPS Merchandise Return V4.0 Label API

Overview

The Merchandise Return V4.0 Label Web Tool lets customers to receive Merchandise Return labels. The Merchandise Return V4.0 Label API returns Merchandise Return labels that are requested by the client.

 

API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=MerchandiseReturnV4

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=MerchReturnCertifyV4

&XML=(see below)

 

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

Request Description

Tag Name

Occurs

Description

Type

Validation

EMRSV4.0Request

required once

Used with API=MerchandiseReturnV4  

(group)

 

EMRSV4.0Request/Option

required once

Specifies what type of #10 window envelope will be used to mail the label to the Customer address.  

string

default=LEFTWINDOW
enumeration=RIGHTWINDOW
enumeration=LEFTWINDOW  

EMRSV4.0Request/Revision

optional repeating up to 1 times

This is for versioning of the API's and for triggering response tags for future versions. In this API use a value of 1 to trigger new functionality. For Example: 1 

string

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

EMRSV4.0Request/CustomerName

required once

Name of customer returning package.  

string

minLength=1
maxLength=32  

EMRSV4.0Request/CustomerAddress1

required once

Secondary address unit designator and number (such as an apartment or suite number (APT 202, STE 100)).  

string

minLength=0
maxLength=32  

EMRSV4.0Request/CustomerAddress2

required once

Address of customer returning the package.  

string

minLength=1
maxLength=32  

EMRSV4.0Request/CustomerCity

required once

City of customer returning the package.  

string

minLength=1
maxLength=20  

EMRSV4.0Request/CustomerState

required once

State of customer returning the package.  

string

length=2  

EMRSV4.0Request/CustomerZip5

required once

ZIP Code of customer returning the package.  

string

pattern=\d{5}  

EMRSV4.0Request/CustomerZip4

required once

ZIP+4 Code of customer returning the package.  

string

pattern=\d{4}
pattern=  

EMRSV4.0Request/RetailerName

required once

Name of Retailer receiving the return package.  

string

minLength=1
maxLength=20  

EMRSV4.0Request/RetailerAddress

required once

Address of Retailer receiving the return package.  

string

minLength=1
maxLength=24  

EMRSV4.0Request/PermitNumber

required once

Permit number provided to Retailer by the local post office.  

string

pattern=\d+  

EMRSV4.0Request/PermitIssuingPOCity

required once

Post Office City that issued the permit.  

string

minLength=1
maxLength=15  

EMRSV4.0Request/PermitIssuingPOState

required once

Post Office State that issued the permit.  

string

length=2  

EMRSV4.0Request/PermitIssuingPOZip5

required once

ZIP Code of Post Office that issued the permit.  

string

pattern=\d{5}  

EMRSV4.0Request/PDUFirmName

optional

Postage Delivery Unit Name

string

minLength=0
maxLength=24  

EMRSV4.0Request/PDUPOBox

required once

Postage Delivery Unit Post Office Box or Street Address.  

string

minLength=1
maxLength=24  

EMRSV4.0Request/PDUCity

required once

Postage Delivery Unit City. Supply either City and State or PO Box with ZIP Code.  

string

minLength=0
maxLength=15  

EMRSV4.0Request/PDUState

required once

Postage Delivery Unit State. Supply either City and State or PO Box with ZIP Code.  

string

pattern=\w{2}
pattern=  

EMRSV4.0Request/PDUZip5

required once

Postage Delivery Unit ZIP Code. Supply either City and State or PO Box with ZIP Code.  

string

pattern=\d{5}
pattern=  

EMRSV4.0Request/PDUZip4

required once

Postage Delivery Unit ZIP+4 Code.  

string

pattern=\d{4}
pattern=  

EMRSV4.0Request/ServiceType

required once

Enter one of the valid entries: “Priority” (for Priority Mail), “First Class Package Service”, or “Ground”.

string

enumeration=

Priority

First Class Package Service

Ground

EMRSV4.0Request/DeliveryConfirmation

required once

Enter "true" for Delivery Confirmation.  

boolean

 

EMRSV4.0Request/InsuranceValue

required once

Numeric currency with dollars and cents (no dollar sign). If insurance is not required, leave value blank. A value of “0.00” will result in an error being returned.  

decimal
string

minExclusive=0.0
maxLength=0  

EMRSV4.0Request/MailingAckPackageID

optional

Deprecated. Retailer assignable number. Superseded by the Merchandise Return Service Number assigned automatically.  

string

minLength=0
maxLength=24  

EMRSV4.0Request/WeightInPounds

required once

Estimated weight is allowed. First Class Mail cannot exceed 13 ounces.  

integer

minInclusive=0
maxInclusive=70  

EMRSV4.0Request/WeightInOunces

required once

Value must be numeric.  

integer

minInclusive=0
maxInclusive=1120  

EMRSV4.0Request/RMA

required once

RMA restricted to 2-7 decimal digits when RMAPICFlag=Y.  

string

minLength=0
maxLength=24  

EMRSV4.0Request/ImageType

required once

One of the valid entries: “TIF”, “PDF”  

string

enumeration=PDF
enumeration=TIF  

EMRSV4.0Request/SenderName

optional

The name of the person or company sending the email. Note: no email is returned when generating a Sample label request.  

string

 

EMRSV4.0Request/SenderEMail

optional

E-mail address of sender. Valid e-mail addresses must be used. Note: No e-mail is returned when generating a Sample label request.  

string

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

EMRSV4.0Request/RecipientName

optional

The name of the person or company receiving the email. Note: no email is returned when generating a Sample label request.  

string

 

EMRSV4.0Request/RecipientEMail

optional

E-mail address of recipient. Valid e-mail addresses must be used. Note: No e-mail is returned when generating a Sample label request.  

string

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

EMRSV4.0Request/RMABarcode

optional

Value of 'true' generates the RMA barcode on the label. System will assume "false" if no value is entered.  

boolean

default=false
 

EMRSV4.0Request/AllowNonCleansedDestAddr

optional

Value of 'true' bypasses destination address cleansing.  Non-cleansed destination addresses may result in undeliverable packages.

boolean

default=false
 

EMRSV4.0Request/AllowNonCleansedCustAddr

optional

Value of 'true' bypasses customer address cleansing.  Non-cleansed customer addresses may result in undeliverable packages.

boolean

default=false

EMRSV4.0Request /Content

optional

Special Contents of package

(group)

 

EMRSV4.0Request    /Content/ContentType

required once – if content included

Type of content

string

 

EMRSV4.0Request/Content/ContentType

required once – if content included

Use to specify ContentType.  Available types are:

 

ContentType

HAZMAT

PERISHABLE

FRAGILE

 

 

 

Example: < ContentType >HAZMAT</ ContentType >

 

Note:  USPS-produced packaging, including Flat Rate and Regional Rate, cannot be used to ship live animals.  Error response will be returned.

string

Enumeration= HAZMAT 

PERISHABLE

FRAGILE

 

EMRSV4.0Request/GroundOnly

Optional

Specifies the package is to be transported Ground Only

boolean

default=false

EMRSV4.0Request/Oversized

Optional

Specifies the package is Oversized

boolean

default=false

EMRSV4.0Request

required once

Used with API=MerchandiseReturnV4  

(alias)

 

 

Request Example

XML Sample Request:

<?xml version="1.0" encoding="UTF-8" ?>

- <<<MRSV4.0Request USERID="XXXXXX" >

 <Option>RIGHTWINDOW</Option>

 <CustomerName>Janice Dickens</CustomerName>

 <CustomerAddress1>Ste 201</CustomerAddress1>

 <CustomerAddress2>7 N Wilkes Barre Blvd</CustomerAddress2>

 <CustomerCity>Wilkes Barre</CustomerCity>

 <CustomerState>PA</CustomerState>

 <CustomerZip5>18702</CustomerZip5>

 <CustomerZip4 />

 <RetailerName>XYZ Corp.</RetailerName>

 <RetailerAddress>123 Main St</RetailerAddress>

 <PermitNumber>293829</PermitNumber>

 <PermitIssuingPOCity>New York</PermitIssuingPOCity>

 <PermitIssuingPOState>NY</PermitIssuingPOState>

 <PermitIssuingPOZip5>10001</PermitIssuingPOZip5>

 <PDUFirmName>PDU Firm Co.</PDUFirmName>

 <PDUPOBox>PO Box 100</PDUPOBox>

 <PDUCity>Wilkes Barre</PDUCity>

 <PDUState>PA</PDUState>

 <PDUZip5>18702</PDUZip5>

 <PDUZip4>1234</PDUZip4>

 <ServiceType>Priority</ServiceType>

 <DeliveryConfirmation>False</DeliveryConfirmation>

 <InsuranceValue />

 <MailingAckPackageID>ID00001</MailingAckPackageID>

 <WeightInPounds>0</WeightInPounds>

 <WeightInOunces>10</WeightInOunces>

 <RMA>RMA 123456</RMA>

 <RMAPICFlag>False</RMAPICFlag>

 <ImageType>TIF</ImageType>

 <RMABarcode>False</RMABarcode>

</EMRSV4.0CertifyRequest> 

 

 Response Description

Tag Name

Occurs

Description

Type

Validation

EMRSV4.0Response

required once

 

(group)

 

EMRSV4.0Response/Zone

required once

Postal Zone Indicates the number of postal rate zones between the origin and destination ZIP Codes.  

string

 

EMRSV4.0Response/MerchandiseReturnLabel

required once

Binary representation of the label in the form selected (PDF, TIF).  

base64Binary

 

EMRSV4.0Response/(choice)

required once

One of two mutually-exclusive package numbers will be returned depending on the value of the EMRSV4.0Request/DeliveryConfirmation boolean.

(choice)

 

EMRSV4.0Response/(choice)/DeliveryConfirmationNumber

if used:
required once

Delivery Confirmation number for the package.  

string

 

EMRSV4.0Response/(choice)/MerchandiseReturnNumber

if used:
required once

Merchandise Return Service Number for the package.  

string

 

EMRSV4.0Response/InsuranceCost

required once

Cost of the insurance.  

decimal

 

EMRSV4.0Response/PDUFirmName

optional

Postage Delivery Unit Name.  Returned if provided in request XML.

strng

 

EMRSV4.0Response/PDUPOBox

required once

Postage Delivery Unit Post Office Box or Street Address.  

string

 

EMRSV4.0Response/PDUCity

required once

Postage Delivery Unit City. Supply either City and State or PO Box with ZIP Code.  

string

 

EMRSV4.0Response/PDUState

required once

Postage Delivery Unit State.  

string

 

EMRSV4.0Response/PDUZip5

required once

Postage Delivery ZIP Code.  

string

pattern=\d{5}  

EMRSV4.0Response/Postnet

required once

Postage Delivery Unit text representation of Postnet barcode. Deprecated; the Postnet barcode is no longer displayed on the label.  

string

minLength=0  

EMRSV4.0Response/CustomerAddress1

required once

Secondary address unit designator and number (such as an apartment or suite number (APT 202, STE 100)).  

string

minLength=0  

EMRSV4.0Response/CustomerAddress2

required once

Address of customer returning the package.  

string

minLength=1  

EMRSV4.0Response/CustomerCity

required once

City of customer returning the package.  

string

minLength=1  

EMRSV4.0Response/CustomerState

required once

State of customer returning the package.  

string

length=2  

EMRSV4.0Response/CustomerZip5

required once

ZIP Code of customer returning the package.  

string

pattern=\d{5}  

EMRSV4.0Response/CustomerZip4

required once

ZIP+4 Code of customer returning the package. May be blank.  

string

pattern=\d{4}
pattern=  

EMRSV4.0Response/CustomerPostnet

required once

Customer text representation of Postnet barcode. Deprecated; the Postnet barcode is no longer displayed on the label.  

string

minLength=0  

EMRSV4.0Response/RDC

optional repeating up to 1 times

 

string

 

EMRSV4.0Response/LogMessage

optional repeating up to 1 times

A text message 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

 

EMRSV4.0CertifyResponse

required once

 

(alias)

 

Error Responses

Error conditions are handled at the main XML document level.  When parsing, it is best to check for an error document first before checking for good data.  Error documents have the following format:

<Error>

<Number></Number>

<Source></Source>

<Description></Description>

<HelpFile></HelpFile>

<HelpContext></HelpContext>

</Error>

Where:

·         Number = the error number generated by the Web Tools server.

·         Source = the component and interface that generated the error on the Web Tools server.

·         Description = the error description.

·         HelpFile = [reserved for future use].

·         HelpContext = [reserved for future use].

Errors that are further down in the hierarchy also follow the above format.

An <Error> element may be returned at the top (response) level if there is a problem with the syntax of the request, or if a system error occurs.

 

If you need assistance with an error response, contact our Internet Customer Care Center uspstechnicalsupport@mailps.custhelp.com.