UPS API Overview

Servicelevels Supported

ServiceCode	Description	Trigger	Region
01	Next Day Air	ServiceLevel = `NXTDYAIR`	Global
02	2nd Day Air	ServiceLevel = `2NDDYAIR`	Global
03	Ground	ServiceLevel = `GROUND`	US
07	Express	ServiceLevel = `EXPRESS`	Global
08	Expedited	ServiceLevel = `EXPEDITED`	Global
11	UPS Standard	ServiceLevel = `STANDARD`	Global
12	3 Day Select	ServiceLevel = `3DAYSELECT`	US
13	Next Day Air Saver	ServiceLevel = `NXTDYSAVER`	US
14	UPS Next Day Air Early	ServiceLevel = `NXTDYEARLY`	US
17	UPS Worldwide Economy DDU	ServiceLevel = `ECONOMYDDU`	Global
54	Express Plus	ServiceLevel = `PLUS`	Global
59	2nd Day Air A.M.	ServiceLevel = `2NDDAYAM`	US
65	UPS Saver	ServiceLevel = `SAVER`	Global
71	UPS Worldwide Express Freight Midday	ServiceLevel = `EXPFRAM`	Global
72	UPS Worldwide Economy DDP	ServiceLevel = `ECONOMYDDP`	Global
74	UPS Express 12:00	ServiceLevel = `1200`	Global
75	UPS Heavy Goods	ServiceLevel = `HEAVY`	US
83*	UPS Today Dedicated Courier	ServiceLevel = `DEDICATED`	Poland
84*	UPS Today Intercity	ServiceLevel = `INTERCITY`	Poland
85*	UPS Today Express	ServiceLevel = `EXPRTODAY`	Poland
86*	UPS Today Express Saver	ServiceLevel = `SAVERTODAY`	Poland
96	UPS Worlwide Express Freight	ServiceLevel = `EXPFREIGHT`	Global

Servicelevels with * are not supported by the UPS API

Servicelevels under construction

ServiceCode	Description	Future trigger	Region
M2	First Class Mail	ServiceLevel = `FIRSTMAIL`	US
M3	Priority Mail	ServiceLevel = `PRIOMAIL`	US
M4	Expedited Mail Innovations	ServiceLevel = `EXMAILINN`	US
M5	Priority Mail Innovations	ServiceLevel = `PRMAILINN`	US
M6	Economy Mail Innovations	ServiceLevel = `ECMAILINN`	US
M7	Mail Innovations (MI) Returns	ServiceLevel = `REMAILINN`	US
70	UPS Access Point Economy	ServiceLevel = `ACCESPOINT`	Global

Special services

Special services for all shipment types

Service Name	Service Code	Trigger
Saturday delivery	SaturdayDeliveryIndicator	shipment.timeWindows.delivery.onlySaturday = `true`
Saturday pickup	SaturdayPickupIndicator	datePickup is a Saturday
Cash on Delivery - Cash or check	COD	ServiceOptions.cashOnDelivery.value >0 Only for European origins
Direct delivery only	Direct Delivery Only (DDO) accessorial in a request would ensure that delivery is made only to the Ship To address on the shipping label	serviceOptions.allowDeliveryToNeighbour = `false` and serviceOptions.holdForPickup <> `true`
Delivery confirmation - signature	DeliveryConfirmation	serviceOptions.signatureForDelivery = `indirect` or `consigneeOnly`
Delivery confirmation - Adult signature	DeliveryConfirmation	serviceOptions.signatureForDelivery = `adult`
Notification - email	Notification	Setup via configuration
International forms	InternationalForms	Invoice is sent when: shipment is dutiable + shipment.commercialInvoice.lines exist
Inside delivery - Room of Choice	InsideDelivery 02	serviceOptions.deliveryInside = `true`
Commercial Invoice removal	CommercialInvoiceRemovalIndicator	serviceOptions.neutralDelivery = `true`
Additional handling package	AdditionalHandlingIndicator	handlingUnits.ServiceOptions.AdditionalHandling = `true`
Shipper release	ShipperReleaseIndicator	serviceOptions.signatureForDelivery = `noSignatureRequired` and collection.countryCode =`US` or `PR` AND collection.countryCode = `US` or `PR`
UPS Proactive Response	UPS 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 Response	handlingUnit.serviceOptions.monitoring.ups.proactiveResponse =`true`
Refrigeration	RefrigerationIndicator	handlingUnit.serviceOptions.equipmentTemperature = `cooled`, `frozen` or `cryo`
Dry Ice	Dry Ice weight	handlingUnit.goodsItems.dangerousGoods.type = `dryIce` handlingUnit.goodsItems.dangerousGoods.quantity.value & unitOfMeasure = `kgm` or `lbs`
Dry ice Audit Required	Indicates a Dry Ice audit will be performed per the Regulation Set requirements	serviceOptions.dryIceAudit = `true`
Alternative delivery address	Alternate Delivery Address (UPS Access Point Address)	addresses.dropOff in `carrierAssignedAddressId` the UPS Access Point ID should be provided
UPS Premier	Bronze, gold, platinum	handlingUnit.serviceOptions.monitoring.ups.premier: - 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 developer.ups.com appendix 2, below the list of codes that UPS allows

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

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

Service Name	Service Code	Trigger
LiftGate For PickUp	LiftGateForPickUpIndicator	serviceOptions.liftGate.collection = `true`
LiftGate For Delivery	LiftGateForDeliveryIndicator	serviceOptions.liftGate.delivery = `true`

Special services for pickup at access point shipments

