api - welcome | usps web tools user’s guide 4 1. usps priority mail express label api 1.1....

Express Mail Label

API

USPS Web Tools™

Application Programming Interface

User’s Guide Document Version 3.5 (7/11/2017)

USPS Web Tools User’s Guide

ii

Contents Introduction to Web Tools ........................................................................................................................ 3

Before you get started: .......................................................................................................................... 3

1. USPS Priority Mail Express Label API ............................................................................................ 4

1.1. Overview .................................................................................................................................... 4

1.2. API Signature ............................................................................................................................. 4

2. Tag Descriptions ............................................................................................................................... 4

2.1. Request Parameters .................................................................................................................... 4

2.1.1. Customs forms and data requirements ................................................................................. 14

2.2. Sample Request ........................................................................................................................ 22

2.3. Response Parameters................................................................................................................ 25

2.4. Sample Response ..................................................................................................................... 28

3. Error Responses .............................................................................................................................. 29

4. Label Examples .............................................................................................................................. 30

4.1. Label Example with Customs Form ......................................................................................... 31


3

Introduction to Web Tools

This document contains a Reference Guide to the Express Mail Label APIs. See the Developer’s Guide (eCommerce API Technical Guides site) 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.

For label specifications such as package dimensions, delivery information, etc., please refer to the Domestic Mail Manual (DMM) at http://pe.usps.com/.

For information specific to domestic mailpieces sent to an Army Post Office (APO), Fleet Post Office (FPOs), and or Diplomatic Post Offices (DPO) see the DMM at http://pe.usps.com/text/dmm300/703.htm#1113810 and http://pe.usps.com/text/dmm300/608.htm#1255642

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. For instance, a line of sample code may be:

<ZipDestination>12345</ZipDestination>

In this instance, you will replace “12345” with the destination ZIP Code for the domestic-bound package.

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 API access requires extra permissions; contact the Internet Customer Care Center [email protected] 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

https://www.usps.com/business/webtools-technical-guides.htm?

http://pe.usps.com/

http://pe.usps.com/text/dmm300/703.htm#1113810

http://pe.usps.com/text/dmm300/608.htm#1255642

https://www.usps.com/business/web-tools-apis/general-api-developer-guide.pdf

https://www.usps.com/business/web-tools-apis/technical-documentation.htm

https://www.usps.com/business/web-tools-apis/welcome.htm

mailto:[email protected]


4

1. USPS Priority Mail Express Label API

1.1. Overview

The Priority Mail Express Label API will let customers create Priority Mail Express Labels. Please note that the API labels are printed without postage. Postage must be purchased and applied separately.

1.2. API Signature

Scheme Host Path API XML https:// secure.shippingapis.com /ShippingAPI.dll? API=ExpressMailLabel &XML=(see

below)

https:// secure.shippingapis.com /ShippingAPI.dll? API=ExpressMailLabelCertify &XML=(see below)

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

2. Tag Descriptions

2.1. Request Parameters

Tag Name Occurs Description Type Validation

ExpressMailLabelRequest

required once

API=ExpressMailLabel (group)

ExpressMailLabelRequest / @USERID

required NMTOKEN

ExpressMailLabelRequest / Option

required once

For future use. empty

ExpressMailLabelRequest / Revision

optional

In this API use a value of 2 to trigger new functionality.

For example: <Revision>2</Revision>

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

ExpressMailLabelRequest / EMCAAccount

required For future use. empty

ExpressMailLabelRequest / EMCAPassword

required For future use. empty

ExpressMailLabelRequest / ImageParameters

optional (group)


5


ExpressMailLabelRequest / ImageParameters / LabelSequence

Optional To be used in the case of multiple packages. Not required if only one package.

string

minOccurs="0" maxOccurs="1"

ExpressMailLabelRequest / ImageParameters / LabelSequence /PackageNumber

Required if…

Required if Label Sequence is selected integer minInclusive value = "1" maxInclusive value = "999"

ExpressMailLabelRequest / ImageParameters / LabelSequence/ TotalPackages

Required if…

Required if Label Sequence is selected integer minInclusive value = "1" maxInclusive value = "999"

ExpressMailLabelRequest / ImageParameters/ImageParameter

optional

Forces a Separate Continuation Page when the item count is greater than five.

SEPARATECONTINUEPAGE – will force

the continuation page (if the item count causes the need for a continuation page) onto a separate page.

For example: <ImageParameter> SEPARATECONTINUEPAGE </ImageParameter>

string Enumeration= SEPARATECONTINUEPAGE

ExpressMailLabelRequest / FromFirstName

required once

Values for either First and Last Name of Recipient or Firm must be sent.

string minLength=0 maxLength=50

ExpressMailLabelRequest / FromLastName

required once

Values for either First and Last Name of Sender or Firm must be sent. For example: <FromLastName>MARTIAN</FromLastName>


ExpressMailLabelRequest / FromFirm

required once

Values for either First and Last Name of Sender or Firm must be sent. For example: <FromFirm>USPS</FromFirm>


ExpressMailLabelRequest / FromAddress1

