UPS API Overview

Servicelevels Supported

01Next Day AirServiceLevel = NXTDYAIRGlobal
022nd Day AirServiceLevel = 2NDDYAIRGlobal
03GroundServiceLevel = GROUNDUS
07ExpressServiceLevel = EXPRESSGlobal
08ExpeditedServiceLevel = EXPEDITEDGlobal
11UPS StandardServiceLevel = STANDARDGlobal
123 Day SelectServiceLevel = 3DAYSELECTUS
13Next Day Air SaverServiceLevel = NXTDYSAVERUS
14UPS Next Day Air EarlyServiceLevel = NXTDYEARLYUS
17UPS Worldwide Economy DDUServiceLevel = ECONOMYDDUGlobal
54Express PlusServiceLevel = PLUSGlobal
592nd Day Air A.M.ServiceLevel = 2NDDAYAMUS
65UPS SaverServiceLevel = SAVERGlobal
71UPS Worldwide Express Freight MiddayServiceLevel = EXPFRAMGlobal
72UPS Worldwide Economy DDPServiceLevel = ECONOMYDDPGlobal
74UPS Express 12:00ServiceLevel = 1200Global
75UPS Heavy GoodsServiceLevel = HEAVYUS
83*UPS Today Dedicated CourierServiceLevel = DEDICATEDPoland
84*UPS Today IntercityServiceLevel = INTERCITYPoland
85*UPS Today ExpressServiceLevel = EXPRTODAYPoland
86*UPS Today Express SaverServiceLevel = SAVERTODAYPoland
96UPS Worlwide Express FreightServiceLevel = EXPFREIGHTGlobal

Servicelevels with * are not supported by the UPS API

Servicelevels under construction
ServiceCodeDescriptionFuture triggerRegion
M2First Class MailServiceLevel = FIRSTMAILUS
M3Priority MailServiceLevel = PRIOMAILUS
M4Expedited Mail InnovationsServiceLevel = EXMAILINNUS
M5Priority Mail InnovationsServiceLevel = PRMAILINNUS
M6Economy Mail InnovationsServiceLevel = ECMAILINNUS
M7Mail Innovations (MI) ReturnsServiceLevel = REMAILINNUS
70UPS Access Point EconomyServiceLevel = ACCESPOINTGlobal

Special services

Special services for all shipment types

Service NameService CodeTrigger
Saturday = true
Saturday pickupSaturdayPickupIndicatordatePickup is a Saturday
Cash on Delivery - Cash or checkCODServiceOptions.cashOnDelivery.value >0
Only for European origins
Direct delivery onlyDirect Delivery Only (DDO) accessorial in a request would ensure that delivery is made only to the Ship To address on the shipping labelserviceOptions.allowDeliveryToNeighbour = false and serviceOptions.holdForPickup <> true
Delivery confirmation - signatureDeliveryConfirmationserviceOptions.signatureForDelivery = indirect or consigneeOnly
Delivery confirmation - Adult signatureDeliveryConfirmationserviceOptions.signatureForDelivery = adult
Notification - emailNotificationSetup via configuration
International formsInternationalFormsInvoice is sent when: shipment is dutiable + shipment.commercialInvoice.lines exist
Inside delivery - Room of ChoiceInsideDelivery 02serviceOptions.deliveryInside = true
Commercial Invoice removalCommercialInvoiceRemovalIndicatorserviceOptions.neutralDelivery = true
Additional handling packageAdditionalHandlingIndicatorhandlingUnits.ServiceOptions.AdditionalHandling = true
Shipper releaseShipperReleaseIndicatorserviceOptions.signatureForDelivery = noSignatureRequired and collection.countryCode =US or PR AND collection.countryCode = US or PR
UPS Proactive ResponseUPS Proactive Response and proactive package tracking.Contractual accessorial for health care companies to allow package monitoring throughout the UPS system. Shippers account needs to have valid contract for UPS Proactive =true
RefrigerationRefrigerationIndicatorhandlingUnit.serviceOptions.equipmentTemperature = cooled, frozen or cryo
Dry IceDry Ice weighthandlingUnit.goodsItems.dangerousGoods.type = dryIce
handlingUnit.goodsItems.dangerousGoods.quantity.value & unitOfMeasure = kgm or lbs
Dry ice Audit RequiredIndicates a Dry Ice audit will be performed per the Regulation Set requirementsserviceOptions.dryIceAudit = true
Alternative delivery addressAlternate Delivery Address (UPS Access Point Address)addresses.dropOff
in carrierAssignedAddressId the UPS Access Point ID should be provided
UPS PremierBronze, gold,
- category: silver, gold or platinum
- instructionCodes: one of the UPS handling Instruction codes 001-015 (excl 013)
handlingUnit.references.rfidRefeference for the tracker from UPS

