1.0 Introduction

This document contains a Reference Guide to the Rate Calculator APIs, RateV4 and IntlRateV2. See the Developers Guide to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The Developer’s Guide also contains information on testing and troubleshooting.

Note: The Request Parameter sections present the XML input tags for generating live requests along with the restrictions on the values allowed. An error message will be returned if an incorrect value is entered. Also, be aware of the maximum character amounts allowed for some tags. If the user enters more than those amounts, an error will not be generated. Web Tools will simply pass in the characters up to the maximum amount allowed and disregard the rest. This is important since the resulting value could prevent a correct response.

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:

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 Web Tools Technical Documentation Page. If you need assistance with an error response, contact the USPS Internet Customer Care Center (ICCC) https://Emailus.usps.com/.

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
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=RateV4	&XML=(see Tag Descriptions below)

2.2 Request Descriptions

Tag Name

Occurs

Description

Type

Validation

RateV4Request

Required

API=RateV4

This API returns the current USPS postage corresponding to the parameters given.

(Group)

RateV4Request / USERID

Required

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

For Example: <USERID=”XXXXXXXXXXXX”>

NMTOKEN

RateV4Request / Revision

Optional

Set this value to “2” to return all currently documented response fields.

For example:

String

RateV4Request / Package

Required repeating up to 25 times

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

(Group)

RateV4Request / Package / Service

Required

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

For example:

<Service>PRIORITY MAIL EXPRESS</Service>

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: For users that want to return all eligible products in a single RateV4 API call, please see details below regarding “All” calls:

<Service>	Description
<All>	When <Service> = “ALL”, all eligible retail products will return in the API response.
<Online>	When <Service> = “ONLINE”, all eligible retail and commercial base products will return in the API response.
<Plus>	When <Service> = “PLUS”, all eligible retail, commercial base, and commercial plus products will return in the API response.

String

whiteSpace=collape
Enumerations=

· First Class Commercial

· First Class

· First Class HFP Commercial

· First Class Returns

· Parcel Select Ground

· Parcel Select DE

· Parcel Select LW

· 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

· Priority Mail Cubic Returns

· Priority Mail Returns

· Retail Ground

· Ground Returns

· Media

· Library

· All

· Online

· Plus

· BPM

· Connect Local

RateV4Request / Package / FirstClassMailType

Optional

Required when:

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

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

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.

Note: Flats are also known as Large Envelopes

String

whiteSpace=collapse

Enumerations=

· LETTER

· FLAT

· PACKAGE SERVICE RETAIL

· POSTCARD

· PACKAGE SERVICE

RateV4Request / Package / ZipOrigination

Required

ZIP code must be valid.

For example: <ZipOrigination>20770</ZipOrigination>

String

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

RateV4Request / Package / ZipDestination

Required

ZIP code must be valid.

For example: <ZipDestination>54324</ZipDestination>

String

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

RateV4Request / Package / Pounds

Required

Value must be numeric.

Package weight cannot exceed 70 pounds.

For example:

String

maxInclusive=70
minInclusive=0

RateV4Request / Package / Ounces

Required

Value must be numeric.

Package weight cannot exceed 70 pounds (1120 ounces).

For example:

String

maxInclusive=1120.0
minInclusive=0.0

RateV4Request / Package / Container

Required

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

Note: The <FirstClassMailType> tag is used instead of the <Container> tag only if the <ServiceType> submitted is “First Class”.

Note: “Cubic Soft Pack” and “Cubic Parcels” are only valid containers for service “Priority Mail Cubic”. Dimensions Length and Height are required when requesting Cubic Soft Pack. Dimensions Length, Height, and Width are required when requesting Cubic Parcels.

Note: “VARIABLE” is used to denote that a customer is using packaging other than a USPS-produced Flat Rate Box/Envelope or Regional Rate Box”.

Note: <Container> enumerations: “SM FLAT RATE BAG”, “LG FLAT RATE BAG”, “FLAT RATE BOX” only applicable when <Service>=“Connect Local.”

String

whiteSpace=collapse
Enumerations=

· 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

· CUBIC PARCELS

· CUBIC SOFT PACK

· SM FLAT RATE BAG

· LG FLAT RATE BAG

· FLAT RATE BOX

RateV4Request / Package / Size

Deprecated

Note: This tag has been deprecated.

<Size> tag and any values within the <Size> tag will not result in an error response and will not impact rates that are returned.

String

minOccurs=0

maxOccurs=1

RateV4Request / Package / Width

Optional

Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.

For more details on dimensional weight pricing or dimension validation reference DMM https://pe.usps.com/text/dmm300/index.htm

Decimal

minExclusive=0.0
totalDigits=10

RateV4Request / Package / Length

Optional

For more details on dimensional weight pricing or dimension validation reference DMM https://pe.usps.com/text/dmm300/index.htm

Decimal

minExclusive=0.0
totalDigits=10

RateV4Request / Package / Height

Optional

For more details on dimensional weight pricing or dimension validation reference DMM https://pe.usps.com/text/dmm300/index.htm

Decimal

minExclusive=0.0
totalDigits=10

RateV4Request / Package / Girth

Optional

For more details on dimensional weight pricing or dimension validation reference DMM https://pe.usps.com/text/dmm300/index.htm

Decimal

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:

String

minOccurs=0

maxOccurs=1

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”, “ONLINE”, or “PLUS”

(Group)

RateV4Request / Package / SpecialServices / SpecialService

Optional, repeating up to 10 times

Available when RateV4Request [Revision='2'].

Defines extra services in order to determine price and availability of additional services.