required once

From address line 1. Use this tag for an apartment or suite number. For example: <FromAddress1>STE 150</FromAddress1>



6


ExpressMailLabelRequest / FromAddress2

required once

From address line 2. For example: <FromAddress2>6600 ROCKLEDGE DR</FromAddress2>


ExpressMailLabelRequest / FromCity

required once

From city. For example: <FromCity>BETHESDA</FromCity>


ExpressMailLabelRequest / FromState

required once

From state. For example: <FromState>MD</FromState>


ExpressMailLabelRequest / FromZip5

required once

From ZIP code. For example: <FromZip5>20212</FromZip5>

string pattern=\d{5}

ExpressMailLabelRequest / FromZip4

required once

From ZIP+4 extension. For example: <FromZip4/>

string minLength=0 pattern=\d{4} pattern=

ExpressMailLabelRequest / FromPhone

required once

From Phone #. 10 digits required (including area code), with no punctuation. For example: <FromPhone>2125551234</FromPhone>


ExpressMailLabelRequest / ToFirstName

required once

Values for either First and Last Name of Recipient or Firm must be sent.

For example: <ToFirstName>Adam</ToFirstName>


ExpressMailLabelRequest / ToLastName

required once

Values for either First and Last Name of Recipient or Firm must be sent. For example: <ToLastName>Smith</ToLastName>


ExpressMailLabelRequest / ToFirm

required once

Values for either First and Last Name of Recipient or Firm must be sent. For example: <ToFirm>ABC CORPORATION</ToFirm>



7


ExpressMailLabelRequest / ToAddress1

required once

Recipient address line 1. Use this tag for an apartment or suite number. For example: <ToAddress1/>


ExpressMailLabelRequest / ToAddress2

required once

Recipient address line 2. Must be a valid address. For example: <ToAddress2>1234 MAIN ST</ToAddress2>


ExpressMailLabelRequest / ToCity

required once

Recipient city. Unless declined using the <StandardizeAddress> tag the API will cleanse (check) the address using USPS databases. Values for either To City and To State or Zip 5 must be sent. For example: <ToCity>ANYTOWN</ToCity>


ExpressMailLabelRequest / ToState

required once

Recipient state. Unless declined using the <StandardizeAddress> tag the API will cleanse (check) the address using USPS databases. Values for either To City and To State or Zip 5 must be sent. For example: <ToState>MN</ToState>

string minLength=0 pattern=\w{2}

ExpressMailLabelRequest / ToZip5

required once

Recipient ZIP code. Must be a valid ZIP code. Unless declined using the <StandardizeAddress> tag the API will cleanse (check) the address using USPS databases. Values for either To City and To State or Zip 5 must be sent. For example: <ToZip5>12345</ToZip5>

string minLength=0 pattern=\d{5}

ExpressMailLabelRequest / ToZip4

required once

Recipient ZIP+4 extension. For example: <ToZip4/>


ExpressMailLabelRequest / ToPOBoxFlag

optional

Indicates if the destination address is a PO Box. For example: <ToPOBoxFlag>True</ToPOBoxFlag>

boolean default=false


8


ExpressMailLabelRequest / ToPhone

required once

Recipient Phone #. If value is entered, 10 digits required (including area code), with no punctuation. For example: <ToPhone>2125551234 </ToPhone>


ExpressMailLabelRequest / ToContactPreference

Optional

This indicates how the recipient will be notified that the package is available for pickup. Specify WAIVED if notification is not desired. For example: <ToContactPreference>EMAIL</ToContactPreference>

string

whiteSpace=collapse enumeration=EMAIL enumeration=SMS enumeration=EMAILSMS enumeration=WAIVED

ExpressMailLabelRequest / ToContactMessaging

Optional

This contains the email address or the text messaging address or is blank depending on the ToContactPreference tag. If the EMAIL or SMS enumeration is used in ToContactPreference, this value must be a syntactically-valid e-mail address. If WAIVED is used, this value must be blank. For example: <ToContactMessaging>[email protected]</ToContactMessaging>

string

maxLength=64 whiteSpace=collapse pattern=\w{0} pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}

ExpressMailLabelRequest / ToContactEmail

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. For example: <ToContactEMail>[email protected]</ToContactEMail>

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

ExpressMailLabelRequest / WeightInOunces

required once

Package weight. Items must weigh 70 pounds or less. For example: <WeightInOunces>80</WeightInOunces>

string pattern=\d{0,4}

ExpressMailLabelRequest / ShipDate

optional Deprecated. See "LabelDate" tag. string pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?

ExpressMailLabelRequest / FlatRate

optional Deprecated. See "Container" tag. boolean default=false


9


ExpressMailLabelRequest / SundayHolidayDelivery

optional

Guaranteed Sunday/Holiday Delivery. When true the label contains special banners and the postage on the label and in the response includes the premium. For example: <SundayHolidayDelivery/>


ExpressMailLabelRequest / StandardizeAddress

optional

Delivery Address Cleansed. Enter "true" if you want the API to check the address for accuracy or "false" if you do not. Parcels with non-standardized addresses run the risk of being undeliverable. For example: <StandardizeAddress/>

