1.0 Introduction to Web Tools

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

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 “12345” with the destination Zip Code for your request.

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

2.0 Package Pickup Web Tools APIs

2.1 Overview

The Package Pickup Web Tools APIs provide convenience to you and your customers. Your carrier will pick up your packages on the next USPS delivery day (Monday through Saturday, excluding holidays) for free. Package Pickup is available for sending packages using Priority Mail Express, Priority Mail, Gound Advantage, international delivery services, or for returned merchandise. Customers requiring pickup of their packages by the USPS currently have two pickup options available to them: next delivery day Package Pickup and Pickup On-Demand. This Web Tools API User Guide applies to next delivery day Package Pickup only. Pickup On-Demand is only available through the USPS website. The information below is presented to illustrate the differences between these two options:

Recogida de Paquetes	Pickup on Demand (recogida por pedido)
Free, regardless of the number of packages.	Per pickup fee, regardless of the number of packages.
Your carrier picks up the next USPS delivery day when your mail is delivered.	Packages are picked up in a specified timeframe.
Available with domestic Priority Mail Express, Priority Mail, ExpressMail, Ground Advantage Commercial, international delivery services, or for merchandise returns.	Available for Express Mail, Priority Mail, single piece paid Standard Post, Express Mail International, Priority Mail International.
Requests must be received by 2:00 a.m. CT. You can edit or cancel a scheduled pickup request until 2:00 a.m. CT on the day of the pickup.	Allow a two-hour timeframe for pickups. Pickup must be cancelled before 5:00 a.m. local time the day of the pickup.
Individual items cannot exceed 70 pounds.	Individual items cannot exceed 70 pounds.
Postage must be prepaid and attached to package(s).	Apply postage to each package.
Packages must be properly sealed and ready for shipment.	Have your packages ready for pickup at the time and day specified.
Packages requiring insurance services need to be taken to a post office.

Full Package Pickup functionality relies on the implementation of five separate APIs:

· Package Pickup Availability API

· Package Pickup Schedule API

· Package Pickup Cancel API

· Package Pickup Change API

· Package Pickup Inquiry API

The five Package Pickup Web Tools work together to provide seamless service to you and your customers. Specifically, the functions of each are as follows:

Package Pickup Availability API checks the availability for Package Pickup at a specific address and informs the user of the first available date for pickup. El servicio de Recogida de Paquetes no se encuentra disponible para todas las direcciones.
Package Pickup Schedule API schedules a Package Pickup and provides the user a confirmation number for the scheduled pickup. Prior to making a Pickup Schedule call, it is recommended to use the Pickup Availability API to confirm that service is available.
Package Pickup Cancel API cancels a scheduled Package Pickup. To use either the Pickup Cancel or Pickup Change API, the exact data returned from the original Pickup Schedule API response must be entered. You must enter address information and the confirmation number. The confirmation number alone cannot be used to cancel or change a scheduled pickup. Address information must be identical to what was entered when the pickup was scheduled. To verify the accuracy of your data, you can use the Pickup Inquiry API.
Package Pickup Change API allows users to change certain data in their original Pickup Schedule request. To use either the Pickup Cancel or Pickup Change API, the exact data from the original Pickup Schedule API request must be entered. You must enter address information and the confirmation number. The confirmation number alone cannot be used to cancel or change a scheduled pickup. The name and phone number of the sender can be changed, along with the number and types of package services, the weight of the packages, and the location of the pickup. Address data and the confirmation number cannot be changed and must be identical to the original Schedule request. To verify the accuracy of your data, you can use the Pickup Inquiry API. Refer to the Delivery Timeline section for information regarding deadlines for changing pickups.
Package Pickup Inquiry API provides the data contained in your original Pickup Schedule request. To use either the Pickup Cancel or Pickup Change API, the exact data from the original Schedule API response must be entered. By using the Pickup Inquiry API, you can obtain the data needed.

For more information regarding Package Pickup Services, please visit https://faq.usps.com/s/article/What-is-Package-Pickup.

3.0 Package Pickup Availability API

3.1 Overview

The Package Pickup Availability API checks the availability for Package Pickup at a specific address and informs the user of the first available date for pickup. Package Pickup is not available for all addresses.

3.1.1 API Signature

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

