API Reference | ReDoc

Shipping

The Shipping Package API gives the application many ways to manage the shipment of packages to their destination.

Reference


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

Run In Postman Open in GitHub

Shipment

The Shipping API makes UPS shipping services available to client applications that communicate with UPS using the Internet

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

Indicates Ship API to display the new release features in Ship API response based on Ship release.

Valid values:

  • v2409
query Parameters
additionaladdressvalidation
string >= 1

Valid Values: city = validation will include city.Length 15

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 (ShipmentRequest) <= 1

Shipment Request.

required
object (ShipmentRequest_Request) <= 1

Request Container

RequestOption
required
string [ 1 .. 15 ] characters <= 1

Optional Processing.

Note: Full address validation is not performed. Therefore, it is the responsibility of the Shipping Tool User to ensure the address entered is correct to avoid an address correction fee. Valid values: nonvalidate = No street level address validation would be performed, but Postal Code/State combination validation would still be performed.

validate = No street level address validation would be performed, but City/State/Postal Code/ combination validation would still be performed.

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.

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: 1607 = 2016 July Supported values: 1601, 1607, 1701, 1707, 1801, 1807, 2108, 2205

object (Shipping_components-schemas-Request_TransactionReference) <= 1

TransactionReference identifies transactions between client and server.

required
object (ShipmentRequest_Shipment) <= 1

Shipment Container

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

The Description of Goods for the shipment. Applies to international and domestic shipments.

Provide a detailed description of items being shipped for documents and non-documents.

Examples: "annual reports" and "9 mm steel screws". Required if all of the listed conditions are true: ShipFrom and ShipTo countries or territories are not the same; The packaging type is not UPS Letter; The ShipFrom and or ShipTo countries or territories are not in the European Union or the ShipFrom and ShipTo countries or territories are both in the European Union and the shipments service type is not UPS Standard.

object (Shipment_ReturnService) <= 1

Type of Return service. When this container exists, the shipment is a return shipment.

DocumentsOnlyIndicator
string <= 1

Indicates a shipment contains written, typed, or printed communication of no commercial value.

If DocumentsOnly is not specified then it implies that the shipment contains non documents or documents of commercial value.

Default is a shipment contains non- documents or documents of commercial value. This is an empty tag, any value inside is ignored.

Valid only for shipments with different origin and destination countries or territories. The origin country or territory is not US, and the destination country or territory is not CA, PR or MX.

required
object (schemas-Shipment_Shipper) <= 1

Container for the Shipper's information.

required
object (schemas-Shipment_ShipTo) <= 1

Ship To Container.

object (schemas-Shipment_AlternateDeliveryAddress) <= 1

AlternateDeliveryAddress Container. Alternate Delivery Address (UPS Access Point Address) required if ShipmentIndicationType is 01 or 02.

object (schemas-Shipment_ShipFrom) <= 1

Ship From Container. Required for return shipment.

Required if pickup location is different from the shipper's address.

Required for Trade Direct shipment.

object (Shipment_PaymentInformation) <= 1

Payment information container for detailed shipment charges. The two shipment charges that are available for specification are Transportation charges and Duties and Taxes. It is required for non-Ground Freight Pricing shipments only.

object (schemas-Shipment_FRSPaymentInformation) <= 1

Container to hold the Payment information for the Ground Freight Pricing Shipments. Required for Ground Freight Pricing Shipments only.

object (Shipment_GlobalTaxInformation) <= 1

Container used to define the properties required for GlobalTaxID.

object (Shipment_WorldEase)

WorldEase is a contract service offering in the UPS shipping that decreases brokerage fees by consolidating loose packages into one shipment for customs clearance.

object (schemas-Shipment_FreightShipmentInformation) <= 1

Container to hold Freight Shipment information.

GoodsNotInFreeCirculationIndicator
string <= 1

Goods Not In Free Circulation indicator. This is an empty tag, any value inside is ignored. This indicator is invalid for a package type of UPS Letter and DocumentsOnly.

object (Shipment_PromotionalDiscountInformation) <= 1

PromotionalDiscountInformation container. This container contains discount information that the customer wants to request each time while placing a shipment.

object (Shipment_DGSignatoryInfo) <= 1

DGSignatoryInfo Container DGPaperImage will be returned if DGSignatoryInfo container present

object (schemas-Shipment_ShipmentRatingOptions) <= 1

ShipmentRatingOptions container.

MovementReferenceNumber
string = 18 characters <= 1

Movement Reference Number (MRN) information. Must contain alphanumeric characters only. Must be a length of 18 characters. The 3rd and 4th Characters must be the Shipper country or territory ISO Code.

Array of objects (Shipment_ReferenceNumber)
required
object (Shipping_components-schemas-Shipment_Service) <= 1

UPS service type.

object (schemas-Shipment_InvoiceLineTotal) <= 1

