1.0 Introduction

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

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

Descripción

Tipo

Validation

RateV4Request

Obligatorio

API=RateV4

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

(Group)

RateV4Request / USERID

Obligatorio

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

Por Ejemplo: USERID="XXXXXXX"

NMTOKEN

RateV4Request / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password.

Por Ejemplo: PASSWORD="XXXXXXX"

NMTOKEN

RateV4Request / Revision

Optional

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

Por ejemplo:

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

Obligatorio

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

Por ejemplo:

<Service>PRIORITY MAIL EXPRESS</Service>

Nota: 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.

Nota: For users that want to return all eligible products in a single RateV4 API call, please see details below regarding “ALL” calls:

<Service>	Descripción
TODOS	When <Service>=“ALL”, all eligible retail products will return in the API response.
EN LÍNEA	When <Service>=“ONLINE”, all eligible retail and commercial base/commercial products will return in the API response. Cubic products will return when eligible.
PLUS	When <Service>=“PLUS”, all eligible retail, commercial base/commercial, and commercial plus products will return in the API response. Cubic products will return when eligible.

String

whiteSpace=collapse
Enumerations=

· ALL

· ONLINE

· PLUS

· PRIORITY

· PRIORITY COMMERCIAL

· PRIORITY MAIL CUBIC

· PRIORITY MAIL RETURNS

· PRIORITY MAIL CUBIC RETURNS

· FIRST CLASS

· FIRST CLASS COMMERCIAL

· PRIORITY MAIL EXPRESS

· PRIORITY MAIL EXPRESS COMMERCIAL

· PRIORITY MAIL EXPRESS RETURNS

· GROUND ADVANTAGE

· GROUND ADVANTAGE COMMERCIAL

· GROUND ADVANTAGE CUBIC

· GROUND ADVANTAGE RETURNS

· PARCEL SELECT DE

· PARCEL SELECT LW

· MEDIA

· LIBRARY

· BPM

· CONNECT LOCAL

RateV4Request / Package / Service DelOpt

Optional

This attribute specifies the service delivery option beyond normal/standard delivery. When the service delivery option attribute is indicated, the results returned will satisfy both the mail class and delivery option indicated.

Por ejemplo:

<Service DelOpt="HAZMAT">PRIORITY</Service>

OPCIÓN DE ENTREGA	Descripción
HAZMAT	Materiales peligrosos
PARCELLOCKER	Parcel Locker Delivery
HFP	Hold for Pickup (Retener para recogida)
SUNHOL	Entrega en domingo/Día Feriado;
ESTÁNDAR	Normal Delivery
DESCONOCIDO	Default - will result in current <Service> enumerations being used to determine response.

String

Default=UNKNOWN

Enumerations=

· HAZMAT

· PARCELLOCKER

· HFP

· SUNHOL

· STANDARD

· UNKNOWN

RateV4Request / Package / FirstClassMailType

Optional

The <FirstClassMailType> tag is returned only if the <ServiceType> submitted is “First Class”

<FirstClassMailType>LETTER</FirstClassMailType>

Nota: Flats are also known as Large Envelopes

String

whiteSpace=collapse

Enumerations=

· LETTER

· FLAT

· POSTCARD

· LARGE POSTCARD

RateV4Request / Package / ZipOrigination

Obligatorio

ZIP code must be valid.

Por ejemplo: <ZipOrigination>20770</ZipOrigination>

String

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

RateV4Request / Package / ZipDestination

Obligatorio

ZIP code must be valid.

Por ejemplo: <ZipDestination>54324</ZipDestination>

String

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

RateV4Request / Package / Pounds

Obligatorio

Value must be numeric.

Package weight cannot exceed 70 pounds.

Por ejemplo:

String

maxInclusive=70
minInclusive=0

RateV4Request / Package / Ounces

Obligatorio

Value must be numeric.

Package weight cannot exceed 70 pounds (1120 ounces).

Por ejemplo:

String