3.2 Request Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupAvailabilityRequest	Obligatorio		(Alias)
CarrierPickupAvailabilityRequest / 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
CarrierPickupAvailabilityRequest / PASSWORD	Optional	This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. Por Ejemplo: PASSWORD="XXXXXXX"	NMTOKEN
CarrierPickupAvailabilityRequest/ FirmName	Optional	Use this tag for a firm or company name. FirmName is Optional except if needed to uniquely identify an address. Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address. Ejemplo: <FirmName>ABC Company</FirmName>	String	minLength=0 maxLength=50
CarrierPickupAvailabilityRequest/ SuiteOrApt	Obligatorio	Use this tag for an apartment or suite number. SuiteOrApt is Optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building. Por ejemplo: <SuiteOrApt>Suite 777</SuiteOrApt>	String	minLength=0 maxLength=50
CarrierPickupAvailabilityRequest/ Address2	Obligatorio	Use this tag for a street address. Por ejemplo: <Address2>1390 Market Street</Address2>	String	minLength=0 maxLength=50
CarrierPickupAvailabilityRequest/ Urbanization	Obligatorio	Use this tag for Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.	String	minLength=0 maxLength=28
CarrierPickupAvailabilityRequest/ City	Obligatorio	Use this tag for a city. Either ZIP5 or City and State are Required. Por ejemplo: <City>Houston</City>	String	minLength=0 maxLength=30
CarrierPickupAvailabilityRequest/ State	Obligatorio	Use this tag for a state abbreviation. Either ZIP5 or City and State are Required. Por ejemplo: <State>TX</State>	String	minLength=0 maxLength=2
CarrierPickupAvailabilityRequest/ ZIP5	Obligatorio	Use this tag for a 5 digit ZIP Code. Either ZIP5 or City and State are Required. Por ejemplo: <ZIP5>77058</ZIP5>	String	minLength=0 maxLength=5
CarrierPickupAvailabilityRequest/ ZIP4	Obligatorio	Maximum characters allowed: 4. Por ejemplo: <ZIP4>1234</ZIP4>	String	minLength=0 maxLength=4
CarrierPickupAvailabilityRequest/ Date	Optional	Use this tag to request a pickup date/time. Por ejemplo: 2006-05-04T18:13:51.0Z	String	minOccurs=0 maxOccurs=1
CarrierPickupAvailabilityRequest	Obligatorio		(Alias)

3.2.1 Sample Request

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<City>Houston</City>

</CarrierPickupAvailabilityRequest>

3.3 Response Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupAvailabilityResponse	Obligatorio		(Alias)
CarrierPickupAvailabilityResponse/ FirmName	Optional	Firm name sending request	String
CarrierPickupAvailabilityResponse/ SuiteOrApt	Obligatorio	Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)	String
CarrierPickupAvailabilityResponse/ Address2	Obligatorio	Pickup address	String
CarrierPickupAvailabilityResponse/ Urbanization	Obligatorio	Urbanización	String
CarrierPickupAvailabilityResponse/ City	Obligatorio	Pickup city	String
CarrierPickupAvailabilityResponse/ State	Obligatorio	Pickup state	String
CarrierPickupAvailabilityResponse/ ZIP5	Obligatorio	Pickup ZIP Code	String
CarrierPickupAvailabilityResponse/ ZIP4	Obligatorio	Pickup ZIP Code+4	String
CarrierPickupAvailabilityResponse/ DayOfWeek	Obligatorio	Day of week for pickup	String
CarrierPickupAvailabilityResponse/ Date	Obligatorio	Scheduled date for pickup	String
CarrierPickupAvailabilityResponse/ CarrierRoute	Optional	Carrier Route (can be C for City, H for Highway, R for Rural)	String
CarrierPickupAvailabilityResponse	Obligatorio		(Alias)

3.3.1 Sample Response

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<City>Houston</City>

<DayOfWeek>Monday</DayOfWeek>

</CarrierPickupAvailabilityResponse>

4.0 Package Pickup Schedule API

4.1 Overview

The Package Pickup Schedule API schedules a Package Pickup and provides the user a confirmation number for the scheduled pickup. Prior to making a Pickup Schedule call, it is recommended to use the Pickup Availability API to confirm that service is available.

4.1.1 API Signature

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