An initial call without the SpecialService tag specified is recommended to determine base availability of special services for each mail class (<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
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
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
Scan Retention	181
Scan + Signature Retention	182
Special Handling - Fragile	190
USPS Connect Sunday Delivery	447

For example:

</SpecialServices>

String

Enumerations=

· 100

· 101

· 102

· 103

· 104

· 105

· 106

· 108

· 109

· 110

· 112

· 118

· 119

· 120

· 125

· 155

· 156

· 160

· 170

· 171

· 172

· 173

· 174

· 175

· 176

· 177

· 178

· 179

· 180

· 181

· 182

· 190

· 447

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

Enumerations=

· HAZMAT

· CREMATEDREMAINS

· FRAGILE

· PERISHABLE

· PHARMACEUTICALS

· MEDICAL SUPPLIES

· LIVES

RateV4Request / Package / Content / ContentDescription

Optional

Available when RateV4Request[Revision=’2’].

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

String

Enumerations=

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

Boolean

Enumerations=

· true

· false

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>

String

Enumerations=

· 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 Letters and Flats will not be returned.

For example:

Boolean

whiteSpace=collapse

Enumerations=

· true

· false

RateV4Request / Package / ReturnLocations

Optional

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

Boolean

Enumerations=

· true

· false

RateV4Request / Package / ReturnServiceInfo

Optional

If a value of “True” is indicated in the request then the response will include the <ServiceInformation> tag containing mail service specific information

Boolean

Enumerations=

· true

· false

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.

For example:

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

For example:

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

Enumerations=

· PEMSH

· HFP

RateV4Request / Package / ReturnDimensionalWeight

Optional

This tag must be explicitly set to “true” for dimensional weight to be returned in the xml response.

Boolean

Enumerations=

· true

· false

RateV4Request / Package /TrackingRetentionPeriod

Optional

Used to determine period of Retention for tracking data

String

minOccurs=0

maxOccurs=1

RateV4Request / Package / SortationLevel

Conditionally Required

Sortation	Description
3D	3-Digit
5D	5-Digit
BAS	Basic
CR	Carrier Route
MIX	Mixed NDC
NDC	NDC
NONE	None
PST	Presort
SCF	SCG
TBE	EMM Tray Box
TBF	Full Tray Box
TBH	Half Tray Box
TBT	Full Tub Tray Box

Note: Required when <Service> = “Parcel Select DE” or “Parcel Select LW”.

Note: <SortationLevel> is not applicable to USPS Connect Local DDU facilities.

Reference https://pe.usps.com/pricechange for additional details.

String

Enumerations=

· 3D

· 5D

· BAS

· CR

· MIX

· NDC

· NONE

· PST

· SCF

· TBE

· TBF

· TBH

· TBT

RateV4Request / Package / DestinationEntryFacilityType

Conditionally Required

Final Distribution Center before delivery to the customer.

Note: Required when <Service> = “Parcel Select DE” or “Parcel Select LW”.

Destination Type	Value
Destination Delivery Unit	DDU
Destination Network Distribution Unit	DNDC
Destination Sectional Center Facility	DSCF

String

Default = NONE

Enumerations=

· DDU

· DNDC

· DCSF

· NONE

RateV4Request / Package /TrackingRetentionPeriod

Optional

Used to determine period of Retention for tracking data.

ServiceID	<TrackingRetentionPeriod>
181	“0.5” (6 Months)
181	“1” (1 Year)
181	“3” (3 Years)
181	“5” (5 Years)
181	“7” (7 Years)
182	“3” (3 Years)
182	“5” (5 Years)
182	“7” (7 Years)
182	“10” (10 Years)

String

minOccurs=0

maxOccurs=1

Enumerations=

· 0.5

· 1

· 3

· 5

· 7

· 10

RateV4Request

Required

(alias)

2.2.1 Sample Request

Request: RateV4

<Service>PRIORITY</Service>

</Package>

</RateV4Request>

Request: RateV4 Military – APO Example:

<Service>Priority</Service>

</Package>

</RateV4Request>

Request: RateV4 Parcel Select DE Example:

<Service>PARCEL SELECT DE</Service>

<Container>VARIABLE</Container>

</SpecialServices>

</Package>

</RateV4Request>

Request: RateV4 Connect Local Example:

<Service>CONNECT LOCAL</Service>

<Size/>

</SpecialServices>

</Package>

</RateV4Request>

2.3 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
RateV4Response	Required		(Group)
RateV4Response / Package	Required repeating up to 25 times		(Group)
RateV4Response / Package / ZipOrigination	Required	Origination ZIP Code from request	String	whiteSpace=collapse length=5 pattern=\d{5}
RateV4Response / Package / ZipDestination	Required	Destination ZIP Code from request	String	whiteSpace=collapse length=5 pattern=\d{5}
RateV4Response / Package / Pounds	Required	Package Weight (Pounds) from request	Integer	maxInclusive=70 minInclusive=0
RateV4Response / Package / Ounces	Required	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
RateV4Response / Package / Container	Optional	Shipping Container (appears where applicable: RateV4Request[Service='ALL' or Service='PRIORITY EXPRESS' or Service='PRIORITY'])	String	whiteSpace=collapse
RateV4Response / Package / Machinable	Optional	Machinable (appears where applicable: RateV4Request[Service='ALL' or Service='FIRST CLASS' or Service=’ Retail Ground’])	String
RateV4Response / Package / Zone	Optional	USPS defined distance codes assigned to each origin and destination ZIP Code pairing for every ZIP Code number in the nation. These distance codes, referred to as zones, are designated as “1 through 9"	String
RateV4Response / Package / Postage	Required 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/>. Refer to Appendix A for all domestic CLASSID values.	Integer
RateV4Response / Package / Postage / MailService	Required	Service Type name	String
RateV4Response / Package / Postage / Rate	Required	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	This sequence consisting of CommitmentDate and Location nodes is mutually exclusive with RateV4Response / Package / Postage / Commitment.	(Group)
RateV4Response / Package / Postage / (Choice) / (sequence) / CommitmentDate	Required	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. For 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	Local cutoff time for drop-off	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / Facility	Required	Facility Name	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / Street	Required	Facility Address	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / City	Required	Facility City	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / State	Required	Facility State	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / Zip	Required	Facility Zip	String
RateV4Response / Package / Postage / (Choice) / Commitment	if used: Required 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	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	Commitment time of day. Only returned for Priority Mail Express Mail variants when "ShipDate" tag is present in the request.	String
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. For 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	Local cutoff time for drop-off	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / Facility	Required	Facility Name	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / Street	Required	Facility Address	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / City	Required	Facility City	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / State	Required	Facility State	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / Zip	Required	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, 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	Returned when RateV4Request[Revision='2']. Special service ID	Integer
RateV4Response / Package / Postage / SpecialServices / SpecialService / ServiceName	Required	Returned when RateV4Request[Revision='2']. Special service name	String
RateV4Response / Package / Postage / SpecialServices / SpecialService / Available	Required	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	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	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	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	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	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 / DimensionalWeightRate	Optional	Dimensional weight retail rate	String
RateV4Response / Package / Postage / DimensionalWeightCommercialRate	Optional	Dimensional weight commercial base rate	String
RateV4Response / Package / Postage / DimensionalWeightCommercialPlusRate	Optional	Dimensional weight commercial plus rate	String
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	Error document (indicates request could not be completed).		See the Error Responses section below.
RateV4Response	Required		(alias)

2.3.1 Sample Response

Response: RateV4:

<FirstClassMailType>LETTER</FirstClassMailType>

<MailService>First-Class Mail® Stamped Letter</MailService>

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

</SpecialService>

<ServiceName>Certified Mail®</ServiceName>

</SpecialService>

<ServiceName>Certified Mail® Restricted Delivery</ServiceName>

</SpecialService>

<ServiceName>Certified Mail® Adult Signature Required</ServiceName>

</SpecialService>

<ServiceName>Certified Mail® Adult Signature Restricted Delivery</ServiceName>

</SpecialService>

<ServiceName>Collect on Delivery</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

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

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceName>Insurance</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceName>Insurance Restricted Delivery</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceName>Registered Mail™</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceName>Registered Mail™ Restricted Delivery</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

</SpecialServices>

</Postage>

</Package>

-<Package ID="2ND">

-<Postage CLASSID="1">

<MailService>Priority Mail 2-Day™</MailService>

-<SpecialServices>

-<SpecialService>

<ServiceName>Adult Signature Required</ServiceName>

</SpecialService>

-<SpecialService>

<ServiceName>Adult Signature Restricted Delivery</ServiceName>

</SpecialService>

-<SpecialService>

<ServiceName>Insurance</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

-<SpecialService>

<ServiceName>Return Receipt</ServiceName>

</SpecialService>

-<SpecialService>

<ServiceName>USPS Tracking™ Electronic</ServiceName>

</SpecialService>

</SpecialServices>

</Postage>

</Package>

-<Package ID="3RD">

-<Postage CLASSID="1">

<MailService>Priority Mail Military™</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="17">

<MailService>Priority Mail Military™ Medium Flat Rate Box</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="28">

<MailService>Priority Mail Military™ Small Flat Rate Box</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="22">

<MailService>Priority Mail Military™ Large Flat Rate Box APO/FPO/DPO</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="16">

<MailService>Priority Mail Military™ Flat Rate Envelope</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

<MailService>Priority Mail Military™ Legal Flat Rate Envelope</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

<MailService>Priority Mail Military™ Padded Flat Rate Envelope</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="38">

<MailService>Priority Mail Military™ Gift Card Flat Rate Envelope</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="42">

<MailService>Priority Mail Military™ Small Flat Rate Envelope</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="40">

<MailService>Priority Mail Military™ Window Flat Rate Envelope</MailService>

<CommitmentName>Military</CommitmentName>

</Postage>

-<Postage CLASSID="6">

<MailService>Media Mail Parcel</MailService>

</Postage>

-<Postage CLASSID="7">

<MailService>Library Mail Parcel</MailService>

</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: RateV4 Military APO Example:

<Container>VARIABLE</Container>

Priority Mail Military™

</MailService>

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

</SpecialService>

<ServiceName>Certified Mail®</ServiceName>

</SpecialService>

Certified Mail® Restricted Delivery

</ServiceName>

</SpecialService>

<ServiceName>Insurance</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>Insurance Restricted Delivery</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>Registered Mail™</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

Registered Mail™ Restricted Delivery

</ServiceName>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>Scan Retention</ServiceName>

<DeclaredValueRequired>false</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>Special Handling - Fragile</ServiceName>

</SpecialService>

<ServiceName>USPS Tracking®</ServiceName>

</SpecialService>

USPS Tracking® Electronic

</ServiceName>

</SpecialService>

</SpecialServices>

</Postage>

A. Securities, currency, or precious metals, including in their raw, unmanufactured state, are prohibited. Official Mail shipments are exempt from this restriction. B. Other than for PMEMS and the exceptions listed below, a customs declaration PS Form 2976 or PS Form 2976-A is required for all items weighing 16 ounces or more, and for all items (regardless of weight) containing potentially dutiable mail contents (e.g., merchandise or goods) addressed to or from this ZIP Code. Other than the exceptions listed below, all PMEMS mailpieces (regardless of mail contents or weight) addressed to or from this ZIP Code must bear a properly completed PS Form 2976-B. The surface area of the address side of the mailpiece must be large enough to contain the applicable customs declaration. The following exceptions apply to known mailers, who for this purpose are defined as follows: B. Business mailers who enter volume mailings through business mail entry units or other bulk mail acceptance locations, pay postage through advance deposit accounts, use permit imprints for postage payment, and submit completed postage statements at the time of entry that certify that the mailpieces contain no dangerous materials that are prohibited by postal regulations. Such business mailers are exempt from providing customs documentation on non-dutiable letters and printed matter. B. All federal, state, and local government agencies whose mailings are regarded as "Official Mail." Such agencies are exempt from providing customs documentation, except for any items addressed to an MPO or DPO to which restriction "B2" applies. C. Cigarettes and other tobacco products, including tobacco leaves, chewing and pipe tobacco, snuff, and cigars are prohibited, including those that are authorized in Publication 52 under PACT. F1. Weapons of any type are prohibited. R. All alcoholic beverages, including those mailable under Publication 52, Part 421, are prohibited. U. Mail addressed to Retirees (Box R) is limited to 16 ounces and up to a 90-day supply of TRICARE medications. This restriction does not apply to mail endorsed "Free Matter for the Blind or Handicapped."

</Restrictions>

</Restriction>

</Package>

</RateV4Response>

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:

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

</Postage>

</Package>

<Error>

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

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

</Error>

</Package>

</RateV4Response>

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
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=IntlRateV2	&XML=(see below)

3.2 Request Descriptions

Tag Name

Occurs

Description

Type

Validation

IntlRateV2Request

Required

API=IntlRateV2

This API returns the current international USPS postage corresponding to the parameters given.

(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

Set this value to “2” to return all currently documented response fields.

For example:

String

IntlRateV2Request / Package

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

NMTOKEN

IntlRateV2Request / Package / Pounds

Required

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

Integer

minInclusive=0

IntlRateV2Request / Package / Ounces

Required

For example:

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

Package type being shipped.

For example: <MailType>Package</MailType>

Note: Airmail M-Bag prices will return for retail pricing when available including when <MailType>=“ALL.” Reference https://pe.usps.com/text/imm/immc2_026.htm for M-Bag pricing details.

Note: When <MailType>= “ALL” is indicated in XML request and a <TrackingRetentionPeriod> value is not specified, the lowest tracking retention period values (i.e., “0.5” (6 months) for ServiceID=“181” and “3” (3 years) for ServiceID=“182”) will be used to return available USPS Tracking Plus extra service options for supported mail services.

String

Default = NONE

Enumerations=

· ALL

· PACKAGE

· POSTCARDS

· ENVELOPE

· LETTER

· LARGEENVELOPE

· FLATRATE

· AIRMAIL MBAG

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

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

For example:

String

Enumerations=

· Y

· N

IntlRateV2Request / Package / GXG / GiftFlag

Required

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

For example:

String

Enumerations=

· Y

· N

IntlRateV2Request / Package / ValueOfContents

Required

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

For example: <ValueOfContents>103.00</ValueOfContents>

String

IntlRateV2Request / Package / Country

Required

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

Optional

Used to specify a container. When package is a roll, integrators should pass <Container>= “ROLL” in XML request. If package is not a roll, integrators should not populate – label response will assume package is not a roll.

Note: When <Container>= “ROLL”, errors will return if dimensions provided in XML request do not meet IMM 251.22 requirements. https://pe.usps.com/text/imm/immc2_021.htm.

String

Enumerations=

· VARIABLE

· RECTANGULAR

· ROLL

IntlRateV2Request / Package / Size

Deprecated

Note: This tag has been deprecated

<Size> tag and any values within the <Size> tag will not result in an error response and will not impact rates that are returned.

String

IntlRateV2Request / Package / Width

Optional

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

Integer

minExclusive=0

IntlRateV2Request / Package / Length

Optional

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

Integer

minExclusive=0

IntlRateV2Request / Package / Height

Optional

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

Integer

minExclusive=0

IntlRateV2Request / Package / Girth

Optional

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

Integer

minExclusive=0

IntlRateV2Request / Package / OriginZip

Optional

Available when 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

Enumerations=

· Y

· N

IntlRateV2Request / Package / CommercialPlusFlag

Optional

Returns commercial plus postage.

For example: <CommercialPlusFlag>Y<CommercialPlusFlag>

String

Enumerations=

· Y

· N

IntlRateV2Request / Package / ExtraServices

Optional

Available when IntlRateV2Request[Revision='2'].

Groups the ExtraService elements.

(Group)

IntlRateV2Request / Package / ExtraServices / ExtraService

Required, repeating up to 6 times

Available when IntlRateV2Request[Revision='2'].Defines extra services in order to determine price and availability of 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 – Priority Mail International	108
Return Receipt	105
Certificate of Mailing	100
Electronic USPS Delivery Confirmation International	109
Scan Retention	181
Scan + Signature Retention	182

Integer

Enumerations=

· 103

· 106

· 108

· 105

· 100

· 109

· 181

· 182

IntlRateV2Request/Package/ AcceptanceDateTime

Optional

Available when IntlRateV2Request[Revision='2'].

Date and Time the package is accepted by USPS. The AcceptanceDateTime tag along with the DestinationPostalCode and OriginZip is used to calculate the GuaranteeAvailability and also GuaranteeAvailability response tag for PMEI services in Kahala countries. ISO 8601 formatted date.

YYYY-MM-DDThh:mm:ss+/-hh:mm

For example, 2014-01-22T14:30:51-06:00

DateTime

IntlRateV2Request/Package/ DestinationPostalCode

Optional

Available when IntlRateV2Request[Revision='2'].

Destination Postal Code

The AcceptanceDateTime tag along with the DestinationPostalCode and OriginZip is used to calculate the GuaranteeAvailability and also GuaranteeAvailability response tag for PMEI services in Kahala countries.

String

IntlRateV2Request/Package/ Content

Optional

Used to describe the contents of the package.

(Group)

IntlRateV2Request/Package/ Content/ContentType

Required if Content supplied.

Contains the enumerated description of the items in the package.

“NonnegotiableDocument” and “Documents” both signify mailable non-negotiable documents and are insured automatically for up to $100, though Insurance will not be returned as an extra service. Additional Insurance cannot be purchased.

Any non-document ContentType values are insured automatically for up to $200 and Insurance will be returned as an explicit extra service in the response. Additional Insurance can be purchased for values $200 and greater.

String

Enumerations=

· CrematedRemains

· NonnegotiableDocum

· Pharmaceuticals

· MedicalSupplies

· Documents

IntlRateV2Request/Package/ Content/ContentDescription

Optional

For future use

String

IntlRateV2Request / Package /TrackingRetentionPeriod

Optional

Used to determine period of Retention for tracking data.

Note: When <ExtraService>= “181” or “182” provided in XML request, a valid <TrackingRetentionPeriod> (see table below) is required otherwise a new error will return to indicate the specified ServiceID and Tracking Retention period combination is invalid.

ServiceID	<TrackingRetentionPeriod>
181	“0.5” (6 Months)
181	“1” (1 Year)
181	“3” (3 Years)
181	“5” (5 Years)
181	“7” (7 Years)
182	“3” (3 Years)
182	“5” (5 Years)
182	“7” (7 Years)

String

minOccurs=0

maxOccurs=1

Enumerations=

· 0.5

· 1

· 3

· 5

· 7

IntlRateV2Request

Required once

(alias)

3.2.1 Sample Requests

Request: IntlRateV2:

<MailType>Package</MailType>

<GXG>

</GXG>

<Country>Australia</Country>

<Container>VARIABLE</Container>

</Package>

<MailType>Envelope</MailType>

<Country>Argentina</Country>

</ExtraServices>

</Package>

</IntlRateV2Request>

3.3 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
IntlRateV2Response	Required	Opening document tag.	(Group)
IntlRateV2Response / Package	Required repeating up to 25 times	Corresponds to each "Package" node in the request. Each "Package" node will contain either an "Error" node or the rate results.	(Group)
IntlRateV2Response / Package / ID	required	Package Identification Number (matches IntlRateV2Request/Package/ID)	NMTOKEN
IntlRateV2Response / Package / Prohibitions	Required	Prohibitions	String
IntlRateV2Response / Package / Restrictions	Required	Restrictions	String
IntlRateV2Response / Package / Observations	Required	Observations	String
IntlRateV2Response / Package / CustomsForms	Required	Customs Forms	String
IntlRateV2Response / Package / ExpressMail	Required	Express Mail	String
IntlRateV2Response / Package / AreasServed	Required	Areas Served	String
IntlRateV2Response / Package / AdditionalRestrictions	Required	Additional restrictions on items being shipped to destination country.	String
IntlRateV2Response / Package / Content	Optional	Echoes the Content from the request. If the Content request is not populated on the request, this tag will not be returned.	(Group)
IntlRateV2Response / Package / Content / ContentType	Optional	Echoes the ContentType from the request. If the Content request is not populated on the request, this tag will not be returned.	String
IntlRateV2Response / Package / Content / ContentDescription	Optional	Echoes the ContentDescription from the request. If the Content request is not populated on the request, this tag will not be returned.	String
IntlRateV2Response / Package / Service	Required repeating up to unbounded times	"Service" tag contains a nested rate and service name.	(Group)
IntlRateV2Response / Package / Service / ID	required	An Integer reflective of the <SvcDescription/>. Refer to Appendix B for all international Service ID values.	Integer	minInclusive=0
IntlRateV2Response / Package / Service / Pounds	Required	Weight of package (pounds)	Integer
IntlRateV2Response / Package / Service / Ounces	Required	Weight of package (ounces)	Decimal
IntlRateV2Response / Package / Service / Machinable	Optional	If specified in request this is echoed back if relevant to computed postage.	String
IntlRateV2Response / Package / Service / MailType	Required	If specified in request this is echoed back if relevant to computed postage.	String
IntlRateV2Response / Package / Service / GXG	Optional	If specified in request this is echoed back if relevant to computed postage.	(Group)
IntlRateV2Response / Package / Service / GXG / POBoxFlag	Required	If specified in request this is echoed back if relevant to computed postage.	String
IntlRateV2Response / Package / Service / GXG / GiftFlag	Required	If specified in request this is echoed back if relevant to computed postage.	String
IntlRateV2Response / Package / Service / Container	Required	If specified in request this is echoed back if relevant to computed postage.	String
IntlRateV2Response / Package / Service / Width	Optional	Value must be numeric. Units are inches.	Integer
IntlRateV2Response / Package / Service / Length	Optional	Value must be numeric. Units are inches.	Integer
IntlRateV2Response / Package / Service / Height	Optional	Value must be numeric. Units are inches.	Integer
IntlRateV2Response / Package / Service / Girth	Optional	Value must be numeric. Units are inches.	Integer
IntlRateV2Response / Package / Service / Country	Required	Destination Country	String
IntlRateV2Response / Package / Service / Postage	Required	Postage Rate Charged	Decimal
IntlRateV2Response / Package / Service / CommercialPostage	Optional	Commercial Base Rate. Returned if specified in request.	Decimal
IntlRateV2Response / Package / Service / CommercialPlusPostage	Optional	Commercial Plus Rate. Returned if specified in request.	Decimal
IntlRateV2Response / Package / Service / ExtraServices	Required	Groups the Extra Service elements.	(Group)
IntlRateV2Response / Package / Service / ExtraServices / ExtraService	Optional, repeating up to unbounded times	“ExtraService” contains nested service name, availability, and pricing. When IntlRateV2Request[Revision<'2'], the only service returned is Insurance.	(Group)
IntlRateV2Response / Package / Service / ExtraServices / ExtraService / ServiceID	Required	Extra service ID	Integer
IntlRateV2Response / Package / Service / ExtraServices / ExtraService / ServiceName	Required	Extra service name	String
IntlRateV2Response / Package / Service / ExtraServices / ExtraService / Available	Required	Availability of extra service. Availability may change depending on extra services passed (selected) in request.	Boolean
IntlRateV2Response / Package / Service / ExtraServices / ExtraService / OnlineAvailable	Optional	Availability of online pricing for extra service. Availability may change depending on extra services passed (selected) in request. Returns when IntlRateV2Request[Revision='2'] and IntlRateV2Request[CommercialPrice=’Y'].	Boolean
IntlRateV2Response / Package / Service / ExtraServices / ExtraService / Price	Required	Extra service pricing. Pricing may change depending on extra services passed in request. When IntlRateV2Request[Revision<'2'], the insurance fee is fully calculated.	Decimal
IntlRateV2Response / Package / Service / ExtraServices / ExtraService OnlinePrice	Optional	Online extra service pricing. Pricing may change depending on extra services passed in request. Returns when IntlRateV2Request[Revision='2'] and IntlRateV2Request[CommercialPrice=’Y'].	Decimal
IntlRateV2Response / Package / Service / ExtraServices / ExtraService DeclaredValueRequired	Optional	Indicates if package value is required to calculate extra service rate. Returns when IntlRateV2Request[Revision='2'].	Boolean
IntlRateV2Response / Package / Service / ValueOfContents	Optional	This echoes back the value provided in the request. This value is used to calculate the insurance fee (ServiceID=1 under Extra Services) or the Insurance Comment explaining why Insurance Fee is not given.	Decimal	pattern=\d+\.\d\d
IntlRateV2Response / Package / Service / InsComment	Optional	Returned when IntlRateV2Request[Revision<'2'] only. Explains why no insurance fee is returned, one of three reasons: SERVICE means insurance is not available for this service; DESTINATION means that insurance is not available to the given country via this service; INSURED VALUE means insurance is available for the country and service, but not for the given value.	String	Enumerations= · INSURED VALUE · SERVICE · DESTINATION
IntlRateV2Response / Package / Service / ParcelIndemnityCoverage	Optional	Deprecated. Tag will no longer be returned. Automatic indemnity coverage has been replaced by the baked-in Insurance amounts of $200 or $100.	Decimal	pattern=\d+\.\d\d
IntlRateV2Response / Package / Service / SvcCommitments	Required	Service Commitments	String
IntlRateV2Response / Package / Service / SvcDescription	Required	Service Description	String
IntlRateV2Response / Package / Service / MaxDimensions	Required	Maximum Dimensions of Package Allowed	String
IntlRateV2Response / Package / Service / MaxWeight	Required	Maximum Weight of Package Allowed	Integer
IntlRateV2Response / Package / Service / GuaranteeAvailability	Optional once	If the Revision tag >= 2 in the request, the service type is one of the following: Priority Express Mail International, PMEI Flat Rate Envelope, PMEI Legal Flat Rate Envelope, and PMEI Padded Flat Rate Envelope, and the country is a Kahala country, the GuaranteeAvailability tag will display the estimated scheduled delivery date. If not, the tag will contain the estimated scheduled delivery days. The AcceptanceDateTime tag along with the DestinationPostalCode and OriginZip is used to calculate the GuaranteeAvailability and also GuaranteeAvailability response tag for PMEI services in Kahala countries. If an estimated scheduled delivery date is available, the format will be MM/DD/YYYY e.g., 01/29/2014. If an estimated scheduled delivery date is not available, the format will be a String. e.g., 3 - 5 business days to many major markets	String
IntlRateV2Response / Package / Service / GXGLocations	Optional	Mailing locations for GXG packages. Based on OriginZip sent in request.	(Group)
IntlRateV2Response / Package / Service / GXGLocations / PostOffice	Optional	Individual Post Office information for mailing GXG packages.	(Group)
IntlRateV2Response / Package / Service / GXGLocations / PostOffice / Name	Required	Name of Post Office.	String
IntlRateV2Response / Package / Service / GXGLocations / PostOffice / Address	Required	Street Address of Post Office.	String
IntlRateV2Response / Package / Service / GXGLocations / PostOffice / City	Required	City in which Post Office is located.	String
IntlRateV2Response / Package / Service / GXGLocations / PostOffice / State	Required	State in which Post Office is located.	String
IntlRateV2Response / Package / Service / GXGLocations / PostOffice / ZipCode	Required	Zip Code of Post Office.	String
IntlRateV2Response / Package / Service / GXGLocations / PostOffice / RetailGXGCutOffTime	Required	Retail/GXG cut off time at location.	String
IntlRateV2Response / Package / Service / GXGLocations / PostOffice / SaturdayCutOffTime	Required	Saturday cut off time at location.	String
IntlRateV2Response	Required		(alias)

3.3.1 Sample Response

Response: IntlRateV2:

<Prohibitions>Coins; bank notes; currency notes (paper money); securities of any kind payable to bearer; traveler's checks; platinum, gold, and silver (except for jewelry items meeting the requirement in "Restrictions" below); precious stones (except when contained in jewelry items meeting the requirement in "Restrictions" below); and other valuable articles are prohibited. Fruit cartons (used or new). Goods bearing the name "Anzac." Goods produced wholly or partly in prisons or by convict labor. Most food, plant, and animal products, including the use of products such as straw and other plant material as packing materials. Perishable infectious biological substances. Radioactive materials. Registered philatelic articles with fictitious addresses. Seditious literature. Silencers for firearms. Used bedding.</Prohibitions>

<Restrictions>Jewelry is permitted only when sent as an insured parcel using Priority Mail International service. In addition, Australian Customs regulations prohibit importation of jewelry that is made with ivory or from endangered species, such as snake, elephant, or crocodile, that does not have an accompanying Import/Export Permit in relation to the Convention on International Trade in Endangered Species of Wild Fauna and Flora (CITES). Meat and other animal products; powdered or concentrated milk; and other dairy products requires permission to import from the Australian quarantine authorities. Permission of the Australian Director-General of Health is required to import medicines.</Restrictions>

<Observations>Duty may be levied on catalogs, price lists, circulars, and all advertising introduced into Australia through the mail, regardless of the class of mail used.</Observations>

<CustomsForms>First-Class Mail International items and Priority Mail International Flat Rate Envelopes and Small Flat Rate Boxes: PS Form 2976 (see 123.61) Priority Mail International parcels: PS Form 2976-A inside 2976-E (envelope)</CustomsForms>

<ExpressMail>Country Code: AU Reciprocal Service Name: Express Post Required Customs Form/Endorsement 1. Business and commercial papers. No form required. Endorse item clearly next to mailing label as BUSINESS PAPERS. 2. Merchandise samples without commercial value microfilm, microfiche, and computer data. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). 3. Merchandise and all articles subject to customs duty. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Note: 1. Coins; banknotes; currency notes, including paper money; securities of any kind payable to bearer; traveler's checks; platinum, gold, and silver; precious stones; jewelry; watches; and other valuable articles are prohibited in Priority Mail Express International shipments to Australia. 2. Priority Mail Express International With Guarantee service - which offers a date-certain, postage-refund guarantee - is available to Australia. Areas Served: All except Lord Howe Island and the Australian Antarctic territories.</ExpressMail>

<AreasServed>Please reference Express Mail for Areas Served.</AreasServed>

<AdditionalRestrictions>No Additional Restrictions Data found.</AdditionalRestrictions>

-<Service ID="12">

<MailType>Package</MailType>

<Container>VARIABLE</Container>

<Country>AUSTRALIA</Country>

<ServiceName>Insurance</ServiceName>

</ExtraService>

</ExtraServices>

<SvcCommitments>1 - 3 business days to many major markets</SvcCommitments>

<SvcDescription>USPS GXG™ Envelopes</SvcDescription>

<MaxDimensions>USPS-Produced regular size cardboard envelope (12-1/2" x 9-1/2"), the legal-sized cardboard envelope (15" x 9-1/2") and the GXG Tyvek envelope (15-1/2" x 12-1/2")</MaxDimensions>

<Name>WILKES BARRE P&DC</Name>

<City>WILKES BARRE</City>

</PostOffice>

</GXGLocations>

</Service>

<MailType>Package</MailType>

<Container>VARIABLE</Container>

<Country>AUSTRALIA</Country>

<ServiceName>Insurance</ServiceName>

</ExtraService>

</ExtraServices>

<SvcCommitments>Wed, Mar 30, 2016 Guaranteed</SvcCommitments>

<SvcDescription>Priority Mail Express International™</SvcDescription>

<MaxDimensions>Max. length 36", max. length plus girth 97"</MaxDimensions>

</Service>

<MailType>Package</MailType>

<Container>VARIABLE</Container>

<Country>AUSTRALIA</Country>

<ServiceName>Insurance</ServiceName>

</ExtraService>

<ServiceName>Certificate of Mailing</ServiceName>

</ExtraService>

-<ExtraService>

<ServiceName>Return Receipt</ServiceName>

</ExtraService>

</ExtraServices>

<SvcCommitments>6 - 10 business days to many major markets</SvcCommitments>

<SvcDescription>Priority Mail International®</SvcDescription>

<MaxDimensions>Max. length 42", max. length plus girth 97"</MaxDimensions>

</Service>

</Package>

-<Package ID="2ND">

<Prohibitions>Articles made of tortoise-shell, mother of pearl, ivory, bone meerschaum and amber (succin), natural or reconstructed, worked jade and mineral substances similar to jade. Canned vegetables, fish, plums and nuts. Funeral urns. Household articles made of tin. Perishable infectious biological substances. Perishable noninfectious biological substances. Pictures and printed matter of pornographic or immoral nature, or which tend to incite crime or juvenile delinquency. Radioactive materials. Saccharine in tablets or packets. Used clothing, accessories, blankets, linen, textile furnishings, footwear and headwear. Watches and clocks.</Prohibitions>

<Restrictions>Articles of gold or platinum, jewelry and precious stones must be licensed by the Algerian Ministry of Finance. Coins, banknotes, negotiable securities, checks and other instruments of payment, may only be imported by the Central Bank of Algeria or approved intermediary banks. Medicines for human or veterinary use, dietetic products, serums, vaccines and similar produce; medical, surgical, and dental instruments and prostheses require prior approval from the Ministry of Public Health and subject to the visa of the Central Algerian Pharmacy.</Restrictions>

<Observations>Import permits or licenses are required for many types of goods; therefore, the sender should ascertain from the addressee before mailing whether the necessary documents are held.</Observations>

<ExpressMail>Country Code: DZ Reciprocal Service Name: EMS Required Customs Form/Endorsement 1. Correspondence and business papers. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Endorse item clearly next to mailing label as BUSINESS PAPERS. 2. Merchandise samples without commercial value and not subject to customs duty. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). 3. Merchandise and all articles subject to customs duty. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Include a commercial invoice in each item. Note: Coins; banknotes; currency notes, including paper money; securities of any kind payable to bearer; traveler's checks; platinum, gold, and silver; precious stones; jewelry; watches; and other valuable articles are prohibited in Priority Mail Express International shipments. All items prohibited in regular international mail are also prohibited in Priority Mail Express International to Algeria. Areas Served: See the following list for areas served. Adrar RP Ain Benian Ain Defla RP Ain Smara Ain Temouchent RP Alger aeroport Priority Mail Express International Alger Didouche Mourad Alger RP Algiers and suburbs, as well as all main towns of Wilaya (department) Annaba aeroport Priority Mail Express International Annaba Amirouche Annaba-Menadia Annaba RP Arzew Batna RP Bechar RP Bejaia RP Berrahal (Annaba) Bilda RP Biskra RP Bordj Bou Arreridj RP Bordj Bounaam Bouira RP Bou Ismail Boumerdes RP Cheraga Chlef RP Constantine aeroport Priority Mail Express International Constentine Daksi Constantine RP Constantine Sidi Mabrouk Dar El Beida Didouche Mourad Djelfa RP Douera El Attaf El Bayadh RP El-Biar El Hadjar (Annaba) El Harrach El Khroub El Khroub Djeffal Amar El Madania El Oued RP El Tarf RP Fouka Ghardaia RP Guelma RP Haasi Messaoud Hadjout Haidra Hamma Bouziane Hussein-Dey In Amenas Jijel RP Kais Khemisti Khenchela RP Kolea Kouba Laghouat RP Lardjen Layoune Mascara RP Medea RP Mila RP Mostaganem RP MSila RP Naama RP Oran Oran aeroport Priority Mail Express International Oum El Bouaghi RP Relizane RP Rouiba Saida RP Setif RP Sidi Bel Abbes-Sidi Yacine Skikda RP Souk Ahras RP Staoueli Tamanrasset RP Tebessa RP Theniet El Had Tiaret RP Tindouf RP Tipaza RP Tissemsilt RP Tizi Ouzou RP Tlemcen RP Zeralda Zighout Youcef</ExpressMail>

<AreasServed>Please reference Express Mail for Areas Served.</AreasServed>

<AdditionalRestrictions>No Additional Restrictions Data found.</AdditionalRestrictions>

<MailType>Envelope</MailType>

<Country>ALGERIA</Country>

-<ExtraService>

<ServiceName>Certificate of Mailing</ServiceName>

</ExtraService>

</ExtraServices>

<InsComment>SERVICE</InsComment>

<SvcCommitments>Varies by destination</SvcCommitments>

<SvcDescription>First-Class Mail® International Letter</SvcDescription>

<MaxDimensions>Max. length 11-1/2", height 6-1/8" or thickness 1/4"</MaxDimensions>

</Service>

</Package>

</IntlRateV2Response>

4.0 Error Responses

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

<Prohibitions>Sample</Prohibitions>

<Restrictions>Sample</Restrictions>

<Observations>Sample</Observations>

<CustomsForms>Sample</CustomsForms>

<ExpressMail>Sample</ExpressMail>

<AreasServed>Sample</AreasServed>

<AdditionalRestrictions>Sample</AdditionalRestrictions>

<MailType>Postcard</MailType>

<Country>ALBANIA</Country>

<InsComment>SERVICE</InsComment>

<SvcCommitments>Varies by destination</SvcCommitments>

<SvcDescription>First-Class Mail&lt;sup&gt;&#174;&lt;/sup&gt; International Postcard</SvcDescription>

<MaxDimensions>Maximum size 6" length x 4-1/4" height</MaxDimensions>

</Service>

</Package>

<Error>

<Source>IntlPostage;clsIntlPostage.CalcAllPostageDimensionsXML;IntlRateV2.ProcessRequest</Source>

<Description>Invalid International Mail Type</Description>

</Error>

</Package>

</IntlRateV2Response>

5.0 Appendix A – RateV4 CLASSID values

CLASSID	Mail Services
0	First-Class Mail; Large Envelope
0	First-Class Mail< Letter
0	First-Class Mail< Parcel
0	First-Class Mail; Postcards
1	Priority Mail
2	Priority Mail Express; Hold For Pickup
3	Priority Mail Express
4	Standard Post
6	Media Mail
7	Library Mail
13	Priority Mail Express; Flat Rate Envelope
15	First-Class Mail; Large Postcards
16	Priority Mail; Flat Rate Envelope
17	Priority Mail; Medium Flat Rate Box
22	Priority Mail; Large Flat Rate Box
23	Priority Mail Express; Sunday/Holiday Delivery
25	Priority Mail Express; Sunday/Holiday Delivery Flat Rate Envelope
27	Priority Mail Express; Flat Rate Envelope Hold For Pickup
28	Priority Mail; Small Flat Rate Box
29	Priority Mail; Padded Flat Rate Envelope
30	Priority Mail Express; Legal Flat Rate Envelope
31	Priority Mail Express; Legal Flat Rate Envelope Hold For Pickup
32	Priority Mail Express; Sunday/Holiday Delivery Legal Flat Rate Envelope
33	Priority Mail; Hold For Pickup
34	Priority Mail; Large Flat Rate Box Hold For Pickup
35	Priority Mail; Medium Flat Rate Box Hold For Pickup
36	Priority Mail; Small Flat Rate Box Hold For Pickup
37	Priority Mail; Flat Rate Envelope Hold For Pickup
38	Priority Mail; Gift Card Flat Rate Envelope
39	Priority Mail; Gift Card Flat Rate Envelope Hold For Pickup
40	Priority Mail; Window Flat Rate Envelope
41	Priority Mail; Window Flat Rate Envelope Hold For Pickup
42	Priority Mail; Small Flat Rate Envelope
43	Priority Mail; Small Flat Rate Envelope Hold For Pickup
44	Priority Mail; Legal Flat Rate Envelope
45	Priority Mail; Legal Flat Rate Envelope Hold For Pickup
46	Priority Mail; Padded Flat Rate Envelope Hold For Pickup
47	Priority Mail; Regional Rate Box A
48	Priority Mail; Regional Rate Box A Hold For Pickup
49	Priority Mail; Regional Rate Box B
50	Priority Mail; Regional Rate Box B Hold For Pickup
53	First-Class; Package Service Hold For Pickup
55	Priority Mail Express; Flat Rate Boxes
56	Priority Mail Express; Flat Rate Boxes Hold For Pickup
57	Priority Mail Express; Sunday/Holiday Delivery Flat Rate Boxes
58	Priority Mail; Regional Rate Box C
59	Priority Mail; Regional Rate Box C Hold For Pickup
61	First-Class; Package Service
62	Priority Mail Express; Padded Flat Rate Envelope
63	Priority Mail Express; Padded Flat Rate Envelope Hold For Pickup
64	Priority Mail Express; Sunday/Holiday Delivery Padded Flat Rate Envelope
88	USPS Connect Local
89	USPS Connect Local Flat Rate Bag - Small
90	USPS Connect Local Flat Rate Bag - Large
91	USPS Connect Local Flat Rate Box

6.0 Appendix B – IntlRateV2 Service ID Values

CLASSID	Mail Services
1	Priority Mail Express International
2	Priority Mail International
4	Global Express Guaranteed; (GXG)**
5	Global Express Guaranteed; Document
6	Global Express Guarantee; Non-Document Rectangular
7	Global Express Guaranteed; Non-Document Non-Rectangular
8	Priority Mail International; Flat Rate Envelope**
9	Priority Mail International; Medium Flat Rate Box
10	Priority Mail Express International; Flat Rate Envelope
11	Priority Mail International; Large Flat Rate Box
12	USPS GXG; Envelopes**
13	First-Class Mail; International Letter**
14	First-Class Mail; International Large Envelope**
15	First-Class Package International Service**
16	Priority Mail International; Small Flat Rate Box**
17	Priority Mail Express International; Legal Flat Rate Envelope
18	Priority Mail International; Gift Card Flat Rate Envelope**
19	Priority Mail International; Window Flat Rate Envelope**
20	Priority Mail International; Small Flat Rate Envelope**
1	Priority Mail Express International
2	Priority Mail International
4	Global Express Guaranteed; (GXG)**
5	Global Express Guaranteed; Document
6	Global Express Guarantee; Non-Document Rectangular
7	Global Express Guaranteed; Non-Document Non-Rectangular
8	Priority Mail International; Flat Rate Envelope**
9	Priority Mail International; Medium Flat Rate Box
10	Priority Mail Express International; Flat Rate Envelope
11	Priority Mail International; Large Flat Rate Box
12	USPS GXG; Envelopes**
13	First-Class Mail; International Letter**
14	First-Class Mail; International Large Envelope**
15	First-Class Package International Service**
16	Priority Mail International; Small Flat Rate Box**
17	Priority Mail Express International; Legal Flat Rate Envelope
18	Priority Mail International; Gift Card Flat Rate Envelope**
19	Priority Mail International; Window Flat Rate Envelope**
20	Priority Mail International; Small Flat Rate Envelope**
28	Airmail M-Bag