API Reference | ReDoc

Pickup

Using the Pickup API, applications can schedule pickups, manage previously scheduled pickups, or cancel previously scheduled pickups.

Reference


Try out UPS APIs with example requests using Postman. Explore API documentation and sample applications through GitHub.

Run In Postman Open in GitHub

Pickup Rate

Using the POST operation of the pickuptype endpoint within the Pickup API, users can request rates for UPS on-demand package pickup. The endpoint allows users to specify pickup details like address, date/time, and other options, and returns pricing information for booking that pickup.

SecurityOAuth2
Request
path Parameters
version
required
string >= 1
Default: "v2409"

Version of the API.

Valid values:

  • v2409
pickuptype
required
string >= 1

Type of pickup. Valid values: oncall smart both. Length 6

header Parameters
transId
string

An identifier unique to the request. Length 32

transactionSrc
string
Default: testing

An identifier of the client/source application that is making the request.Length 512

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1
required
object (PickupRateRequest) <= 1

This request is used to rate an on-callpickup.

required
object (PickupRateRequest_Request) <= 1

Common element for all services

RequestOption
string [ 1 .. 15 ] characters

Not used by pick up

SubVersion
string = 4 characters <= 1

When UPS introduces new elements in the response that are not associated with new request elements, Subversion is used. This ensures backward compatibility.

To get such elements you need to have the right Subversion. The value of the subversion is explained in the Response element Description. Supported values: 1607, 1707,2007

Example: Itemized Charges are returned only when the Subversion element is present and greater than or equal to '1601'.

Format: YYMM = Year and month of the release. Example: 1601 = 2016 January

object (Pickup_components-schemas-Request_TransactionReference) <= 1

Transaction Reference Container

object (PickupRateRequest_ShipperAccount) <= 1

Shipper account information.

AccountNumber
required
string [ 6 .. 10 ] characters <= 1

UPS account number. Shipper's (requester of the pickup) UPS account number

AccountCountryCode
required
string = 2 characters <= 1

Country code as defined by ISO-3166. Refer to Country or Territory Codes in the Appendix for valid values.

required
object (PickupRateRequest_PickupAddress) <= 1

The address to pickup the packages

AddressLine
string [ 1 .. 73 ] characters <= 1

Detailed street address. For Jan. 2010 release, only one AddressLine is allowed.

City
required
string [ 1 .. 50 ] characters <= 1

City or equivalent

StateProvince
string [ 1 .. 50 ] characters <= 1

State province code or equivalent

PostalCode
required
string [ 1 .. 8 ] characters <= 1

Postal code for countries with postal codes.

CountryCode
required
string = 2 characters <= 1

Upper-case two-char long country code as defined by ISO-3166. Refer to Country or Territory Codes in the Appendix for valid values.

ResidentialIndicator
required
string = 1 characters <= 1

Indicates if the pickup address is commerical or residential. Valid values: Y = Residential address N = Non-residential (Commercial) address (default)

AlternateAddressIndicator
required
string = 1 characters <= 1

Indicates if the pickup address is different than the address specified in the customer's profile.
Valid values: Y = Alternate address N = Original pickup address (default)

ServiceDateOption
required
string = 1 characters <= 1

Indicates the pickup timeframe.

  • 01 = Same-Day Pickup
  • 02 = Future-Day Pickup
  • 03 = A Specific-Day Pickup

If 03 is selected, then PickupDate, EarliestReadyTime, and LatestClosetime must be specified.

object (PickupRateRequest_PickupDateInfo) <= 1

Required if the ServiceDateOption is: 03 A Specific-Day Pickup

CloseTime
required
string = 4 characters <= 1

The latest local close time. Format: HHmm

  • Hour: 0-23
  • Minute: 0-59
ReadyTime
required
string = 4 characters <= 1

The earliest local ready Time. Format: HHmm

  • Hour: 0-23
  • Minute: 0-59
PickupDate
required
string = 8 characters <= 1

The specific local pickup date. Format: yyyyMMdd

  • yyyy = Year Applicable
  • MM = 01-12
  • dd = 01-31
RateChartType
string = 1 characters <= 1

Rate Type with which pickup is rated. Possible RateChart values for different regions will be:

US 48 origin: 1 – Daily Rates 3 – Standard List Rates 4 – Retail Rates.

Alaska/Hawaii origin: 1 – Daily Rates 3 – Standard List Rates 4 – Retail Rates.

All Other origins: 1 – Rates 5 - Regional Rates 6 - General List Rates.

3 and 4 do not apply

TaxInformationIndicator
string = 1 characters <= 1

Indicates whether to return detailed taxes for on-callpickups. Valid values:

  • Y = Rate this pickup with taxes
  • N = Do not rate this pickup with taxes (default)
UserLevelDiscountIndicator
string = 1 characters <= 1

Indicates whether to return user level promo discount for the on-callpickups. Valid values: Y = Rate this pickup with user level promo discount N = Do not rate this pickup with user level promo discount(default)