Container to hold InvoiceLineTotal Information. Required for forward shipments whose origin is the US and destination is Puerto Rico or Canada. Not available for any other shipments. FOR OTHER DESTINATIONS the InvoiceLineTotal in the International Forms Container must be used.

ShipmentRiskEnteringEU
string = 2 characters <= 1

Code that identifies the risk of the Shipment entering the European Union (EU). Values: 01 = AT RISK of Entering the EU 02 = NOT AT RISK of Entering the EU 03 = RISK UNKNOWN of Entering the EU

NumOfPiecesInShipment
string [ 1 .. 5 ] characters <= 1

Total number of pieces in all pallets in a UPS Worldwide Express Freight Shipment. It is required for UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday Shipment. Valid values are 1 to 99999.

USPSEndorsement
string = 1 characters <= 1

USPS Endorsement. Valid values: 1 = Return Service Requested 2 = Forwarding Service Requested 3 = Address Service Requested 4 = Change Service Requested and 5 = No Service Selected. Note: For International Mail Innovations shipments use No Service Selected. International Mail Innovations shipments are applicable for Priority Mail Innovations and Mail Innovations Economy Mail Innovations services only. Required for Mail Innovations forward shipments.

MILabelCN22Indicator
string <= 1

Indicates single label with both MI label and CN22 form. International CN22 form is required.

SubClassification
string = 2 characters <= 1

A component encoded on the barcode of the Mail Innovations label. Valid values: IR = Irregular MA = Machineable SubClass is only required if the customer's contract have them subclass the package not UPS.

CostCenter
string [ 1 .. 30 ] characters <= 1

Customer assigned identifier for report and billing summarization displays to the right of the Cost Center title. Required for Mail Innovations Return shipments. It is shown on the bottom of the shipping label as reference 2.

Cost Center length is alphanumeric with a max length of 30 for Mail Innovations forward shipments.

Cost Center length is numeric with a max length of 4 for Mail Innovations Return shipments.

CostCenterBarcodeIndicator
string <= 1

Presence/Absence indicator. Presence of this indicator means that the customer is requesting for the CostCenter field to be barcoded at the bottom of the label.

PackageID
string [ 1 .. 30 ] characters <= 1

Customer-assigned unique piece identifier that returns visibility events. Required only for Mail Innovations forward shipments. Alpha numeric values only. It is shown on the bottom of the shipping label as reference 1.

PackageIDBarcodeIndicator
string <= 1

Presence/Absence indicator. Presence of this indicator means that the customer is requesting for the PackageID field to be barcoded at the bottom of the label.

IrregularIndicator
string = 1 characters <= 1

Mail classification defined by the USPS. Valid values: 1 = Balloon 2 = Oversize 3 = Not Applicable

Array of objects (schemas-Shipment_ShipmentIndicationType)
MIDualReturnShipmentKey
string [ 4 .. 50 ] characters <= 1

MIDualReturnShipmentKey is unique key required to process Mail Innovations Dual Return Shipment.

The unique identifier (key) would be returned in response of first phase of Mail Innovations Dual Return Shipments.

This unique identifier (key) would be part of request for second phase of Mail Innovations Dual Return Shipments.

Format: For Package return shipments, the package tracking number is concatenated with the system time (YYYY-MM-DDHH.MM.SS.NNN), followed by service code.

For MI Return shipments, the Mail Manifest ID (MMI) is concatenated with the system time. The unique identifier (key) is required to link the package and the Mail Innovations portion of Dual Return shipment.

If unique identifier (key) is empty in the request for UPS Mail Innovations Return Service, the request will be treated as the first phase of the Mail Innovations Dual Returns Request.

If the MIDualReturnShipmentIndicator is present with empty or null MIDualReturnShipmentKey in UPS Package Return Shipment, the request will be treated as the first phase of Dual MI Return Label Shipment.

This field would be ignored if MIDualReturnShipmentIndicator is not present in UPS Package Return Shipment request.

MIDualReturnShipmentIndicator
string <= 1

MIDualReturnShipmentIndicator is an indicator to identify a Package Shipment is part of UPS Mail Innovations Dual Label Shipment.

Its presence means Package Shipment is part of UPS Mail Innovations Dual Label shipment. If the indicator is present in Package Shipment request, shipment would be considered as part of a Dual Mail Innovations Returns.

This indicator is not valid with UPS Mail Innovations Returns Service code.

RatingMethodRequestedIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. RatingMethodRequestedIndicator is an indicator. If present, Billable Weight Calculation method information and Rating Method information would be returned in response.

TaxInformationIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. TaxInformationIndicator is an indicator. If present, any taxes that may be applicable to a shipment would be returned in response. If this indicator is requested with NegotiatedRatesIndicator, Tax related information, if applicable, would be returned only for Negotiated Rates and not for Published Rates. The Tax related information includes any type of Taxes, corresponding Monetary Values, Total Charges with Taxes and disclaimers (if applicable) would be returned in response.

