customs forms api - welcome | usps forms api usps web tools™ ... (4) contain goods destined to...

Customs Forms API

USPS Web Tools™

Application Programming Interface

Reference Document Version 8.7 (01/17/2016)

Contents

1 Introduction ................................................................................................. 3

2 Customs Forms (CN22V2) API ....................................................................... 4

2.1 Customs Forms (CN22V2) Request ......................................................................... 4

2.2 API Signature .......................................................................................................... 4

2.2.1 Request Parameters ........................................................................................................ 5

2.2.2 Request Example ........................................................................................................... 14

2.3 Customs Forms (CN22V2) Response ...................................................................... 16

2.3.1 Response Parameters .................................................................................................... 16

2.2.1 Response Example ......................................................................................................... 17

2.4 Label Example ....................................................................................................... 18

3 Customs Forms (CP72V3) API ..................................................................... 19

3.1 Customs Forms (CP72V3) Request ......................................................................... 19

3.1.1 API Signature ................................................................................................................. 19

3.1.2 Request Parameters ...................................................................................................... 19

3.1.3 Request Example ........................................................................................................... 29

3.2 Customs Forms (CP72V3) Response ....................................................................... 32

3.2.1 Response Parameters .................................................................................................... 32

3.2.2 Response Example ......................................................................................................... 33

3.3 Label Example ....................................................................................................... 34

1 Introduction

As required under 123.6 of the USPS International Mail Manual, for international mail, only three customs declaration forms are used for international mail:

a. PS Form 2976, Customs Declaration CN 22 — Sender’s Declaration.

b. PS Form 2976‐A, Customs Declaration and Dispatch Note — CP 72.

c. PS Form 2976‐B, Priority Mail Express International Shipping Label and Customs Form. Note: For international mail, PS Form 2976‐B is used only for Priority Mail Express International items. However, as noted in DMM 703.2.3, PS Form 2976‐B is also used with Priority Mail Express items sent to APO/FPO/DPO destinations.

Users must know which form is applicable for each shipment. The correct form for each country and content combination can be found in Section 123 of the USPS International Mail Manual (IMM).

2 Customs Forms (CN22V2) API

2.1 Customs Forms (CN22V2) Request

A PS Form 2976, Customs Declaration CN22 – Sender’s Declaration, must be used on all First‐Class Mail International® package size items (small packets), First‐Class Package International Service™ items, Priority Mail International® Small Flat Rate Boxes, M‐bags, and certain Priority Mail Express International™ items. Refer to the International Mail Manual (IMM®) at pe.usps.com for additional information. Also use this form on a First‐Class Mail International mailpiece or Priority Mail International Flat Rate Envelopes if ANY of the following applies:

The mailpiece weighs 16 ounces or more (the maximum weight limit is 4 pounds);

The mailpiece exceeds 3/4 inch in thickness;

The mailpiece contains dutiable goods. NOTE: Priority Mail International Flat Rate Envelopes and First‐Class Mail International large envelopes (flats) containing only documents, weighing under 16 ounces, and meeting the flat‐size characteristics do not require a PS Form 2976. Do not use this form for mailpieces that:

(1) Contain items valued over $400; (2) Require an export license; (3) Contain goods (non‐documents) destined to Iran, Sudan, or Syria; or (4) Contain goods destined to Cuba or North Korea, other than gift parcels or humanitarian donations as defined by 15 CFR § 740.12.

Goods may be subject to restrictions. It is the responsibility of the mailer to inquire about and abide by any import and export regulations and restrictions (e.g., quarantine, pharmaceutical, etc.), and to properly complete this form NOTE: Refer to the current “Overseas Military/Diplomatic Mail” section of the latest Postal Bulletin at usps.com for additional information regarding APO, FPO and DPO destinations.

2.2 API Signature

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

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

2.2.1 Request Parameters

Tag Name Occurs Description Type Validation

CustomsCN22V2Request

required once

API=CustomsCN22V2 PS Form 2976, Customs Declaration CN 22 ‐ Sender's Declaration, is used by foreign customs' authorities to clear mail for entry into their country and, when appropriate, assess duty and taxes. Failure to fully and accurately complete this form may result in the delay of the mail, inconvenience to the recipient, or the incorrect assessment of duty and taxes..

(group)

CustomsCN22V2Request / @USERID

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

NMTOKEN

CustomsCN22V2Request / @PASSWORD

optional For backward compatibility; not validated. token

CustomsCN22V2Request / Option

optional This tag is for future use. Do not enter any value.

empty

CustomsCN22V2Request / ImageParameters

optional Groups the ImageParameters elements. (group) minOccurs=0

CustomsCN22V2Request / ImageParameters/ ImageParameter

optional

Returns alternate label image. Only alternate 4’’x6’’ size label image may be requested at this time.

4X6LABEL (4X6 on a full page 8.5/11” background)

4X6LABELL (Landscape – true size 4X6; image rotated, not on an 8.5 x 11 background page)

4X6LABELP (Portrait – true size 4X6, not on an 8.5 x 11 background page)

SEPARATECONTINUEPAGE – will force the continuation page (if the item count causes the need for a continuation page) onto a separate page.

For example: <ImageParameter>4X6LABEL</ImageParameter>

string

Default=4X6LABEL Enumerations= 4X6LABEL 4X6LABELL 4X6LABELP SEPARATECONTINUEPAGE


CustomsCN22V2Request / FromFirstName

optional

Both FromFirstName and FromLastName are required if FromFirmName is left blank. First and last names are concatenated and then truncated to 45 characters to fit on label

string maxLength=24 minLength=0

CustomsCN22V2Request / FromLastName