Responses
200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/shipments/{version}/pickup/{pickuptype}
Request samples
application/json
{
  • "PickupRateRequest": {
    }
}
Response samples
application/json
{
  • "PickupRateResponse": {
    }
}

Pickup Pending Status

Using the GET operation of the pickuptype endpoint within the Pickup API, users can retrieve the status of shipments sent via UPS pickup service. The endpoint uses the account number as a required parameter and returns a status of received/dispatched/completed/incomplete/updated ETA, or cancelled.

SecurityOAuth2
Request
path Parameters
version
required
string >= 1
Default: "v2409"

Version of API

Valid values:

  • v2409
pickuptype
required
string >= 1

Type of pickup. Valid values: oncall smart both. Length 6

header Parameters
transId
string

An identifier unique to the request. Length 32

transactionSrc
string
Default: testing

An identifier of the client/source application that is making the request.Length 512

AccountNumber
required
string

The specific account number that belongs to the shipper.Length 6 or 10

Responses
200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

get/shipments/{version}/pickup/{pickuptype}
Request samples 
Response samples 
application/json
{
  • "PickupPendingStatusResponse": {
    }
}
Pickup Cancel
Using the CancelBy endpoint of the Pickup API, users can request cancellation of a UPS on-demand package pickup. When the PRN (pickup request number), transaction ID, and the transaction source are supplied as required parameters, the endpoint returns confirmation that the pickup has been cancelled.


SecurityOAuth2 
Request 
path Parameters
CancelBy
required
string
Valid Values: 01 = AccountNumber, 02 = PRN


 
version
required
string  >= 1 
 Default:  "v2409"
Version of API.


Valid values:


    

  • v2409
    • 



 
header Parameters
transId
string
An identifier unique to the request. Length 32


 
transactionSrc
string
 Default:  testing
An identifier of the client/source application that is making the request.Length 512


 
Prn
string
The pickup equest number (PRN) generated by 
UPS pickup system.
Required if CancelBy = prn.Length 26


 
Responses 
200
successful operation


400
Invalid Request


401
Unauthorized Request


403
Blocked Merchant


429
Rate Limit Exceeded


delete/shipments/{version}/pickup/{CancelBy}
Request samples 
Response samples 
application/json
{
  • "PickupCancelResponse": {
    }
}
Pickup Creation
Using the Pickup API, applications can schedule pickups, manage previously scheduled pickups, or cancel previously scheduled pickups.


SecurityOAuth2 
Request 
path Parameters
version
required
string  >= 1 
 Default:  "v2409"
Version of the API.


Valid values:


    

  • v2409
    • 



 
header Parameters
transId
string
An identifier unique to the request. Length 32


 
transactionSrc
string
 Default:  testing
An identifier of the client/source application that is making the request.Length 512


 
Request Body schema: application/json
Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".


  <= 1 
required
object (PickupCreationRequest)   <= 1 
This request is for scheduling an on-call pickup


 
required
object (PickupCreationRequest_Request)   <= 1 
Common element for all services


 
SubVersion
string  = 4 characters  <= 1 
When UPS introduces new elements in the response that are not associated with new request elements, Subversion is used. This ensures backward compatibility.


To get such elements you need to have the right Subversion. The value of the subversion is explained in the Response element Description. Supported values: 1607, 1707,2007


Example: Itemized Charges are returned only when the Subversion element is present and greater than or equal to '1601'. 


Format: YYMM = Year and month of the release.
Example: 1601 = 2016 January


 
object (Pickup_components-schemas-Request_TransactionReference)   <= 1 
Transaction Reference Container


 
RatePickupIndicator
required
string  = 1 characters  <= 1 
Indicates whether to rate the on-callpickup or not. 
Valid values:
Y = Rate this pickup
N = Do not rate this pickup (default)


 
RateChartType
string  = 1 characters  <= 1 
Rate Type with which pickup is rated. Possible RateChart values for different regions will be:


US 48 origin:


    

  • 1 – Daily Rates
    • 

  • 3 – Standard List Rates
    • 

  • 4 – Retail Rates.
    • 



 Alaska/Hawaii origin:


    

  • 1 – Daily Rates
    • 

  • 3 – Standard List Rates
    • 

  • 4 – Retail Rates.
    • 



All Other origins:


    

  • 1 – Rates
    • 

  • 5 - Regional Rates
    • 

  • 6 - General List Rates.
    • 