object (schemas-Shipment_ShipmentServiceOptions) <= 1

Container for Shipment Service Options.

Locale
string = 5 characters <= 1

Represents 5 character ISO Locale that allows the user to request Reference Number Code on Label, Label instructions and Receipt instructions (if applicable) in desired language. Locale is specified by the combination of language code and country or territory code - 2 character language code and 2 character country or territory code seperated by an underscore ('_') character. If Locale element is requested along with LabelLinksIndicator, the URL to retrieve Label and Receipts (if applicable) will be returned in the requested Locale. Please note only LabelURL and ReceiptURL (if applicable) will be returned. LocalLanguageLabelURL and LocalLanguageReceiptURL will not be returned if Locale element is present in request. Queen's English (en_GB) is the default

ShipmentValueThresholdCode
string = 2 characters <= 1

Shipment Value Threshold Code. 01 = Shipment value is below or equals to threshold value 02 = Shipment value is above threshold value. NA = Not Applicable

MasterCartonID
string [ 1 .. 24 ] characters <= 1

Master Carton ID. If Economy Service (17 or 72) : Economy Shipment will be associated with given Master Carton ID. If Non-Economy Service: Master Carton Shipment will be created for given Master Carton ID.

MasterCartonIndicator
string <= 1

Master Carton Indicator. Presence of the indicator means Master Carton ID will be created and returned to client. This is an empty tag, any value inside is ignored. MasterCartonIndicator is only valid with Econmoy Shipment (Service Code 17 or 72). Will be ignored if master carton id present.

ShipmentDate
string = 8 characters <= 1

User can send up to 7 days in the future with current date as day zero. Format: YYYYMMDD

required
Array of objects (Shipping_components-schemas-Shipment_Package) <= 200
QuoteID
string = 35 characters <= 1

This field is used to pass the Quote ID generated from the Global Checkout API. This is mandatory to validate your Global Checkout Guaranteed Landed Cost.

object (Shipment_TradeDirect) <= 1

A UPS product that enables customers to ship directly from a manufacturer to end consumers in a different country.

object (ShipmentRequest_LabelSpecification) <= 1

Container used to define the properties required by the user to print and/or display the UPS shipping label. Required for shipment without return service or shipments with PRL return service. Required for Electronic Return Label or Electronic Import Control Label shipments with SubVersion greater than or equal to 1707.

required
object (LabelSpecification_LabelImageFormat) <= 1

LabelImageFormat Container.

HTTPUserAgent
string [ 1 .. 64 ] characters <= 1

Browser HTTPUserAgent String. This is the preferred way of identifying GIF image type to be generated. Required if /ShipmentRequest/LabelSpecificationLabelSpecification/LabelImageFormat/Code = Gif. Default to Mozilla/4.5 if this field is missing or has invalid value.

required
object (LabelSpecification_LabelStockSize) <= 1

Container for the EPL2, ZPL or SPL label size. Valid for EPL2, ZPL and SPL Labels.

Array of objects (LabelSpecification_Instruction)
CharacterSet
string = 3 characters <= 1

Language character set expected on label. Valid values: dan = Danish (Latin-1) nld = Dutch (Latin-1) fin = Finnish (Latin-1) fra = French (Latin-1) deu = German (Latin-1) itl = Italian (Latin-1) nor = Norwegian (Latin-1) pol = Polish (Latin-2) por = Poruguese (Latin-1) spa = Spanish (Latin-1) swe = Swedish (Latin-1) ces = Czech (Latin-2) hun = Hungarian (Latin-2) slk = Slovak (Latin-2) rus = Russian (Cyrillic) tur = Turkish (Latin-5) ron = Romanian (Latin-2) bul = Bulgarian (Latin-2) est = Estonian (Latin-2) ell = Greek (Latin-2) lav = Latvian (Latin-2) lit = Lithuanian (Latin-2) eng = English (Latin-1) Default is English (Latin-1).

object (ShipmentRequest_ReceiptSpecification) <= 1

Container used to allow the user to choose to print a thermal receipt.

required
object (ReceiptSpecification_ImageFormat) <= 1

ImageFormat Container.

Responses
200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/shipments/{version}/ship
Request samples
application/json
{
  • "ShipmentRequest": {
    }
}
Response samples
application/json
{
  • "ShipmentResponse": {
    }
}

Void Shipment

The Void Shipping API is used to cancel the previously scheduled shipment

SecurityOAuth2
Request
path Parameters
version
required
string
Default: "v2409"

API Version

Valid values:

  • v2409
shipmentidentificationnumber
required
string >= 1

The shipment's identification number Alpha-numeric. Must pass 1Z rules. Must be upper case. Length 18

query Parameters
trackingnumber
string >= 1

The package's tracking number. You may have up to 20 different tracking numbers listed. If more than one tracking number, pass this value as: trackingnumber= ["1ZISUS010330563105","1ZISUS01033056310 8"] with a coma separating each number. Alpha-numeric. Must pass 1Z rules. Must be upper case. Length 18

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