4.2 Request Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupScheduleRequest	Obligatorio		(Alias)
CarrierPickupScheduleRequest / 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
CarrierPickupScheduleRequest / PASSWORD	Optional	This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. Por Ejemplo: PASSWORD="XXXXXXX"	NMTOKEN
CarrierPickupScheduleRequest / FirstName	Obligatorio	Only alpha characters, apostrophes, spaces, periods, and hyphens "-" may be used. For example: <FirstName>Juan</FirstName>	String	minLength=0 maxLength=50
CarrierPickupScheduleRequest / LastName	Obligatorio	Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used. Por ejemplo: <LastName>Pérez</LastName>	String	minLength=0 maxLength=50
CarrierPickupScheduleRequest / FirmName	Optional	Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used. Use this tag for a firm or company name. Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address. Nota: FirmName is Optional except if the First Name and Last Name tags are null. Por ejemplo: <FirmName>ABC Company</FirmName>	String	minLength=0 maxLength=50
CarrierPickupScheduleRequest / SuiteOrApt	Obligatorio	Apartment or suite number. Optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building. Por ejemplo: <SuiteOrApt>Suite 777</SuiteOrApt>	String	minLength=0 maxLength=50
CarrierPickupScheduleRequest / Address2	Obligatorio	Street address. Por ejemplo: <Address2>1390 MARKET STREET</Address2>	String	minLength=0 maxLength=50
CarrierPickupScheduleRequest / Urbanization	Obligatorio	Use this tag for Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.	String	minLength=0 maxLength=28
CarrierPickupScheduleRequest / City	Obligatorio	City name. Either ZIP5 or City and State are required. For example: <City>Houston</City>	String	minLength=0 maxLength=30
CarrierPickupScheduleRequest / State	Obligatorio	State abbreviation. Either ZIP5 or City and State are required. Por ejemplo: <State>TX</State>	String	minLength=0 maxLength=2
CarrierPickupScheduleRequest / ZIP5	Obligatorio	5-digit ZIP Code. Either ZIP5 or City and State are required. For example: <ZIP5>77058</ZIP5>	String	minLength=0 maxLength=5
CarrierPickupScheduleRequest / ZIP4	Obligatorio	Use this tag for a 4 digit ZIP Code. Por ejemplo: <ZIP4>1234</ZIP4>	String	minLength=0 maxLength=4
CarrierPickupScheduleRequest / Phone	Obligatorio	Two formats are allowed: (###) 123-4567 or ###-123-4567. Por ejemplo: <Phone>5555551234</Phone> or <Phone>555-555-1234</Phone>	String	minLength=0 maxLength=14
CarrierPickupScheduleRequest / Extension	Optional	Optional value for Phone Extension. Por ejemplo: <Extension>201</Extension>	String	minOccurs=0 minLength=0 maxLength=4
CarrierPickupScheduleRequest / Package	Obligatorio	No values entered with this tag. <ServiceType> and <Count> tags are embedded under this. Refer to the XML request example section, below, to see how these embedded tags are formatted. If the <Count> for a service type is zero, you do not need to encode a <Package> but you must have at least one <Package> with embedded <ServiceType> and <Count> tags.	(Group)
CarrierPickupScheduleRequest / Package/ ServiceType	Obligatorio	This tag is embedded under the <Package> tag. If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags. Refer to the XML Request Example below to see how these embedded tags are formatted. For example: <ServiceType>PriorityMailExpress</ServiceType> Nota: A pickup cannot be scheduled or changed when there are only packages with <ServiceType>="OtherPackages”	String	minLength="0" Enumeration= · PriorityMailExpress · PriorityMail · ExpressMail · GroundAdvantage · Returns · International · OtherPackages
CarrierPickupScheduleRequest / Package/ Count	Obligatorio	This tag is embedded under the <Package> tag. Enter the number of packages for the accompanying <ServiceType> tag. Maximum characters allowed: 3 or 999 packages. If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags. Refer to the XML request example section, below, to see how these embedded tags are formatted. Por ejemplo: <Count>2</Count>	String	minLength=0 maxLength=3 minInclusive=1 maxInclusive=999
CarrierPickupScheduleRequest / EstimatedWeight	Obligatorio	Enter the estimated aggregate weight (in pounds) of all packages being picked up. For example: <EstimatedWeight>14</EstimatedWeight>	String	minLength=0 maxLength=5
CarrierPickupScheduleRequest / PackageLocation	Obligatorio	Enter one of the following values: Nota: "Other" requires information in the value for the <SpecialInstructions> tag. Por ejemplo: <PackageLocation>Front Door</PackageLocation>	String	Enumeration= · Front Door · Back Door · Side Door · Knock on Door/Ring Bell · Mail Room · Office · Reception · In/At Mailbox · Other
CarrierPickupScheduleRequest / SpecialInstructions	Optional / Required	Value Required when PackageLocation is “Other”. Only alpha, numeric, commas, periods, apostrophes, _, &, -, ( ), ?, #, / +, @ and space characters may be used. Por ejemplo: <SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>	String	minLength=0 maxLength=255
CarrierPickupScheduleRequest / EmailAddress	Optional	If provided, email notifications will be sent confirming package pickup, or request changes and cancellations. Maximum characters allowed: 50. Por ejemplo: <EmailAddress>cpapple@email.com</EmailAddress>	String	minOccurs=0 minLength=0 maxLength=255
CarrierPickupScheduleRequest	Obligatorio		(Alias)

4.2.1 Sample Request

<LastName>Pérez</LastName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<City>Houston</City>

<ServiceType>PriorityMailExpress</ServiceType>

</Package>

<ServiceType>PriorityMail</ServiceType>

</Package>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

</CarrierPickupScheduleRequest>

4.3 Response Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupScheduleResponse	Obligatorio		(Alias)
CarrierPickupScheduleResponse / FirstName	Obligatorio	First name of person sending request.	String
CarrierPickupScheduleResponse / LastName	Obligatorio	Last name of person sending request.	String
CarrierPickupScheduleResponse / FirmName	Optional	Firm name sending request (if supplied in request).	String
CarrierPickupScheduleResponse / SuiteOrApt	Obligatorio	Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address).	String
CarrierPickupScheduleResponse / Address2	Obligatorio	Pickup address	String
CarrierPickupScheduleResponse / Urbanization	Obligatorio	Urbanization (if supplied in request).	String
CarrierPickupScheduleResponse / City	Obligatorio	Pickup city.	String
CarrierPickupScheduleResponse / State	Obligatorio	Pickup state.	String
CarrierPickupScheduleResponse / ZIP5	Obligatorio	Pickup ZIP Code.	String
CarrierPickupScheduleResponse / ZIP4	Obligatorio	Pickup ZIP Code+4.	String
CarrierPickupScheduleResponse / Phone	Obligatorio	Phone number of the sender.	String
CarrierPickupScheduleResponse / Extension	Obligatorio	Phone extension of sender (if supplied in request).	String
CarrierPickupScheduleResponse / Package	Obligatorio	Packages to be picked up. Can be multiple <Packages> with accompanying <ServiceType> and <Count> tags.	(Group)
CarrierPickupScheduleResponse / Package/ ServiceType	Obligatorio	Types of package services requested.	String
CarrierPickupScheduleResponse / Package/ Count	Obligatorio	Number of packages for each service type requested.	String
CarrierPickupScheduleResponse / EstimatedWeight	Obligatorio	Total estimated weight of all packages to be picked up.	String
CarrierPickupScheduleResponse / PackageLocation	Obligatorio	Location of pickup.	String
CarrierPickupScheduleResponse / SpecialInstructions	Obligatorio	Special instructions for pickup.	String
CarrierPickupScheduleResponse / ConfirmationNumber	Obligatorio	Confirmation number for pickup.	String
CarrierPickupScheduleResponse / DayOfWeek	Obligatorio	Day of week for pickup.	String
CarrierPickupScheduleResponse / Date	Obligatorio	Scheduled date for pickup.	String
CarrierPickupScheduleResponse / CarrierRoute	Optional	Carrier Route (can be C for City, H for Highway, R for Rural).	String
CarrierPickupScheduleResponse / EmailAddress	Optional	Email Address (if supplied in request).	String
CarrierPickupScheduleResponse	Obligatorio		(Alias)