3 and 4 do not apply


 
TaxInformationIndicator
string  = 1 characters  <= 1 
Indicates whether to return detailed taxes for the on-callpickups. 
Valid values:
Y = Rate this pickup with taxes
N = Do not rate this pickup with taxes (default)


 
UserLevelDiscountIndicator
string  = 1 characters  <= 1 
Indicates whether to return user level promo discount for the on-callpickups. 
Valid values:
Y = Rate this pickup with user level promo discount
N = Do not rate this pickup with user level promo discount(default)


 
object (PickupCreationRequest_Shipper)   <= 1 
On-call pickup shipper or requestor information.   Must provide when choose to pay the pickup by shipper account number, BillThirdParty account number, or BillReceiver account number. 
It is optional if the shipper chooses any other payment method. However, it is highly recommended to provide if available.


 
object (Shipper_Account)   <= 1 
Shipper account information. 
Must provide when choose to pay the pickup by shipper account number


 
object (Shipper_ChargeCard)   <= 1 
Container for Charge Card payment method  Required if Payment method is 03. Credit/Charge card payment is valid for US, CA, PR and GB origin pickups.


 
required
object (PickupCreationRequest_PickupDateInfo)   <= 1 
The container of desired pickup date


 
CloseTime
required
string  = 4 characters  <= 1 
Pickup location's local close time.


    

  • User provided Close Time must be later than the Earliest Allowed Customer Close Time.
    • 

  • Earliest Allowed Customer Close Time is defined by UPS pickup operation system.
    • 

  • CloseTime minus ReadyTime must be greater than the LeadTime.
    • 

  • LeadTime is determined by UPS pickup operation system. LeadTime is the minimum amount of time UPS requires between customer's request for a pickup and driver arriving at the location for the pickup.
    • 



Format: HHmm


    

  • Hour: 0-23
    • 

  • Minute: 0-59
    • 



 
ReadyTime
required
string
Pickup location's local ready time. 
ReadyTime means the time when your shipment(s) can be ready for UPS to pick up. 


    

  • User provided ReadyTime must be earlier than CallByTime. 
    • 

  • CallByTime is determined by UPS pickup operation system. CallByTime is the Latest time a Customer can call UPS or self-serve on UPS.com and complete a Pickup Request and UPS can still make the Pickup service request. 
    • 

  • If ReadyTime is earlier than current local time, UPS uses the current local time as the ReadyTime.  Format: HHmm
Hour: 0-23
Minute: 0-59
    • 



 
PickupDate
required
string  = 4 characters  <= 1 
Local pickup date of the location. Format: yyyyMMdd


    

  • yyyy = Year Appliable
    • 

  • MM = 01–12
    • 

  • dd = 01–31
    • 



 
required
object (PickupCreationRequest_PickupAddress)   <= 1 
The container of pickup address.


 
CompanyName
required
string  [ 1 .. 27 ] characters  <= 1 
Company name


 
ContactName
required
string  [ 1 .. 22 ] characters  <= 1 
Name of contact person


 
AddressLine
required
Array of strings
Detailed street address. For Jan. 2010 release, only one AddressLine is allowed


 
Room
string  [ 1 .. 8 ] characters  <= 1 
Room number


 
Floor
string  [ 1 .. 3 ] characters  <= 1 
Floor number


 
City
required
string  [ 1 .. 50 ] characters  <= 1 
City or equivalent


 
StateProvince
string  [ 1 .. 50 ] characters  <= 1 
State or province for postal countries; county for Ireland (IE) and district code for Hong Kong (HK)


 
Urbanization
string  [ 1 .. 50 ] characters  <= 1 
    

  • Barrio for Mexico (MX)
    • 

  • Urbanization for Puerto Rico (PR)
    • 

  • Shire for United Kingdom (UK)
    • 



 
PostalCode
string  [ 1 .. 8 ] characters  <= 1 
Postal code or equivalent for postal countries


 
CountryCode
required
string  = 2 characters  <= 1 
The pickup country or territory code as defined by ISO-3166. 
Refer to Country or Territory Codes in the Appendix for valid values.


 
ResidentialIndicator
required
string  = 1 characters  <= 1 
Indicates if the pickup address is commercial or residential. 
Valid values:
Y = Residential address
N = Non-residential (Commercial) address (default)


 
PickupPoint
string  [ 1 .. 11 ] characters  <= 1 
The specific spot to pickup at the address.


 
required
object (PickupAddress_Phone)   <= 1 
Contact telephone number.


 
AlternateAddressIndicator
required
string  = 1 characters  <= 1 
Indicates if pickup address is a different address than that specified in a customer's profile. 
Valid values:
Y = Alternate address
N = Original pickup address (default)


 
required
Array of objects (PickupCreationRequest_PickupPiece) 
 
 Array 
ServiceCode
required
string  = 3 characters  <= 1 
Refer to Service Codes in the Appendix for valid values.


 
Quantity
required
string  [ 1 .. 3 ] characters  <= 1 
Number of pieces to be picked up. 
Max per service: 999


 
DestinationCountryCode
required
string  = 2 characters  <= 1 
The destination country code as defined by ISO-3166.
Refer to Country or Territory Codes in the Appendix for valid values.


 
ContainerCode
required
string  = 2 characters  <= 1 
Container type. Valid values:


    

  • 01 = PACKAGE
    • 

  • 02 = UPS LETTER
    • 

  • 03 = PALLET
    • 