Responses
200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

delete/shipments/{version}/void/cancel/{shipmentidentificationnumber}
Request samples 
Response samples 
application/json
{
  • "VoidShipmentResponse": {
    }
}
Label Recovery
The Label Shipping API allows us to retrieve forward and return labels.


SecurityOAuth2 
Request 
path Parameters
version
required
string  >= 1 
 Default:  "v1"
When UPS introduces new elements in the 
response that are not associated with new 
request elements, Subversion is used. This 
ensures backward compatibility. 
v1  original features of the application. No 
support for CODTurn-inPage, HighValueReport 
or InternationalForms features returned in the 
response
v1701  includes support for CODTurn-inPage 
features returned in the response.
V1903
 Length 5


 
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 (LabelRecoveryRequest)   <= 1 
Request for obtaining the Label for the return shipment.


 
required
object (LabelRecoveryRequest_Request)   <= 1 
Request Container.


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


Format: YYMM = Year and month of the release.
Example: 1701 = 2017 January  Supported values: 1701, 1707, 1903


 
RequestOption
string
Request option is no longer used.


 
object (LRRequest_TransactionReference)   <= 1 
Container that identifies transactions between client and server.


 
object (LabelRecoveryRequest_LabelSpecification)   <= 1 
Container that is used to define the properties required by the user to print and/ or display the UPS shipping label.  Required for the shipment without return service, or shipment with PRL return service.


 
HTTPUserAgent
string  [ 1 .. 64 ] characters  <= 1 
Browser HTTPUserAgent String. This is the preferred way of identifying GIF image type to be generated.  Required if / LabelSpecification/LabelImageFormat/Code = Gif. Default to Mozilla/4.5 if this field is missing or has invalid value.


 
object (LabelRecovery_LabelSpecification_LabelImageFormat)   <= 1 
The file format of the label and receipt. Defaults to HTML format if this node does not exist.


 
object (LabelRecovery_LabelSpecification_LabelStockSize)   <= 1 
Container to hold Label Height and Width information.  Applicable if Label Image Code is ZPL, EPL and SPL. Ignored for other Label Image Code types.


 
object (LabelRecoveryRequest_Translate)   <= 1 
Translate container allows the user to specify the language he/she would like a specific portion of response to return. 
The language is specified by the combination of language code and dialect code. 
Valid combinations are: LanguageCode + DialectCode.  Either Translate container or Locale element can be present in a given request. Both can't be requested together in same request.
Combinations: 
eng GB = Queen's English 
Spa 97 = Castilian Spanish 
ita 97 = Italian 
fra 97 = France French 
fra CA = Canadian French 
deu 97 = German 
por 97 = Portugal Portuguese 
nld 97 = Dutch 
dan 97 = Danish 
fin 97 = Finnish 
swe 97 = Swedish 
eng CA = Canadian English 
Eng US = US English 
Default language is Queen's English 


If the Ship from country or territory is Canada, the Language defaults to Canadian English. 


If the ship from country or territory is US, the language defaults to US English.


If shipping from some other country or territory, the language defaults to Queens English.


 
LanguageCode
required
string  [ 2 .. 3 ] characters  <= 1 
The Language code. The language codes are three letter language codes. Supported languages are:


    

  • eng - English
    • 

  • spa - Spanish
    • 

  • ita - Italian
    • 

  • fra - French
    • 

  • deu - German
    • 

  • por -Portuguese
    • 

  • nld – Dutch
    • 

  • dan - Danish
    • 

  • fin - Finnish
    • 

  • swe – Swedish
    • 

  • nor – Norwegian
    • 



 
DialectCode
required
string  = 2 characters  <= 1 
Valid dialect codes are:


    

  • CA - Canada
    • 

  • GB - Great Britain
    • 

  • US - United States
    • 

  • 97 – Not Applicable
    • 



 