optional

Both FromFirstName and FromLastName are required if FromFirmName is left blank.

First and last names are concatenated and then truncated to 45 characters to fit on label

string

maxLength=24 minLength=0

CustomsCN22V2Request / FromFirm

optional

FromFirm is required if FromFirstName and FromLastName are left blank.

For example: <FromFirm></FromFirm> string


CustomsCN22V2Request / FromAddress1

optional

Use this tag for a suite or apartment number only. Otherwise, leave blank.

For example: <FromAddress1/> string


CustomsCN22V2Request / FromAddress2

required once

Use this tag for the primary address line.

For example: <FromAddress2>10 Elm Street </FromAddress2>

string


CustomsCN22V2Request / FromUrbanization

optional

Use this tag for Puerto Rico only. ZIP Code prefixes 006 to 009, if area is so designated.

For example: <FromUrbanization>URB Caparra Ter</FromUrbanization>

string


CustomsCN22V2Request / FromCity

required once

The city is any acceptable mailing name for the five‐digit ZIP Code serving the intended recipient.

For example: <FromCity>Anytown</FromCity>

string


CustomsCN22V2Request / FromState

required once

Use 2‐letter USPS abbreviation.

For example: <FromState>TX</FromState>

string length=2

CustomsCN22V2Request / FromZip5

required once

Use valid 5‐digit ZIP code.

For example: <FromZip5>01234</FromZip5>

string minLength=5 pattern=\d{5}


CustomsCN22V2Request / FromZip4

optional

If value is entered, four digits are required. This is the ZIP+4 extension.

For example: <FromZip4>5678</FromZip4>

string

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

CustomsCN22V2Request / FromPhone

optional

10 digits required (including area code), with no punctuation. Use format: 2125551234

For example: <FromPhone>5555555555</FromPhone>


CustomsCN22V2Request / ToFirstName

optional

Both ToFirstName and ToLastName are required if ToFirm is left blank.

For example: <ToFirstName>John</ToFirstName>


CustomsCN22V2Request / ToLastName

optional

Both ToFirstName and ToLastName are required if ToFirm is left blank.

For example: <ToLastName>Doe</ToLastName>


CustomsCN22V2Request / ToFirm

optional

ToFirm is required if ToFirstName and ToLastName are left blank.

For example: <ToFirm></ToFirm> string


CustomsCN22V2Request / ToAddress1

optional Deprecated. See “ToFirstName” and “ToLastName” tags.



optional Deprecated. See “ToFirm” tag string maxLength=48 minLength=0


required once

Use ToAddress3 and ToAddress4 for primary and secondary address lines, as needed. For example: <ToAddress3>123 Calle 6</ToAddress3>



required once

Use ToAddress3 and ToAddress4 for primary and secondary address lines, as needed. For example: <ToAddress4>Apartado 3068</ToAddress4>




required once

Use ToAddress5 for destination city information

For example: <ToAddress5>Puerto Vallarta</ToAddress5>



required once

Use ToAddress6 for destination postal code information

For example: <ToAddress6>MX46807</ToAddress6>


CustomsCN22V2Request / (sequence)

required once

Either a ToCountry or ToAPOFPOZip5 code may be specified but not both. Use ToAPOFPOZip5 when destination is an APO, FPO, DPO or US Possession, Territory or Freely Associated State ZIP code.

(group)

CustomsCN22V2Request / (sequence) / ToCountry

required once