4.3.1 Sample Response

<LastName>Pérez</LastName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<City>Houston</City>

<ServiceType>PriorityMailExpress</ServiceType>

</Package>

<ServiceType>PriorityMail</ServiceType>

</Package>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions> Packages are behind the screen door.</SpecialInstructions>

<DayOfWeek>Monday</DayOfWeek>

</CarrierPickupScheduleResponse>

5.0 Package Pickup Cancel API

5.1 Overview

The Package Pickup Cancel API cancels a scheduled Package Pickup. To use either the Pickup Cancel or Pickup Change Web Tools, the exact data from the original Schedule API response must be entered. You must enter address information and the confirmation number. Confirmation number alone cannot be used to cancel or change a scheduled pickup. Address information must be identical to what was entered when the pickup was scheduled.

5.1.1 API Signature

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

5.2 Request Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupCancelRequest	Obligatorio		(Alias)
CarrierPickupCancelRequest / 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
CarrierPickupCancelRequest / PASSWORD	Optional	This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. Por Ejemplo: PASSWORD="XXXXXXX"	NMTOKEN
CarrierPickupCancelRequest/ FirmName	Optional	Maximum characters allowed: 50. Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used. Firm or company name is optional except if needed to uniquely identify an address. Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address. Por ejemplo: <FirmName>ABC Company</FirmName>	String	minLength=0 maxLength=50
CarrierPickupCancelRequest/ SuiteOrApt	Obligatorio	Apartment or suite number. Optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building. Por ejemplo: <SuiteOrApt>Suite 777</SuiteOrApt>	String	minLength=0 maxLength=50
CarrierPickupCancelRequest/ Address2	Obligatorio	Street address. Por ejemplo: <Address2>1390 MARKET STREET</Address2>	String	minLength=0 maxLength=50
CarrierPickupCancelRequest/ Urbanization	Obligatorio	Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.	String	minLength=0 maxLength=28
CarrierPickupCancelRequest/ City	Obligatorio	City name. Either ZIP5 or City and State are Required Por ejemplo: <City>Houston</City>	String	minLength=0 maxLength=30
CarrierPickupCancelRequest/ State	Obligatorio	State abbreviation. Either ZIP5 or City and State are Required. Por ejemplo: <State>TX</State>	String	minLength=0 maxLength=2
CarrierPickupCancelRequest/ ZIP5	Obligatorio	5 digit ZIP Code. Either ZIP5 or City and State are Required. Por ejemplo: <ZIP5>77058</ZIP5>	String	minLength=0 maxLength=5
CarrierPickupCancelRequest/ ZIP4	Obligatorio	4 digit ZIP Code. Por ejemplo: <ZIP4>1234</ZIP4>	String	minLength=0 maxLength=4
CarrierPickupCancelRequest/ ConfirmationNumber	Obligatorio	Enter exact Confirmation Number returned with Package Pickup Schedule request. Por ejemplo: <ConfirmationNumber>ABC12345</ConfirmationNumber>	String	minLength=0 maxLength=30
CarrierPickupCancelRequest	Obligatorio		(Alias)

