Merchandise Return Bulk Label API

 

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 1.5 (08/13/2019)

 

 

 

 

 

 

 

 

 

 


Contents

1.0        Introduction to Web Tools. 3

1.1       Before you get started: 3

2.0        USPS Merchandise Return Bulk Label API 3

2.1       Overview.. 3

2.2       API Signature. 4

2.3       Tag Descriptions. 4

3.0        Electronic Merchandise Return Service Bulk Response. 8

3.1       Merchandise Return Bulk Label Example. 9

3.2       Error Responses. 9

 


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

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

Label APIs require extra permissions; contact the Internet Customer Care Center https://Emailus.usps.com/ to request access. Indicate “Label API Access” in the subject line and explain in the body of the email:

1.                   How the shipper intends to purchase and apply postage to the labels

2.                   If the label image provided by the API will be modified in any way by the shipper or the software

2.0   USPS Merchandise Return Bulk Label API

2.1    Overview

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


 

2.2    API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=MerchReturnV4Bulk

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=MerchReturnV4BulkCertify

&XML=(see below)

 

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

2.3    Request Descriptions

Tag Name

Occurs

Description

Type

Validation

EMRSV4.0BulkRequest

required once

Used with API=MerchReturnV4Bulk  

(group)

 

EMRSV4.0BulkRequest / USERID

required

This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID. 

NMTOKEN

 

EMRSV4.0BulkRequest / Option

required once

Reserved for future use

string

default=LEFTWINDOW

enumerations=
RIGHTWINDOW
LEFTWINDOW  

EMRSV4.0BulkRequest / 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.0BulkRequest / LabelCount

Required Once

Number of labels to produce

string

Min = 1

Max = 30

EMRSV4.0BulkRequest / ImageParameters

Optional

Group

(group)

 

EMRSV4.0BulkRequest / ImageParameter

Optional

Image options

String

Enumeration = 4X6LabelP

Enumeration = 2UP

EMRSV4.0BulkRequest / RetailerName

required once

Name of Retailer receiving the return package.  

string

minLength=1
maxLength=50

EMRSV4.0BulkRequest / RetailerAddress

required once

Address of Retailer receiving the return package.  

string

minLength=1
maxLength=50

EMRSV4.0BulkRequest / PermitNumber

required once

Permit number provided to Retailer by the local post office.  

string

pattern=\d+  

EMRSV4.0BulkRequest / PermitIssuingPOCity

required once

Post Office City that issued the permit.  

string

minLength=1
maxLength=15

EMRSV4.0BulkRequest / PermitIssuingPOState

required once

Post Office State that issued the permit.  

string

pattern=\w{2}
pattern=  

minLength=2
maxLength=2

EMRSV4.0BulkRequest / PermitIssuingPOZip5

required once

ZIP Code of Post Office that issued the permit.  

string

pattern=\d{5}  

EMRSV4.0BulkRequest / PDUFirmName

optional

Postage Delivery Unit Name

string

minLength=0
maxLength=50  

EMRSV4.0BulkRequest / PDUPOBox

required once

Postage Delivery Unit Post Office Box or Street Address.  

string

minLength=1
maxLength=24  

EMRSV4.0BulkRequest / PDUCity

required once

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

string

minLength=0
maxLength=20  

EMRSV4.0BulkRequest / PDUState

required once

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

string

pattern=\w{2}
pattern=  

minLength=2
maxLength=2

EMRSV4.0BulkRequest / 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.0BulkRequest / PDUZip4

required once

Postage Delivery Unit ZIP+4 Code.  

string

pattern=\d{4}
pattern=  

EMRSV4.0BulkRequest / ServiceType

required once

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

string

enumeration=

Priority
First Class Package Service
Ground

EMRSV4.0BulkRequest / DeliveryConfirmation

required once

Enter "true" for Delivery Confirmation.  

boolean

 

EMRSV4.0BulkRequest / 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.0BulkRequest / WeightInPounds

required once

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

integer

minInclusive=0
maxInclusive=70  

EMRSV4.0BulkRequest / WeightInOunces

required once

Value must be numeric.  

integer

minInclusive=0
maxInclusive=1120  

EMRSV4.0BulkRequest / ImageType

required once

One of the valid entries: “PDF”,”TIF”. (Note to BSA reviewing this. TIF is a valid type yet was missing. I added it. Was it missing for a reason? Delete comment when finished.) 

string

enumeration=PDF  

enumeration=TIF 

EMRSV4.0BulkRequest / 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.0BulkRequest / 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.0BulkRequest / 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.0BulkRequest / 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.0BulkRequest / AllowNonCleansedDestAddr

optional

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

boolean

default=false
 

EMRSV4.0BulkRequest / NineDigitRoutingZip

optional

Value of ‘true’ generates label barcode with nine digit routing zip code.

boolean

default=false

EMRSV4.0BulkRequest

required once

 

(alias)

 

 


 

2.3.1   Request Example

 

        <EMRSV4.0BulkRequest USERID="xxxxxxxxxxxx">

 <Option></Option>

<LabelCount>3</ LabelCount >

<ImageParameters>

     <ImageParameter>4X6LabellP</ ImageParameter >

     <ImageParameter>2UP</ ImageParameter >

</ ImageParameters >

<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.0BulkRequest> 

 

 


 

2.4  Response Descriptions

Tag Name

Occurs

Description

Type

Validation

EMRSV4.0BulkResponse

required once

Used with API= EMRSV4.0BulkResponse

(group)

 

EMRSV4.0BulkResponse / MerchandiseReturnLabel

<group>

 

Required

 

EMRSV4.0BulkResponse / InsuranceCost

String

Insurance Value

Required

 

EMRSV4.0BulkResponse / PDUFirmName

String

Facility Name

Optional

 

EMRSV4.0BulkResponse / PDUPOBox

String

Facility Po Box

Required

 

EMRSV4.0BulkResponse / PDUPOBoxAbbreviation

String

Facility PO Box Abbreviation

Optional

 

EMRSV4.0BulkResponse / PDUCity

String

Facility City

Required

 

EMRSV4.0BulkResponse / PDUCityAbbreviation

String

Facility City Name Abbreviation

Optional

 

EMRSV4.0BulkResponse / PDUState

String

Facility State

Required

 

EMRSV4.0BulkResponse / PDUZip5

String

5 character zip

Required

 

EMRSV4.0BulkResponse / PDUZip4

String

4 character zip

Required

 

EMRSV4.0BulkResponse / Postnet

String

Numerical bar code

Required

 

 

2.4.1   Response Example

   <?xml version="1.0"?>

< <EMRSV4.0BulkCertifyResponse>

  <MerchandiseReturnLabel>xxxxxxx

  </MerchandiseReturnLabel>

  <InsuranceCost>4.40</InsuranceCost>

  <PDUFirmName>12345678901234567890123456789012345678901234567890</PDUFirmName>

  <PDUPOBox>14500 LORAIN AVE</PDUPOBox>

  <PDUCity>CLEVELAND</PDUCity>

  <PDUState>OH</PDUState>

  <PDUZip5>44111</PDUZip5>

  <PDUZip4>9998</PDUZip4>

  <Postnet>44111999800</Postnet>

</EMRSV4.0BulkCertifyResponse>

 

 

 

3.0   Electronic Merchandise Return Service Bulk Response

3.1    Merchandise Return Bulk Label Example

3.2    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 the Internet Customer Care Center https://Emailus.usps.com/.