boolean default=true

ExpressMailLabelRequest / WaiverOfSignature

optional

No Signature Required for Delivery. Enter "true" if you do not want a signature for receipt of the package or "false" if you do. For example: <WaiverOfSignature/>

boolean default=true

ExpressMailLabelRequest / CarrierRelease

optional For future use. boolean minOccurs="0"

ExpressMailLabelRequest / NoHoliday

optional Deprecated. See "SundayHolidayDelivery" tag.


ExpressMailLabelRequest / NoWeekend

optional No Saturday Delivery. Enter "true" if you do not want the package delivered on Saturday or "false" if you do.


ExpressMailLabelRequest / SeparateReceiptPage

optional

Label & Customer Online Record Printed on two separate pages. Enter "true" if you want the shipping label and online customer record printed on two separate pages or "false" if you want them printed on the same single page. For example: <SeparateReceiptPage>true</SeparateReceiptPage>


ExpressMailLabelRequest / POZipCode

required once

ZIP Code of Post Office or collection box where item is mailed. May be different than From ZIP Code. For example: <POZipCode/>



10


ExpressMailLabelRequest / FacilityType

optional

Has values: "DDU", "SCF", "BMC", "ADC", "ASF". Optional, but cannot be left blank if specified. For example: <FacilityType>DDU</FacilityType>

string

enumeration=DDU enumeration=SCF enumeration=BMC enumeration=ADC enumeration=ASF

ExpressMailLabelRequest / ImageType

required once

Label Image Type. For example: <ImageType>PDF</ImageType>

string enumeration=PDF enumeration=TIF enumeration=None

ExpressMailLabelRequest / LabelDate

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-2011, or mm/dd/yyyy, such as 02/14/2011. For example: <LabelDate/>

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

ExpressMailLabelRequest / LabelTime

optional

Time Package Will Be Mailed. Time may be midnight (00:00) to 23:59. Enter the time in the format: HH:MM such as 13:30. For example: <LabelTime>15:00</LabelTime>

string minLength=0 pattern=\d{1,2}/:d{2} pattern=\d{0}

ExpressMailLabelRequest / CustomerRefNo

optional

User-assigned Number for Internal Use. For example: <CustomerRefNo>XYZ-123</CustomerRefNo>


ExpressMailLabelRequest / SenderName

optional

Name of E-mail Sender. For example: <SenderName>C. P. Apple</SenderName>

string minLength=0

ExpressMailLabelRequest / SenderEMail

optional

E-mail Address of Sender. Valid e-mail addresses must be used. For example: <SenderEMail>[email protected]</SenderEMail>


ExpressMailLabelRequest / RecipientName

optional Name of E-mail Recipient For example: <RecipientName/>

string minLength=0


11


ExpressMailLabelRequest / RecipientEMail

optional

E-mail Address of Recipient. Valid e-mail addresses must be used. For example: <RecipientEMail></RecipientEMail>


ExpressMailLabelRequest / HoldForManifest

optional Restricted use. Holds manifest record for possible inclusion in SCAN request.

string enumeration=Y enumeration=N

ExpressMailLabelRequest / CommercialPrice

optional

Indicates if commercial-base price should be returned. For commercial-base price eligibility, please reference the Domestic Mail Manual at http://pe.usps.com/. For example: <CommercialPrice>False </CommercialPrice>


ExpressMailLabelRequest / InsuredAmount

optional

Use this tag for entering an insurance amount, if applicable.

For example: <InsuredAmount>100.00</InsuredAmount>

decimal

default=0 minInclusive=0 maxInclusive=9999.99 totalDigits=8 whiteSpace=collapse

ExpressMailLabelRequest / Container

optional

Use to specify special containers or container attributes that may affect postage; otherwise leave blank. Required when <Revision>=‘2’. Note: RECTANGULAR or NONRECTANGULAR must be indicated when <Size>LARGE</Size>. For example: <Container>FLAT RATE ENVELOPE</Container>

string

whiteSpace=collapse enumeration=

VARIABLE

RECTANGULAR

NONRECTANGULAR

FLAT RATE ENVELOPE

LEGAL FLAT RATE

ENVELOPE

PADDED FLAT RATE

ENVELOPE

ExpressMailLabelRequest / Size

optional

Required when <Revision>=’2’. Defined as follows: REGULAR: all package dimensions are under 12’’; LARGE: any package dimension is greater than 12’’ For example: <Size>REGULAR</Size>

string

whiteSpace=collapse enumeration=LARGE enumeration=REGULAR

http://pe.usps.com/


12


ExpressMailLabelRequest / Width

optional

Value must be numeric. Units are inches. Required when Size is LARGE. For example: <Width>5.5</Width>

decimal minExclusive=0.0 totalDigits=10

ExpressMailLabelRequest / Length

optional

Value must be numeric. Units are inches. Required when Size is LARGE. For example: <Length>11</Length>


ExpressMailLabelRequest / Height

optional

Value must be numeric. Units are inches. Required when Size is LARGE. For example: <Height>11</Height>