maxInclusive=1120.0
minInclusive=0.0

RateV4Request / Package / Container

Obligatorio

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

Nota: When <Service>=“PRIORITY MAIL CUBIC”, “PRIORITY MAIL CUBIC RETURNS” or “GROUND ADVANTAGE CUBIC”, the only valid containers are “CUBIC PARCELS” or “CUBIC SOFT PACK”. It is recommended to pass the largest Cubic dimension as “Length” in <Length> request tag and the second largest dimension as “Width” in <Width> request tag.

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

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

· CUBIC PARCELS

· CUBIC SOFT PACK

· SM FLAT RATE BAG

· LG FLAT RATE BAG

· FLAT RATE BOX

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.

Por ejemplo:

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.

Por ejemplo: <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
Seguro	100
Insurance – Priority Mail Express	101
Acuse de recibo	102
Collect on Delivery (Cobro a la entrega)	103
Certificado de Envío (Formulario 3665)	104
Certified Mail (Correo certificado)	105
USPS Tracking	106
Signature Confirmation	108
Registered Mail (Correo registrado	109
Acuse de recibo electrónico	110
Registered mail COD collection Charge	112
Return Receipt – Priority Mail Express	118
Requisito de firma por parte de un adulto	119
Entrega restringida con firma de un adulto	120
Insurance – Priority Mail	125
USPS Tracking Electronic	155
Signature Confirmation Electronic	156
Certificado de Envío (Formulario 3817)	160
Entrega Restringida de Certified Mail	170
Certified Mail con Requisito de Firma por Parte de un Adulto	171
Entrega restringida de Certified Mail con Requisito de Firma por Parte de un Adulto	172
Signature Confirm. Restrict. Entrega	173
Signature Confirmation Electronic Restricted Delivery	174
Entrega Restringida de Collect on Delivery	175
Entrega Restringida de Registered Mail	176
Entrega Restringida con Seguro	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
Servicio de Entrega de Etiquetas de USPS	183
USPS Connect Sunday Delivery (Availability depends on Destination ZIP Code)	447
HAZMAT Services	ServiceID
Air Eligible Ethanol Package	810
Class 1 – Toy Propellant/Safety Fuse Package	811
Class 3 – Flammable Liquid Package	812
Class 7 – Radioactive Materials Package	813
Class 8 – Corrosive Materials Package	814
Class 8 – Nonspillable Wet Battery Package	815
Class 9 – Lithium Battery Marked – Ground Only Package	816
Class 9 – Lithium Battery – Returns Package	817
Class 9 – Lithium batteries, marked package	818
Class 9 – Dry Ice Package	819
Class 9 – Lithium batteries, unmarked package	820
Class 9 – Magnetized Materials Package	821
Division 4.1 – Flammable Solids or Safety Matches Package	822
Division 5.1 – Oxidizers Package	823
Division 5.2 – Organic Peroxides Package	824
Division 6.1 – Toxic Materials Package	825
Division 6.2 – Infectious Substances Package	826
Excepted Quantity Provision Package	827
Ground Only Hazardous Materials	828
ID8000 Consumer Commodity Package	829
Lighters Package	830
LTD QTY Ground Package	831
Small Quantity Provision Package	832

Por ejemplo:

</SpecialServices>

Nota: When <SpecialService>= “125” and <Value> is less than or equal to $100, the insurance price returned will be zero (“$0.00”) to reflect baked-in insurance. If <Value> is greater than $100, the insurance price returned will reflect an extra cost since baked-in insurance was exceeded.

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

· 447

HAZMAT Services:

· 810

· 811

· 812

· 813

· 814

· 815

· 816

· 817

· 818

· 819

· 820

· 821

· 822

· 823

· 824

· 825

· 826

· 827

· 828

· 829

· 830

· 831

· 832

RateV4Request / Package / Content

Optional

Available when RateV4Request[Revision='2'].

Groups the ContentType and ContentDescription elements.

Grupo

RateV4Request / Package / Content / ContentType

Optional

Available when RateV4Request [Revision=’2’].

Defines the type of content of the package.

String

Enumerations=

· CREMATEDREMAINS

· 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=“GROUND ADVANTAGE’’]

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']

