Rate Calculator APIs

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 2.15 (1/28/19)

 

 

 

 

 

 

 

 

 

 


 


Contents

1.0         Introduction to Web Tools. 3

1.1           Before you get started: 3

2.0         Domestic Rates API - RateV4. 3

2.1           Overview.. 3

2.1.1     API Signature. 3

2.2           Request Tag Descriptions. 4

2.2.1     Sample Requests. 12

2.3           Response Tag Descriptions. 13

2.3.1     Sample Response. 22

2.4           Error Responses. 31

3.0         International Rates API – IntlRateV2. 32

3.1           Overview.. 32

3.1.1     API Signature. 32

3.2           Request Tag Descriptions. 33

3.2.1     Sample Requests. 38

3.3           Response Tag Descriptions. 39

3.3.1     Sample Response. 45

3.4           Error Responses. 50

5.0         Appendix A - RateV4 Service Request Matrix. 52

 


1.0   Introduction to Web Tools

This document contains a Reference Guide to the Rate Calculator APIs, RateV4 and IntlRateV2. 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. For instance, a line of sample code may be:

 

<Pounds>2</Pounds>

 

In this instance, you will replace “2” with the weight in pounds for the package.

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.

2.0   Domestic Rates API - RateV4

2.1    Overview

The RateV4 API lets customers calculate the rate for domestic packages and envelopes given the weight and dimensions of the item.  The RateV4 API limits the data requested to twenty five (25) packages per transaction.

2.1.1   API Signature       

Scheme

Host

Path

API

XML

http://

 

https://

production.shippingapis.com

 

secure.shippingapis.com

/ShippingAPI.dll?

 

/ShippingAPI.dll

API=RateV4

 

API=RateV4

&XML=(see Tag Descriptions below)

&SML=(see Tag Descriptions below)


2.2    Request Tag Descriptions

Tag Name

Occurs

Description

Type

Validation

RateV4Request

required once

API=RateV4

This API returns the current USPS postage corresponding to the parameters given such as destination, weight of package, class of mail service, and so on.

(group)

 

RateV4Request / @USERID

required

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

NMTOKEN

 

RateV4Request / Revision

optional

Optional for “Base” RateV4 functionality.

 

For full RateV4 functionality use Revision=“2”

string

 

RateV4Request / Package / SortationLevel

Optional

Sortation

Description

3D

3-Digit

5D

5-Digit

BAS

Basic

CR

Carrier Route

MIX

Mixed NDC

NDC

NDC

PST

Presort

SCF

SCG

TBE

EMM Tray Box

TBF

Full Tray Box

TBH

Half Tray Box

TBT

Full Tub Tray Box

String

 

RateV4Request / Package / DestinationEntryFacilityType

Optional

Final Distribution Center before delivery to the customer.

 

String

 

RateV4Request / Package / Nonprofit

Optional

Profit vs Non-Profit

 

Values ‘Y’ or ‘N’ (Default ‘N’)

String

 

RateV4Request / Package

required once repeating up to 25 times

See the RateV4 Service Request chart for valid combinations of the following tags.

(group)

 

RateV4Request / Package / @ID

required

No restrictions on number or type of characters provided valid XML syntax and unique to request. 

For example: <Package ID="0"/>

NMTOKEN

 

RateV4Request / Package / Service

required once

Web Tool validates the entry to one of the service types.

For example:

<Service>PRIORITY MAIL EXPRESS</Service>

 

Please see Appendix A for detailed business rules regarding combinations of Service, Container, dimensions and other request values.

 

Note:  When all available prices are requested (e.g. <Service>=”PRIORITY”, “PRIORITY MAIL EXPRESS”): Flat Rate and Regional Rate prices will not be included in the response when <ContentType>=”LIVES”

 

Note: Mailable matter not required to be mailed as First-Class Mail is permitted with Retail Ground to Zones 5-9. Zones 1-4 items are limited to mailable hazardous materials, live animals, and other “surface-only” items. Retail Ground can only be used for Zones 5-9 unless the shipment is oversized or contains classes of materials. (e.g. certain HAZMAT) For more details, see: http://pe.usps.com/businessmail101/classes/packageServices.htm.

 

Note:  The use of <Service> = “BPM” is restricted. If access to this service is needed, please reach out to the following email address:

 webtools@usps.gov

Note:  The use of <Service> = “Priority Mail Cubic” requires additional steps. If access to this service is needed, please reach out to  webtools@usps.gov

string

whiteSpace=collapse
enumeration=

· First Class

· First Class Commercial

· First Class  HFP Commercial

· Priority

· Priority Commercial

· Priority Cpp

· Priority HFP Commercial

· Priority HFP CPP

· Priority Mail Express

· Priority Mail Express Commercial

· Priority Mail Express CPP

· Priority Mail Express Sh

· Priority Mail Express Sh Commercial

· Priority Mail Express HFP

· Priority Mail Express HFP Commercial

· Priority Mail Express HFP CPP

· Priority Mail Cubic

· Retail Ground

· Media

· Library

· All

· Online

· Plus

· BPM

RateV4Request / Package / FirstClassMailType

optional

Required when:

 