UPS Premier handling instructions codes

As per appendix 2, below the list of codes that UPS allows

Instruction CodeHandling Instruction (Executed Upon Exception with Delay)Exclusivity with Other CodesSilverGoldPlatinum
001No Special Handling RequiredCannot be selected with any other code111
002Controlled Room Temperature (CRT) - Do Not Refrigerate, Maintain Temp Range = 15 - 25 C)Mutually Exclusive (within 02 through 06)111
003Refrigerate (Temp Range = 2-8 C)Mutually Exclusive (within 02 through 06)111
004Frozen (Freezer) ( Temp Range <-20 C)Mutually Exclusive (within 02 through 06)111
005Dry Ice Replenish (Temp Range <-80 C)Mutually Exclusive (within 02 through 06)111
006Cryo - Liquid-Nitrogen dry-vapor (Temp Range < -150 C) - do not open liquid nitrogen tankMutually Exclusive (within 02 through 06)111
007Return to Shipper111
008Expedite To Receiver - All Modes Up to and Including Extraction to CourierMutually Exclusive (within 08 through 10)11
009Expedite To Receiver - UPS Air Network Only (Next Flight)Mutually Exclusive (within 08 through 10)111
010Expedite To Receiver - Ground Courier only (No Air)Mutually Exclusive (within 08 through 10)11
011Hold for Instruction11
012Hold for Will Call111
014Contact UPS Premier Control Tower111
015Upgrade to Weekend Delivery (if not delivered Friday)111

Special services for UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday

Service NameService CodeTrigger
LiftGate For PickUpLiftGateForPickUpIndicatorserviceOptions.liftGate.collection = true
LiftGate For = true

Special services for pickup at access point shipments

Service NameService CodeTrigger
EPRA ReleaseCodeEPRAReleasCodeserviceOptions.holdForPickup =Y and serviceOptions.lockerDelivery.entryCode is populated
Deliver to consignee onlyDeliverToAddresseeOnlyIndicator is shipper specified restriction that requires the addressee to be the one who takes final delivery of the “Hold For PickUp at UPS Access Point package. Presence of indicator means shipper restriction will apply to the shipmentserviceOptions.allowDeliveryToNeighbour = false and serviceOptions.holdForPickup =true

Return services

Following return services are available:

UPS Service code & nameTrigger
2 = UPS Print and Mail (PNM)Not implemented
3 = UPS Return Service 1-Attempt (RS1)serviceOptions.returns.pickupPolicy = one
5 = UPS Return Service 3-Attempt (RS3)serviceOptions.returns.pickupPolicy = fixed
8 = UPS Electronic Return Label (ERL)serviceOptions.returns.pickupPolicy = erl
In configuration choose if email should be sent with label to email in collection address
9 = UPS Print Return Label (PRL)serviceOptions.returns.pickupPolicy = prl
10 = UPS Exchange Print Return LabelserviceOptions.returns.pickupPolicy = exchange
11 = UPS Pack & Collect Service 1-Attempt Box 1serviceOptions.returns.pickupPolicy = paC1
and serviceOptions.returns.boxType = 1
12 = UPS Pack & Collect Service 1-Attempt Box 2serviceOptions.returns.pickupPolicy = paC1
and serviceOptions.returns.boxType = 2
13 = UPS Pack & Collect Service 1-Attempt Box 3serviceOptions.returns.pickupPolicy = paC1
and serviceOptions.returns.boxType = 3
14 = UPS Pack & Collect Service 1-Attempt Box 4serviceOptions.returns.pickupPolicy = paC1
and serviceOptions.returns.boxType = 4
15 = UPS Pack & Collect Service 1-Attempt Box 5serviceOptions.returns.pickupPolicy = paC1
and serviceOptions.returns.boxType = 5
16 = UPS Pack & Collect Service 3-Attempt Box 1serviceOptions.returns.pickupPolicy = paC3
and serviceOptions.returns.boxType = 1
17 = UPS Pack & Collect Service 3-Attempt Box 2serviceOptions.returns.pickupPolicy = paC3
and serviceOptions.returns.boxType = 2
18 = UPS Pack & Collect Service 3-Attempt Box 3serviceOptions.returns.pickupPolicy = paC3
and serviceOptions.returns.boxType = 3
19 = UPS Pack & Collect Service 3-Attempt Box 4serviceOptions.returns.pickupPolicy = paC3
and serviceOptions.returns.boxType = 4
20 = UPS Pack & Collect Service 3-Attempt Box 5serviceOptions.returns.pickupPolicy = paC3
and serviceOptions.returns.boxType = 5
Other services These are not implemented but UPS offers them via their integration. If you need any of these service options, please contact us.

Special services for all shipment types

Service NameService CodeTrigger
Notification - voice messageNotificationNot implemented
Notification - text message messageNotificationNot implemented
Returns of DocumentThe shipper has requested the ReturnOfDocument accessorial be added to the shipment Valid for Poland to Poland shipmentNot implemented
Carbon Neutral shipment requestIndicates the shipment will be rated as carbon neutralNot implemented
Exchanger forwardExchangeForwardIndicatorNot implemented
SDL shipmentSDLShipmentIndicatorNot implemented
Inside delivery - White gloveInsideDelivery 01Not implemented
Inside delivery - InstallationInsideDelivery 03Not implemented
Item DisposalItemDisposalNot implemented
UPS Premium Care
Only valid for Canada to Canada movements
PremiumCareIndicatorNot implemented
HazmatDangerous goodsNot implemented
Dry ice Medical UseRelevant only in CFR regulation set. If present it is used to designate the Dry Ice is for any medical use and rates are adjusted for DryIce weight more than 2.5 KGS or 5.5 LBS.Not implemented
UPS Access Point Delivery aka Retail to Retail (R2R)Where merchant delivers goods to UPS Access point and ups picks up from thereNot implemented

Special services for UPS Returns Exchange and UPS Returns Pack and Collect shipments

Service NameService CodeTrigger
Pre Alert notification - emailPreAlertNotifcationNot implemented
Pre Alert notification - voice messagePreAlertNotifcationNot implemented
Pre Alert notification - text messagePreAlertNotifcationNot implemented

Special services for UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday

Service NameService CodeTrigger
Hold for PickupHoldForPickupIndicatorNot implemented
Dropoff At UPS FacilityDropoffAtUPSFacilityIndicatorNot implemented
Restricted Articles - Diagnostic SpecimensDiagnosticSpecimensIndicatorNot implemented
Restricted Articles - Alchoholic beveragesAlcoholicBeveragesIndicatorNot implemented
Restricted Articles - PerishablesPerishablesIndicatorNot implemented
Restricted Articles - PlantsPlantsIndicatorNot implemented
Restricted Articles - SeedsSeedsIndicatorNot implemented
Restricted Articles - Special ExceptionsSpecialExceptionsIndicatorNot implemented
Restricted Articles - TobaccoTobaccoIndicatorNot implemented
Shipper Export declaration forShipperExportDeclarationIndicator
indicates that customer would be using UPS prepared SED form
Not implemented