Code
required
string  = 2 characters  <= 1 
Used to specify what will be translated. 
Valid code: 
01 = label direction instructions and receipt


 
object (LabelRecoveryRequest_LabelDelivery)   <= 1 
Container for the Label Delivery accessorial. One Label Delivery per shipment.


 
LabelLinkIndicator
string  <= 1 
Indicates the Label Recovery and Receipt Recovery URL links are to be returned in the XML Response. Valid for following shipment -
Print/Electronic Return Label
Print/Electronic Import Control Label
Forward shipment except for Mail Innovations Forward


 
ResendEMailIndicator
string  <= 1 
Not Used. If this tag is present, resend the Label Delivery notification email.


 
TrackingNumber
string  [ 1 .. 18 ] characters  <= 1 
Small Package Tracking Number. Required if Mail Innovations Tracking Number or ReferenceNumber/Value and ShipperNumber is not provided.  If only TrackingNumber is provided, the request will be treated as Small Package Shipment. Label Recovery will return label for Small Package Tracking Number.
If both, TrackingNumber and MailInnovationsTrackingNumber are provided, the request will be treated as Dual Mail Innovations Return Shipment. Label Recovery will return two labels one each for - Small Package Tracking Number and Mail Innovations Return Tracking Number.


 
MailInnovationsTrackingNumber
string  [ 1 .. 34 ] characters  <= 1 
Mail Innovations Tracking Number.  Required if Tracking Number or ReferenceNumber/Value is not populated. 
If only MailInnovationsTrackingNumber is provided, the request will be treated as Single Mail Innovations Return Shipment. Label Recovery will return label for Mail Innovations Return Tracking Number.
If both, TrackingNumber and MailInnovationsTrackingNumber are provided, the request will be treated as Dual Mail Innovations Return Shipment. Label Recovery will return two labels one each for - Small Package Tracking Number and Mail Innovations Return Tracking Number.


 
object (LabelRecoveryRequest_ReferenceValues)   <= 1 
Container that holds reference number and shipper number  If tracking number is not present use reference Number


 
required
object (ReferenceValues_ReferenceNumber)   <= 1 
Container for reference number


 
ShipperNumber
required
string  = 6 characters  <= 1 
Required if ReferenceNumber/Value is populated. Shipper's six digit account number. Must be six alphanumeric characters. Must be associated with the Internet account used to login.


 
Locale
string  = 5 characters  <= 1 
Represents 5 character ISO Locale that allows the user to request Reference Number Code on Label, Label instructions, Receipt instructions (if available for given tracking number) and High Value Report (if available for given tracking number) in desired language. 
Locale is specified by the combination of language code and country or territory code - 2 character language code and 2 character country code seperated by an underscore ('_') character. Example - de_DE. Please refer to Appendix for supported values for Locale.  Either Translate container or Locale element can be present in a given request. Both can't be requested together in same request.


 
object (LabelRecoveryRequest_UPSPremiumCareForm)   <= 1 
UPS Premium Care Form container.  Default is PDF when container is not provided. 
  Valid only for Canada to Canada movements. UPS Premium Care Form will be returned in  both US English and Canadian French language.


 
PageSize
required
string  = 2 characters  <= 1 
Size of UPS Premium Care Form.  Valid values: 
01 = A4 Size
02 = Letter Size


 
PrintType
required
string  = 2 characters  <= 1 
Format of UPS Premium Care Form.  Valid values: 
01 = PNG
02 = PDF


 
Responses 
200
successful operation


400
Invalid Request


401
Unauthorized Request


403
Blocked Merchant


429
Rate Limit Exceeded


post/labels/{version}/recovery
Request samples 
application/json
{
  • "LabelRecoveryRequest": {
    }
}
Response samples 
application/json
{
  • "LabelRecoveryResponse": {
    }
}
ShipmentDeprecated
The Shipping API makes UPS shipping services available to client applications that communicate with UPS 
using the Internet


SecurityOAuth2 
Request 
path Parameters
deprecatedVersion
required
string  >= 1 
 Default:  "v1"
Indicates Ship API to display the new release features in Ship API response based on Ship release.


Valid values:


    

  • v1
    • 

  • v1601
    • 

  • v1607
    • 

  • v1701
    • 

  • v1707
    • 

  • v1801
    • 

  • v1807
    • 

  • v2108
    • 

  • v2205
    • 



 
query Parameters
additionaladdressvalidation
string  >= 1 
Valid Values: 
city = validation will include city.Length 15


 
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 (ShipmentRequest)   <= 1 
Shipment Request.


 
required
object (ShipmentRequest_Request)   <= 1 
Request Container


 
RequestOption
required
string  [ 1 .. 15 ] characters  <= 1 
Optional Processing.  


Note: Full address validation is not performed. Therefore, it is the responsibility of the Shipping Tool User to ensure the address entered is correct to avoid an address correction fee.  Valid values:
nonvalidate = No street level address validation would be performed, but Postal Code/State combination validation would still be performed.


validate = No street level address validation would be performed, but City/State/Postal Code/ combination validation would still be performed.


 
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.


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: 1607 = 2016 July  Supported values: 1601, 1607, 1701, 1707, 1801, 1807, 2108, 2205


 
object (Shipping_components-schemas-Request_TransactionReference)   <= 1 
TransactionReference identifies transactions between client and server.


 
required
object (ShipmentRequest_Shipment)   <= 1 
Shipment Container


 
Description
string  [ 1 .. 50 ] characters  <= 1 
The Description of Goods for the shipment. Applies to international and domestic shipments. 


Provide a detailed description of items being shipped for documents and non-documents. 