Note: 03 is used for only WWEF services


 
object (PickupCreationRequest_TotalWeight)   <= 1 
Container for the total weight of all the items.


 
Weight
required
string  = 6 characters  <= 1 
The weight of the package. 
One decimal digit is allowed. Example: 10.9


 
UnitOfMeasurement
required
string  = 3 characters  <= 1 
The code representing the unit of measurement associated with the package.
LBS = Pounds
KGS = Kilograms


 
OverweightIndicator
string  = 1 characters  <= 1 
Indicates if at least any package is over 70 lbs or 32 kgs. 
Valid values: 
Y = Over weight 
N = Not over weight (default)  Not required for WWEF service.


 
Array of objects (PickupCreationRequest_TrackingData) 
 
 Array 
TrackingNumber
string  = 18 characters  <= 1 
Tracking number for return shipment or forward shipment packages.  Tracking number(s) that have been previously used to pay for on-call pickup cannot be used again.


 
object (PickupCreationRequest_TrackingDataWithReferenceNumber)   <= 3 
Container for Tracking Number with its associated reference numbers.  This container should be populated to provide visibility into shipment tied to pickup being scheduled.  TrackingDataWithReferenceNumber and TrackingData container cannot be present at the same time.


 
TrackingNumber
required
string  = 18 characters  <= 1 
Tracking number for shipment packages.


 
ReferenceNumber
Array of strings  [ 1 .. 35 ] characters  <= 3 
The reference number associated with the tracking number.


 
PaymentMethod
required
string  = 2 characters  <= 1 
The payment method to pay for this on call pickup.
00 = No payment needed
01 = Pay by shipper account
03 = Pay by charge card
04 = Pay by 1Z tracking number
05 = Pay by check or money order
06 = Cash(applicable only for these countries - BE,FR,DE,IT,MX,NL,PL,ES,GB,CZ,HU,FI,NO)
07=Pay by PayPal
Refer to Appendix # for valid payment methods for CZ, HU, FI and NO
  For countries and (or) zip codes where pickup is free of charge, please submit 00, means no payment needed as payment method. 


    

  • If 01 is the payment method, then ShipperAccountNumber and ShipperAccount CountryCode must be provided.
    • 

  • If 03 is selected, then CreditCard information should be provided.
    • 

  • If 04 is selected, then the shipper agreed to pay for the pickup packages.
    • 

  • If 05 is selected, then the shipper will pay for the pickup packages with a check or money order.
    • 



 
SpecialInstruction
string  [ 1 .. 57 ] characters  <= 1 
Special handling instruction from the customer


 
ReferenceNumber
string  [ 1 .. 35 ] characters  <= 1 
Information entered by a customer for Privileged reference


 
object (PickupCreationRequest_FreightOptions)   <= 1 
Container will be used to indicate Service options, add optional Original service center, destination address and shipment details related to the UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday.


 
object (FreightOptions_ShipmentServiceOptions)   <= 1 
Supports various optional indicators


 
OriginServiceCenterCode
string  [ 1 .. 5 ] characters  <= 1 
Origin SLIC. This will be obtained from submitting a pickup service center request. See PickupGetFacilitiesServiceCenterRequest.


 
OriginServiceCountryCode
string  = 2 characters  <= 1 
Country or territory of Service Center SLIC chosen to drop off.


 
object (FreightOptions_DestinationAddress)   <= 1 
Destination Address Container.


 
required
object (FreightOptions_ShipmentDetail)   <= 1 
Refers to the ShipmentDetail Container under Freight Options


 
ServiceCategory
string  = 2 characters  <= 1 
Service Category.
Applicable to the following countries:
BE, FR, DE, IT, MX, NL, PL, ES, GB 
Valid values: 
01 - domestic (default)
02 - international
03 - transborder


 
CashType
string  = 2 characters  <= 1 
Describes the type of cash funds that the driver will collect.
Applicable to the following countries:
BE,FR,DE,IT,MX,NL,PL,ES,GB
Valid values: 
01 - Pickup only (default)
02 - Transportation only
03 - Pickup and Transportation


 
ShippingLabelsAvailable
string  = 1 characters  <= 1 
This element should be set to "Y" in the request to indicate that user has pre-printed shipping labels for all the packages, otherwise this will be treated as false.


 
object (PickupCreationRequest_Notification)   <= 1 
Container for pickup notification


 
ConfirmationEmailAddress
string  [ 1 .. 50 ] characters  <= 1 
Email address where the pickup notification is sent.


 
UndeliverableEmailAddress
string  [ 1 .. 50 ] characters  <= 1 
Email address for used exceptions.


 
Responses 
200
successful operation


400
Invalid Request


401
Unauthorized Request


403
Blocked Merchant


429
Rate Limit Exceeded