ExpressMailLabelRequest / Girth

optional

Value must be numeric. Units are inches. Girth is only required when Container = ‘NONRECTANGULAR’ and Size=’LARGE’. For example: <Girth>41</Girth>


ExpressMailLabelRequest / NineDigitRoutingZip

optional

Indicates if an IMPB barcode format is desired. “True” returns an IMPB barcode with a nine digit routing zip code, and “false” returns and IMPB barcode with a five digit routing zip code. For example: <NineDigitRoutingZip>true</NineDigitRoutingZip>


ExpressMailLabelRequest / ExtraServices

optional Groups extra services elements (group)

ExpressMailLabelRequest / ExtraServices / ExtraService

optional, repeating up to unbounded times

Use to specify extra services. Currently available services are:

Service Name ServiceID

Adult Signature 119

Adult Signature Restricted Delivery

120

10:30 AM Delivery (PME) 161

Insurance Restricted Delivery (PME)

178

Special Handling- Fragile 190

For example: <ExtraService>119</ExtraService>

string

enumeration=119 enumeration=120 enumeration=161 enumeration=178 enumeration=190


13


ExpressMailLabelRequest / ReturnCommitments

optional

Indicates if commitment information should be returned. For example: <ReturnCommitments>True</ReturnCommitments>


ExpressMailLabelRequest / Content optional

Groups Content elements when a special Content is included in the shipment.

(group)

ExpressMailLabelRequest / Content / ContentType

required once – if content included

Use to specify ContentType. Available types are:

ContentType HAZMAT CrematedRemains Lives Perishable

Required if LIVES. Example: < ContentType >Lives</ 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 CrematedRemains Lives Perishable

ExpressMailLabelRequest / Content / ContentDescriptor

Optional

Description of contents. Required for ContentType of LIVES For example: <ContentDescriptor>Bees</ContentDescriptor>

string

enumeration= Bees DayOldPoultry AdultBirds Other

ExpressMailLabelRequest /MeterData optional

Meter Data grouping. The optional Meter Data tags are used by Click-n-Ship and the Meter-Paid Label Solution teams to populate the Shipping Partner Event File (SPE)

(group)

ExpressMailLabelRequest /MeterData/ MeterVendorID

optional Meter Data grouping. string minLength value="0" maxLength value="2"

ExpressMailLabelRequest /MeterData/ MeterSerialNumber

optional Meter Vendor ID, which is the 2 digit number USPS assigned vendor ID.

string minLength value="0" maxLength value="20"


14


ExpressMailLabelRequest /MeterData/ MeterModelID

optional Serial number of meter used for postage. string minLength value="0" maxLength value="15"

ExpressMailLabelRequest /MeterData/ RateCategory

optional

Two digit model number of the Meter For example: PC-Postage models are 1 numeric followed by 1 alpha. <MeterModelID>7a</MeterModelID>


ExpressMailLabelRequest /MeterData/ IndiciumCreationRecordDate

optional

Four digit value denotes Product / Rate Category (As defined by the IBI data dictionary)

string pattern value="\d{1,2}/\d{1,2}/\d{4}|"

ExpressMailLabelRequest /MeterData/IBI optional

Date IBI was created Example: 12/19/2016 This tag is mostly used by PC Postage, metered and IMI PC Compliant customers


2.1.1. Customs forms and data requirements for shipping to/from Military and Diplomatic (APO/FPO/DPO) and US Possessions, Territories and Freely Associated States (PTFAS) shipping.

Please see the below “CustomsContentType” tag for specific customs forms, data requirements and logic

ExpressMailLabelRequest / ShippingContents

required once or optional

Required only if a customs form is required based on Customs Content Type and Weight.

(group)

ExpressMailLabelRequest / ShippingContents / ItemDetail

required once repeating up to 30 times or optional

required once repeating up to 30 times if generating an Integrated Customs Form, otherwise not required

(group)

ExpressMailLabelRequest / ShippingContents / ItemDetail /Description

Optional/required

Description of the item. Required only if a customs form is required based on Customs Content Type and Weight. For example: <Description>Policy guidelines document</Description>



15


ExpressMailLabelRequest / ShippingContents / ItemDetail /Quantity

Optional/required

Quantity of the item. Integer value required. Required only if a customs form is required based on Customs Content Type and Weight. For example: <Quantity>1</Quantity>

integer whitespace=collapse maxInclusive value=9999

ExpressMailLabelRequest / ShippingContents / ItemDetail / Value

Optional/required

The data entered with this tag provides the value of the set of items. If the item is 2 boxes of 50 pens and the value of each box is $10.00, "20.00" (2 boxes x $10.00) should be entered. If the value of each pen is .25 then "25.00" (100 pens x .25) should be entered. Required only if a customs form is required based on Customs Content Type and Weight. For example: <Value>55.00</Value>

decimal

minExclusive value=0 totalDigits value=8 maxInclusive value=99999.99

ExpressMailLabelRequest / ShippingContents / ItemDetail / NetPounds

optional/required