Examples: "annual reports" and "9 mm steel screws".  Required if all of the listed conditions are true: 
ShipFrom and ShipTo countries or territories are not the same; The packaging type is not UPS Letter; The ShipFrom and or ShipTo countries or territories are not in the European Union or the ShipFrom and ShipTo countries or territories are both in the European Union and the shipments service type is not UPS Standard.


 
object (Shipment_ReturnService)   <= 1 
Type of Return service. When this container exists, the shipment is a return shipment.


 
DocumentsOnlyIndicator
string  <= 1 
Indicates a shipment contains written, typed, or printed communication of no commercial value. 


If DocumentsOnly is not specified then it implies that the shipment contains non documents or documents of commercial value. 


Default is a shipment contains non- documents or documents of commercial value.  This is an empty tag, any value inside is ignored. 


Valid only for shipments with different origin and destination countries or territories. The origin country or territory is not US, and the destination country or territory is not CA, PR or MX.


 
required
object (schemas-Shipment_Shipper)   <= 1 
Container for the Shipper's information.


 
required
object (schemas-Shipment_ShipTo)   <= 1 
Ship To Container.


 
object (schemas-Shipment_AlternateDeliveryAddress)   <= 1 
AlternateDeliveryAddress Container.  Alternate Delivery Address (UPS Access Point Address) required if ShipmentIndicationType is 01 or 02.


 
object (schemas-Shipment_ShipFrom)   <= 1 
Ship From Container.  Required for return shipment. 


Required if pickup location is different from the shipper's address. 


Required for Trade Direct shipment.


 
object (Shipment_PaymentInformation)   <= 1 
Payment information container for detailed shipment charges. The two shipment charges that are available for specification are Transportation charges and Duties and Taxes.  It is required for non-Ground Freight Pricing shipments only.


 
object (schemas-Shipment_FRSPaymentInformation)   <= 1 
Container to hold the Payment information for the Ground Freight Pricing Shipments.  Required for Ground Freight Pricing Shipments only.


 
object (Shipment_GlobalTaxInformation)   <= 1 
Container used to define the properties required for GlobalTaxID.


 
object (Shipment_WorldEase) 
WorldEase is a contract service offering in the UPS shipping that decreases brokerage fees by consolidating
loose packages into one shipment for customs clearance.


 
object (schemas-Shipment_FreightShipmentInformation)   <= 1 
Container to hold Freight Shipment information.


 
GoodsNotInFreeCirculationIndicator
string  <= 1 
Goods Not In Free Circulation indicator.  This is an empty tag, any value inside is ignored. This indicator is invalid for a package type of UPS Letter and DocumentsOnly.


 
object (Shipment_PromotionalDiscountInformation)   <= 1 
PromotionalDiscountInformation container. This container contains discount information that the customer wants to request each time while placing a shipment.


 
object (Shipment_DGSignatoryInfo)   <= 1 
DGSignatoryInfo Container  DGPaperImage will be returned if DGSignatoryInfo container present


 
object (schemas-Shipment_ShipmentRatingOptions)   <= 1 
ShipmentRatingOptions container.


 
MovementReferenceNumber
string  = 18 characters  <= 1 
Movement Reference Number (MRN) information.  Must contain alphanumeric characters only. Must be a length of 18 characters. The 3rd and 4th Characters must be the Shipper country or territory ISO Code.


 
Array of objects (Shipment_ReferenceNumber) 
 
required
object (Shipping_components-schemas-Shipment_Service)   <= 1 
UPS service type.


 
object (schemas-Shipment_InvoiceLineTotal)   <= 1 
Container to hold InvoiceLineTotal Information.  Required for forward shipments whose origin is the US and destination is Puerto Rico or Canada. Not available for any other shipments. FOR OTHER DESTINATIONS the InvoiceLineTotal in the International Forms Container must be used.


 
ShipmentRiskEnteringEU
string  = 2 characters  <= 1 
Code that identifies the risk of the Shipment entering the European Union (EU). 
 Values: 01 = AT RISK of Entering the EU 
 02 = NOT AT RISK of Entering the EU 
 03 = RISK UNKNOWN of Entering the EU


 
NumOfPiecesInShipment
string  [ 1 .. 5 ] characters  <= 1 
Total number of pieces in all pallets in a UPS Worldwide Express Freight Shipment.  It is required for UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday Shipment. Valid values are 1 to 99999.


 
USPSEndorsement
string  = 1 characters  <= 1 
USPS Endorsement.
Valid values: 
1 = Return Service Requested 
2 = Forwarding Service Requested 
3 = Address Service Requested 
4 = Change Service Requested and 
5 = No Service Selected. 
Note: For International Mail Innovations shipments use No Service Selected. International Mail Innovations shipments are applicable for Priority Mail Innovations and Mail Innovations Economy Mail Innovations services only.  Required for Mail Innovations forward shipments.


 
MILabelCN22Indicator
string  <= 1 
Indicates single label with both MI label and CN22 form.  International CN22 form is required.


 
SubClassification
string  = 2 characters  <= 1 
A component encoded on the barcode of the Mail Innovations label.   Valid values: 
IR = Irregular
MA = Machineable
SubClass is only required if the customer's contract have them subclass the package not UPS.


 
CostCenter
string  [ 1 .. 30 ] characters  <= 1 
Customer assigned identifier for report and billing summarization displays to the right of the Cost Center title.  Required for Mail Innovations Return shipments. It is shown on the bottom of the shipping label as reference 2.