post/pickupcreation/{version}/pickup
Request samples 
application/json
{
  • "PickupCreationRequest": {
    }
}
Response samples 
application/json
{
  • "PickupCreationResponse": {
    }
}
Pickup Get Political Division1 List
The countrycode endpoint of the Pickup API helps retrieve a list of political divisions (states) in a specified country or territory.


SecurityOAuth2 
Request 
path Parameters
version
required
string  >= 1 
 Default:  "v2409"
Version of API.


Valid values:


    

  • v2409
    • 



 
countrycode
required
string  >= 1 
Country or terrirtory for which the list will 
represent.Length 2


 
header Parameters
transId
required
string
An identifier unique to the request. Length 32


 
transactionSrc
required
string
 Default:  testing
An identifier of the client/source application that is making the request.Length 512


 
Responses 
200
successful operation


400
Invalid Request


401
Unauthorized Request


403
Blocked Merchant


429
Rate Limit Exceeded


get/pickup/{version}/countries/{countrycode}
Request samples 
Response samples 
application/json
{
  • "PickupGetPoliticalDivision1ListResponse": {
    }
}
Pickup Get Service Center Facilities
The servicecenterlocations endpoint of the Pickup API helps retrieve service center information in a specified area - including location address, phone number, SLIC (Standard Location Identification Code), and hours of operation for pick-up and drop-off requests


SecurityOAuth2 
Request 
path Parameters
version
required
string
 Default:  "v2409"
Version of API.


Valid values:


    

  • v2409
    • 



 
header Parameters
transId
string
An identifier unique to the request. Length 32


 
transactionSrc
string
 Default:  testing
An identifier of the client/source application that is making the request.Length 512


 
Request Body schema: application/json
Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".


  <= 1 
required
object (PickupGetServiceCenterFacilitiesRequest)   <= 1 
This request is to retrieve UPS Facility location information including location address, phone number, SLIC, and hours of operation for pick-up and drop-off requests


 
required
object (PickupGetServiceCenterFacilitiesRequest_Request)   <= 1 
Container for the Request.


 
object (Pickup_components-schemas-Request_TransactionReference)   <= 1 
Transaction Reference Container


 
required
Array of objects (PickupGetServiceCenterFacilitiesRequest_PickupPiece) 
 
 Array 
ServiceCode
required
string  = 3 characters  <= 1 
The service code.
96 = WWEF  Required for WWEF shipments.


 
ContainerCode
required
string  = 2 characters  <= 1 
The container type
03 = PALLET  Required for WWEF shipments.


 
object (PickupGetServiceCenterFacilitiesRequest_OriginAddress)   <= 1 
Indicates the address of the shipper to allow for the nearest Drop off facility Search.  Conditionally required for drop off location search.


 
StreetAddress
string  [ 1 .. 73 ] characters  <= 1 
Indicates the address of the shipper to allow for the nearest Drop off facility Search.  Conditionally required if proximitySearchIndicator is present.


 
City
string  [ 1 .. 50 ] characters  <= 1 
Indicates the address of the shipper to allow for the nearest Drop off facility Search  Conditionally required if proximitySearchIndicator is present.


 
StateProvince
string  [ 1 .. 50 ] characters  <= 1 
Indicates the address of the shipper to allow for the nearest Drop off facility Search.  Conditionally required if proximitySearchIndicator is present and if country or territory is US/CA/IE/HK.


 
PostalCode
string  [ 1 .. 8 ] characters  <= 1 
Indicates the address of the shipper to allow for the nearest Drop off facility Search  Conditionally required if proximitySearchIndicator is present and if country or territory has postal code.It does not apply to non-postal countries such as IE and HK.


 
CountryCode
required
string  = 2 characters  <= 1 
Indicates the address of the shipper to allow for the nearest Drop off facility Search


 
object (OriginAddress_OriginSearchCriteria)   <= 1 
Origin Search Criteria Container  Required if Proximity SearchIndicator is present.


 
object (PickupGetServiceCenterFacilitiesRequest_DestinationAddress)   <= 1 
DestinationAddress container.  Conditionally required for pickup location search.


 
City
string  [ 1 .. 50 ] characters  <= 1 
Indicates the address of the consignee to allow for the nearest Pickup facility Search.  Required for non-postal country Ireland (IE).


 
StateProvince
string  [ 1 .. 50 ] characters  <= 1 
Indicates the address of the consignee to allow for the nearest Pickup facility Search.
1 = District code for Hong Kong (HK)
2 = County for Ireland (IE)
3 = State or province for all the postal countries  Required for non-postal countries including HK and IE.


 
PostalCode
string  [ 1 .. 8 ] characters  <= 1 
Indicates the address of the consignee to allow for the nearest Pickup facility Search  It does not apply to non-postal countries. Example: IE and HK.


 
CountryCode
required
string  [ 1 .. 3 ] characters  <= 1 
The pickup country or territory code as defined by ISO-3166. Please check check separate pickup country or territory list to find out all the pickup eligible countries.


 
Locale
required
string  = 5 characters  <= 1 
Origin Country or Territory Locale.  Locale should be Origin Country. Example: en_US. 
The Last 50 instruction will be send based on this locale. Locale is required if PoximityIndicator is present for Drop Off facilities.


 
ProximitySearchIndicator
string  <= 1 
Proximity Indicator. Indicates the user requested the proximity search for UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday locations for the origin address and/or the airport code, and the sort code for destination address.


 
Responses 
200
successful operation