Por ejemplo:

<SortBy>PACKAGE</SortBy>

String

Enumerations=

· LETTER

· LARGEENVELOPE

· PACKAGE

· FLATRATE

RateV4Request / Package / Machinable

Optional

Machinable parcels are defined as parcels less than or equal to 15”x18”x22” inches and less than or equal 25 pounds. Any parcel that exceeds either threshold (dimensions or weight) will be considered nonmachinable.

Nota: The API will validate provided dimensions and/or weight to determine machinability. In this case the <Machinable> tag will be ignored. If these are not provided, then the <Machinable> tag will be used to designate if shipment is Machinable (true) or Nonmachinable (false).

Por ejemplo:

<Machinable>verdadero</Machinable>

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.

Por ejemplo:

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. If <ShipDate> value is not provided, the current date will be used for delivery date calculations.

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

Por ejemplo:

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 ShipDate Commitment data elements.

EMSH stands for Express Mail Sunday/Holiday and will return that response structure when used.

When HFP (Hold For Pickup) is used, an additional <CommitmentTime> element is returned and the Hold For Pickup response structure is used.

Por ejemplo:

String

Default=EMSH

Enumerations=

· EMSH

· HFP

RateV4Request / Package / SortationLevel

Optional

Clasificación	Descripción
3D	3-Digit
5D	5-Digit
BAS	Basic
CR	Ruta del cartero
MIX	Mixed NDC
NDC	NDC
NINGUNA	Ninguna
PST	Preclasificación
SCF	SCG
TBE	EMM Tray Box
TBF	Full Tray Box
TBH	Half Tray Box
TBT	Full Tub Tray Box

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

String

Enumerations=

· 3D

· 5D

· BAS

· CR

· MIX

· NDC

· NONE

· PST

· SCF

· TBE

· TBF

· TBT

· TBH

RateV4Request / Package / DestinationEntryFacilityType

Conditionally Required

Drop Off location for destination entry products.

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

Destination Type	Valor
Destination Delivery Unit	DDU
Destination Network Distribution Unit	DNDC
Destination Sectional Center Facility	DSCF
Destination Hub	DHUB

String

Default = NONE

Enumerations=

· DDU

· DNDC

· DCSF

· DHUB

· NONE

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.