The country name entered must match an entry from the USPS‐approved International Index of Countries and Localities (see http://pe.usps.com/text/imm/immctry.htm). To avoid request errors, use the country name exactly as it appears in the Index of Countries and Localities.

For example: <ToCountry>Japan</ToCountry>

string minLength=0 maxLength=100


CustomsCN22V2Request / (sequence) / ToAPOFPOZip5

optional

If destination is one of the 50 states or DC, an APO, FPO, DPO or US Possession, Territory or Freely Associated State supply the ZIP code here. Note that Address5 and Address6 are ignored when ToAPOFPOZip is supplied. Military addresses must show the grade, full name with middle name or initial, and PSC number, unit number, or ship name. Replace the city name with "APO", "FPO", “DPO” and the state with "AA," "AE," or "AP," and use a special ZIP Code. Enter the recipient APO/FPO ZIP code using tag <ToAPOFPOZip5>.

For example: <ToAPOFPOZip5>96612</ToAPOFPOZip5>

Use the tags <ToAddress1>, <ToAddress2>, <ToAddress3>, <ToAddress4> for the recipient address. Use the tag <ToAddress4> to enter the entire APO, FPO, DPO city, state, and ZIP code.

For example: <ToAddress4>FPO, AP 96612</ToAddress4> ___________________________________

Packages addressed to non‐military destinations in US Possessions, Territories and Freely Associated States are addressed by entering the recipient zip code in the <ToAPOFPOZip5> tag.


Use the tags <ToAddress1>, <ToAddress2>, <ToAddress3>, <ToAddress4> for the recipient address.

string


CustomsCN22V2Request / ToPhone

required once

No format checking is done on international phone numbers.

For example: <ToPhone>011 52 (322)222‐0069</ToPhone>

string



CustomsCN22V2Request / ToFax

required once

No format checking is done on international fax numbers.

For example: <ToFax>011 52 (322)222‐0074</ToFax>

string


CustomsCN22V2Request / ToEmail

required once

Single, complete valid e‐mail address is required if tag is used.

For example: <ToEmail>[email protected]</ToEmail>

string

maxLength=100 pattern=([\w_\‐\.]+)@(([\w‐]+\.))+[a‐zA‐Z]{2,4}

CustomsCN22V2Request / ShippingContents

required once

Groups the ItemDetail elements. (group)

CustomsCN22V2Request / ShippingContents / ItemDetail

required once repeating up to 5 times

Each element represents a single content‐declaration line item.

(group)

CustomsCN22V2Request / ShippingContents / ItemDetail / Description

required once

Description of the item.

For example: <Description>Policy guidelines document</Description>

string


CustomsCN22V2Request / ShippingContents / ItemDetail / Quantity

required once

Quantity of the item. Integer value required.

For example: <Quantity>1</Quantity> integer

minExclusive=0 maxInclusive=999

CustomsCN22V2Request / ShippingContents / ItemDetail / Value

required once

The data entered with this tag provides the total value for the line item. If the item is 2 boxes of 50 pens and the value of each box is $10.00, "20.00" (2 boxes x $10.00) should be entered. If the value of each pen is .25 then "25.00" (100 pens x .25) should be entered.

For example: <Value>55.00</Value>

decimal

minExclusive=0 totalDigits=8 maxInclusive=99999.99

CustomsCN22V2Request / ShippingContents / ItemDetail / NetPounds

required once

Provide the integral pounds component of the weight of the entire line item.

For example: <NetPounds>1</NetPounds>

integer

default=0 totalDigits=2 minInclusive=0 maxInclusive=70


CustomsCN22V2Request / ShippingContents / ItemDetail / NetOunces

required once

Provide the ounces component of the weight of the entire line item.

For example: <NetOunces>5</NetOunces>

decimal

totalDigits=5 minInclusive=0 maxInclusive=1120

CustomsCN22V2Request / ShippingContents / ItemDetail / HSTariffNumber

required once

For commercial items only. If known, the HS tariff number must be based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization.

For example: <HSTariffNumber>490110490110</HSTariffNumber>

string

maxLength=12 minLength=0 pattern=\d{6} pattern=\d{0}

CustomsCN22V2Request / ShippingContents / ItemDetail / CountryOfOrigin

optional

For commercial items only. Country of Origin means the country where the goods originated, e.g. were produced, manufactured, or assembled. It is recommended you supply this information and attach an invoice to the outside to accelerate customs clearance in processing the items. The country name entered must match an entry from the USPS‐approved International Index of Countries and Localities (see http://pe.usps.com/text/imm/immctry.htm). To avoid request errors, use the country name exactly as it appears in the Index of Countries and Localities.

For example: <CountryOfOrigin>United States</CountryOfOrigin>


CustomsCN22V2Request / GrossPounds

required once

Gross pounds and ounces together represent the total package weight, including packing material. For example, a package weighing 3 lbs 8 ounces would have "3" entered here and "8" entered with the <GrossOunces> tag. The Web Tool will check for maximum shipping weight of 4 pounds. Allowable weight may change based on the service used to send package and the destination country.

For example: <GrossPounds>3</GrossPounds>

decimal

default=0 minInclusive=0 maxInclusive=70 totalDigits=5


CustomsCN22V2Request / GrossOunces

required once

Enter the ounces component of the total package weight with this tag.

For example: <GrossOunces>8</GrossOunces>

decimal

default=0 totalDigits=5 maxInclusive=1120 minInclusive=0

CustomsCN22V2Request / ImageType

required once

Controls the type of image returned in the response.

For example: <ImageType>PDF</ImageType>

string

enumeration=PDF enumeration=TIF enumeration=NONE

CustomsCN22V2Request / ImageLayout

optional

Controls how the multipage form is returned in the response tags. "ONEPERFILE" returns one page per response tag while “ALLINONEFILE” returns all pages in a single response tag. When the SEPARATECONTINUEPAGE value is specified in an <ImageParameter> tag, the continuation page will be placed on the top of separate full page image.

This second image can be returned as a single multi‐image file by specifying the ALLINONEFILE value in the <ImageLayout> tag or it can also be specified explicitly by specifying the ONEPERFILE value in the <ImageLayout> tag.

string

default=ONEPERFILE enumerations= ONEPERFILE ALLINONEFILE

CustomsCN22V2Request / ContentType

required once

Enter a Content Type from the choices available.

For example: <ContentType>DOCUMENTS</ContentType>

string

enumeration=

SAMPLE

GIFT DOCUMENTS

MERCHANDISE

HUMANITARIAN

DANGEROUSGOODS

OTHER

CustomsCN22V2Request / ContentTypeOther

optional

For content type description when CustomsCN22V2Request / ContentType="OTHER"

For example: <ContentTypeOther>Pharmaceuticals</ContentTypeOther>



CustomsCN22V2Request / HSTariffNumber

required once

For backward compatibility only. Use <HSTariffNumber> field within the Item Detail group.

string


CustomsCN22V2Request / CountryOfOrigin

required once

For backward compatibility only. Use <CountryOfOrigin> field within the Item Detail group.


CustomsCN22V2Request / CustomerRefNo

optional

Written to Postal Manifest Detail record.

For example: <CustomerRefNo>Ref #369246</CustomerRefNo>


CustomsCN22V2Request / MailClass

optional Restricted use. For authorized users, if present, must contain one of the valid choices. Ignored for all other users.

string

enumerations= EMI PMEI PMIFRESFRB FCMI MBAG

CustomsCN22V2Request / HoldForManifest

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

string enumeration=Y enumeration=N

CustomsCN22V2Request / EELPFC

optional

EELPFC is synonymous with AES/ITN, which stands for the Automated Export Systems / International Transaction Number. International packages within certain categories, accepted by the Postal Service or any delivery company, must display an Internal Transaction Number (ITN) or an Automated Export System (AES) Exemption.

Please see https://aesdirect.census.gov/ for details.

For example: <EELPFC>30.37a</EELPFC>

string

minLength=0 maxLength=35

CustomsCN22V2Request / LabelDate

optional

Date the mail will enter the mail stream. No more than 3 days in the future. Default is day of request.

For example: <LabelDate>09/28/2010</LabelDate>

string

maxLength=10 pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?


CustomsCN22V2CertifyRequest

required once

API=CustomsCN22V2Certify This API is used by integrators to provide samples and/or to evaluate their software without producing a "live" shipping document.

(alias)

2.2.2 Request Example

<CustomsCN22V2CertifyRequest USERID="xxx" PASSWORD=""><ImageParameters> <ImageParameter>4X6LABEL</ImageParameter> </ImageParameters> <FromFirstName>JOHN</FromFirstName> <FromLastName>DOE</FromLastName> <FromFirm>The Firm Mattress Co.</FromFirm> <FromAddress1>Suite A</FromAddress1> <FromAddress2>10 ELM STREET</FromAddress2> <FromUrbanization>The URB</FromUrbanization> <FromCity>ANYTOWN</FromCity> <FromState>ST</FromState> <FromZip5>01234</FromZip5> <FromZip4>5678</FromZip4> <FromPhone>3019185825</FromPhone> <ToFirstName>Steve</ToFirstName> <ToLastName>Jobs</ToLastName> <ToFirm>MS. C. P. APPLE</ToFirm> <ToAddress2></ToAddress2> <ToAddress3>APARTADO 3068</ToAddress3> <ToAddress4>ADDR4 info</ToAddress4> <ToAddress5>ADD5 info</ToAddress5> <ToAddress6>46807 PUERTO VALLARTA JALISCO</ToAddress6> <ToCountry>MEXICO</ToCountry> <ToPhone>(018)‐38‐080‐371‐399</ToPhone> <ToFax>(018)‐38‐080‐371‐399</ToFax> <ToEmail>[email protected]</ToEmail> <ShippingContents>

<ItemDetail> <Description>Policy guidelines document</Description> <Quantity>1</Quantity> <Value>55.00</Value> <NetPounds>0</NetPounds> <NetOunces>1</NetOunces> <HSTariffNumber>307789808</HSTariffNumber> <CountryOfOrigin>Japan</CountryOfOrigin>

</ItemDetail><ItemDetail> <Description>Policy guidelines document</Description> <Quantity>2</Quantity> <Value>55.00</Value>

<NetPounds>0</NetPounds> <NetOunces>1</NetOunces> <HSTariffNumber>307789808</HSTariffNumber> <CountryOfOrigin>Japan</CountryOfOrigin>

</ItemDetail><ItemDetail> <Description>Policy guidelines document</Description> <Quantity>1</Quantity> <Value>15.00</Value> <NetPounds>0</NetPounds> <NetOunces>1</NetOunces> <HSTariffNumber>307789808</HSTariffNumber> <CountryOfOrigin>Japan</CountryOfOrigin>

</ItemDetail><ItemDetail> <Description>Policy guidelines document</Description> <Quantity>3</Quantity> <Value>50.00</Value> <NetPounds>0</NetPounds> <NetOunces>1</NetOunces> <HSTariffNumber>307789808</HSTariffNumber> <CountryOfOrigin>Japan</CountryOfOrigin>

</ItemDetail><ItemDetail> <Description>Corporate Letterhead</Description> <Quantity>50</Quantity> <Value>37.00</Value> <NetPounds>0</NetPounds> <NetOunces>1</NetOunces>

</ItemDetail><ItemDetail> <Description>Corporate Letterhead</Description> <Quantity>500</Quantity> <Value>32.00</Value> <NetPounds>0</NetPounds> <NetOunces>1</NetOunces>

</ItemDetail> </ShippingContents> <GrossPounds>4</GrossPounds> <GrossOunces>0</GrossOunces> <ImageType>TIF</ImageType> <ImageLayout>ALLINONEFILE</ImageLayout> <ContentType>Documents</ContentType> <HSTariffNumber>89098776</HSTariffNumber> <CountryOfOrigin>Canada</CountryOfOrigin>

<CustomerRefNo>CRef 10705</CustomerRefNo> <EELPFC>802.9B</EELPFC> </CustomsCN22V2CertifyRequest>

2.3 Customs Forms (CN22V2) Response

2.3.1 Response Parameters


CustomsCN22V2CertifyResponse required once

(alias)

CustomsCN22V2Response required once

(group)

CustomsCN22V2Response / TotalValue

required once

Value of all items being shipped decimal

CustomsCN22V2Response / CustomsBarcodeNumber

required once

Barcode number required by Customs Service

string

CustomsCN22V2Response / CN22V2FormImage

required once

Encoded image of Customs Form CN 22 (empty if ImageType='NONE')

base64Binary

CustomsCN22V2Response / CN22V2InstructionsImage

required once

Encoded image of Customs Form CN 22 instructions

base64Binary

CustomsCN22V2Response / CN22V2ContinuationImage

optional If the tag “CustomsCN22V2Request / ImageParameters/ ImageParameter” 4X6LABELL or 4X6LABELP are specified (resulting in true 4x6 sized images), and the count of items cause the need for a continuation page, the continuation image will be generated and the <CN22V2ContinuationImage> tag will be present and populated. Likewise, if a full page images is generated and the count of items cause the need for a continuation page AND SEPARATECONTINUEPAGE was specified, the <CN22V2ContinuationImage> tag will be present and populated.

base64Binary

CustomsCN22V2Response / Prohibitions

required once

List of items prohibited from mailing based on country of destination

string

CustomsCN22V2Response / Restrictions

required once

Restrictions on items being shipped based on country of destination

string

CustomsCN22V2Response / Observations

required once

Additional mailing information based on country of destination

string

CustomsCN22V2Response / CustomsForms

required once

Customs forms required to mail to destination country

string

CustomsCN22V2Response / Regulations

required once

Additional regulations for shipping to destination country

string

CustomsCN22V2Response / AdditionalRestrictions

required once

Additional restrictions on items being shipped to destination country

string

2.2.1 Response Example

<CustomsCN22V2Response> <?xml version="1.0"?> <CustomsCN22V2CertifyResponse> <TotalValue>244.00</TotalValue> <CustomsBarcodeNumber>LJXXXXXXXXXUS</CustomsBarcodeNumber> <CN22V2FormImage>SUkqAAgAAAASAP4ABAAB <!‐‐ over 10000 suppressed ‐‐> </CN22V2FormImage> <CN22V2InstructionsImage></CN22V2InstructionsImage> <Prohibitions>Ammunition, firing caps, and loaded metal cartridges <!‐‐ suppressed ‐‐> <Restrictions>Chocolate and products made of chocolate require prior authorization <!‐‐ suppressed ‐‐> <Observations>1. Goods whose commercial value exceed U.S. $70 dollars should be <!‐‐ suppressed ‐‐> <CustomsForms>First‐Class Mail International items and Priority Mail International<!‐‐ suppressed ‐‐> <Regulations>Country Code:MX Reciprocal Service Name: Servicio de Correspondencia Agrupada (SERCA) or Correos Acelerado International (CAI) Required Customs Form/Endorsement 1. Co<!‐‐ suppressed ‐‐> <AdditionalRestrictions>No Additional Restrictions Data found.</AdditionalRestrictions> </CustomsCN22V2CertifyResponse>

2.4 Label Example

3 Customs Forms (CP72V3) API

PS Form 2976‐A, Customs Declaration and Dispatch Note CP 72, is used on all Express Mail International and Priority Mail International parcels, with exception to Priority Mail International Flat Rate Envelope and Small Flat Rate Box.

An image of PS Form 2976‐A, Customs Declaration and Dispatch Note — CP 72, is available at http://about.usps.com/forms/ps2976a.pdf along with instructions to complete the form.

3.1 Customs Forms (CP72V3) Request

3.1.1 API Signature

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

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

3.1.2 Request Parameters


CustomsCP72V3Request required once

API=CustomsCP72V3 PS Form 2976‐A, Customs Declaration and Dispatch Note CP 72

(group)

CustomsCP72V3Request / @USERID

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

NMTOKEN

CustomsCP72V3Request / @PASSWORD

optional For backward compatibility; not validated.

token

CustomsCP72V3Request / Option

optional

This tag is for future use. Do not enter any value.

For example: <Option></Option> empty

CustomsCP72V3Request / ImageParameters

optional Groups alternate image options. (group)


CustomsCP72V3Request / ImageParameters / ImageParameter

Optional, repeating up to 3 times

Returns alternate label image. Only alternate 4’’x6’’ size label image may be requested at this time.

4X6LABEL (4X6 on a full page 8.5/11” background)

4X6LABELL (Landscape – true size 4X6; image rotated)

4X6LABELP (Portrait – true size 4X6) For example: <ImageParameter>4X6LABEL</ImageParameter>

string

Default=4X6LABEL Enumerations= 4X6LABEL 4X6LABELL 4X6LABELP

CustomsCP72V3Request / FromFirstName

optional Both FromFirstName and FromLastName are required if FromFirmName is left blank.


CustomsCP72V3Request / FromLastName

optional Both FromFirstName and FromLastName are required if FromFirmName is left blank.


CustomsCP72V3Request / FromFirm

optional FromFirm is required if FromFirstName and FromLastName are left blank.

string


CustomsCP72V3Request / FromAddress1

optional Use this tag for a suite or apartment number only. Otherwise, leave blank.

string


CustomsCP72V3Request / FromAddress2

required once

Use this tag for the primary address line. string


CustomsCP72V3Request / FromUrbanization

optional Use this tag for Puerto Rico only. ZIP Code prefixes 006 to 009, if area is so designated.

string


CustomsCP72V3Request / FromCity

required once

The city is any acceptable mailing name for the five‐digit ZIP Code serving the intended recipient.

string


CustomsCP72V3Request / FromState

required once

Use 2‐letter USPS abbreviation. string length=2

CustomsCP72V3Request / FromZip5

required once

Use valid 5‐digit ZIP code. string minLength=5 pattern=\d{5}


CustomsCP72V3Request / FromZip4

optional If value is entered, four digits are required. This is the ZIP+4 extension.

string


CustomsCP72V3Request / FromPhone

optional 10 digits required (including area code), with no punctuation. Use format: 2125551234


CustomsCP72V3Request / FromCustomsReference

optional

Enter a value for the "Sender's Customs Reference" that will appear on the label. The text entered is any reference number that the sender wishes to use.


CustomsCP72V3Request / ToFirstName

optional Both ToFirstName and ToLastName are required if ToFirm is left blank.


CustomsCP72V3Request / ToLastName

optional Both ToFirstName and ToLastName are required if ToFirm is left blank.


CustomsCP72V3Request / ToFirm

optional ToFirm is required if ToFirstName and ToLastName are left blank.


CustomsCP72V3Request / ToAddress1

optional Deprecated. See “ToFirstName” and “ToLastName” tags.



optional Deprecated. See “ToFirm” tag string maxLength=48 minLength=0


required once

Three address lines are provided, but only one is required. Use as many as needed for complete address.



required once

Three address lines are provided, but only one is required. Use as many as needed for complete address.



optional Three address lines are provided, but only one is required. Use as many as needed for complete address.


CustomsCP72V3Request / ToPostalCode

required once

Enter the postal code for the recipient. string maxLength=9 minLength=0

CustomsCP72V3Request / ToCity

required once

Recipient's city.

For example: <ToCity>PUERTO VALLARTA</ToCity>



CustomsCP72V3Request / (sequence)

required once

Either a ToCountry or ToAPOFPOZip5 code may be specified but not both. Use ToAPOFPOZip5 when destination is an APO, FPO, DPO or US Possession, Territory or Freely Associated State ZIP code.

(group)

CustomsCP72V3Request / (sequence) / ToCountry

required once

The country name entered must match an entry from the USPS‐approved International Index of Countries and Localities (see http://pe.usps.com/text/imm/immctry.htm). To avoid request errors, use the country name exactly as it appears in the Index of Countries and Localities.

For example: <ToCountry>Netherlands West Indies (Netherlands Antilles)</ToCountry>



CustomsCP72V3Request / (sequence) / ToAPOFPOZip5

optional

Supply the ZIP code here. Note that ToPostalCode and ToCity are ignored when ToAPOFPOZip is supplied. Military addresses must show the grade, full name with middle name or initial, and PSC number, unit number, or ship name. Replace the city name with "APO", “FPO", or “DPO” and the state with "AA," "AE," or "AP," and use a special ZIP Code. Enter the recipient APO, FPO, DPO ZIP code using tag <ToAPOFPOZip5>.


Use the tags <ToAddress3> and <ToAddress4> for the recipient address. Use the tag <ToAddress4> to enter the entire APO, FPO, DPO city, state, and ZIP code.

For example: <ToAddress4>FPO, AP 96612</ToAddress4> _________________________________

Packages addressed to non‐military destinations in US Possessions, Territories and Freely Associated States are addressed by entering the recipient zip code in the <ToAPOFPOZip5> tag.


Use the tags <ToAddress3> and <ToAddress4> for the recipient address.

string


CustomsCP72V3Request / ToPhone

required once

No format checking is done on international phone numbers.


CustomsCP72V3Request / ToFax

required once

No format checking is done on international fax numbers.



CustomsCP72V3Request / ToEmail

required once

Single, complete valid e‐mail address is required if tag is used.

string

maxLength=36 pattern=([\w_\‐\.]+)@(([\w‐]+\.))+[a‐zA‐Z]{2,4}

CustomsCP72V3Request / ToReference

optional Enter a value for the "Importer's Reference" that will appear on the label.


CustomsCP72V3Request / NonDeliveryOption

required once

To be used in the event the package is undeliverable.

string

enumeration= RETURN REDIRECT ABANDON

CustomsCP72V3Request / AltReturnAddress1

required once

Corresponds to the "REDIRECT" option with the NonDeliveryOption tag; ignored, otherwise. Six address lines are provided but only one is required. Use as many as needed for complete address.

string



required once


string



required once


string



required once


string



required once


string




required once


string


CustomsCP72V3Request / AltReturnCountry

required once

Required when NonDeliveryOption='REDIRECT' and displayed as last line of redirect address. Use "UNITED STATES" for redirect addresses in the US or US Possessions and Territories.


CustomsCP72V3Request / ShippingContents

required once

Groups the ItemDetail elements. (group)

CustomsCP72V3Request / ShippingContents / ItemDetail

required once repeating up to 30 times

Each element represents a single content‐declaration line item.

(group)

CustomsCP72V3Request / ShippingContents / ItemDetail / Description

required once

Description of the item.

For example: <Description>Policy guidelines document</Description>


CustomsCP72V3Request / ShippingContents / ItemDetail / Quantity

required once

Quantity of the item. Integer value required.

For example: <Quantity>1</Quantity> integer

minExclusive=0 maxInclusive=999

CustomsCP72V3Request / ShippingContents / ItemDetail / Value

required once

The data entered with this tag provides the total value for the line item. If the item is 2 boxes of 50 pens and the value of each box is $10.00, "20.00" (2 boxes x $10.00) should be entered. If the value of each pen is .25 then "25.00" (100 pens x .25) should be entered.

For example: <Value>55.00</Value>

decimal

minExclusive=0 totalDigits=8 maxInclusive=99999.99

CustomsCP72V3Request / ShippingContents / ItemDetail / NetPounds

required once

Provide the integral pounds component of the weight of the entire line item.

integer

default=0 totalDigits=2 minInclusive=0 maxInclusive=70

CustomsCP72V3Request / ShippingContents / ItemDetail / NetOunces

required once

Provide the ounces component of the weight of the entire line item.

decimal totalDigits=5 minInclusive=0 maxInclusive=1120


CustomsCP72V3Request / ShippingContents / ItemDetail / HSTariffNumber

required once

For commercial items only. If known, the HS tariff number must be based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization.

string


CustomsCP72V3Request / ShippingContents / ItemDetail / CountryOfOrigin

required once

For commercial items only. Country of Origin means the country where the goods originated, e.g. were produced, manufactured, or assembled. It is recommended you supply this information and attach an invoice to the outside to accelerate customs clearance in processing the items. The country name entered must match an entry from the USPS‐approved International Index of Countries and Localities (see http://pe.usps.com/text/imm/immctry.htm). To avoid request errors, use the country name exactly as it appears in the Index of Countries and Localities.


CustomsCP72V3Request / InsuredNumber

optional For backward compatibility; not validated.


CustomsCP72V3Request / InsuredAmount

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

decimal

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

CustomsCP72V3Request / SDRInsuredValue

optional Convert the U.S. dollar amount to the special drawing right (SDR) value and enter it in the SDR value block.

decimal

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

CustomsCP72V3Request / Postage

optional Use this tag for entering a postage amount, if known.

decimal

default=0 minInclusive=0 maxInclusive=9999.999 totalDigits=8


CustomsCP72V3Request / GrossPounds

required once

Gross pounds and ounces together represent the total package weight, including packing material. For example, a package weighing 3 lbs 8 ounces would have "3" entered here and "8" entered with the <GrossOunces> tag. The Web Tool will check for maximum shipping weight of 70 pounds. Allowable weight may change based on the service used to send package and the destination country.

decimal

default=0 minInclusive=0 maxInclusive=70 totalDigits=5

CustomsCP72V3Request / GrossOunces

required once

Enter the ounces component of the total package weight with this tag.

decimal

default=0 totalDigits=5 maxInclusive=1120 minInclusive=0

CustomsCP72V3Request / DeliveryType

required once

Airmail or Surface must be specified. string

enumerations=

AIRMAIL SURFACE

CustomsCP72V3Request / ContentType

required once

Enter a Content Type from the choices available. If "OTHER" then CustomsCP72V3Request / ContentTypeOther is a required value.

string

enumerations=

SAMPLE

GIFT DOCUMENTS

MERCHANDISE

RETURN HUMANITARIAN

DANGEROUSGOODS

OTHER

CustomsCP72V3Request / ContentTypeOther

optional Required when CustomsCP72V3Request / ContentType="OTHER"


CustomsCP72V3Request / Comments

optional

Enter any comments to appear on the form.

For example: <Comments></Comments>

string


CustomsCP72V3Request / LicenseNumber

optional Enter license number, if known or if included in package.

string



CustomsCP72V3Request / CertificateNumber

optional Enter certificate number, if known or if included in package.

string


CustomsCP72V3Request / InvoiceNumber

optional Enter invoice number, if known or if included in package.

string


CustomsCP72V3Request / ImageType

required once

Controls the type of image returned in the response.

string

enumeration=PDF enumeration=TIF enumeration=NONE

CustomsCP72V3Request / ImageLayout

optional

Controls how the multipage form is returned in the response tags. "ONEPERFILE" returns one page per response tag while “ALLINONEFILE” returns all pages in a single response tag. The “TRIM” options conserve page space if possible by combining two form parts on a single page. For example: <ImageLayout>ONEPERFILE<ImageLayout>

string

default=ONEPERFILE enumerations= ONEPERFILE ALLINONEFILE TRIMONEPERFILE TRIMALLINONEFILE

CustomsCP72V3Request / CustomerRefNo

optional

Written to Postal Manifest Detail record.

For example: <CustomerRefNo>Ref #369246</CustomerRefNo>


CustomsCP72V3Request / MailClass

optional Restricted use. For authorized users, if present, must contain one of the valid choices. Ignored for all other users.

string

enumerations= EMI PMI PMIFRESFRB FCMI MBAG PMEI

CustomsCP72V3Request / HoldForManifest

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

string enumerations= Y N


CustomsCP72V3Request / EELPFC

optional

EELPFC is synonymous with AES/ITN, which stands for the Automated Export Systems / International Transaction Number. International packages within certain categories, accepted by the Postal Service or any delivery company, must display an Internal Transaction Number (ITN) or an Automated Export System (AES) Exemption.

Please see

https://aesdirect.census.gov/ for details.

string


CustomsCP72V3Request / LabelDate

optional

Date the mail will enter the mail stream. No more than 3 days in the future. Default is day of request.

string

maxLength=10 pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?

CustomsCP72V3CertifyRequest required once

API=CustomsCP72V3Certify This API is used by integrators to provide samples and/or to evaluate their software without producing a "live" shipping document.

(alias)

3.1.3 Request Example

<CustomsCP72V3CertifyRequest USERID="xxx"> <Option /> <ImageParameters> <ImageParameter>4X6LABEL</ImageParameter> </ImageParameters> <FromFirstName>Joe</FromFirstName> <FromLastName>Wellsfargo</FromLastName> <FromFirm>Avanade Inc.</FromFirm> <FromAddress1>From Address 1</FromAddress1> <FromAddress2>7050 FAIRGROUNDS PKWY</FromAddress2> <FromUrbanization>From Urbanization</FromUrbanization> <FromCity>SAN ANTONIO</FromCity> <FromState>TX</FromState> <FromZip5>78238</FromZip5> <FromZip4>4540</FromZip4> <FromPhone>2985551212</FromPhone> <FromCustomsReference> From CustomsReference</FromCustomsReference> <ToFirstName>Zerah</ToFirstName> <ToLastName>Dacan</ToLastName> <ToFirm>Red‐Robin Bird Farm</ToFirm> <ToAddress3>2/25‐27 Birds Avenue</ToAddress3>

<ToAddress4>To Address 4</ToAddress4> <ToAddress5>To Address 5</ToAddress5> <ToPostalCode>2601</ToPostalCode> <ToCity>ACTON</ToCity> <ToCountry>Australia</ToCountry> <ToAPOFPOZip5 /> <ToPhone>1234567890</ToPhone> <ToFax>0987654321</ToFax> <ToEmail>[email protected]</ToEmail> <ToReference>To Reference</ToReference> <NonDeliveryOption>Return</NonDeliveryOption> <AltReturnAddress1 /> <AltReturnAddress2 /> <AltReturnAddress3 /> <AltReturnAddress4 /> <AltReturnAddress5 /> <AltReturnAddress6 /> <AltReturnCountry>Afghanistan</AltReturnCountry> <ShippingContents> <ItemDetail> <Description>Description 1</Description> <Quantity>1</Quantity> <Value>1.11</Value> <NetPounds></NetPounds> <NetOunces>1</NetOunces> <HSTariffNumber>123456</HSTariffNumber> <CountryOfOrigin>Brazil</CountryOfOrigin> </ItemDetail> <ItemDetail> <Description>Description 2</Description> <Quantity>2</Quantity> <Value>2.22</Value> <NetPounds></NetPounds> <NetOunces>2</NetOunces> <HSTariffNumber>234567</HSTariffNumber> <CountryOfOrigin>Switzerland</CountryOfOrigin> </ItemDetail> <ItemDetail> <Description>Description 3</Description> <Quantity>3</Quantity> <Value>3.33</Value> <NetPounds></NetPounds> <NetOunces>3</NetOunces> <HSTariffNumber>123456</HSTariffNumber> <CountryOfOrigin>Brazil</CountryOfOrigin> </ItemDetail> <ItemDetail> <Description>Description 4</Description> <Quantity>4</Quantity> <Value>4.44</Value> <NetPounds></NetPounds> <NetOunces>4</NetOunces> <HSTariffNumber>234567</HSTariffNumber> <CountryOfOrigin>Switzerland</CountryOfOrigin>

</ItemDetail> <ItemDetail> <Description>Description 5</Description> <Quantity>5</Quantity> <Value>5.55</Value> <NetPounds></NetPounds> <NetOunces>5</NetOunces> <HSTariffNumber>123456</HSTariffNumber> <CountryOfOrigin>Brazil</CountryOfOrigin> </ItemDetail> </ShippingContents> <InsuredNumber>Ins1234</InsuredNumber> <InsuredAmount>999.99</InsuredAmount> <SDRInsuredValue>123.56</SDRInsuredValue> <Postage>99.90</Postage> <GrossPounds>2</GrossPounds> <GrossOunces>8</GrossOunces> <DeliveryType>AIRMAIL</DeliveryType> <ContentType>Documents</ContentType> <ContentTypeOther>Type Other</ContentTypeOther> <Comments>This is a commment</Comments> <LicenseNumber>Lic1234</LicenseNumber> <CertificateNumber>Cert5678</CertificateNumber> <InvoiceNumber>Inv9090</InvoiceNumber> <ImageType>TIF</ImageType> <ImageLayout></ImageLayout> <CustomerRefNo>Customer Ref #</CustomerRefNo> <HoldForManifest>N</HoldForManifest> <EELPFC>NOEEI 30.37(a)</EELPFC> <LabelDate></LabelDate> </CustomsCP72V3CertifyRequest>

3.2 Customs Forms (CP72V3) Response

3.2.1 Response Parameters


CustomsCP72V3Response required once

(group)

CustomsCP72V3Response / Postage required once

Postage amount decimal

CustomsCP72V3Response / TotalValue

required once

Value of all items being shipped

decimal

CustomsCP72V3Response / CustomsBarcodeNumber

required once

Mail service related barcode

string

CustomsCP72V3Response / CP72V3Page1Image

required once

Encoded images of label (may be empty depending upon layout option selected)

base64Binary


required once


base64Binary


required once


base64Binary


required once


base64Binary


required once


base64Binary

CustomsCP72V3Response / CP72V3InstructionsImage

required once


base64Binary

CustomsCP72V3Response / Prohibitions

required once

List of items prohibited from mailing based on country of destination

string

CustomsCP72V3Response / Restrictions

required once

Restrictions on items being shipped based on country of destination

string

CustomsCP72V3Response / Observations

required once

Additional mailing information based on country of destination

string

CustomsCP72V3Response / CustomsForms

required once

Customs forms required to mail to destination country

string


CustomsCP72V3Response / Regulations

required once

Additional regulations for shipping to destination country

string

CustomsCP72V3Response / AdditionalRestrictions

required once

Additional restrictions on items being shipped to destination country

string

CustomsCP72V3CertifyResponse required once

(alias)

3.2.2 Response Example

<?xml version="1.0"?> <CustomsCP72V3CertifyResponse> <Postage>99.90</Postage> <TotalValue>16.65</TotalValue> <CustomsBarcodeNumber>CJXXXXXXXXXUS</CustomsBarcodeNumber> <CP72V3Page1Image>SUkqAAgAAAASAP4ABAAB <!‐‐ over 10000 suppressed ‐‐> </CP72V3Page1Image> <CP72V3Page2Image></CP72V3Page2Image> <CP72V3Page3Image></CP72V3Page3Image> <CP72V3Page4Image></CP72V3Page4Image> <CP72V3Page5Image></CP72V3Page5Image> <CP72V3InstructionsImage></CP72V3InstructionsImage> <Prohibitions>Coins; bank notes; currency notes (paper money); securities <!‐‐ suppressed ‐‐> <Restrictions>Jewelry is permitted only when sent as an insured parcel using Priority Mail <!‐‐ suppressed ‐‐> <Observations>Duty may be levied on catalogs, price lists, circulars, and all<!‐‐ suppressed ‐‐> <CustomsForms>First‐Class Mail International items and Priority Mail International Flat <!‐‐ suppressed ‐‐> <Regulations>Country Code:AU Reciprocal Service Name: Express Post Required Customs<!‐‐ suppressed ‐‐> <AdditionalRestrictions>No Additional Restrictions Data found.</AdditionalRestrictions> </CustomsCP72V3CertifyResponse>

3.3 Label Example