400
Invalid Request


401
Unauthorized Request


403
Blocked Merchant


429
Rate Limit Exceeded


post/pickup/{version}/servicecenterlocations
Request samples 
application/json
{
  • "PickupGetServiceCenterFacilitiesRequest": {
    }
}
Response samples 
application/json
{
  • "PickupGetServiceCenterFacilitiesResponse": {
    }
}
Pickup CancelDeprecated
Using the CancelBy endpoint of the Pickup API, users can request cancellation of a UPS on-demand package pickup. When the PRN (pickup request number), transaction ID, and the transaction source are supplied as required parameters, the endpoint returns confirmation that the pickup has been cancelled.


SecurityOAuth2 
Request 
path Parameters
CancelBy
required
string
Valid Values: 01 = AccountNumber, 02 = PRN


 
deprecatedVersion
required
string  >= 1 
 Default:  "v2409"
Version of API.


Valid values:


    

  • v2409
    • 



 
header Parameters
transId
string
An identifier unique to the request. Length 32


 
transactionSrc
string
 Default:  testing
An identifier of the client/source application that is making the request.Length 512


 
Prn
string
The pickup equest number (PRN) generated by 
UPS pickup system.
Required if CancelBy = prn.Length 26


 
Responses 
200
successful operation


400
Invalid Request


401
Unauthorized Request


403
Blocked Merchant


429
Rate Limit Exceeded


delete/shipments/{deprecatedVersion}/pickup/{CancelBy}
Request samples 
Response samples 
application/json
{
  • "PickupCancelResponse": {
    }
}
Pickup CreationDeprecated
Using the Pickup API, applications can schedule pickups, manage previously scheduled pickups, or cancel previously scheduled pickups.


SecurityOAuth2 
Request 
path Parameters
deprecatedVersion
required
string  >= 1 
 Default:  "v2409"
Version of the API.


Valid values:


    

  • v1
    • 

  • v1607
    • 

  • v1707
    • 



 
header Parameters
transId
string
An identifier unique to the request. Length 32


 
transactionSrc
string
 Default:  testing
An identifier of the client/source application that is making the request.Length 512


 
Request Body schema: application/json
Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".


  <= 1 
required
object (PickupCreationRequest)   <= 1 
This request is for scheduling an on-call pickup


 
required
object (PickupCreationRequest_Request)   <= 1 
Common element for all services


 
SubVersion
string  = 4 characters  <= 1 
When UPS introduces new elements in the response that are not associated with new request elements, Subversion is used. This ensures backward compatibility.


To get such elements you need to have the right Subversion. The value of the subversion is explained in the Response element Description. Supported values: 1607, 1707,2007


Example: Itemized Charges are returned only when the Subversion element is present and greater than or equal to '1601'. 


Format: YYMM = Year and month of the release.
Example: 1601 = 2016 January


 
object (Pickup_components-schemas-Request_TransactionReference)   <= 1 
Transaction Reference Container


 
RatePickupIndicator
required
string  = 1 characters  <= 1 
Indicates whether to rate the on-callpickup or not. 
Valid values:
Y = Rate this pickup
N = Do not rate this pickup (default)


 
RateChartType
string  = 1 characters  <= 1 
Rate Type with which pickup is rated. Possible RateChart values for different regions will be:


US 48 origin:


    

  • 1 – Daily Rates
    • 

  • 3 – Standard List Rates
    • 

  • 4 – Retail Rates.
    • 



 Alaska/Hawaii origin:


    

  • 1 – Daily Rates
    • 

  • 3 – Standard List Rates
    • 

  • 4 – Retail Rates.
    • 



All Other origins:


    

  • 1 – Rates
    • 

  • 5 - Regional Rates
    • 

  • 6 - General List Rates.
    • 