5.2.1 Sample Request

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<City>Houston</City>

</CarrierPickupCancelRequest>

5.3 Response Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupCancelResponse	Obligatorio		(Alias)
CarrierPickupCancelResponse/ FirmName	Obligatorio	Firm name sending request (if supplied in request)	String
CarrierPickupCancelResponse/ SuiteOrApt	Obligatorio	Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)	String
CarrierPickupCancelResponse/ Address2	Obligatorio	Pickup address	String
CarrierPickupCancelResponse/ Urbanization	Obligatorio	Urbanization (if supplied in request)	String
CarrierPickupCancelResponse/ City	Obligatorio	Pickup city	String
CarrierPickupCancelResponse/ State	Obligatorio	Pickup state	String
CarrierPickupCancelResponse/ ZIP5	Obligatorio	Pickup ZIP Code	String
CarrierPickupCancelResponse/ ZIP4	Obligatorio	Pickup ZIP Code+4 (if supplied in request)	String
CarrierPickupCancelResponse/ ConfirmationNumber	Obligatorio	Confirmation number for pickup	String
CarrierPickupCancelResponse/ Status	Obligatorio	Status of request to cancel	String
CarrierPickupCancelResponse	Obligatorio	Type of Response	(Alias)

5.3.1 Sample Response

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<City>Houston</City>

<Status>Your pickup request was cancelled.</Status>

</CarrierPickupCancelRequest>

6.0 Package Pickup Change API

6.1 Overview

Allows users to change certain data in their original Pickup Schedule API request. To use either the Pickup Cancel or Pickup Change API, the exact data from the original Pickup Schedule API response must be entered. You must enter address information and the confirmation number. The confirmation number alone cannot be used to cancel or change a scheduled pickup. The number and types of package services, the weight of the packages, and the location of the pickup can be changed. Address data and the confirmation number cannot be changed and must be identical to the original Schedule request. To verify the accuracy of your data, you can use the Pickup Inquiry API.

6.1.1 API Signature

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