Cost Center length is alphanumeric with a max length of 30 for Mail Innovations forward shipments.


Cost Center length is numeric with a max length of 4 for Mail Innovations Return shipments.


 
CostCenterBarcodeIndicator
string  <= 1 
Presence/Absence indicator. Presence of this indicator means that the customer is requesting for the CostCenter field to be barcoded at the bottom of the label.


 
PackageID
string  [ 1 .. 30 ] characters  <= 1 
Customer-assigned unique piece identifier that returns visibility events.  Required only for Mail Innovations forward shipments. Alpha numeric values only. It is shown on the bottom of the shipping label as reference 1.


 
PackageIDBarcodeIndicator
string  <= 1 
Presence/Absence indicator. Presence of this indicator means that the customer is requesting for the PackageID field to be barcoded at the bottom of the label.


 
IrregularIndicator
string  = 1 characters  <= 1 
Mail classification defined by the USPS.   Valid values: 
1 = Balloon
2 = Oversize
3 = Not Applicable


 
Array of objects (schemas-Shipment_ShipmentIndicationType) 
 
MIDualReturnShipmentKey
string  [ 4 .. 50 ] characters  <= 1 
MIDualReturnShipmentKey is unique key required to process Mail Innovations Dual Return Shipment. 


The unique identifier (key) would be returned in response of first phase of Mail Innovations Dual Return Shipments. 


This unique identifier (key) would be part of request for second phase of Mail Innovations Dual Return Shipments.


Format: 
For Package return shipments, the package tracking number is concatenated with the system time (YYYY-MM-DDHH.MM.SS.NNN), followed by service code. 


For MI Return shipments, the Mail Manifest ID (MMI) is concatenated with the system time.  The unique identifier (key) is required to link the package and the Mail Innovations portion of Dual Return shipment. 


If unique identifier (key) is empty in the request for UPS Mail Innovations Return Service, the request will be treated as the first phase of the Mail Innovations Dual Returns Request. 


If the MIDualReturnShipmentIndicator is present with empty or null MIDualReturnShipmentKey in UPS Package Return Shipment, the request will be treated as the first phase of Dual MI Return Label Shipment. 


This field would be ignored if MIDualReturnShipmentIndicator is not present in UPS Package Return Shipment request.


 
MIDualReturnShipmentIndicator
string  <= 1 
MIDualReturnShipmentIndicator is an indicator to identify a Package Shipment is part of UPS Mail Innovations Dual Label Shipment. 


Its presence means Package Shipment is part of UPS Mail Innovations Dual Label shipment.  If the indicator is present in Package Shipment request, shipment would be considered as part of a Dual Mail Innovations Returns. 


This indicator is not valid with UPS Mail Innovations Returns Service code.


 
RatingMethodRequestedIndicator
string  <= 1 
Presence/Absence Indicator. Any value inside is ignored. RatingMethodRequestedIndicator is an indicator.
If present, Billable Weight Calculation method information and Rating Method information would be returned in response.


 
TaxInformationIndicator
string  <= 1 
Presence/Absence Indicator. Any value inside is ignored. TaxInformationIndicator is an indicator. If present, any taxes that may be applicable to a shipment would be returned in response. If this indicator is requested with NegotiatedRatesIndicator, Tax related information, if applicable, would be returned only for Negotiated Rates and not for Published Rates. The Tax related information includes any type of Taxes, corresponding Monetary Values, Total Charges with Taxes and disclaimers (if applicable) would be returned in response.


 
object (schemas-Shipment_ShipmentServiceOptions)   <= 1 
Container for Shipment Service Options.


 
Locale
string  = 5 characters  <= 1 
Represents 5 character ISO Locale that allows the user to request Reference Number Code on Label, Label instructions and Receipt instructions (if applicable) in desired language. 
Locale is specified by the combination of language code and country or territory code - 2 character language code and 2 character country or territory code seperated by an underscore ('_') character.  If Locale element is requested along with LabelLinksIndicator, the URL to retrieve Label and Receipts (if applicable) will be returned in the requested Locale. Please note only LabelURL and ReceiptURL (if applicable) will be returned. LocalLanguageLabelURL and LocalLanguageReceiptURL will not be returned if Locale element is present in request.
Queen's English (en_GB) is the default


 
ShipmentValueThresholdCode
string  = 2 characters  <= 1 
Shipment Value Threshold Code. 01 = Shipment value is below or equals to threshold value
02 = Shipment value is above threshold value.     NA = Not Applicable


 
MasterCartonID
string  [ 1 .. 24 ] characters  <= 1 
Master Carton ID. If Economy Service (17 or 72) : Economy Shipment will be associated with given Master Carton ID. If Non-Economy Service: Master Carton Shipment will be created for given Master Carton ID.


 
MasterCartonIndicator
string  <= 1 
Master Carton Indicator. Presence of the indicator means Master Carton ID will be created and returned to client. 
This is an empty tag, any value inside is ignored.                                                                  MasterCartonIndicator is only valid with Econmoy Shipment (Service Code 17 or 72). Will be ignored if master carton id present.


 
ShipmentDate
string  = 8 characters  <= 1 
User can send up to 7 days in the future with current date as day zero. Format: YYYYMMDD


 
required
Array of objects (Shipping_components-schemas-Shipment_Package)   <= 200 
 