3 and 4 do not apply


 
TaxInformationIndicator
string  = 1 characters  <= 1 
Indicates whether to return detailed taxes for the on-callpickups. 
Valid values:
Y = Rate this pickup with taxes
N = Do not rate this pickup with taxes (default)


 
UserLevelDiscountIndicator
string  = 1 characters  <= 1 
Indicates whether to return user level promo discount for the on-callpickups. 
Valid values:
Y = Rate this pickup with user level promo discount
N = Do not rate this pickup with user level promo discount(default)


 
object (PickupCreationRequest_Shipper)   <= 1 
On-call pickup shipper or requestor information.   Must provide when choose to pay the pickup by shipper account number, BillThirdParty account number, or BillReceiver account number. 
It is optional if the shipper chooses any other payment method. However, it is highly recommended to provide if available.


 
object (Shipper_Account)   <= 1 
Shipper account information. 
Must provide when choose to pay the pickup by shipper account number


 
object (Shipper_ChargeCard)   <= 1 
Container for Charge Card payment method  Required if Payment method is 03. Credit/Charge card payment is valid for US, CA, PR and GB origin pickups.


 
required
object (PickupCreationRequest_PickupDateInfo)   <= 1 
The container of desired pickup date


 
CloseTime
required
string  = 4 characters  <= 1 
Pickup location's local close time.


    

  • User provided Close Time must be later than the Earliest Allowed Customer Close Time.
    • 

  • Earliest Allowed Customer Close Time is defined by UPS pickup operation system.
    • 

  • CloseTime minus ReadyTime must be greater than the LeadTime.
    • 

  • LeadTime is determined by UPS pickup operation system. LeadTime is the minimum amount of time UPS requires between customer's request for a pickup and driver arriving at the location for the pickup.
    • 



Format: HHmm


    

  • Hour: 0-23
    • 

  • Minute: 0-59
    • 



 
ReadyTime
required
string
Pickup location's local ready time. 
ReadyTime means the time when your shipment(s) can be ready for UPS to pick up. 


    

  • User provided ReadyTime must be earlier than CallByTime. 
    • 

  • CallByTime is determined by UPS pickup operation system. CallByTime is the Latest time a Customer can call UPS or self-serve on UPS.com and complete a Pickup Request and UPS can still make the Pickup service request. 
    • 

  • If ReadyTime is earlier than current local time, UPS uses the current local time as the ReadyTime.  Format: HHmm
Hour: 0-23
Minute: 0-59
    • 



 
PickupDate
required
string  = 4 characters  <= 1 
Local pickup date of the location. Format: yyyyMMdd


    

  • yyyy = Year Appliable
    • 

  • MM = 01–12
    • 

  • dd = 01–31
    • 



 
required
object (PickupCreationRequest_PickupAddress)   <= 1 
The container of pickup address.


 
CompanyName
required
string  [ 1 .. 27 ] characters  <= 1 
Company name


 
ContactName
required
string  [ 1 .. 22 ] characters  <= 1 
Name of contact person


 
AddressLine
required
Array of strings
Detailed street address. For Jan. 2010 release, only one AddressLine is allowed


 
Room
string  [ 1 .. 8 ] characters  <= 1 
Room number


 
Floor
string  [ 1 .. 3 ] characters  <= 1 
Floor number


 
City
required
string  [ 1 .. 50 ] characters  <= 1 
City or equivalent


 
StateProvince
string  [ 1 .. 50 ] characters  <= 1 
State or province for postal countries; county for Ireland (IE) and district code for Hong Kong (HK)


 
Urbanization
string  [ 1 .. 50 ] characters  <= 1 
    

  • Barrio for Mexico (MX)
    • 

  • Urbanization for Puerto Rico (PR)
    • 

  • Shire for United Kingdom (UK)
    • 



 
PostalCode
string  [ 1 .. 8 ] characters  <= 1 
Postal code or equivalent for postal countries


 
CountryCode
required
string  = 2 characters  <= 1 
The pickup country or territory code as defined by ISO-3166. 
Refer to Country or Territory Codes in the Appendix for valid values.


 
ResidentialIndicator
required
string  = 1 characters  <= 1 
Indicates if the pickup address is commercial or residential. 
Valid values:
Y = Residential address
N = Non-residential (Commercial) address (default)


 
PickupPoint
string  [ 1 .. 11 ] characters  <= 1 
The specific spot to pickup at the address.


 
required
object (PickupAddress_Phone)   <= 1 
Contact telephone number.


 
AlternateAddressIndicator
required
string  = 1 characters  <= 1 
Indicates if pickup address is a different address than that specified in a customer's profile. 
Valid values:
Y = Alternate address
N = Original pickup address (default)


 
required
Array of objects (PickupCreationRequest_PickupPiece) 
 
 Array 
ServiceCode
required
string  = 3 characters  <= 1 
Refer to Service Codes in the Appendix for valid values.


 
Quantity
required
string  [ 1 .. 3 ] characters  <= 1 
Number of pieces to be picked up. 
Max per service: 999


 
DestinationCountryCode
required
string  = 2 characters  <= 1 
The destination country code as defined by ISO-3166.
Refer to Country or Territory Codes in the Appendix for valid values.


 
ContainerCode
required
string  = 2 characters  <= 1 
Container type. Valid values:


    

  • 01 = PACKAGE
    • 

  • 02 = UPS LETTER
    • 

  • 03 = PALLET
    • 