Special services for import control shipments

Service NameService CodeTrigger
Import controlImportControlIndicatorNot implemented

Special services for pickup at access point shipments

Service NameService CodeTrigger
Access point CODAccessPointCODNot implemented

Package Types available

We map the following package types to UPS:

UPS PackagecodeDescriptiongateway package type
01UPS Lettercarrier-envelope
02Customer Supplied PackageDefault if nothing else found
24UPS 25KG Boxcarrier-25kg-box
25UPS 10KG Boxcarrier-10kg-box
2aSmall Express Boxcarrier-small-box
2bMedium Express Boxcarrier-medium-box
2cLarge Express Boxcarrier-large-box
Other packages Below UPS package codes can be configured with a custom mapping in the ordering configuration.
UPS PackagecodeDescriptiongateway package type
21UPS Express BoxUse custom mapping
56FlatsUse custom mapping
57ParcelsUse custom mapping
58BPMUse custom mapping
59First ClassUse custom mapping
60PriorityUse custom mapping
61MachineablesUse custom mapping
62IrregularsUse custom mapping
63Parcel PostUse custom mapping
64BPM ParcelUse custom mapping
65Media MailUse custom mapping
66BPM FlatUse custom mapping
67Standard FlatUse custom mapping

International forms

For shipments, UPS provides the option to add international forms. These are typically used for Dutiable shipments. We have implemented following types of international forms:

  • Commercial Invoice: we upload the commercial invoice data to UPS, so UPS can generate the commercial invoice.
  • Parcial Invoice: applies as invoice for return shipments
  • Customer generated forms: this is where the user can upload a PDF file with the shipment. This is a contractual service with UPS and needs to be enabled on the account on See paperless-api-enrollment for details how to enable this service.

The documents that UPS creates are returned by UPS and are available in ShipitSmarter as a PDF file.

Other forms Below forms are not implemented but UPS offers them via their integration. If you need any of these forms, please contact us. - Certificate of Origin -> Not supported - NAFTA Certificate of Origin -> Not supported - Packing list --> Not supported - Airfreight packing list --> Not supported - CN22 Form (Only US outbound)--> Not supported - UPS Premium Care Form (Only Canada domestic)--> Not supported

Commercial Invoice

The commercial invoice is generated by the system based on the information provided in the shipment. The following fields are mandatory:

  • Shipment should be dutiable
    • Dutiable means: shipment is under bond (shipment.serviceOptions.customsClearance=true) or all below conditions are met:
      • Shipment is crossing a customs region border (e.g. from EU to US)
      • Shipment is not a document
  • Shipment should contain invoice lines: shipment.commercialInvoice.lines should be populated
  • UPS Only accepts 1 currency for the complete invoice. The invoice is taken from:
    • The declared value on shipment level: shipment.declaredValue.currencyCode
    • If above empty: the first invoice line: shipment.commercialInvoice.line.unitCustomsValue.currencyCode

Partial Invoice

This is the same invoice as the commercial invoice, but only triggered if it is a return shipment: shipment.serviceOptions.returns.isReturn = true

Rating API specifics

When using the rating API, we always request all available service options including transit times. If supported by UPS, it includes the same service options as the shipping API.

Not implemented for Rates API

  • TaxInformation: 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. 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.
  • PromotionalDiscount: PromotionCode and Promotion alias for discount on shipment charges.
  • Freight shipments
  • MasterCartons: MasterCartonIndicator is only valid with Econmoy Shipment
  • WWEShipment
  • Collect, ThirdParty, ConsigneeBilled accounts are not transmitted to UPS. The price is always basedon the contract with UPS for the shipper.