Provide the pounds OR ounces component of the weight of the individual item listed with <Description> when a customs form is required based on Customs Content Type and Weight. For example: <NetPounds>1</NetPounds>

integer totalDigits value=2 minInclusive value=0 maxInclusive value=70

ExpressMailLabelRequest / ShippingContents / ItemDetail / NetOunces

optional/required

Provide the ounces OR pounds component of the weight of the individual item listed with <Description> when a customs form is required based on Customs Content Type and Weight. For example: <NetOunces>5</NetOunces>

decimal totalDigits value=5 minInclusive value=0 maxInclusive value=1120

ExpressMailLabelRequest / ShippingContents / ItemDetail / HSTariffNumber

optional

For commercial items only. If known, the HS tariff number must be based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization. For example: <HSTariffNumber>490110</HSTariffNumber>



16


ExpressMailLabelRequest / ShippingContents / ItemDetail / CountryofOrigin

optional

Country of Origin means the country where the goods originated, e.g. were produced, manufactured, or assembled. It is recommended you supply this information and attach an invoice to the outside to accelerate customs clearance in processing the items. The country name entered must match an entry from the USPS-approved International Index of Countries (see http://pe.usps.com/text/imm/immctry.htm) and Localities or be "United States". For example: <CountryOfOrigin>United States</CountryOfOrigin>


ExpressMailLabelRequest / ToPhone optional

10 digits required (including area code), with no punctuation. Use format: 2125551234 For example: <ToPhone>5555555555</ToPhone>

string

minOccurs=0 whiteSpace=collapse length=10 pattern=\d{10}

ExpressMailLabelRequest / FromPhone optional

10 digits required (including area code), with no punctuation. Use format: 2125551234 For example: <FromPhone>5555555555</FromPhone>

string

minOccurs=0 whiteSpace=collapse length=10 pattern=\d{10}

ExpressMailLabelRequest / SenderMID optional

Mailer Identification Number. The MID is a six- or nine-digit number.

string

minOccurs=0 minLength=6 maxLength=9

ExpressMailLabelRequest / EMConfirmationNumber

optional

This tag allows for a user to enter a valid USPS barcode that will be displayed on customs form. When this tag is not present, a barcode will be generated automatically. Note: Reference the BarcodeConstructCode tag below for valid barcode constructs. For example: <EMConfirmationNumber> 4202114492551901000006902104017030</EMConfirmationNumber>


http://pe.usps.com/text/imm/immctry.htm

http://pe.usps.com/text/imm/immctry.htm


17


ExpressMailLabelRequest / BarcodeConstructCode

optional This tag allows a user to specify what type of barcode construct is being used in the <EMConfirmationNumber> tag

string

enumerations= C01 C02 C03 C04 C05 C06 C07 C09 C10 N01 N02 N03 N04 N05 N06 N07 N08 N09 N10

ExpressMailLabelRequest / CustomsManifestOptOut

optional

This tag allows a user to opt out of electronically sending an EMCDB manifest with customs data for export compliance. Note: only available when <BarcodeNumber> field is provided. For example: <CustomsManifestOptOut>false</CustomsManifestOptOut>

string Default= false Enumeration= true Enumeration= false


18


ExpressMailLabelRequest / CustomsContentType

Required

Specifies the content of the package or envelope.

For example: <CustomsContentType>DOCUMENTS</CustomsContentType>

When sending TO or FROM an APO/FPO/DPO or PTFAS, additional Customs information is required. This requirement is triggered when

The “ToState” is an APO/FPO/DPO or PTFAS

The “POZipCode” is specified and is an APO/FPO/DPO or PTFAS

The “POZipCode” is NOT specified and The “FromState” is an APO/FPO/DPO or PTFAS

When one of the above conditions occurs, The Customs Content Type tag is required. If the Content Type is “DOCUMENTS” and the “WeightInOunces” is specified and is less than 16 oz. no additional Customs tags are required from this section.

String

minOccurs=0 enumeration=

MERCHANDISE GIFT DOCUMENTS SAMPLE RETURN OTHER HUMANITARIAN DANGEROUSGOODS

ExpressMailLabelRequest / ContentComments

optional

Required tag if <CustomsContentType> =Other Enter any comments. For example: <ContentComments></ContentComments>

string minOccurs=0

ExpressMailLabelRequest / RestrictionType

optional Restriction Types string

minOccurs=0 Enumeration=

Quarantine Sanitary Inspection Phytosanitary Inspection Other

ExpressMailLabelRequest / RestrictionComments

Optional Restriction Comments. Required when <RestrictionType>="Other”

string minOccurs=0


19


ExpressMailLabelRequest / AESITN optional

AES/TN Exemption is a code that indicates the reason why you did not need to file electronic export information

string minOccurs=0

ExpressMailLabelRequest / ImportersReference

optional Importers Reference. The Importer’s Reference might be a tax code, importer code, or VAT number used for sales tax

string minOccurs=0

ExpressMailLabelRequest / ImportersContact optional

Importers Contact. Enter, if known, the Importer’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery.

string minOccurs=0

ExpressMailLabelRequest / ExportersReference

optional Exporters Reference. The Exporter’s Reference might be a tax code, importer code, or VAT number used for sales tax

string minOccurs=0

ExpressMailLabelRequest / ExportersContact optional

Exporters Contact. Enter, if known, the Exporter’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery.

string minOccurs=0

ExpressMailLabelRequest / InvoiceNumber optional Invoice Number string minOccurs=0

ExpressMailLabelRequest / LicenseNumber optional License Number string minOccurs=0

ExpressMailLabelRequest / CertificateNumber

optional Certificate Number string minOccurs=0

ExpressMailLabelRequest / NonDeliveryOption

optional

In case package is undeliverable, enter one of the following: "RETURN" for package to be returned to <FromAddress> above. "REDIRECT" to return package to address specified in the below tags. "ABANDON" to dispose of undeliverable package. For example: <NonDeliveryOption>RETURN</NonDeliveryOption>

string enumeration=RETURN enumeration=REDIRECT enumeration=ABANDON


20


ExpressMailLabelRequest / AltReturnAddress1

optional

Required if NonDeliveryOption tag=REDIRECT. Suggested use of this tag is for an apartment or suite number. For example: <AltReturnAddress1>Apt 1</AltReturnAddress1> Note: 1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address. 2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string minOccurs=0


optional

Required if NonDeliveryOption tag=REDIRECT. Suggested use of this tag is the Recipient address line 2. Must be a valid address. For example: <AltReturnAddress2>123 Main Ave </ AltReturnAddress2> Note: 1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address. 2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string minOccurs=0


21



optional

Required if NonDeliveryOption tag=REDIRECT. Suggested use of this tag is the Recipient city. Note: 1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address. 2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string minOccurs=0


optional

Required if NonDeliveryOption tag=REDIRECT. Suggested use of this tag is the Recipient state. Use 2-letter USPS abbreviation. Note: 1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address. 2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string minOccurs=0


optional

Required if NonDeliveryOption tag=REDIRECT. Suggested use of this tag is the recipient ZIP code. Note: 1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address. 2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string minOccurs=0


22



optional

Required if NonDeliveryOption tag=REDIRECT. Suggested use of this tag is the recipient ZIP+4 extension Note: 1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address. 2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string minOccurs=0

ExpressMailLabelRequest / AltReturnCountry optional

Required if NonDeliveryOption tag=REDIRECT. Country. Tag must equal United States for this API.

string minOccurs=0

ExpressMailLabelRequest / LabelImportType

optional “for internal USPS use” string

ExpressMailLabelRequest

required once

(alias)

2.2. Sample Request

Test XML Request - Standard without generating Military / PTFAS Integrated Customs Form:

https://production.shippingapis.com/ShippingAPITest.dll?API=ExpressMailLabelRequest2&XML<ExpressMailLabelCertifyRequest USERID="XXXXXX"> <Option/> <Revision>2</Revision> <EMCAAccount/> <EMCAPassword/> <ImageParameters> <LabelSequence> <PackageNumber>2</PackageNumber> <TotalPackages>3</TotalPackages> </LabelSequence> </ImageParameters> <FromFirstName>Bill</FromFirstName> <FromLastName>Strong</FromLastName> <FromFirm/> <FromAddress1></FromAddress1> <FromAddress2>6406 Ivy Lane</FromAddress2> <FromCity>Greenbelt</FromCity> <FromState>MD</FromState>


23

<FromZip5>20770</FromZip5> <FromZip4></FromZip4> <FromPhone>3015551212</FromPhone> <ToFirstName>John</ToFirstName> <ToLastName>Doe</ToLastName> <ToFirm/> <ToAddress1>404f</ToAddress1> <ToAddress2>3900 Connecticut Ave</ToAddress2> <ToCity>Washington</ToCity> <ToState>DC</ToState> <ToZip5></ToZip5> <ToZip4></ToZip4> <ToPhone>2025551212</ToPhone> <WeightInOunces>55</WeightInOunces> <FlatRate></FlatRate> <WaiverOfSignature>TRUE</WaiverOfSignature> <SeparateReceiptPage></SeparateReceiptPage> <POZipCode/> <ImageType>GIF</ImageType> <HoldForManifest>n</HoldForManifest> <CommercialPrice>True</CommercialPrice> <InsuredAmount></InsuredAmount> <Container>FLAT RATE ENVELOPE</Container> <Size>REGULAR</Size> <NineDigitRoutingZip>True</NineDigitRoutingZip> <ExtraServices> <ExtraService>ADULTRESTRICTED</ExtraService> </ExtraServices> <ReturnCommitments>true</ReturnCommitments> </ExpressMailLabelCertifyRequest>

Test XML Request – and creating a Military / PTFAS Integrated Customs Form:

https://production.shippingapis.com/ShippingAPITest.dll?API=ExpressMailLabelRequest2&XML<ExpressMailLabelCertifyRequest USERID="XXXXXX"> <Option/> <Revision>2</Revision> <EMCAAccount/> <EMCAPassword/> <ImageParameters> <LabelSequence> <PackageNumber>2</PackageNumber> <TotalPackages>3</TotalPackages> </LabelSequence> </ImageParameters> <FromFirstName>Bill</FromFirstName> <FromLastName>Strong</FromLastName> <FromFirm/> <FromAddress1></FromAddress1> <FromAddress2>6406 Ivy Lane</FromAddress2> <FromCity>Greenbelt</FromCity> <FromState>MD</FromState> <FromZip5>20770</FromZip5> <FromZip4></FromZip4> <FromPhone>3015551212</FromPhone> <ToFirstName>John</ToFirstName> <ToLastName>Doe</ToLastName> <ToFirm/> <ToAddress1>404f</ToAddress1> <ToAddress2>3900 Connecticut Ave</ToAddress2> <ToCity>Washington</ToCity> <ToState>DC</ToState>


24

<ToZip5></ToZip5> <ToZip4></ToZip4> <ToPhone>2025551212</ToPhone> <WeightInOunces>12</WeightInOunces> <FlatRate></FlatRate> <WaiverOfSignature>TRUE</WaiverOfSignature> <SeparateReceiptPage></SeparateReceiptPage> <POZipCode/> <ImageType>TIF</ImageType> <LabelDate></LabelDate> <HoldForManifest>n</HoldForManifest> <CommercialPrice>True</CommercialPrice> <InsuredAmount>1000</InsuredAmount> <Container>VARIABLE</Container> <Size>REGULAR</Size> <Width>1</Width> <Length>1</Length> <Height>1</Height> <Girth></Girth> <NineDigitRoutingZip>True</NineDigitRoutingZip> <ExtraServices> <ExtraService></ExtraService> </ExtraServices> <ReturnCommitments>true</ReturnCommitments> <ShippingContents> <ItemDetail> <Description>Description 1</Description> <Quantity>9999</Quantity> <Value>1.11</Value> <NetPounds></NetPounds> <NetOunces>1</NetOunces> <HSTariffNumber>123456789012</HSTariffNumber> <CountryOfOrigin>AUSTRALIA</CountryOfOrigin> </ItemDetail> <ItemDetail> <Description>Description 2</Description> <Quantity>2</Quantity> <Value>2.22</Value> <NetPounds></NetPounds> <NetOunces>2</NetOunces> <HSTariffNumber>234567</HSTariffNumber> <CountryOfOrigin>AUSTRALIA</CountryOfOrigin> </ItemDetail> <ItemDetail> <Description>Description 3</Description> <Quantity>3</Quantity> <Value>3.33</Value> <NetPounds></NetPounds> <NetOunces>3</NetOunces> <HSTariffNumber>123456</HSTariffNumber> <CountryOfOrigin>AUSTRALIA</CountryOfOrigin> </ItemDetail> <ItemDetail> <Description>Description 4</Description> <Quantity>4</Quantity> <Value>4.44</Value> <NetPounds></NetPounds> <NetOunces>4</NetOunces> <HSTariffNumber>234567</HSTariffNumber> <CountryOfOrigin>AUSTRALIA</CountryOfOrigin> </ItemDetail>


25

<ItemDetail> <Description>Description 5</Description> <Quantity>5</Quantity> <Value>5.55</Value> <NetPounds></NetPounds> <NetOunces>5</NetOunces> <HSTariffNumber>123456</HSTariffNumber> <CountryOfOrigin>AUSTRALIA</CountryOfOrigin> </ItemDetail> <ItemDetail> <Description>Description 6</Description> <Quantity>6</Quantity> <Value>6.66</Value> <NetPounds></NetPounds> <NetOunces>6</NetOunces> <HSTariffNumber>234567</HSTariffNumber> <CountryOfOrigin>AUSTRALIA</CountryOfOrigin> </ItemDetail> </ShippingContents> <SenderMID>123456789</SenderMID> <CustomsContentType>Document</CustomsContentType> <ContentComments>1234567890123456789012345</ContentComments> <RestrictionType>Phytosanitary Inspection</RestrictionType> <RestrictionComments>1234567890123456789012345</RestrictionComments> <AESITN>12345678901234567890123456789012345</AESITN> <ImportersReference>123456789012345678901234567890</ImportersReference> <ImportersContact>Importers Contact: This field can be 50 chars long</ImportersContact> <ExportersReference>12345678901234</ExportersReference> <ExportersContact>Exporters Contact: This field can be 50 chars long</ExportersContact> <InvoiceNumber>Invoice89012345</InvoiceNumber> <LicenseNumber>License Number12</LicenseNumber> <CertificateNumber>CertificateX</CertificateNumber> </ExpressMailLabelCertifyRequest>

2.3. Response Parameters


ExpressMailLabelResponse required once

(group)

ExpressMailLabelResponse / ToFirstName

required once

First Name of Recipient string

ExpressMailLabelResponse / ToLastName

required once

Last Name of Recipient string

ExpressMailLabelResponse / ToFirm required once

Company Name string

ExpressMailLabelResponse / ToAddress1

required once

To Address Line 1 string

ExpressMailLabelResponse / ToAddress2

required once

To Address Line 2 string

ExpressMailLabelResponse / ToCity required once

To City string


26


ExpressMailLabelResponse / ToState required once

To State string

ExpressMailLabelResponse / ToZip5 required once

To ZIP Code string

ExpressMailLabelResponse / ToZip4 required once

To ZIP Code+4 string

ExpressMailLabelResponse / Postage required once

Amount of Postage Required, does not include amount for fragile special handling if requested,, does not include insurance or other extra service fees.

decimal

ExpressMailLabelResponse / EMConfirmationNumber

required once

Priority Mail Express Tracking Number

string

ExpressMailLabelResponse / EMLabel optional

Priority Mail Express Label, if requested (where <ImageType> tag not "None")

base64Binary

ExpressMailLabelResponse / EMReceipt

optional

Separate Express Mail Customer Online Record, if requested using <SeparateReceiptPage> tag

base64Binary

ExpressMailLabelResponse / RDC

optional repeating up to 1 times

string

ExpressMailLabelResponse / InsuranceFee

optional decimal minExclusive=0.0 maxInclusive=5000

ExpressMailLabelResponse / ExtraServices

required once

(group)

ExpressMailLabelResponse / Extra Services / Extra Service

optional, repeating up to unbounded times

Groups extra service information

(group)

ExpressMailLabelResponse / Extra Services / Extra Service / ServiceID

required once

Extra Service ID string

ExpressMailLabelResponse / Extra Services / Extra Service / ServiceName

required once

Extra Service Name string


27


ExpressMailLabelResponse / Extra Services / Extra Service / ServiceFee

optional Extra Service fee decimal

ExpressMailLabelResponse / Zone required once

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

string

ExpressMailLabelResponse / CarrierRoute

required once

string

ExpressMailLabelResponse / Commitment

optional Returned if <ReturnCommitments> is true in the request.

(group)

ExpressMailLabelResponse / Commitment / CommitmentName

optional Commitment name such as 1-day, 2-day, 3-day, Military, DPO

String

ExpressMailLabelResponse / Commitment / ScheduledDeliveryDate

optional Date in the YYYY-MM-DD format.

date

ExpressMailLabelResponse / LogMessage

optional

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

ExpressMailLabelCertifyResponse required once

(alias)

28

2.4. Sample Response

Test XML Response - Standard without generating Military / PTFAS Integrated Customs Form:

<?xml version="1.0"?>

<ExpressMailLabelCertifyResponse>

<ToFirstName>John</ToFirstName>

<ToLastName>Doe</ToLastName>

<ToFirm></ToFirm>

<ToAddress1>APT 404F</ToAddress1>

<ToAddress2>3900 CONNECTICUT AVE NW</ToAddress2>

<ToCity>WASHINGTON</ToCity>

<ToState>DC</ToState>

<ToZip5>20008</ToZip5>


<Postage>44.95</Postage>

<EMConfirmationNumber>42XXXXXXXXXX59</EMConfirmationNumber>

<EMLabel>R0lGODdhcgZmCIcAAAAA



</EMLabel>

<RDC>0007</RDC>

<ExtraServices>

<ExtraService>

<ExtraServiceID>20</ExtraServiceID>

<ExtraServiceName>ADULTRESTRICTED</ExtraServiceName>

<ExtraServiceFee>5.75</ExtraServiceFee>

</ExtraService>

</ExtraServices>

<Zone>01</Zone>

<CarrierRoute>C###</CarrierRoute>

<Commitment>

<CommitmentName>1-Day</CommitmentName>

<ScheduledDeliveryDate>20##-##-##</ScheduledDeliveryDate>

</Commitment>

</ExpressMailLabelCertifyResponse>

Test XML Response – and creating a Military / PTFAS Integrated Customs Form:

<?xml version="1.0"?>

<ExpressMailLabelCertifyResponse>

<ToFirstName>John</ToFirstName>

<ToLastName>Doe</ToLastName>

<ToFirm></ToFirm>

<ToAddress1>APT 404F</ToAddress1>

<ToAddress2>3900 CONNECTICUT AVE NW</ToAddress2>

<ToCity>WASHINGTON</ToCity>

<ToState>DC</ToState>



<Postage>15.13</Postage>

<EMConfirmationNumber>42XXXXXXXXXX59</EMConfirmationNumber>

<EMLabel>R0lGODdhcgZmCIcAAAAA



</EMLabel>

<RDC>0007</RDC>

<InsuranceFee>0.00</InsuranceFee>

<ExtraServices/>

<Zone>01</Zone>

<CarrierRoute>C000</CarrierRoute>

<Commitment>

<CommitmentName>Military</CommitmentName>


29

<ScheduledDeliveryDate>2015-11-13</ScheduledDeliveryDate>

</Commitment>

</ExpressMailLabelCertifyResponse>

3. 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 [email protected]

mailto:[email protected]


30

4. Label Examples


31

4.1. Label Example with Customs Form

api - welcome | usps web tools user’s guide 4 1. usps priority mail express label api 1.1....

Documents