Service Name	Service Code	Trigger
EPRA ReleaseCode	EPRAReleasCode	serviceOptions.holdForPickup =`Y` and serviceOptions.lockerDelivery.entryCode is populated
Deliver to consignee only	DeliverToAddresseeOnlyIndicator 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 shipment	serviceOptions.allowDeliveryToNeighbour = `false` and serviceOptions.holdForPickup =`true`

Return services

Following return services are available:

UPS Service code & name	Trigger
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 Label	serviceOptions.returns.pickupPolicy = `exchange`
11 = UPS Pack & Collect Service 1-Attempt Box 1	serviceOptions.returns.pickupPolicy = `paC1` and serviceOptions.returns.boxType = `1`
12 = UPS Pack & Collect Service 1-Attempt Box 2	serviceOptions.returns.pickupPolicy = `paC1` and serviceOptions.returns.boxType = `2`
13 = UPS Pack & Collect Service 1-Attempt Box 3	serviceOptions.returns.pickupPolicy = `paC1` and serviceOptions.returns.boxType = `3`
14 = UPS Pack & Collect Service 1-Attempt Box 4	serviceOptions.returns.pickupPolicy = `paC1` and serviceOptions.returns.boxType = `4`
15 = UPS Pack & Collect Service 1-Attempt Box 5	serviceOptions.returns.pickupPolicy = `paC1` and serviceOptions.returns.boxType = `5`
16 = UPS Pack & Collect Service 3-Attempt Box 1	serviceOptions.returns.pickupPolicy = `paC3` and serviceOptions.returns.boxType = `1`
17 = UPS Pack & Collect Service 3-Attempt Box 2	serviceOptions.returns.pickupPolicy = `paC3` and serviceOptions.returns.boxType = `2`
18 = UPS Pack & Collect Service 3-Attempt Box 3	serviceOptions.returns.pickupPolicy = `paC3` and serviceOptions.returns.boxType = `3`
19 = UPS Pack & Collect Service 3-Attempt Box 4	serviceOptions.returns.pickupPolicy = `paC3` and serviceOptions.returns.boxType = `4`
20 = UPS Pack & Collect Service 3-Attempt Box 5	serviceOptions.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 Name	Service Code	Trigger
Notification - voice message	Notification	Not implemented
Notification - text message message	Notification	Not implemented
Returns of Document	The shipper has requested the ReturnOfDocument accessorial be added to the shipment Valid for Poland to Poland shipment	Not implemented
Carbon Neutral shipment request	Indicates the shipment will be rated as carbon neutral	Not implemented
Exchanger forward	ExchangeForwardIndicator	Not implemented
SDL shipment	SDLShipmentIndicator	Not implemented
Inside delivery - White glove	InsideDelivery 01	Not implemented
Inside delivery - Installation	InsideDelivery 03	Not implemented
Item Disposal	ItemDisposal	Not implemented
UPS Premium Care Only valid for Canada to Canada movements	PremiumCareIndicator	Not implemented
Hazmat	Dangerous goods	Not implemented
Dry ice Medical Use	Relevant 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 there	Not implemented

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

Service Name	Service Code	Trigger
Pre Alert notification - email	PreAlertNotifcation	Not implemented
Pre Alert notification - voice message	PreAlertNotifcation	Not implemented
Pre Alert notification - text message	PreAlertNotifcation	Not implemented

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

Service Name	Service Code	Trigger
Hold for Pickup	HoldForPickupIndicator	Not implemented
Dropoff At UPS Facility	DropoffAtUPSFacilityIndicator	Not implemented
Restricted Articles - Diagnostic Specimens	DiagnosticSpecimensIndicator	Not implemented
Restricted Articles - Alchoholic beverages	AlcoholicBeveragesIndicator	Not implemented
Restricted Articles - Perishables	PerishablesIndicator	Not implemented
Restricted Articles - Plants	PlantsIndicator	Not implemented
Restricted Articles - Seeds	SeedsIndicator	Not implemented
Restricted Articles - Special Exceptions	SpecialExceptionsIndicator	Not implemented
Restricted Articles - Tobacco	TobaccoIndicator	Not implemented
Shipper Export declaration for	ShipperExportDeclarationIndicator indicates that customer would be using UPS prepared SED form	Not implemented

Special services for import control shipments

Service Name	Service Code	Trigger
Import control	ImportControlIndicator	Not implemented

Special services for pickup at access point shipments

Service Name	Service Code	Trigger
Access point COD	AccessPointCOD	Not implemented

Package Types available

We map the following package types to UPS:

UPS Packagecode	Description	gateway package type
01	UPS Letter	`carrier-envelope`
02	Customer Supplied Package	Default if nothing else found
03	Tube	`carrier-tube`
04	PAK	`carrier-pak`
24	UPS 25KG Box	`carrier-25kg-box`
25	UPS 10KG Box	`carrier-10kg-box`
30	Pallet	`pallet`
2a	Small Express Box	`carrier-small-box`
2b	Medium Express Box	`carrier-medium-box`
2c	Large Express Box	`carrier-large-box`

Other packages

Below UPS package codes can be configured with a custom mapping in the ordering configuration.

UPS Packagecode	Description	gateway package type
21	UPS Express Box	Use custom mapping
56	Flats	Use custom mapping
57	Parcels	Use custom mapping
58	BPM	Use custom mapping
59	First Class	Use custom mapping
60	Priority	Use custom mapping
61	Machineables	Use custom mapping
62	Irregulars	Use custom mapping
63	Parcel Post	Use custom mapping
64	BPM Parcel	Use custom mapping
65	Media Mail	Use custom mapping
66	BPM Flat	Use custom mapping
67	Standard Flat	Use 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 ups.com. 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.