ShipmentSpecialServices Property
Contains the collection of special services offered by UPS on shipment level.
Syntax
upsrates.getShipmentSpecialServices([callback]) upsrates.setShipmentSpecialServices( shipmentSpecialServices, [callback])
Default Value
0
Callback
The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).
The callback for the getShipmentSpecialServices([callback]) method is defined as:
function(err, data){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'data' is the value returned by the method.
The callback for the setShipmentSpecialServices([callback]) method is defined as:
function(err){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'err' has 2 properties which hold detailed information:
err.code err.message
Remarks
To request any of the special services offered by UPS in a rate request, you must set the ShipmentSpecialServices to a set of flags as listed below (specified in hexadecimal notation). They can be or-ed together to include multiple conditions:
Value | Meaning |
0x00008000L | Hold for Pickup |
0x00100000L | Liftgate Dropoff |
0x00200000L | Liftgate Pickup |
0x08000000L | Return Shipment |
0x10000000L | Saturday Delivery |
0x20000000000L | Return of Document |
0x40000000000L | Import Control |
0x80000000000L | Commercial Invoice Removal |
0x0100000000000L | Exchange Forward |
0x0200000000000L | Carbon Neutral |
0x0400000000000L | Dropoff at UPS Facility |
The meaning and limitations for each special service option are listed below:
- Hold for Pickup:
This indicates that UPS should deliver your package to the UPS Customer Center you choose and then call the recipient
when the package is ready.
This is applicable only if ServiceType is set to stUPSWorldwideExpressFreight.
- Liftgate Dropoff:
This requests that UPs provide their liftgate services unload a shipment when unloading docks are not available.
This is applicable only if ServiceType is set to stUPSWorldwideExpressFreight.
- Liftgate Pickup:
This requests that UPs provide their liftgate services load a shipment when loading docks are not available.
This is applicable only if ServiceType is set to stUPSWorldwideExpressFreight.
- Return Shipment:
This is applicable to return shipments only. Indicates that the ship request is made for Print Return Label (PRL).
With this option you can print a return label to include in an outbound shipment, or provide a label to your customer separately.
If you want to arrange for UPS to mail a return label to your customer, you can use the ReturnPrintAndMail config setting.
If you want to arrange for UPS to email a return label to your customer, you can use the ElectronicReturnLabel config setting.
If you want to arrange for UPS to make one attempt to pick up the package to be returned, you can use the ReturnServiceFirstAttempt config setting.
If you want to arrange for UPS to make three attempts to pick up the package to be returned, you can use the ReturnServiceThirdAttempt config setting.
Using the last 4 options: in the server response, you will receive only a Tracking number for the shipment to be returned, but not a return label and/or return receipt.
For return shipments, one of the following conditions must be met on AccountCountryCode, SenderCountryCode and RecipientCountryCode: At least two of these country codes are the same; None of these country codes are the same and are a member of the EU; None of these country codes are the same and at least one of them is not a member of the EU, and the shipper must have third country contract service. Following is a list of restrictions that are applicable when using return label types. This cannot be combined with COD, Saturday Delivery, Saturday Pickup, and/or Delivery Confirmation service options. For international shipments with return service, the Invoice flag is the only valid value for FormTypes. The availability of return service depends on the origin and destination country code, and on the selected ServiceType. The PackageDescription is required to be provided in the request for each package contained in the shipment. The PackageType should be set to a value other than: 4 (ptUPS25kgBox), 5 (ptUPS10kgBox), and 6 (ptPallet). Return shipments cannot be voided at the package level. Return shipments can be voided within 24 hours only.
Also please note that when you set this option that only the return label is being printed, you must submit a separate request to print the shipping label.
- Saturday Delivery: Indicates that you request to have the shipment delivered on a Saturday. Saturday delivery service is available for an additional charge depending on the package service type and origin/destination pair. This service is not available for return shipments.
- Return of Document: This may also be referred to as the Return of Invoice service and is unique to Poland. If set UPS will use their Return of Document service to return the signed invoice to the shipper.
- Commercial Invoice Removal: When set this will indicate that the commercial invoice should be removed before delivery, thus not revealing the value of the contents to the recipient.
- Carbon Neutral: This is required to make a shipment that is carbon neutral.
- Exchange Forward: This is required in order to make exchange forward shipments.
- Dropoff at UPS Facility:
When set this indicates that the package will be dropped off at a UPS Facility.
This is applicable only if ServiceType is set to stUPSWorldwideExpressFreight.
Data Type
Long64