6.2 Request Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupChangeRequest	Obligatorio		(Alias)
CarrierPickupChangeRequest / 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
CarrierPickupChangeRequest / PASSWORD	Optional	This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. Por Ejemplo: PASSWORD="XXXXXXX"	NMTOKEN
CarrierPickupChangeRequest/ FirstName	Obligatorio	Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used. Por ejemplo: <FirstName>Juan</FirstName>	String	minLength=0 maxLength=50
CarrierPickupChangeRequest/ LastName	Obligatorio	Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used. Por ejemplo: <LastName>Pérez</LastName>	String	minLength=0 maxLength=50
CarrierPickupChangeRequest/ FirmName	Optional	Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used. Use this tag for a firm or company name. FirmName is Optional except if First Name and Last Name tags are null. Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address. Por ejemplo: <FirmName>ABC Company</FirmName>	String	minLength=0 maxLength=50
CarrierPickupChangeRequest/ SuiteOrApt	Optional	Apartment or suite number. Optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building. Por ejemplo: <SuiteOrApt>Suite 777</SuiteOrApt>	String	minLength=0 maxLength=50
CarrierPickupChangeRequest/ Address2	Obligatorio	Use this tag for a street address. Por ejemplo: <Address2>1390 MARKET STREET</Address2>	String	minLength=0 maxLength=50
CarrierPickupChangeRequest/ Urbanization	Obligatorio	Use this tag for Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.	String	minLength=0 maxLength=28
CarrierPickupChangeRequest/ City	Obligatorio	Use this tag for a city. Either ZIP5 or City and State are Required. Por ejemplo: <City>Houston</City>	String	minLength=0 maxLength=30
CarrierPickupChangeRequest/ State	Obligatorio	Use this tag for a state abbreviation. Either ZIP5 or City and State are Required. Por ejemplo: <State>TX</State>	String	minLength=0 maxLength=2
CarrierPickupChangeRequest/ ZIP5	Obligatorio	Use this tag for a 5 digit ZIP Code. Either ZIP5 or City and State are Required. Por ejemplo: <ZIP5>77058</ZIP5>	String	minLength=0 maxLength=5
CarrierPickupChangeRequest/ ZIP4	Obligatorio	Use this tag for a 4 digit ZIP Code. Por ejemplo: <ZIP4>1234</ZIP4>	String	minLength=0 maxLength=4
CarrierPickupChangeRequest/ Phone	Obligatorio	Two formats are allowed: (###) 123-4567 or ###-123-4567. Por ejemplo: <Phone>(555) 555-1234</Phone> or <Phone>555-555-1234</Phone>	String	minLength=0 maxLength=14
CarrierPickupChangeRequest/ Extension	Obligatorio	Extension related to the Phone Number For example: <Extension>201</Extension>	String	minLength=0 maxLength=4
CarrierPickupChangeRequest/ Package	Obligatorio	No values entered with this tag. <ServiceType> and <Count> tags are embedded under this. Refer to the XML request example section, below, to see how these embedded tags are formatted. If the <Count> for a service type is zero, you do not need to encode a <Package> but you must have at least one <Package> with embedded <ServiceType> and <Count> tags.	(Group)
CarrierPickupChangeRequest/ Package/ ServiceType	Obligatorio	This tag is embedded under the <Package> tag. If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags. Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted. Por ejemplo: <ServiceType>PriorityMailExpress</ServiceType> Nota: A pickup cannot be scheduled or changed when there are only packages with <ServiceType>= "OtherPackages”	String	Enumerations: · PriorityMailExpress · PriorityMail · ExpressMail · GroundAdvantage · Returns · International · OtherPackages
CarrierPickupChangeRequest/ Package/ Count	Obligatorio	This tag is embedded under the <Package> tag. Enter the number of packages for the accompanying <ServiceType> tag. Maximum characters allowed: 3 or 999 packages There must be at least one Priority Mail Express Package or one Priority Mail package or one returned merchandise package to make this a valid request. If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags. Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted. Por ejemplo: <Count>2</Count>	String	minLength=0 maxLength=3 minInclusive=1 maxInclusive=999
CarrierPickupChangeRequest/ EstimatedWeight	Obligatorio	Enter the estimated aggregate weight (in pounds) of all packages being picked up. For example: <EstimatedWeight>14</EstimatedWeight>	String	minLength=0 maxLength=5
CarrierPickupChangeRequest/ PackageLocation	Obligatorio	Nota: "Other" requires information in the value for the <SpecialInstructions> tag. Por ejemplo: <PackageLocation>Front Door</PackageLocation>	String	Enumeration: · Front Door · Back Door · Side Door · Knock on Door/Ring Bell · Mail Room · Office · Reception · In/At Mailbox · Other
CarrierPickupChangeRequest/ SpecialInstructions	Optional / Required	Only alpha, numeric, commas, periods, apostrophes, _, &, -, ( ), ?, #, / +, @ and space characters may be used. Required when Package Location tag is “Other” Por ejemplo: <SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>	String	minLength=0 maxLength=255
CarrierPickupChangeRequest/ ConfirmationNumber	Obligatorio	Enter exact Confirmation Number returned with Package Pickup Schedule request. Por ejemplo: ConfirmationNumber>ABC12345</ConfirmationNumber>	String	minLength=0 maxLength=30
CarrierPickupChangeRequest/ EmailAddress	Optional	If provided, email notifications will be sent confirming package pickup, or request changes and cancellations. Maximum characters allowed: 50. Por ejemplo: <EmailAddress>cpapple@email.com</EmailAddress>	String	minOccurs="0" minLength=0 maxLength=50
CarrierPickupChangeRequest	Obligatorio		(Alias)

6.2.1 Sample Request

<LastName>Pérez</LastName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<City>Houston</City>

<ServiceType>PriorityMailExpress</ServiceType>

</Package>

<ServiceType>PriorityMail</ServiceType>

</Package>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions> Packages are behind the screen door.</SpecialInstructions>

</CarrierPickupChangeRequest>

6.3 Response Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupChangeResponse	Obligatorio		(Alias)
CarrierPickupChangeResponse/ FirstName	Obligatorio	First name of person sending request	String
CarrierPickupChangeResponse/ LastName	Obligatorio	Last name of person sending request	String
CarrierPickupChangeResponse/ FirmName	Optional	Firm name sending request (if supplied in request)	String
CarrierPickupChangeResponse/ SuiteOrApt	Obligatorio	Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)	String
CarrierPickupChangeResponse/ Address2	Obligatorio	Pickup address	String
CarrierPickupChangeResponse/ Urbanization	Obligatorio	Urbanization (if supplied in request)	String
CarrierPickupChangeResponse/ City	Obligatorio	Pickup city	String
CarrierPickupChangeResponse/ State	Obligatorio	Pickup state	String
CarrierPickupChangeResponse/ ZIP5	Obligatorio	Pickup ZIP Code	String
CarrierPickupChangeResponse/ ZIP4	Obligatorio	Pickup ZIP Code+4	String
CarrierPickupChangeResponse/ Phone	Obligatorio	Phone number of sender	String
CarrierPickupChangeResponse/ Extension	Obligatorio	Phone extension of sender (if supplied in request)	String
CarrierPickupChangeResponse/ Package	Obligatorio	Packages to be picked up (multiple <Package> tags can be returned with accompanying <ServiceType> and <Count> tags.	(group)
CarrierPickupChangeResponse/ Package/ ServiceType	Obligatorio	Types of package services requested	String
CarrierPickupChangeResponse/ Package/ Count	Obligatorio	Number of packages for each service type requested	String
CarrierPickupChangeResponse/ EstimatedWeight	Obligatorio	Total estimated weight of all packages to be picked up	String
CarrierPickupChangeResponse/ PackageLocation	Obligatorio	Location of pickup	String
CarrierPickupChangeResponse/ SpecialInstructions	Optional	Special instructions for pickup	String
CarrierPickupChangeResponse/ ConfirmationNumber	Obligatorio	Confirmation number for pickup	String
CarrierPickupChangeResponse/ DayOfWeek	Obligatorio	Day of week for pickup	String
CarrierPickupChangeResponse/ Date	Obligatorio	Scheduled date for pickup	String
CarrierPickupChangeResponse/ Status	Optional	Status of request to change	String
CarrierPickupChangeResponse/ EmailAddress	Optional	Email Address (if supplied in request)	String
CarrierPickupChangeResponse	Obligatorio		(Alias)

6.3.1 Sample Response

<LastName>Pérez</LastName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<City>Houston</City>

<ServiceType>PriorityMailExpress</ServiceType>

</Package>

<ServiceType>PriorityMail</ServiceType>

</Package>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

<DayOfWeek>Monday</DayOfWeek>

<Status>Actualización exitosa</Status>

</CarrierPickupChangeResponse>

7.0 Package Pickup Inquiry API

7.1 Overview

The Package Pickup Inquiry API provides the data contained in your original Pickup Schedule request. To use either the Pickup Cancel or Pickup Change API, the exact data from the original Schedule response must be entered. By using the Pickup Inquiry API, you can obtain the data needed.

7.1.1 API Signature

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

7.2 Request Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupInquiryRequest	Obligatorio		(Alias)
CarrierPickupInquiryRequest / 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
CarrierPickupInquiryRequest / PASSWORD	Optional	This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. Por Ejemplo: PASSWORD="XXXXXXX"	NMTOKEN
CarrierPickupInquiryRequest / FirmName	Optional	Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used. Firm or company name is optional except if needed to uniquely identify an address. Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address. Por ejemplo: <FirmName>ABC Company</FirmName>	String	minLength=0 maxLength=50
CarrierPickupInquiryRequest / SuiteOrApt	Obligatorio	Apartment or suite number is optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building. Por ejemplo: <SuiteOrApt>Suite 777</SuiteOrApt>	String	minLength=0 maxLength=50
CarrierPickupInquiryRequest / Address2	Obligatorio	Use this tag for a street address. Por ejemplo: <Address2>1390 MARKET STREET</Address2>	String	minLength=0 maxLength=50
CarrierPickupInquiryRequest / Urbanization	Obligatorio	Use this tag for an Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.	String	minLength=0 maxLength=28
CarrierPickupInquiryRequest / City	Obligatorio	Use this tag for a city. Either ZIP5 or City and State are Required Por ejemplo: <City>Houston</City>	String	minLength=0 maxLength=30
CarrierPickupInquiryRequest / State	Obligatorio	Use this tag for a state abbreviation. Either ZIP5 or City and State are Required. Por ejemplo: <State>TX</State>	String	minLength=0 maxLength=2
CarrierPickupInquiryRequest / ZIP5	Obligatorio	Use this tag for a 5 digit ZIP Code. Maximum characters allowed: 5. Either ZIP5 or City and State are Required. Por ejemplo: <ZIP5>77058</ZIP5>	String	minLength=0 maxLength=5
CarrierPickupInquiryRequest / ZIP4	Obligatorio	Maximum characters allowed: 4. Por ejemplo: <ZIP4>1234</ZIP4>	String	minLength=0 maxLength=4
CarrierPickupInquiryRequest / ConfirmationNumber	Obligatorio	Enter exact Confirmation Number returned with Package Pickup Schedule request. Por ejemplo: <ConfirmationNumber>ABC12345</ConfirmationNumber>	String	minLength=1 maxLength=30
CarrierPickupInquiryRequest	Obligatorio		(Alias)

7.2.1 Sample Request

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 MARKET STREET</Address2>

<City>Houston</City>

</CarrierPickupInquiryRequest>

7.3 Response Descriptions

Tag Name	Occurs	Descripción	Tipo	Validation
CarrierPickupInquiryResponse/	Obligatorio		(Alias)
CarrierPickupInquiryResponse/ FirstName	Obligatorio	First name of person sending request	String
CarrierPickupInquiryResponse/ LastName	Obligatorio	Last name of person sending request	String
CarrierPickupInquiryResponse/ FirmName	Obligatorio	Firm name sending request (if supplied in request)	String
CarrierPickupInquiryResponse/ SuiteOrApt	Obligatorio	Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)	String
CarrierPickupInquiryResponse/ Address2	Obligatorio	Pickup address	String
CarrierPickupInquiryResponse/ Urbanization	Obligatorio	Urbanization (if supplied in request)	String
CarrierPickupInquiryResponse/ City	Obligatorio	Pickup city	String
CarrierPickupInquiryResponse/ State	Obligatorio	Pickup state	String
CarrierPickupInquiryResponse/ ZIP5	Obligatorio	Pickup ZIP Code	String
CarrierPickupInquiryResponse/ ZIP4	Obligatorio	Pickup ZIP Code+4	String
CarrierPickupInquiryResponse/ Phone	Obligatorio	Phone number of the sender.	String
CarrierPickupInquiryResponse/ Extension	Obligatorio	Phone extension of sender (if supplied in request)	String
CarrierPickupInquiryResponse/ Package	Obligatorio	Packages to be picked up (multiple <Package> tags can be returned with accompanying <ServiceType> and <Count> tags.	(group)
CarrierPickupInquiryResponse/ Package/ ServiceType	Obligatorio	Types of package services requested	String
CarrierPickupInquiryResponse/ Package/ Count	Obligatorio	Number of packages for each service type requested	String
CarrierPickupInquiryResponse/ EstimatedWeight	Obligatorio	Total estimated weight of all packages to be picked up	String
CarrierPickupInquiryResponse/ PackageLocation	Obligatorio	Location of pickup	String
CarrierPickupInquiryResponse/ SpecialInstructions	Obligatorio	Special instructions for pickup	String
CarrierPickupInquiryResponse/ ConfirmationNumber	Obligatorio	Confirmation number for pickup	String
CarrierPickupInquiryResponse/ DayOfWeek	Obligatorio	Day of week for pickup	String
CarrierPickupInquiryResponse/ Date	Obligatorio	Scheduled date for pickup	String
CarrierPickupInquiryResponse/ EmailAddress	Optional	Dirección de correo electrónico	String
CarrierPickupInquiryResponse/	Obligatorio		(Alias)

7.3.1 Sample Response

<LastName>Pérez</LastName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<City>Houston</City>

<ServiceType>PriorityMailExpress</ServiceType>

</Package>

<ServiceType>PriorityMail</ServiceType>

</Package>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions> Packages are behind the screen door.</SpecialInstructions>

<DayOfWeek>Monday</DayOfWeek>

</CarrierPickupInquiryResponse>