ServiceID	<TrackingRetentionPeriod>
181	“0.5” (6 Months)
181	“1” (1 Year)
181	“3” (3 Years)
181	“5” (5 Years)
181	“7” (7 Years)
181	“10” (10 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 / Package / ReturnFees

Optional

This tag must be set to “true” for <Fees> to be returned. This tag is used so customers can see what fees apply to their postage.

Boolean

Default=false

Enumerations=

· true

· false

RateV4Request / Package / ReturnHSCodeReqd

Optional

Include <ReturnHSCodeReqd>=“Y” (Yes) to return <HSCodeReqd> indicator in response to identify which APO/FPO/DPO destinations will require valid Harmonization Code and Content/Item descriptions due to international shipping regulatory mandates.

Per international shipping regulatory mandates, shipments to European Union (EU) countries are required to contain a valid Harmonization Code and Content/Item description. Harmonization Code (i.e., HS Tariff Number) must be based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization. To learn more about providing acceptable item descriptions, view the chart below or read the EU’s guidance on acceptable terms at Guidance on Acceptable and Unacceptable Terms for the Description of Goods.

Default=N

Enumerations=

· Y

· N

RateV4Request

Obligatorio

(alias)

2.2.1 Sample Request

Request: RateV4

<Service>PRIORITY</Service>

<Machinable>VERDADERO</Machinable>

</Package>

</RateV4Request>

Request: RateV4 Military – APO Example:

<Service>priority mail</Service>

<Machinable>Verdadero</Machinable>

</Package>

</RateV4Request>

Request: RateV4 Parcel Select DE Example:

<Service>PARCEL SELECT DE</Service>

<Container>VARIABLE</Container>

</SpecialServices>

<Machinable>verdadero</Machinable>

</Package>

</RateV4Request>

Request: RateV4 Connect Local Example:

<Service>CONNECT LOCAL</Service>

<Container>CAJA FLAT RATE (TARIFA FIJA)</Container>

</SpecialServices>

<Machinable>Verdadero</Machinable>

</Package>

</RateV4Request>

Request: RateV4 – Non Standard Fee Example

<Service>TODOS</Service>

<Container>Variable</Container>

<Machinable>Falso</Machinable>

<ReturnLocations>False</ReturnLocations>

<ReturnServiceInfo>False</ReturnServiceInfo>

</Package>

</RateV4Request>

Request: RateV4 – <Service DelOpt> Example

<Size>Regular</Size>

<SortBy>package</SortBy>

<Machinable>Verdadero</Machinable>

</Package>

</RateV4Request>

2.3 Response Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
RateV4Response	Obligatorio		(Group)
RateV4Response / Package	Required repeating up to 25 times		(Group)
RateV4Response / Package / ZipOrigination	Obligatorio	Origination ZIP Code from request	String	whiteSpace=collapse length=5 pattern=\d{5}
RateV4Response / Package / ZipDestination	Obligatorio	Destination ZIP Code from request	String	whiteSpace=collapse length=5 pattern=\d{5}
RateV4Response / Package / Pounds	Obligatorio	Package Weight (Pounds) from request	Integer	maxInclusive=70 minInclusive=0
RateV4Response / Package / Ounces	Obligatorio	Package Weight (Ounces) from request	Decimal	maxInclusive=1120.0 minInclusive=0.0 totalDigits=10
RateV4Response / Package / FirstClassMailType	Optional	Appears when RateV4Request [Service='FIRST CLASS']. Por ejemplo: <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'])	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	Obligatorio	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	Obligatorio	Service Type name	String
RateV4Response / Package / Postage / Rate	Obligatorio	Retail Rate Published Retail Rates are available at our Postal Explorer Price List.	Decimal
RateV4Response / Package / Postage / CommercialRate	Optional	Commercial Rate. Published Commercial and Commercial Base Rates are available at our Postal Explorer Price List. Appears only where applicable for published Commercial and Commercial Base products and when requested via RateV4Request[e.g., Service='ONLINE' or Service='PRIORITY COMMERCIAL' or Service='CONNECT LOCAL'].	Decimal
RateV4Response / Package / Postage / CommercialPlusRate	Optional	Commercial Rate. Appears only where applicable for published Commercial Plus products and when requested via RateV4Request[e.g., Service='PLUS'].	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 EMSH 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: Obligatorio	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	Expected Delivery Date: yyyy-mm-dd. Can only returned when ShipDate tag is present in the request.	String
RateV4Response / Package / Postage / (Choice) / (sequence) / CommitmentName	Optional	Expected Delivery returned in number of days. Ex. <CommitmentName>3-Day</CommitmentName> Inclusion of ShipDate with Priority Mail and Priority Mail Express variants will return both <CommitmentName> and <CommitmentDate> in the response.	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. Por ejemplo: <Location> <CutOff>8:00 PM</CutOff> <Facility>BUZÓN DE EXPRESS MAIL</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	Obligatorio	Local cutoff time for drop-off	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / Facility	Obligatorio	Facility Name	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / Street	Obligatorio	Facility Address	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / City	Obligatorio	Facility City	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / State	Obligatorio	Facility State	String
RateV4Response / Package / Postage / (Choice) / (sequence) / Location / Zip	Obligatorio	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. Inclusion of ShipDate with Option="HFP" will return <CommitmentTime>, <CommitmentName>, and <CommitmentDate> in the response in this Hold for Pickup structure.	(Group)
RateV4Response / Package / Postage / (Choice) / Commitment / CommitmentDate	Required once	Expected Delivery Date: yyyy-mm-dd. Can only returned when ShipDate tag is present in the request.	String
RateV4Response / Package / Postage / (Choice) / Commitment / CommitmentName	Optional	Expected Delivery returned in number of days. Ex. <CommitmentName>3-Day</CommitmentName> Inclusion of ShipDate with Priority Mail and Priority Mail Express variants will return both <CommitmentName> and <CommitmentDate> in the response.	String
RateV4Response / Package / Postage / (Choice) / Commitment / CommitmentTime	Required once	Expected Pickup Time on day of delivery. Ex. <CommitmentTime>6:00 PM</CommitmentTime>. Must include <ShipDate> Option="HFP" (i.e., <ShipDate Option="HFP">MM/DD/YYYY</ ShipDate> in the request to return <CommitmentTime>.	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. Por ejemplo: <Location> <CutOff>8:00 PM</CutOff> <Facility>BUZÓN DE EXPRESS MAIL</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	Obligatorio	Local cutoff time for drop-off	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / Facility	Obligatorio	Facility Name	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / Street	Obligatorio	Facility Address	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / City	Obligatorio	Facility City	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / State	Obligatorio	Facility State	String
RateV4Response / Package / Postage / (Choice) / Commitment / Location / Zip	Obligatorio	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	Obligatorio	Returned when RateV4Request[Revision='2']. Special service ID	Integer
RateV4Response / Package / Postage / SpecialServices / SpecialService / ServiceName	Obligatorio	Returned when RateV4Request[Revision='2']. Special service name	String
RateV4Response / Package / Postage / SpecialServices / SpecialService / Available	Obligatorio	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	Obligatorio	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	Obligatorio	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	Obligatorio	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	Obligatorio	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	Obligatorio	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 / Postage / Fees	Optional	Returns when <ReturnFees> = “true” Dimensional weight pricing will include length and volume fees to account for cost of processing oversized parcels	String
RateV4Response / Package / Postage / Fees / Fee	Obligatorio		String
RateV4Response / Package / Postage / Fees / Fee / FeeType	Obligatorio	Indicates what type of Fee is being requested: - Non Standard Length Fee - Non Standard Volume Fee	String
RateV4Response / Package / Postage / Fees / Fee / FeeType / FeePrice	Obligatorio	Non Standard Length Fee(s) a. 15" < x < 22" = $0 (for all packages) b. 22" < x < 30" = $2 (for DDU entered packages) c. 22" < x < 30" = $3 (for DNDC/DSCF entered packages) d. 22" < x < 30" = $4 (for all other packages) e. x > 30" = $7.50 (for DDU entered packages) f. x > 30" = $11.25 (for DNDC/DSCF entered packages) g. x > 30" = $15 (for all other packages) Non Standard Volume Fee(s) a. x > 2 cubic feet (3546 cubic inches) = $15 (for all packages) Live Animal Transportation Fee(s) a. $0.20 (for all packages) Nonmachinable Fee(s) a. $0.25 (for all packages)	String
RateV4Response / Package / Postage / Fees / Fee / FeeType / FeePrice / FeeInformation	Obligatorio	Fee Information indicates the fee is <Rate>	String
RateV4Response / Package / Postage / Fees / Fee / FeeType / FeePrice / FeeInformation / FeeInfo FeeInfoType =”PriceType”	Obligatorio	Fee Information indicates the fee is <Rate>	String
RateV4Response / Package / HSCodeReqd	Optional	Returns when <ReturnHSCodeReqd>=“Y” (Yes). When <HSCodeReqd>True</HSCodeReqd> Indicates which APO/FPO/DPO destinations will require valid Harmonization Code and Content/Item descriptions because of new international shipping regulatory mandates. Per international shipping regulatory mandates, shipments to European Union (EU) countries are required to contain a valid Harmonization Code and Content/Item description. Harmonization Code (i.e., HS Tariff Number) must be based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization. To learn more about providing acceptable item descriptions, view the chart below or read the EU’s guidance on acceptable terms at Guidance on Acceptable and Unacceptable Terms for the Description of Goods.	String	Enumerations= · True · False
RateV4Response / Package / Restriction / Restrictions	Obligatorio	APO/FPO Restrictions provided if the Destination ZIP Code is an APO/FPO ZIP Code.	String
RateV4Response / Attributes	Obligatorio	When <ReturnFees> = True, the new Attributes tag will return to show Oversize fees and/or Dimensional Weight fees. Any future package attributes that impact a price returned will be included in the attributes tag.	String
RateV4Response / Attributes / Attribute Key	Obligatorio	Attribute Key: DimensionalWeightR = RetailRate DimensionalWeightCB = Commercial Rate DimensionalWeightCP = Commerical Plus Rate Grande	String
RateV4Response / Package / Error	if used: Obligatorio	Error document (indicates request could not be completed).		See the Error Responses section below.
RateV4Response	Obligatorio		(alias)

2.3.1 Sample Response

Response: RateV4:

<Container>VARIABLE</Container>

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

<ServiceName>Adult Signature Required</ServiceName>

<Available>verdadero</Available>

</SpecialService>

<ServiceName>Adult Signature Restricted Delivery</ServiceName>

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

<ServiceName>Collect on Delivery</ServiceName>

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

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

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>Insurance</ServiceName>

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>Insurance Restricted Delivery</ServiceName>

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

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

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

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

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>Scan Retention</ServiceName>

<Available>verdadero</Available>

<DeclaredValueRequired>false</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>USPS Label Delivery Service</ServiceName>

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

</SpecialServices>

</Postage>

</Package>

</RateV4Response>

Response: RateV4 Military APO Example:

<Container>VARIABLE</Container>

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

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

<ServiceName>Insurance</ServiceName>

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>Insurance Restricted Delivery</ServiceName>

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

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

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

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

<Available>verdadero</Available>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

<ServiceName>Scan Retention</ServiceName>

<Available>verdadero</Available>

<DeclaredValueRequired>false</DeclaredValueRequired>

<DueSenderRequired>false</DueSenderRequired>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

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

<Available>verdadero</Available>

</SpecialService>

</SpecialServices>

</Postage>

<Restrictions>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. C2. E-cigarettes and related products (e.g., nicotine liquids, e-liquids, parts, or supplies) are prohibited. D. Coffee is prohibited. E. Medicines (prescription, over-the-counter, vitamins, and supplements) are prohibited when mailed to individuals for human or animal use. This prohibition does not apply when medicines are sent as Official Mail only between specifically designated agencies such as pharmaceutical distributors, hospitals, clinics, and pharmacies. 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." F3. Replica weapons and inert explosive devices (such as grenades) and weapons parts are prohibited. H. Meats, including preserved meats, bones, skin, hair, feathers, horns or hoofs of hoofed animals, and wool samples whether hermetically sealed or not, are prohibited. M. Fruits, vegetables, live animals, and live plants are prohibited. R. All alcoholic beverages, including those mailable under Publication 52, Part 421, are prohibited. S. Synthetic cannabinoids used to stimulate the central nervous system commonly known as "synthetic marijuana," "K2," or "Spice" are prohibited. F. Firearms of any type are prohibited, except firearms mailed to or by official U.S. government agencies. This restriction does not apply to firearms mailed from this MPO ZIP Code, provided ATF and USPS regulations are met. Antique firearms do not require an ATF form. </Restrictions>

</Restriction>

</Package>

</RateV4Response>

Response: RateV4 – Non Standard Fee Example

<Machinable>FALSO</Machinable>

<MailService>USPS Ground Advantage&lt;sup&gt;&#8482;&lt;/sup&gt; HAZMAT</MailService>

<Fees>

<Fee>

<FeeType>Nonstandard Length fee > 30 in.</FeeType>

</FeeInformation>

</Fee>

<Fee>

<FeeType>Nonstandard Volume fee > 2 cu. ft.</FeeType>

</FeeInformation>

</Fee>

</Fees>

<Attribute Key="Oversized">verdadero</Attribute>

</Attributes>

</Postage>

<MailService>USPS Ground Advantage&lt;sup&gt;&#8482;&lt;/sup&gt;</MailService>

<Fees>

<Fee>

<FeeType>Nonstandard Length fee > 30 in.</FeeType>

</FeeInformation>

</Fee>

<Fee>

<FeeType>Nonstandard Volume fee > 2 cu. ft.</FeeType>

</FeeInformation>

</Fee>

</Fees>

<Attribute Key="Oversized">verdadero</Attribute>

</Attributes>

</Postage>

<MailService>USPS Ground Advantage&lt;sup&gt;&#8482;&lt;/sup&gt; Hold For Pickup</MailService>

<Fees>

<Fee>

<FeeType>Nonstandard Length fee > 30 in.</FeeType>

</FeeInformation>

</Fee>

<Fee>

<FeeType>Nonstandard Volume fee > 2 cu. ft.</FeeType>

</FeeInformation>

</Fee>

</Fees>

<Attribute Key="Oversized">verdadero</Attribute>

</Attributes>

</Postage>

<MailService>USPS Ground Advantage&lt;sup&gt;&#8482;&lt;/sup&gt; Parcel Locker</MailService>

<Fees>

<Fee>

<FeeType>Nonstandard Length fee > 30 in.</FeeType>

</FeeInformation>

</Fee>

<Fee>

<FeeType>Nonstandard Volume fee > 2 cu. ft.</FeeType>

</FeeInformation>

</Fee>

</Fees>

<Attribute Key="Oversized">verdadero</Attribute>

</Attributes>

</Postage>

</Package>

</RateV4Response>

RateV4 Response - <Service DelOpt = Parcel Locker> Example

<Machinable>VERDADERO</Machinable>

<MailService>USPS Ground Advantage&lt;sup&gt;&#8482;&lt;/sup&gt; Parcel Locker</MailService>

</Postage>

<MailService>Priority Mail Express 2-Day&lt;sup&gt;&#174;&lt;/sup&gt; Parcel Locker</MailService>

</Postage>

<MailService>Priority Mail&lt;sup&gt;&#174;&lt;/sup&gt; Parcel Locker</MailService>

</Postage>

<MailService>USPS Ground Advantage&lt;sup&gt;&#8482;&lt;/sup&gt; Cubic Parcel Locker</MailService>

</Postage>

<MailService>Priority Mail&lt;sup&gt;&#174;&lt;/sup&gt; Large Flat Rate Box Parcel Locker</MailService>

<MaxDimensions>USPS-Produced Box: 12-1/4"(L) X 12"(W) X 6"(H)</MaxDimensions>

</Postage>

<MailService>Priority Mail&lt;sup&gt;&#174;&lt;/sup&gt; Medium Flat Rate Box Parcel Locker</MailService>

<MaxDimensions>USPS-Produced Box: 13-5/8" x 11-7/8" x 3-3/8" or 11" x 8-1/2" x 5-1/2"</MaxDimensions>

</Postage>

<MailService>Priority Mail&lt;sup&gt;&#174;&lt;/sup&gt; Small Flat Rate Box Parcel Locker</MailService>

<MaxDimensions>USPS-Produced Box: 8-5/8" x 5-3/8" x 1-5/8"</MaxDimensions>

</Postage>

<MailService>Media Mail Parcel Parcel Locker</MailService>

</Postage>

<MailService>Library Mail Parcel Parcel Locker</MailService>

</Postage>

</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

Descripción

Tipo

Validation

IntlRateV2Request

Obligatorio

API=IntlRateV2

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

(Group)

IntlRateV2Request / USERID

Obligatorio

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

Por Ejemplo: USERID="XXXXXXX"

NMTOKEN

IntlRateV2Request / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password.

Por Ejemplo: PASSWORD="XXXXXXX"

NMTOKEN

IntlRateV2Request / Revision

Optional

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

Por ejemplo:

String

IntlRateV2Request / Package

Required repeating up to 25 times

Opening Package tag.

(Group)

IntlRateV2Request / Package / ID

Obligatorio

No restriction on number or type of characters provided valid XML syntax and unique to request.
Por ejemplo:

NMTOKEN

IntlRateV2Request / Package / Pounds

Obligatorio

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.
Por ejemplo:

Integer

minInclusive=0

IntlRateV2Request / Package / Ounces

Obligatorio

Por ejemplo:

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.

Por ejemplo: <Machinable>Verdadero</Machinable>

Boolean

default=true

IntlRateV2Request / Package / MailType

Obligatorio

Package type being shipped.

Por ejemplo: <MailType>Package</MailType>

Nota: 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.

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

Obligatorio

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

Por ejemplo:

String

Enumerations=

· Y

· N

IntlRateV2Request / Package / GXG / GiftFlag

Obligatorio

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

Por ejemplo:

String

Enumerations=

· Y

· N

IntlRateV2Request / Package / ValueOfContents

Obligatorio

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

Por ejemplo: <ValueOfContents>103.00</ValueOfContents>

String

IntlRateV2Request / Package / Country

Obligatorio

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.

Por ejemplo:

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

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

Nota: 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.

Por ejemplo: <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 (Correo registrado	103
Insurance – Global Express Guaranteed	106
Insurance – Priority Mail International	108
Acuse de recibo	105
Certificado de envío	100
Confirmación Electrónica de Entrega Internacional de USPS	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.

Nota: 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 / Package / ReturnHSCodeReqd

Optional

When this tag is set to “Y” for Yes then <HSCodeReqd> will return, which is an indicator for which destinations will require valid Harmonization Code and Content/Item descriptions because of new international shipping regulatory mandates.

Default= N

Enumerations=

· Y (Yes)

· N (No)

IntlRateV2Request

Required once

(alias)

3.2.1 Sample Requests

Request: IntlRateV2:

IntlRateV2Request USERID="XXXXXXXXX" PASSWORD="">

<Machinable>Verdadero</Machinable>

<MailType>Package</MailType>

<GXG>

</GXG>

<Country>Royal Mail del</Country>

<Container>VARIABLE</Container>

</Package>

<Country>Kazakhstan</Country>

<Container>RECTANGULAR</Container>

</Package>

</IntlRateV2Request>

3.3 Response Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
IntlRateV2Response	Obligatorio	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	obligatorio	Package Identification Number (matches IntlRateV2Request/Package/ID)	NMTOKEN
IntlRateV2Response / Package / Prohibitions	Obligatorio	Prohibitions	String
IntlRateV2Response / Package / Restrictions	Obligatorio	Restricciones	String
IntlRateV2Response / Package / Observations	Obligatorio	Observations	String
IntlRateV2Response / Package / CustomsForms	Obligatorio	Formularios de aduana	String
IntlRateV2Response / Package / ExpressMail	Obligatorio	Express Mail	String
IntlRateV2Response / Package / AreasServed	Obligatorio	Areas Served	String
IntlRateV2Response / Package / AdditionalRestrictions	Obligatorio	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	obligatorio	An Integer reflective of the <SvcDescription/>. Refer to Appendix B for all international Service ID values.	Integer	minInclusive=0
IntlRateV2Response / Package / Service / Pounds	Obligatorio	Weight of package (pounds)	Integer
IntlRateV2Response / Package / Service / Ounces	Obligatorio	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	Obligatorio	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	Obligatorio	If specified in request this is echoed back if relevant to computed postage.	String
IntlRateV2Response / Package / Service / GXG / GiftFlag	Obligatorio