QuoteID
string  = 35 characters  <= 1 
This field is used to pass the Quote ID generated from the Global Checkout API. This is mandatory to validate your Global Checkout Guaranteed Landed Cost.


 
object (Shipment_TradeDirect)   <= 1 
A UPS product that enables customers to ship directly from a manufacturer to end consumers in a different country.


 
object (ShipmentRequest_LabelSpecification)   <= 1 
Container used to define the properties required by the user to print and/or display the UPS shipping label.  Required for shipment without return service or shipments with PRL return service. Required for Electronic Return Label or Electronic Import Control Label shipments with SubVersion greater than or equal to 1707.


 
required
object (LabelSpecification_LabelImageFormat)   <= 1 
LabelImageFormat Container.


 
HTTPUserAgent
string  [ 1 .. 64 ] characters  <= 1 
Browser HTTPUserAgent String. This is the preferred way of identifying GIF image type to be generated.  Required if /ShipmentRequest/LabelSpecificationLabelSpecification/LabelImageFormat/Code = Gif. Default to Mozilla/4.5 if this field is missing or has invalid value.


 
required
object (LabelSpecification_LabelStockSize)   <= 1 
Container for the EPL2, ZPL or SPL label size.  Valid for EPL2, ZPL and SPL Labels.


 
Array of objects (LabelSpecification_Instruction) 
 
CharacterSet
string  = 3 characters  <= 1 
Language character set expected on label.
Valid values:
dan = Danish (Latin-1)
nld = Dutch (Latin-1)
fin = Finnish (Latin-1)
fra = French (Latin-1)
deu = German (Latin-1)
itl = Italian (Latin-1)
nor = Norwegian (Latin-1)
pol  = Polish (Latin-2)
por = Poruguese (Latin-1)
spa = Spanish (Latin-1) 
swe = Swedish (Latin-1) 
ces = Czech (Latin-2)
hun = Hungarian (Latin-2)
slk = Slovak (Latin-2)
rus = Russian (Cyrillic)
tur = Turkish (Latin-5)
ron = Romanian (Latin-2)
bul = Bulgarian (Latin-2)
est = Estonian (Latin-2)
ell = Greek (Latin-2)
lav = Latvian (Latin-2)
lit = Lithuanian (Latin-2)
eng = English (Latin-1)  Default is English (Latin-1).


 
object (ShipmentRequest_ReceiptSpecification)   <= 1 
Container used to allow the user to choose to print a thermal receipt.


 
required
object (ReceiptSpecification_ImageFormat)   <= 1 
ImageFormat Container.


 
Responses 
200
successful operation


400
Invalid Request


401
Unauthorized Request


403
Blocked Merchant


429
Rate Limit Exceeded


post/shipments/{deprecatedVersion}/ship
Request samples 
application/json
{
  • "ShipmentRequest": {
    }
}
Response samples 
application/json
{
  • "ShipmentResponse": {
    }
}
Void ShipmentDeprecated
The Void Shipping API is used to cancel the previously scheduled shipment


SecurityOAuth2 
Request 
path Parameters
deprecatedVersion
required
string
 Default:  "v1"
API Version.


Valid values:


    

  • v1
    • 



 
shipmentidentificationnumber
required
string  >= 1 
The shipment's identification number 
Alpha-numeric. Must pass 1Z rules. Must be 
upper case. Length 18


 
query Parameters
trackingnumber
string  >= 1 
The package's tracking number. You may have 
up to 20 different tracking numbers listed.
If more than one tracking number, pass this 
value as: trackingnumber= 
["1ZISUS010330563105","1ZISUS01033056310
8"] with a coma separating each number.
Alpha-numeric. Must pass 1Z rules. Must be 
upper case. Length 18


 
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


 
Responses 
200
successful operation


400
Invalid Request


401
Unauthorized Request


403
Blocked Merchant


429
Rate Limit Exceeded


delete/shipments/{deprecatedVersion}/void/cancel/{shipmentidentificationnumber}
Request samples 
Response samples 
application/json
{
  • "VoidShipmentResponse": {
    }
}
➔ Next to TradeDirect