Note: 03 is used for only WWEF services


 
object (PickupCreationRequest_TotalWeight)   <= 1 
Container for the total weight of all the items.


 
Weight
required
string  = 6 characters  <= 1 
The weight of the package. 
One decimal digit is allowed. Example: 10.9


 
UnitOfMeasurement
required
string  = 3 characters  <= 1 
The code representing the unit of measurement associated with the package.
LBS = Pounds
KGS = Kilograms


 
OverweightIndicator
string  = 1 characters  <= 1 
Indicates if at least any package is over 70 lbs or 32 kgs. 
Valid values: 
Y = Over weight 
N = Not over weight (default)  Not required for WWEF service.


 
Array of objects (PickupCreationRequest_TrackingData) 
 
 Array 
TrackingNumber
string  = 18 characters  <= 1 
Tracking number for return shipment or forward shipment packages.  Tracking number(s) that have been previously used to pay for on-call pickup cannot be used again.


 
object (PickupCreationRequest_TrackingDataWithReferenceNumber)   <= 3 
Container for Tracking Number with its associated reference numbers.  This container should be populated to provide visibility into shipment tied to pickup being scheduled.  TrackingDataWithReferenceNumber and TrackingData container cannot be present at the same time.


 
TrackingNumber
required
string  = 18 characters  <= 1 
Tracking number for shipment packages.


 
ReferenceNumber
Array of strings  [ 1 .. 35 ] characters  <= 3 
The reference number associated with the tracking number.


 
PaymentMethod
required
string  = 2 characters  <= 1 
The payment method to pay for this on call pickup.
00 = No payment needed
01 = Pay by shipper account
03 = Pay by charge card
04 = Pay by 1Z tracking number
05 = Pay by check or money order
06 = Cash(applicable only for these countries - BE,FR,DE,IT,MX,NL,PL,ES,GB,CZ,HU,FI,NO)
07=Pay by PayPal
Refer to Appendix # for valid payment methods for CZ, HU, FI and NO
  For countries and (or) zip codes where pickup is free of charge, please submit 00, means no payment needed as payment method. 


    

  • If 01 is the payment method, then ShipperAccountNumber and ShipperAccount CountryCode must be provided.
    • 

  • If 03 is selected, then CreditCard information should be provided.
    • 

  • If 04 is selected, then the shipper agreed to pay for the pickup packages.
    • 

  • If 05 is selected, then the shipper will pay for the pickup packages with a check or money order.
    • 



 
SpecialInstruction
string  [ 1 .. 57 ] characters  <= 1 
Special handling instruction from the customer


 
ReferenceNumber
string  [ 1 .. 35 ] characters  <= 1 
Information entered by a customer for Privileged reference


 
object (PickupCreationRequest_FreightOptions)   <= 1 
Container will be used to indicate Service options, add optional Original service center, destination address and shipment details related to the UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday.


 
object (FreightOptions_ShipmentServiceOptions)   <= 1 
Supports various optional indicators


 
OriginServiceCenterCode
string  [ 1 .. 5 ] characters  <= 1 
Origin SLIC. This will be obtained from submitting a pickup service center request. See PickupGetFacilitiesServiceCenterRequest.


 
OriginServiceCountryCode
string  = 2 characters  <= 1 
Country or territory of Service Center SLIC chosen to drop off.


 
object (FreightOptions_DestinationAddress)   <= 1 
Destination Address Container.


 
required
object (FreightOptions_ShipmentDetail)   <= 1 
Refers to the ShipmentDetail Container under Freight Options


 
ServiceCategory
string  = 2 characters  <= 1 
Service Category.
Applicable to the following countries:
BE, FR, DE, IT, MX, NL, PL, ES, GB 
Valid values: 
01 - domestic (default)
02 - international
03 - transborder


 
CashType
string  = 2 characters  <= 1 
Describes the type of cash funds that the driver will collect.
Applicable to the following countries:
BE,FR,DE,IT,MX,NL,PL,ES,GB
Valid values: 
01 - Pickup only (default)
02 - Transportation only
03 - Pickup and Transportation


 
ShippingLabelsAvailable
string  = 1 characters  <= 1 
This element should be set to "Y" in the request to indicate that user has pre-printed shipping labels for all the packages, otherwise this will be treated as false.


 
object (PickupCreationRequest_Notification)   <= 1 
Container for pickup notification


 
ConfirmationEmailAddress
string  [ 1 .. 50 ] characters  <= 1 
Email address where the pickup notification is sent.


 
UndeliverableEmailAddress
string  [ 1 .. 50 ] characters  <= 1 
Email address for used exceptions.


 
Responses 
200
successful operation


400
Invalid Request


401
Unauthorized Request


403
Blocked Merchant


429
Rate Limit Exceeded


post/pickupcreation/{deprecatedVersion}/pickup
Request samples 
application/json
{
  • "PickupCreationRequest": {
    }
}
Response samples 
application/json
{
  • "PickupCreationResponse": {
    }
}
➔ Next to Pre-Notification