RateV4Request[Service='FIRST CLASS'] or RateV4Request[Service='FIRST CLASS COMMERCIAL’],

or RateV4Request[Service='FIRST CLASS HFP COMMERCIAL’]

 

For example: <FirstClassMailType>LETTER</FirstClassMailType>

 

Note:  The <FirstClassMailType> tag is returned only if the <ServiceType> submitted is “First Class”.  If any other <ServiceType> is returned (Including “First Class Commercial”) the <Container> tag is used.

 

string

whiteSpace=collapse
enumeration=

LETTER
FLAT
PACKAGE SERVICE RETAIL

POSTCARD

PACKAGE SERVICE

RateV4Request / Package / ZipOrigination

required once

ZIP code must be valid.

For example: <ZipOrigination>20770</ZipOrigination>

string

whiteSpace=collapse
length=5
pattern=\d{5}

RateV4Request / Package / ZipDestination

required once

ZIP code must be valid.

For example: <ZipDestination>54324</ZipDestination>

string

length=5
whiteSpace=collapse
pattern=\d{5}

RateV4Request / Package / Pounds

required once

Value must be numeric. Package weight in ounces is computed by 16*RateV4Request/Package/Pounds + RateV4Request/Package/Ounces. Package weight cannot exceed 70 pounds. 


Examples:

 <Pounds>2</Pounds>

<Pounds>2.12345678</Pounds>

string

maxInclusive=70
minInclusive=0

RateV4Request / Package / Ounces

required once

Value must be numeric. Package weight in ounces is computed by 16*RateV4Request/Package/Pounds + RateV4Request/Package/Ounces. Package weight cannot exceed 70 pounds (1120 ounces).  

 

Example:

<Ounces>0</Ounces>

<Ounces>0.12345678</Ounces>

string

maxInclusive=1120.0
minInclusive=0.0
totalDigits=10

RateV4Request / Package / Container

required once

Use to specify special containers or container attributes that may affect postage; otherwise, leave blank.

 

Note:

 

1.  RECTANGULAR or NONRECTANGULAR must be indicated when <Size>LARGE</Size>.
For example: <Container>LEGAL FLAT RATE ENVELOPE</Container>

 

2.  The <FirstClassMailType> tag is returned only if the <ServiceType> submitted is “First Class”.  If any other <ServiceType> is returned (Including “First Class Commercial”) the <Container> tag is used.

 

Note: “Cubic Soft Pack” and “Cubic Parcels” are only valid containers for service “Priority Mail Cubic”

string

default=VARIABLE
whiteSpace=collapse
enumeration=

·     VARIABLE

·     FLAT RATE ENVELOPE

·     PADDED FLAT RATE ENVELOPE

·     LEGAL FLAT RATE ENVELOPE

·     SM FLAT RATE ENVELOPE

·     WINDOW FLAT RATE ENVELOPE

·     GIFT CARD FLAT RATE ENVELOPE

·     SM FLAT RATE BOX

·     MD FLAT RATE BOX

·     LG FLAT RATE BOX

·     REGIONALRATEBOXA

·     REGIONALRATEBOXB

·     RECTANGULAR

·     NONRECTANGULAR

·     CUBIC PARCELS

·     CUBIC SOFT PACK

RateV4Request / Package / Size

required once

Defined as follows:

 

REGULAR: Package dimensions are 12’’ or less;

LARGE: Any package dimension is larger than 12’’.

 

For example: <Size>REGULAR</Size>

string

whiteSpace=collapse
enumeration=LARGE
enumeration=REGULAR

RateV4Request / Package / Width

optional

Value must be numeric. Units are inches. Required when RateV4Request/Size is LARGE.


For example: <Width>5.5</Width>

string

minExclusive=0.0
totalDigits=10

RateV4Request / Package / Length

optional

Value must be numeric. Units are inches. Required when RateV4Request/Size is LARGE.


For example: <Length>11</Length>

string

minExclusive=0.0
totalDigits=10

RateV4Request / Package / Height

optional

Value must be numeric. Units are inches. Required when RateV4Request/Size is LARGE.


For example: <Height>11</Height>

string

minExclusive=0.0
totalDigits=10

RateV4Request / Package / Girth

optional

Value must be numeric. Units are inches. Required when RateV4Request/Size is LARGE, and RateV4Request/Container is NONRECTANGULAR or VARIABLE/NULL.

 

For example: <Girth>11</Girth>

string

minExclusive=0.0
totalDigits=10

RateV4Request / Package / Value

optional

Available when RateV4Request[Revision='2'].

 

Package value.  Used to determine availability and cost of extra services.

 

For example: <Value>150.00</Value>

string

minExclusive=0.0
totalDigits=10

RateV4Request / Package / AmountToCollect

optional

Available when RateV4Request [Revision='2'].

 

Collect on delivery amount.  Used to determine availability and cost of extra services.

 

For example: <AmountToCollect>150.00</AmountToCollect>

string

minExclusive=0.0
totalDigits=10

RateV4Request / Package / SpecialServices

optional

Available when RateV4Request [Revision='2'].

 

Groups the SpecialServices elements.

 

Special Services prices and availability will not be returned when Service = “ALL” or “ONLINE”

(group)

 

RateV4Request / Package / SpecialServices / SpecialService

optional, repeating up to 10 times

Available when RateV4Request[Revision='2'].

 

Defines extra services desired in order to determine cost of desired services and availability of other, additional services.

 

An initial rate call without the SpecialService tag specified is recommended to determine base availability of special services for each mail service.

The extra service definitions are as follows:

Special Service Name

ServiceID

Insurance

100

Insurance – Priority Mail Express

101

Return Receipt

102

Collect on Delivery

103

Certificate of Mailing (Form 3665)

104

Certified Mail

105

USPS Tracking

106

Return Receipt for Merchandise

107

Signature Confirmation

108

Registered Mail

109

Return Receipt Electronic

110

Registered mail COD collection Charge

112

Return Receipt – Priority Mail Express

118

Adult Signature Required

119

Adult Signature Restricted Delivery

120

Insurance – Priority Mail

125

USPS Tracking Electronic

155

Signature Confirmation Electronic

156

Certificate of Mailing (Form 3817)

160

Priority Mail Express 1030 AM Delivery

161

Certified Mail Restricted Delivery

170

Certified Mail Adult Signature Required

171

Certified Mail Adult Signature Restricted Delivery

172

Signature Confirm. Restrict. Delivery

173

Signature Confirmation Electronic Restricted Delivery

174

Collect on Delivery Restricted Delivery

175

Registered Mail Restricted Delivery

176

Insurance Restricted Delivery

177

Insurance Restrict.  Delivery – Priority Mail

179

Insurance Restrict. Delivery – Priority Mail Express

178

Insurance Restrict. Delivery (Bulk Only)

180

Special Handling - Fragile

190

 

For example:

<SpecialServices>

<SpecialService>100<SpecialService>

<SpecialService>108<SpecialService>

</SpecialServices>

string

Enumerations=

100

101

102

103

104

105

106

107

108

109

110

112

118

119

120

125

155

156

160

161

170

171

172

173

174

175

176

177

178

179

180

190

RateV4Request / Package / Content

optional

Available when RateV4Request[Revision='2'].

 

Groups the ContentType and ContentDescription elements.

group

 

RateV4Request / Package / Content / ContentType

optional

Available when RateV4Request[Revision=’2’].

 

Defines the type of content of the package.

string

enumeration=

HAZMAT

CREMATEDREMAINS

FRAGILE

PERISHABLE

PHARMACEUTICALS

MEDICALSUPPLIES

LIVES

RateV4Request / Package / Content / ContentDescription

optional

Available when RateV4Request[Revision=’2’].

 

Describes the content of the package. Optional but required for ContentType ‘LIVES’.

string

enumeration=

BEES

DAYOLDPOULTRY

ADULTBIRDS

OTHER

RateV4Request / Package / GroundOnly

optional

Available when RateV4Request [Revision=’2’].

 

RateV4Request[Service=’ Retail Ground’]

 

Use “true” when shipment contains mailable hazardous materials, live animals and other “surface-only” items.

string

Default=false

enumeration=false

enumeration=true

RateV4Request / Package / SortBy

optional

Available when RateV4Request [Revision='2'].

 

Returns all mailing services available based on item shape.  When specified, value in <Container> is ignored.

 

Available when:

RateV4Request[Service='ALL'] RateV4Request[Service='ONLINE']

 

For example: <SortBy>PACKAGE</SortBy>

 

default=CONTAINER

enumeration=

LETTER

LARGEENVELOPE

PACKAGE

FLATRATE

RateV4Request / Package / Machinable

optional

RateV4Request/Machinable is required when:

 

RateV4Request[Service='FIRST CLASS' and (FirstClassMailType='LETTER' or FirstClassMailType='FLAT')]

RateV4Request[Service='Retail Ground’] RateV4Request[Service='ALL'] RateV4Request[Service='ONLINE']

 

If false, First Class Mail Large Envelopes will not be returned.


For example: <Machinable>true</Machinable>

string

whiteSpace=collapse

enumeration=true

enumeration=false

RateV4Request / Package / ReturnLocations

optional

Include Dropoff Locations in Response if available. Requires "ShipDate" tag.

string

default=true

enumeration=true

enumeration=false

RateV4Request / Package / ReturnServiceInfo

optional

Include mail service specific information in Response if available.

string

enumeration=false

enumeration=true

RateV4Request /

Package /

DropOffTime

optional

Time Package Will Be Mailed. Enter drop off time in format: HH:mm, such as 13:45.

 

Inclusion of Drop Off Time will result increased accuracy of <CommitmentName> and <CommitmentDate> in the response for Priority Mail and Priority Mail Express variants.

 

Example:

<DropOffTime>13:45</DropOffTime>

string

 

RateV4Request / Package / ShipDate

optional

Date Package Will Be Mailed. Ship date may be today plus 0 to 3 days in advance. Enter the date in format: yyyy-mm-dd, such as 2013-07-28.

 

Inclusion of Ship Date will result in <CommitmentName> and <CommitmentDate> in the response for Priority Mail and Priority Mail Express variants


Example:

<ShipDate Option="HFP">2013-07-28</ShipDate>

string

pattern=\d{2}-[a-zA-z]{3}-\d{4}

RateV4Request / Package / ShipDate / @Option

optional

The value of this attribute specifies how the RateV4Response will structure the Priority Express Mail Commitment data elements.

string

default=PEMSH
enumeration=PEMSH
enumeration=HFP

 

2.2.1   Sample Requests

All requests should hit the http://production.shippingapis.com/ShippingAPI.dll end point with the API=RateV4 and XML=<the sample XML request below> key value pairs using either a HTTP POST or a HTTP GET.

Request with Revision Tag:

<RateV4Request USERID="xxxx">

<Revision>2</Revision>

<Package ID="1ST">

<Service>FIRST CLASS</Service>

<FirstClassMailType>LETTER</FirstClassMailType>

<ZipOrigination>44106</ZipOrigination>

<ZipDestination>20770</ZipDestination>

<Pounds>0</Pounds>

<Ounces>3.12345678</Ounces>

<Container/>

<Size>REGULAR</Size>

<Machinable>true</Machinable>

</Package>

<Package ID="2ND">

<Service>PRIORITY</Service>

<ZipOrigination>44106</ZipOrigination>

<ZipDestination>20770</ZipDestination>

<Pounds>1</Pounds>

<Ounces>8</Ounces>

<Container>NONRECTANGULAR</Container>

<Size>LARGE</Size>

<Width>15</Width>

<Length>30</Length>

<Height>15</Height>

<Girth>55</Girth>

<Value>1000</Value>

<SpecialServices>

<SpecialService>1</SpecialService>

</SpecialServices>

</Package>

<Package ID="3RD">

<Service>ALL</Service>

<ZipOrigination>90210</ZipOrigination>

<ZipDestination>96698</ZipDestination>

<Pounds>8</Pounds>

<Ounces>32</Ounces>

<Container/>

<Size>REGULAR</Size>

<Machinable>true</Machinable>

<DropOffTime>23:59</DropOffTime>

<ShipDate>2016-03-23</ShipDate>

</Package>

</RateV4Request>

 

 

 

 

 

Request - Live Animal Sample:

<RateV4Request USERID="XXXXX">

<Revision>2</Revision>     

<Package ID="0">   

  <Service>PRIORITY</Service>

  <FirstClassMailType></FirstClassMailType>  

  <ZipOrigination>22201</ZipOrigination>   

  <ZipDestination>26301</ZipDestination>   

  <Pounds>8</Pounds>   

  <Ounces>2</Ounces>   

  <Container>VARIABLE</Container>   

  <Size>Regular</Size>

  <Width>0</Width>

  <Length>0</Length>

  <Height>0</Height>

  <Girth>0</Girth>

  <Content>

    <ContentType>LIVES</ContentType>

    <ContentDescription>OTHER</ContentDescription>

  </Content>   

  <Machinable>TRUE</Machinable>   

</Package>

</RateV4Request>

 

2.3    Response Tag Descriptions

Tag Name

Occurs

Description

Type

Validation

RateV4Response

required once

 

(group)

 

RateV4Response / Package

required once repeating up to 25 times

 

(group)

 

RateV4Response / Package / @ID

Required

Corresponds to ID attribute in request. 
For example: <Package ID="0"/>

NMTOKEN

 

RateV4Response / Package / ZipOrigination

required once

Origination ZIP Code from request  

string

whiteSpace=collapse
length=5
pattern=\d{5}  

RateV4Response / Package / ZipDestination

required once

Destination ZIP Code from request  

string

whiteSpace=collapse
length=5
pattern=\d{5}  

RateV4Response / Package / Pounds

required once

Package Weight (Pounds) from request  

integer

maxInclusive=70
minInclusive=0  

RateV4Response / Package / Ounces

required once

Package Weight (Ounces) from request  

decimal

maxInclusive=1120.0
minInclusive=0.0
totalDigits=10  

RateV4Response / Package / FirstClassMailType

optional

Appears when RateV4Request [Service='FIRST CLASS'].
For example: <FirstClassMailType>LETTER</FirstClassMailType

string

whiteSpace=collapse
enumeration=

LETTER
FLAT
PACKAGE SERVICE RETAIL

POSTCARD  

PACKAGE SERVICE

RateV4Response / Package / Container

optional

Shipping Container (appears where applicable: RateV4Request[Service='ALL' or Service='PRIORITY EXPRESS*' or Service='PRIORITY*'])  

string

whiteSpace=collapse
enumeration=

·    VARIABLE

·    FLAT RATE ENVELOPE

·    PADDED FLAT RATE ENVELOPE

·    LEGAL FLAT RATE ENVELOPE

·    SM FLAT RATE ENVELOPE

·    WINDOW FLAT RATE ENVELOPE

·    GIFT CARD FLAT RATE ENVELOPE

·    SM FLAT RATE BOX

·    MD FLAT RATE BOX

·    LG FLAT RATE BOX

·    REGIONALRATEBOXA

·    REGIONALRATEBOXB

·    RECTANGULAR

·    NONRECTANGULAR    

RateV4Response / Package / Size

required once

Package Size from request  

string

whiteSpace=collapse
enumeration=

LARGE
REGULAR 

RateV4Response / Package / Width

optional

Package Width from request  

decimal

minExclusive=0.0
totalDigits=10  

RateV4Response / Package / Length

optional

Package Length from request  

decimal

minExclusive=0.0
totalDigits=10  

RateV4Response / Package / Height

optional

Package Height from request  

decimal

minExclusive=0.0
totalDigits=10  

RateV4Response / Package / Girth

optional

Package Girth from request  

decimal

minExclusive=0.0
totalDigits=10  

RateV4Response / Package / Machinable

optional

Machinable (appears where applicable: RateV4Request[Service='ALL' or Service='FIRST CLASS' or Service=’ Retail Ground’])  

string

enumeration=TRUE
enumeration=FALSE  

RateV4Response / Package / Zone

optional

Returned if zone for the postage service is different than the zone for package tag.

 

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

string

 

RateV4Response / Package / Postage

required once repeating up to unbounded times

Postage tag contains a nested postal rate and service description.  

(group)

 

RateV4Response / Package / Postage / @CLASSID

required

A mail class identifier for the postage returned. Not necessarily unique within a <Package/>.                

integer

 

RateV4Response / Package / Postage / MailService

required once

Service Type name  

string

 

RateV4Response / Package / Postage / Rate

required once

Retail Rate  

decimal

 

RateV4Response / Package / Postage / CommercialRate

optional

Commercial Rate. Appears only where applicable and only when requested via RateV4Request[Service='ONLINE' or

Service='FIRST CLASS COMMERCIAL'

Service='FIRST CLASS HFP COMMERCIAL' Service='PRIORITY COMMERCIAL' or

Service='PRIORITY HFP COMMERCIAL' or Service='PRIORITY MAIL EXPRESS COMMERCIAL' or Service='PRIORITY MAIL EXPRESS SH COMMERCIAL' or

Service='PRIORITY MAIL EXPRESS HFP COMMERCIAL'].  

decimal

 

RateV4Response / Package / Postage / CommercialPlusRate

optional

Commercial Rate. Appears only where applicable and only when requested via RateV4Request[Service=’PLUS’ or

Service='PRIORITY CPP’ or

Service='PRIORITY HFP CPP’ or

Service='PRIORITY MAIL EXPRESS CPP’ or

Service='PRIORITY MAIL EXPRESS HFP CPP’].  

decimal

 

RateV4Response / Package / Postage / MaxDimensions

optional

Maximum dimensions for a USPS produced product. Appears where applicable: RateV4Request[SortBy<>’CONTAINER’]

string

 

RateV4Response / Package / Postage / ServiceInformation

optional

Mail Service Information.  Appears where applicable: RateV4Request[ReturnServiceInfo=’true’] 

string

 

RateV4Response / Package / Postage / (choice)

optional

This choice depends on the RateV4Request / ShipDate / @Option attribute. If the attribute is missing or has the enumeration value of PEMSH then the original Express Mail Sunday/Holiday structure is used. Otherwise, if the attribute has the enumeration value of HFP, then the Hold For Pickup structure is used. If RateV4Request / ShipDate is not present, then neither choice is returned.

(choice)

 

RateV4Response / Package / Postage / (choice) / (sequence)

if used:
required once

This sequence consisting of CommitmentDate and Location nodes is mutually exclusive with RateV4Response / Package / Postage / Commitment.

(group)

 

RateV4Response / Package / Postage / (choice) / (sequence) / CommitmentDate

required once

Calculated Date Package Will Be Delivered: yyyy-mm-dd, such as 2013-07-28. Only returned for Priority Mail Express Mail variants when "ShipDate" tag is present in the request.  

string

 

RateV4Response / Package / Postage / (choice) / Commitment / CommitmentName

Optional

Inclusion of Ship Date will result in <CommitmentName> and <CommitmentDate> in the response for Priority Mail and Priority Mail Express variants

 

String

 

RateV4Response / Package / Postage / (choice) / (sequence) / Location

optional repeating up to 200 times

Collection of Dropoff Locations with Cutoff times. Only returned with Express Mail variants, when "ShipDate" tag is present in the request, and the "ReturnLocations" tag is not false. Example: <Location>
<CutOff>8:00 PM</CutOff>
<Facility>EXPRESS MAIL COLLECTION BOX</Facility>
<Street>9201 EDGEWORTH DR</Street>
<City>CAPITOL HEIGHTS</City>
<State>MD</State>
<Zip>20790</Zip>
</Location> 

(group)

 

RateV4Response / Package / Postage / (choice) / (sequence) / Location / CutOff

required once

Local cutoff time for drop-off  

string

 

RateV4Response / Package / Postage / (choice) / (sequence) / Location / Facility

required once

Facility Name  

string

 

RateV4Response / Package / Postage / (choice) / (sequence) / Location / Street

required once

Facility Address  

string

 

RateV4Response / Package / Postage / (choice) / (sequence) / Location / City

required once

Facility City  

string

 

RateV4Response / Package / Postage / (choice) / (sequence) / Location / State

required once

Facility State  

string

 

RateV4Response / Package / Postage / (choice) / (sequence) / Location / Zip

required once

Facility Zip  

string

 

RateV4Response / Package / Postage / (choice) / Commitment

if used:
required once repeating up to 5 times

This node is mutually exclusive with RateV4Response / Package / Postage / CommitmentDate and RateV4Response / Package / Postage / Location.  

(group)

 

RateV4Response / Package / Postage / (choice) / Commitment / CommitmentDate

required once

Calculated Date Package Will Be Delivered: yyyy-mm-dd, such as 2013-07-28. Only returned for Priority Mail Express Mail variants when "ShipDate" tag is present in the request.  

string

 

RateV4Response / Package / Postage / (choice) / Commitment / CommitmentTime

required once

Commitment time of day. Only returned for Priority Mail Express Mail variants when "ShipDate" tag is present in the request.  

string

enumeration=10:30 AM
enumeration=12:00 PM
enumeration=3:00 PM

RateV4Response / Package / Postage / (choice) / Commitment / Location

optional repeating up to 200 times

Collection of Dropoff Locations with Cutoff times. Only returned with Priority Mail Express Mail variants, when "ShipDate" tag is present in the request, and the "ReturnLocations" tag is not false. Example: <Location>
<CutOff>8:00 PM</CutOff>
<Facility>EXPRESS MAIL COLLECTION BOX</Facility>
<Street>9201 EDGEWORTH DR</Street>
<City>CAPITOL HEIGHTS</City>
<State>MD</State>
<Zip>20790</Zip>
</Location> 

(group)

 

RateV4Response / Package / Postage / (choice) / Commitment / Location / CutOff

required once

Local cutoff time for drop-off  

string

 

RateV4Response / Package / Postage / (choice) / Commitment / Location / Facility

required once

Facility Name  

string

 

RateV4Response / Package / Postage / (choice) / Commitment / Location / Street

required once

Facility Address  

string

 

RateV4Response / Package / Postage / (choice) / Commitment / Location / City

required once

Facility City  

string

 

RateV4Response / Package / Postage / (choice) / Commitment / Location / State

required once

Facility State  

string

 

RateV4Response / Package / Postage / (choice) / Commitment / Location / Zip

required once

Facility Zip  

string

 

RateV4Response / Package / Postage / SpecialServices

optional

Returned when RateV4Request[Revision='2'].

 

Groups the Special Service elements.

(group)

 

RateV4Response / Package / Postage / SpecialServices / SpecialService

required once, repeating up to unbounded times

Returned when RateV4Request[Revision='2'].

 

SpecialService” contains nested service name, availability, and pricing.

(group)

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / ServiceID

required once

Returned when RateV4Request[Revision='2'].

 

Special service ID

Integer

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / ServiceName

required once

Returned when RateV4Request[Revision='2'].

 

Special service name

string

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / Available

required once

Returned when RateV4Request[Revision='2'].

 

Availability of special service.  Availability may change depending on special services passed (selected) in request.

boolean

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / AvailableOnline

required once

Returned when RateV4Request[Revision='2'].

 

Availability of special service for online only rates.  Not all special services have online rates.

boolean

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / AvailableCPP

required once

Returned when RateV4Request[Revision='2'].

 

Availability of special service for Commercial Plus Price only.  Not all special services have Commercial Plus Prices.

boolean

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / Price

required once

Returned when RateV4Request[Revision='2'].

 

Special service pricing. Pricing may change depending on special services passed (selected) in request.

decimal

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / PriceOnline

required once

Returned when RateV4Request[Revision='2'].

 

Special service pricing. Pricing may change depending on special services passed (selected) in request. Not all special services have online rates.

decimal

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / PriceCPP

required once

Returned when RateV4Request[Revision='2'].

 

Special service Commercial Plus Pricing. Commercial Plus Pricing may change depending on special services passed (selected) in request. Not all special services have Commercial Plus Pricing.

decimal

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / DeclaredValueRequired

optional

Returned if applicable when RateV4Request[Revision='2'].

 

Indicates if special service requires a declared package value (specified in RateV4Request[Value])to determine correct pricing.

boolean

 

RateV4Response / Package / Postage / SpecialServices / SpecialService / DueSenderRequired

optional

Returned if applicable when RateV4Request[Revision='2'].

 

Indicates if special service requires a due sender amount (specified in RateV4Request[AmountToCollect]) to determine correct pricing.

boolean

 

RateV4Response / Package / Postage / Zone

Optional

Returned only if a zone is present for this mail service.  Zone is only displayed for specific PM APO/DPO/FPO addresses.

 

Postal Zone indicates the number of postal zones between the origin and destination ZIP codes

string

 

RateV4Response / Package / Restriction

optional

Groups the Restriction Elements

(group)

 

RateV4Response / Package / Restriction / Restrictions

Required

APO/FPO Restrictions provided if the Destination ZIP Code is an APO/FPO ZIP Code.  

string

 

RateV4Response / Package / Error

if used:
required once

Error document (indicates request could not be completed).  

 

 See the Error Responses section below.

 

2.3.1   Sample Response

All requests should hit the http://production.shippingapis.com/ShippingAPI.dll end point with the API=RateV4 and XML=<the sample XML request below> key value pairs using either a HTTP POST or a HTTP GET.

Revision ‘2’ Response:

-<RateV4Response>

-<Package ID="1ST">

<ZipOrigination>44106</ZipOrigination>

<ZipDestination>20770</ZipDestination>

<Pounds>0</Pounds>

<Ounces>3.12345678</Ounces>

<FirstClassMailType>LETTER</FirstClassMailType>

<Size>REGULAR</Size>

<Machinable>TRUE</Machinable>

<Zone>3</Zone>

-<Postage CLASSID="0">

<MailService>First-Class Mail&lt;sup&gt;&#174;&lt;/sup&gt; Stamped Letter</MailService>

<Rate>1.10</Rate>

-<SpecialServices>

-<SpecialService>

<ServiceID>104</ServiceID>

<ServiceName>Certificate of Mailing (Form 3817)</ServiceName>

<Available>true</Available>

<Price>1.30</Price>

</SpecialService>

-<SpecialService>

<ServiceID>105</ServiceID>

<ServiceName>Certified Mail&lt;sup&gt;&#174;&lt;/sup&gt;</ServiceName>

<Available>true</Available>

<Price>3.30</Price>

</SpecialService>

-<SpecialService>

<ServiceID>170</ServiceID>

<ServiceName>Certified Mail&lt;sup&gt;&#174;&lt;/sup&gt; Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>8.25</Price>

</SpecialService>

-<SpecialService>

<ServiceID>171</ServiceID>

<ServiceName>Certified Mail&lt;sup&gt;&#174;&lt;/sup&gt; Adult Signature Required</ServiceName>

<Available>true</Available>

<Price>8.25</Price>

</SpecialService>

-<SpecialService>

<ServiceID>172</ServiceID>

<ServiceName>Certified Mail&lt;sup&gt;&#174;&lt;/sup&gt; Adult Signature Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>8.25</Price>

</SpecialService>

-<SpecialService>

<ServiceID>103</ServiceID>

<ServiceName>Collect on Delivery</ServiceName>

<Available>true</Available>

<Price>6.95</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>175</ServiceID>

<ServiceName>Collect on Delivery Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>11.90</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>100</ServiceID>

<ServiceName>Insurance</ServiceName>

<Available>true</Available>

<Price>2.10</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>177</ServiceID>

<ServiceName>Insurance Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>14.00</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>109</ServiceID>

<ServiceName>Registered Mail&lt;sup&gt;&#8482;&lt;/sup&gt;</ServiceName>

<Available>true</Available>

<Price>11.70</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>176</ServiceID>

<ServiceName>Registered Mail&lt;sup&gt;&#8482;&lt;/sup&gt; Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>16.65</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

</SpecialServices>

</Postage>

</Package>

-<Package ID="2ND">

<ZipOrigination>44106</ZipOrigination>

<ZipDestination>20770</ZipDestination>

<Pounds>1</Pounds>

<Ounces>8</Ounces>

<Container>NONRECTANGULAR</Container>

<Size>LARGE</Size>

<Zone>3</Zone>

-<Postage CLASSID="1">

<MailService>Priority Mail 2-Day&lt;sup&gt;&#8482;&lt;/sup&gt;</MailService>

<Rate>20.70</Rate>

<CommitmentDate>2016-03-28</CommitmentDate>

<CommitmentName>2-Day</CommitmentName>

-<SpecialServices>

-<SpecialService>

<ServiceID>119</ServiceID>

<ServiceName>Adult Signature Required</ServiceName>

<Available>true</Available>

<Price>5.70</Price>

</SpecialService>

-<SpecialService>

<ServiceID>120</ServiceID>

<ServiceName>Adult Signature Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>5.95</Price>

</SpecialService>

-<SpecialService>

<ServiceID>1</ServiceID>

<ServiceName>Insurance</ServiceName>

<Available>true</Available>

<Price>14.05</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>102</ServiceID>

<ServiceName>Return Receipt</ServiceName>

<Available>true</Available>

<Price>2.70</Price>

</SpecialService>

-<SpecialService>

<ServiceID>155</ServiceID>

<ServiceName>USPS Tracking&lt;sup&gt;&#8482;&lt;/sup&gt; Electronic</ServiceName>

<Available>true</Available>

<Price>0.00</Price>

</SpecialService>

</SpecialServices>

</Postage>

</Package>

-<Package ID="3RD">

<ZipOrigination>90210</ZipOrigination>

<ZipDestination>96698</ZipDestination>

<Pounds>8</Pounds>

<Ounces>32</Ounces>

<Size>REGULAR</Size>

<Machinable>TRUE</Machinable>

<Zone>4</Zone>

-<Postage CLASSID="1">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt;</MailService>

<Rate>14.90</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="17">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt; Medium Flat Rate Box</MailService>

<Rate>13.45</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="28">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt; Small Flat Rate Box</MailService>

<Rate>6.80</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="22">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt; Large Flat Rate Box APO/FPO/DPO</MailService>

<Rate>16.75</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="16">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt; Flat Rate Envelope</MailService>

<Rate>6.45</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="44">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt; Legal Flat Rate Envelope</MailService>

<Rate>6.45</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="29">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt; Padded Flat Rate Envelope</MailService>

<Rate>6.80</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="38">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt; Gift Card Flat Rate Envelope</MailService>

<Rate>6.45</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="42">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt; Small Flat Rate Envelope</MailService>

<Rate>6.45</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="40">

<MailService>Priority Mail Military&lt;sup&gt;&#8482;&lt;/sup&gt; Window Flat Rate Envelope</MailService>

<Rate>6.45</Rate>

<CommitmentDate/>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="6">

<MailService>Media Mail Parcel</MailService>

<Rate>6.93</Rate>

</Postage>

-<Postage CLASSID="7">

<MailService>Library Mail Parcel</MailService>

<Rate>6.62</Rate>

</Postage>

-<Restriction>

<Restrictions>A1. Mail addressed to 'Any Servicemember' or similar wording such as 'Any Soldier, Sailor, Airman or Marine', 'Military Mail', etc., is prohibited. Mail must be addressed to an individual or job title, such as 'Commander', 'Commanding Officer', etc. A2. APO/FPO/DPO addresses shall not include a city and/or country name. B. When a customs declaration is required, the surface area of the address side of the item to be mailed must be large enough to contain completely the applicable customs declaration, postage, and any applicable markings, endorsements, and extra service labels. Customs declarations forms required for use to or from APO/FPO/DPO addresses are as follows: B. a. Priority Mail Express mailpieces must bear PS Form 2976-B. B. b. For other mail classes, mailpieces must bear PS Form 2976 (or, if the customer prefers, a PS Form 2976-A) if the mailpiece weighs 16 ounces or more, or contains goods. The following exceptions apply: B. a. Known mailers are exempt from providing customs documentation on non-dutiable letters, and printed matter weighing 16 ounces or more. A known mailer is a business mailer who enters volume mailings through a business mail entry unit (BMEU) or other bulk mail acceptance location, pays postage through an advance deposit account, uses a permit imprint for postage payment, and submits a completed postage statement at the time of entry that certifies the mailpieces contain no dangerous materials that are prohibited by postal regulations. B. b. All federal, state, and local government agencies whose mailings are regarded as "Official Mail" are exempt from providing customs documentation on mail addressed to an APO, FPO, or DPO except for those to which restriction "B2" applies. B. c. Prepaid mail from military contractors is exempt, providing the mailpiece is endorsed "Contents for Official Use - Exempt from Customs Requirements." V. Priority Mail Express Military Service (PMEMS) not available from any origin. </Restrictions>

</Restriction>

</Package>

</RateV4Response>

 

Response - Live Animal Sample:

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

-<RateV4Response>

-<Package ID="0">

<ZipOrigination>22201</ZipOrigination>

<ZipDestination>26301</ZipDestination>

<Pounds>8</Pounds>

<Ounces>2</Ounces>

<Container>VARIABLE</Container>

<Size>REGULAR</Size>

<Zone>3</Zone>

-<Postage CLASSID="1">

<MailService>Priority Mail 3-Day&lt;sup&gt;&#8482;&lt;/sup&gt;</MailService>

<Rate>13.20</Rate>

<CommitmentDate>2016-03-29</CommitmentDate>

<CommitmentName>3-Day</CommitmentName>

-<SpecialServices>

-<SpecialService>

<ServiceID>119</ServiceID>

<ServiceName>Adult Signature Required</ServiceName>

<Available>true</Available>

<Price>5.70</Price>

</SpecialService>

-<SpecialService>

<ServiceID>120</ServiceID>

<ServiceName>Adult Signature Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>5.95</Price>

</SpecialService>

-<SpecialService>

<ServiceID>104</ServiceID>

<ServiceName>Certificate of Mailing (Form 3817)</ServiceName>

<Available>true</Available>

<Price>1.30</Price>

</SpecialService>

-<SpecialService>

<ServiceID>105</ServiceID>

<ServiceName>Certified Mail&lt;sup&gt;&#174;&lt;/sup&gt;</ServiceName>

<Available>true</Available>

<Price>3.30</Price>

</SpecialService>

-<SpecialService>

<ServiceID>170</ServiceID>

<ServiceName>Certified Mail&lt;sup&gt;&#174;&lt;/sup&gt; Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>8.25</Price>

</SpecialService>

-<SpecialService>

<ServiceID>171</ServiceID>

<ServiceName>Certified Mail&lt;sup&gt;&#174;&lt;/sup&gt; Adult Signature Required</ServiceName>

<Available>true</Available>

<Price>8.25</Price>

</SpecialService>

-<SpecialService>

<ServiceID>172</ServiceID>

<ServiceName>Certified Mail&lt;sup&gt;&#174;&lt;/sup&gt; Adult Signature Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>8.25</Price>

</SpecialService>

-<SpecialService>

<ServiceID>103</ServiceID>

<ServiceName>Collect on Delivery</ServiceName>

<Available>true</Available>

<Price>6.95</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>175</ServiceID>

<ServiceName>Collect on Delivery Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>11.90</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>125</ServiceID>

<ServiceName>Insurance</ServiceName>

<Available>true</Available>

<Price>0.00</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>179</ServiceID>

<ServiceName>Insurance Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>0.00</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>109</ServiceID>

<ServiceName>Registered Mail&lt;sup&gt;&#8482;&lt;/sup&gt;</ServiceName>

<Available>true</Available>

<Price>11.70</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>176</ServiceID>

<ServiceName>Registered Mail&lt;sup&gt;&#8482;&lt;/sup&gt; Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>16.65</Price>

<DeclaredValueRequired>true</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceID>107</ServiceID>

<ServiceName>Return Receipt for Merchandise</ServiceName>

 

<Available>true</Available>

<Price>4.20</Price>

</SpecialService>

-<SpecialService>

<ServiceID>173</ServiceID>

<ServiceName>Signature Confirmation&lt;sup&gt;&#8482;&lt;/sup&gt; Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>7.85</Price>

</SpecialService>

-<SpecialService>

<ServiceID>156</ServiceID>

<ServiceName>Signature Confirmation&lt;sup&gt;&#8482;&lt;/sup&gt; Electronic</ServiceName>

<Available>true</Available>

<Price>2.35</Price>

</SpecialService>

-<SpecialService>

<ServiceID>174</ServiceID>

<ServiceName>Signature Confirmation&lt;sup&gt;&#8482;&lt;/sup&gt; Electronic Restricted Delivery</ServiceName>

<Available>true</Available>

<Price>7.30</Price>

</SpecialService>

-<SpecialService>

<ServiceID>155</ServiceID>

<ServiceName>USPS Tracking&lt;sup&gt;&#8482;&lt;/sup&gt; Electronic</ServiceName>

<Available>true</Available>

<Price>0.00</Price>

</SpecialService>

</SpecialServices>

</Postage>

</Package>

</RateV4Response>

 

 

Example RateV4 XML request with new tags:

 

http://stg-production.shippingapis.com/ShippingApi.dll?API=RateV4&XML=<RateV4Request USERID="XXXXX">

<Revision>2</Revision>

<Package ID="1">

<Service>standard mail marketing parcel</Service>

<ZipOrigination>18702</ZipOrigination>

<ZipDestination>16901</ZipDestination>

<Pounds>0</Pounds>

<Ounces>1</Ounces>

<Container>Parcel</Container>

<Size>Regular</Size>

<SortBy></SortBy>

<Machinable>True</Machinable>

 <SortationLevel>5D</SortationLevel> <DestinationEntryFacilityType>DDU</DestinationEntryFacilityType>

 <Nonprofit>N</Nonprofit>

</Package>

 

</RateV4Request>

 

Example RateV4 XML response with new product:

 

…<RateV4Response>

<Package ID="1">

<ZipOrigination>18702</ZipOrigination>

<ZipDestination>16901</ZipDestination>

<Pounds>0</Pounds>

<Ounces>1</Ounces>

<Container>PARCEL</Container>

<Size>REGULAR</Size>

<Zone>2</Zone> <Postage CLASSID="80"> <MailService>USPS Marketing Mail Marketing Parcels Presorted 5-Digit</MailService> <Rate>0.00</Rate> <CommercialRate>0.691</CommercialRate>

+<SpecialServices>

</Postage>

<SortationLevel>5D</SortationLevel> <DestinationEntryFacilityType>DDU</DestinationEntryFacilityType>

 <Nonprofit>N</Nonprofit>

</Package>

 

 

 

 For more information contact webtools@usps.gov

 

2.4    Error Responses

Error conditions are handled at the main XML document level and Package node 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.  But if there is a problem with a specific Package within the request, an <Error> element will be returned within the <Package> element that pertains to the specific package ID.  Since the RateV4 API allows you to submit multiple packages within a single request document, the response may contain a mix of domestic rate information and errors.  For requests containing multiple package IDs, you need to check if there is an <Error> within a given <Package> element, as well as checking for an error at the top level for example:

<?xml version="1.0"?>

<RateV4Response>

  <Package ID="0">

    <ZipOrigination>07747</ZipOrigination>

    <ZipDestination>90210</ZipDestination>

    <Pounds>11</Pounds>

    <Ounces>4</Ounces>

    <Container>VARIABLE</Container>

    <Size>REGULAR</Size>

    <Zone>8</Zone>

    <Postage CLASSID="3">

      <MailService>Priority Mail Express&amp;lt;sup&amp;gt;&amp;#8482;&amp;lt;/sup&amp;gt;</MailService>

      <Rate>92.85</Rate>

    </Postage>

  </Package>

  <Package ID="1">

    <Error>

      <Number>-2147219498</Number>

      <Source>DomesticRatesV4;RateEngineV4.ProcessRequest</Source>

      <Description>Please enter a valid ZIP Code for the sender.  </Description>

      <HelpFile></HelpFile>

      <HelpContext>1000440</HelpContext>

    </Error>

  </Package>

</RateV4Response>

 

If you need assistance with an error response, contact the USPS Internet Customer Care Center (ICCC) uspstechnicalsupport@mailps.custhelp.com

3.0   International Rates API – IntlRateV2

3.1    Overview

The IntlRateV2 API lets customers calculate the rate for international packages and envelopes given the weight and dimensions of the item.  The IntlRateV2 API limits the data requested to twenty five (25) packages per transaction.

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

3.1.1   API Signature

Scheme

Host

Path

API

XML

http://

 

https://

production.shippingapis.com

 

secure.shippingapis.com

/ShippingAPI.dll?

 

/ShippingAPI.dll?

API=IntlRateV2

 

API=IntlRateV2

&XML=(see Tag Descriptions below)

&XML=(see Tag Descriptions below)

3.2    Request Tag Descriptions

Tag Name

Occurs

Description

Type

Validation

IntlRateV2Request

required once

Opening document tag.  

(group)

 

IntlRateV2Request / @USERID

required

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

NMTOKEN

 

IntlRateV2Request / Revision

optional

Optional for base IntlRateV2 functionality. 

 

For full IntlRateV2 functionality use Revision=“2”

string

 

IntlRateV2Request / Package

required once repeating up to 25 times

Opening Package tag.  

(group)

 

IntlRateV2Request / Package / ID

required

No restriction on number or type of characters provided valid XML syntax and unique to request. 
For example: <Package ID="0">...</Package>

NMTOKEN

 

IntlRateV2Request / Package / Pounds

required once

Value must be numeric. Package weight generally cannot exceed 70 pounds.  Maximum decimal places are 8. Refer to the International Mail Manual (IMM) for weight requirements per country and mail service. The IMM can be found at the Postal Explorer web site. 


Examples:

<Pounds>2</Pounds>

<Pounds>2.12345678</Pounds>

integer

minInclusive=0  

IntlRateV2Request / Package / Ounces

required once

Value must be numeric. Package weight generally cannot exceed 70 pounds.  Maximum decimal places are 8. Refer to the International Mail Manual (IMM) for weight requirements per country and mail service. The IMM can be found at the Postal Explorer web site

Examples:

<Ounces>4</Ounces>

<Ounces>4.12345678</Ounces>

decimal

minInclusive=0.0  

IntlRateV2Request / Package / Machinable

optional

Indicates whether or not the item is machinable. A surcharge is applied to a First-Class Mail International item if it has one or more non-machinable characteristics. See International Mail Manual (IMM) Section 241.217 for more information. 

For example: <Machinable>True</Machinable>

boolean

default=true
 

IntlRateV2Request / Package / MailType

required once

Package type being shipped.

 

For example: <MailType>Package</MailType>

string

enumeration=

ALL
PACKAGE

POSTCARDS
ENVELOPE

LETTER

LARGEENVELOPE

FLATRATE

IntlRateV2Request / Package / GXG

optional

If GXG rate is desired, then this group must be specified. Note that if this data precludes delivery, due to size or availability of service at the destination, then GXG rates simply will not be returned (not an error condition.)  

(group)

 

IntlRateV2Request / Package / GXG / POBoxFlag

required once

Specify as "Y" if the destination is a post office box.  

For example <POBoxFlag>Y</POBoxFlag>

string

enumeration=Y
enumeration=N

IntlRateV2Request / Package / GXG / GiftFlag

required once

Specify as "Y" if the package contains a gift.  

For example <GiftFlag>Y</GiftFlag>

string

enumeration=Y
enumeration=N

IntlRateV2Request / Package / ValueOfContents

required once

If specified, used to compute Insurance fee (if insurance is available for service and destination).


For example: <ValueOfContents>1,003.00</ValueOfContents

string

 

IntlRateV2Request / Package / Country

required once

Entries must be from the USPS list of valid countries from the International Country Listings. To access the International Country Listings, go to the Index of Countries and Localities.

For example: <Country>Albania</Country>  

string

 

IntlRateV2Request / Package / Container

required once

Use to specify special containers or container attributes that may affect postage.  Required when Size=”LARGE”.

 

For example: <Container>RECTANGULAR</Container> 

string

enumeration=

RECTANGULAR
NONRECTANGULAR

IntlRateV2Request / Package / Size

required once

Defined as follows:

 

REGULAR: dimensions are 12’’ or less;

LARGE: dimensions are larger than 12’’.

 

For example: <Size>REGULAR</Size> 

string

enumeration=

REGULAR
LARGE

IntlRateV2Request / Package / Width

required once

Typically, the "thickness" of the package as measured in inches rounded to the nearest whole inch.  Required to obtain GXG pricing and when Size=”LARGE”.

For example: <Width>15</Width>

integer

minExclusive=0  

IntlRateV2Request / Package / Length

required once

The longest side of the package as measured in inches rounded to the nearest whole inch.  Required to obtain GXG pricing and when Size=”LARGE”.

For example: <Length>15</Length>

integer

minExclusive=0  

IntlRateV2Request / Package / Height

required once

The "height" of the package as measured in inches rounded to the nearest whole inch.  Required to obtain GXG pricing and when Size=”LARGE”.

For example: <Height>15</ Height >

integer

minExclusive=0  

IntlRateV2Request / Package / Girth

required once

The "girth" of the package as measured in inches rounded to the nearest whole inch.  Required to obtain GXG pricing when pricing and when Size=”LARGE” and Container=”NONRECTANGULAR”.

For example: <Girth>15</Girth>

Integer

minExclusive=0  

IntlRateV2Request / Package / OriginZip

optional

Available when IntlRateV2Request [Revision='2'].

 

Origin ZIP Code is required to determine Priority Mail International price to Canadian destinations and is used to determine mail-ability of Global Express Guaranteed. When provided, the response will return a list of Post Office locations where GXG is accepted. The Origin ZIP Code must be valid. 

For example: <OriginZip>20770</OriginZip

string

length=5
pattern=\d{5}  

IntlRateV2Request / Package / CommercialFlag

optional

Returns commercial base postage.

For example: <CommercialFlag>Y<CommercialFlag>

string

enumeration=Y
enumeration=N

IntlRateV2Request / Package / CommercialPlusFlag

optional

Returns commercial plus postage.

For example: <CommercialPlusFlag>Y<CommercialPlusFlag>

string

enumeration=Y
enumeration=N

IntlRateV2Request / Package / ExtraServices

optional

Available when IntlRateV2Request[Revision='2'].

 

Groups the ExtraService elements.  

(group)

 

IntlRateV2Request / Package / ExtraServices / ExtraService

required once, repeating up to 6 times

Available when IntlRateV2Request[Revision='2'].

 

Defines extra services desired by user in order to determine cost of desired services and availability of other, additional services. 

 

An initial rate call without the ExtraService tag specified is recommended to determine base availability of extra services for each mail service.

 

The extra service definitions are as follows:

Extra Service Name

ServiceID

Registered Mail

103

Insurance – Global Express Guaranteed

106

Insurance – Express Mail International