Upload
others
View
6
Download
0
Embed Size (px)
Citation preview
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 1 of 166
Gemini Web Service API
Developer’s Guide
UPS – Gemini 8.0
July 9th, 2018
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 2 of 166
Quick Start
Introduction ....................................................................................................................................... 6
Process Descriptions ................................................................................................................................. 8
Command Overview List .......................................................................................................................... 14
Best Practices ............................................................................................................................................ 15
System Overview and Design ................................................................................................................. 17
Calling the Gemini Web Service API ...................................................................................................... 22
Installing the Gemini XML Validator ...................................................................................................... 23
Labels and Label Information ................................................................................................................. 27
Manifest Documents ................................................................................................................................. 27
Integrated Shipment Tracking ................................................................................................................ 27
Appendix A: Service Codes .................................................................................................................... 28
Appendix B: Command Formats and Details ....................................................................................... 29
Appendix C: XML Schema Document (XSD) ........................................................................................ 92
Appendix D: Master API Error Code List .............................................................................................. 93
Appendix E: Error Groups ..................................................................................................................... 147
Appendix F: Java Coding Examples and Class Definitions ............................................................ 149
Appendix G: Payment Types................................................................................................................. 152
Glossary .................................................................................................................................................... 153
End User License Agreement (EULA) and Full Disclaimer .............................................................. 158
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 3 of 166
Table of Contents
Introduction .................................................................................................................................................. 6
Gemini 7 Web Service Interface ............................................................................................................................ 6
Development Tools ................................................................................................................................................. 6
Technical Support ................................................................................................................................................... 6
Certification of 3rd Party Vendor Software ............................................................................................................ 7
Responsibilities ....................................................................................................................................................... 7
Business Rules ....................................................................................................................................................... 7
Disclaimer ................................................................................................................................................................ 7
Process Descriptions ................................................................................................................................. 8
Orders ...................................................................................................................................................................... 8
Consolidation of Orders Together into Shipments ................................................................................................ 8
Shipping Labels ...................................................................................................................................................... .9
Final Processing of Shipments .............................................................................................................................10
Manifest and Interim Manifest Printing ................................................................................................................11
Summary of Typical Steps That Occur When Invoking Commands ..................................................................11
Command Overview List .......................................................................................................................... 14
Best Practices ............................................................................................................................................ 15
Programmers’ Best Practice for Calling Commands...........................................................................................15
System Overview and Design ................................................................................................................. 17
Gemini Interface Architecture ...............................................................................................................................17
Gemini Interface Component Design ...................................................................................................................18
SOAP Protocol ......................................................................................................................................................18
SOAP Envelope Header for Commands and Returns ........................................................................................18
Security ..................................................................................................................................................................19
XML Header ..........................................................................................................................................................19
Standard XML Format for Calling a Function ......................................................................................................20
Standard Error Return Fields ...............................................................................................................................21
Calling the Gemini Web Service API ...................................................................................................... 22
Formatting the XML ..............................................................................................................................................22
Sending Formatted XML to the UPS Gemini Servers ........................................................................................22
Checking the Result ..............................................................................................................................................22
Installing the Gemini XML Test Harness ............................................................................................... 23
List of XML Test Harness Files & XML Templates .............................................................................................23
Installation is Simple .............................................................................................................................................24
How to “Debug” Your XML Input ..........................................................................................................................24
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 4 of 166
Labels and Label Information ................................................................................................................. 27
Manifest Documents ................................................................................................................................. 27
Embedded PDF images........................................................................................................................................27
Integrated Shipment Tracking ................................................................................................................ 27
Appendix A: Service Codes .................................................................................................................... 28
Appendix B: Command Formats and Details ....................................................................................... 29
UserAuthenticate...................................................................................................................................................29
GetPaymentTypes ................................................................................................................................................31
GetCurrencyCodes ...............................................................................................................................................33
GetCountries .........................................................................................................................................................35
GetServices ...........................................................................................................................................................37
GetAirportCities .....................................................................................................................................................39
GetCityData ...........................................................................................................................................................41
OrderRate ..............................................................................................................................................................47
OrderSubmit ..........................................................................................................................................................49
OrderSave .............................................................................................................................................................61
OrderPostpone ......................................................................................................................................................64
PostponeAll ...........................................................................................................................................................66
OrderCancel ..........................................................................................................................................................68
OrderSearch ..........................................................................................................................................................69
ShipmentCancel ....................................................................................................................................................73
PrintLabel ..............................................................................................................................................................75
PrintManifest .........................................................................................................................................................77
EODSubmit............................................................................................................................................................80
Update ...................................................................................................................................................................82
ConsigneeSave .....................................................................................................................................................84
ConsigneeSearch..................................................................................................................................................87
Appendix C: XML Schema Document (XSD) ........................................................................................ 92
Appendix D: Master API Error Code List .............................................................................................. 93
Appendix E: Error Groups ..................................................................................................................... 147
Appendix F: Java Coding Examples and Class Definitions ............................................................ 149
Appendix G: Payment Types................................................................................................................. 152
Glossary .................................................................................................................................................... 153
End User License Agreement (EULA) and Full Disclaimer .............................................................. 158
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 5 of 166
Table of Figures Figure 1: Summary of Commands......................................................................................................................... 14 Figure 2: Architectural Overview ................................................................................................................ 17 Figure 3: Standard XML Header for Each Command ................................................................................. 19 Figure 4: Error Return Fields....................................................................................................................... 21 Figure 5: List of Files Included with the Gemini 7.0 Installation Package ................................................. 24 Figure 6: Service Codes .............................................................................................................................. 28 Figure 7: UserAuthenticate Record Layout ................................................................................................ 29 Figure 8: UserAuthenticate Return Fields .................................................................................................. 30 Figure 9: GetPaymentTypes Record Layout ............................................................................................... 31 Figure 10: GetPaymentTypes Return Fields ............................................................................................... 32 Figure 11: GetCurrencyCodes Record Layout ........................................................................................... 33 Figure 12: GetCurrencyCodes Return Fields ............................................................................................. 34 Figure 13: GetCountries Record Layout ..................................................................................................... 35 Figure 14: GetCountries Return Fields ....................................................................................................... 36 Figure 15: GetServices Record Layout ....................................................................................................... 37 Figure 16: GetServices Return Fields ......................................................................................................... 38 Figure 17: GetAirportCities Record Layout ................................................................................................ 39 Figure 18: GetAirportCities Return Fields .................................................................................................. 40 Figure 19: GetCityData Record Layout ....................................................................................................... 42 Figure 20: GetCityData Return Fields ......................................................................................................... 43 Figure 21: OrderRate Return Fields ............................................................................................................ 48 Figure 22: OrderSubmit Record Layout ...................................................................................................... 53 Figure 23: Items Array Record Layout ........................................................................................................ 53 Figure 24: OrderSubmit Return Fields ........................................................................................................ 55 Figure 25 OrderPostpone Record Layout ................................................................................................... 64 Figure 26: OrderPostpone Return Fields .................................................................................................... 65 Figure 27: PostponeAll Record Layout ....................................................................................................... 66 Figure 28: PostponeAll Return Fields ......................................................................................................... 67 Figure 29: Order Cancel Record Layout ..................................................................................................... 68 Figure 30: OrderCancel Return Fields ........................................................................................................ 68 Figure 31: OrderSearch Record Layout ...................................................................................................... 70 Figure 32: OrderSearch Return Fields ........................................................................................................ 71 Figure 33: Possible Criteria Operators ....................................................................................................... 73 Figure 34: Order Status Values ................................................................................................................... 73 Figure 35: ShipmentCancel Record Layout ................................................................................................ 74 Figure 36: ShipmentCancel Return Fields .................................................................................................. 74 Figure 37: PrintLabel Record Layout .......................................................................................................... 76 Figure 38: PrintLabel Return Fields ............................................................................................................ 76 Figure 39: PrintManifest Record Layout ..................................................................................................... 78 Figure 40: PrintManifest Return Fields ....................................................................................................... 79 Figure 41: EODSubmit Record Layout ........................................................................................................ 80 Figure 42: EODSubmit Return Fields .......................................................................................................... 81 Figure 43: Update Record Layout ............................................................................................................... 83 Figure 44: Update Types ............................................................................................................................. 83 Figure 45: Update Return Fields ................................................................................................................. 83 Figure 46: ConsigneeSave Record Layout ................................................................................................. 85 Figure 47: ConsigneeSave Return Fields ................................................................................................... 86 Figure 48: ConsigneeSearch Record Layout .............................................................................................. 87 Figure 49: ConsigneeSearch Return Fields ................................................................................................ 89
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 6 of 166
Introduction
Welcome to Gemini™, the fast and efficient shipping system from UPS. Powered by Gemini, you can:
• Send freight data to us from your computerized shipping system
• Generate standard UPS shipping labels and manifests
• Search submitted orders by various criteria
• Cancel submitted order requests
• Calculate freight rates for intra-country and export shipments.
Gemini streamlines your shipping process by providing you with timely information, by automating order processing and order management, and by creating shipping labels and manifest documentation.
In addition, a publicly exposed component that is separate from Gemini provides you with integrated shipment tracking via the Internet. Internet shipment tracking enables you to monitor the status of your shipments quickly and efficiently. Once our company has received your freight, you can get real-time status updates on your shipments, regardless of the mode of transportation.
We designed our fast and efficient shipping system to integrate your supply-chain systems with our company’s system while maintaining the security of both systems. Third-party shipping systems and in-house systems can use our proprietary shipping system to process UPS shipments. UPS will work with you or your third-party application provider to provide you with the best service available.
Gemini Web Service Interface
The Gemini Web Service API provides an interface to our company’s Gemini shipment entry system via the Internet. The interface allows UPS customers to make Gemini calls remotely through the Internet to UPS server running the Gemini system.
Our company’s Gemini Web Service uses Simple Object Access Protocol (SOAP). The data passed in and returned must match exactly the XML format specified by our company.
The Gemini Web Service is available on SSL only and requires HTTPS connection for access. HTTP requests are not allowed.
This document describes how to access the Gemini Web Service Interface and the data that the interface returns.
Development Tools
UPS provides developers with an interface test package to simplify integration with our company’s Gemini system. The Gemini Interface Test Package includes:
• Technical specifications
• A test application that demonstrates how developers can implement the API calls
• XML code examples
Technical Support
Technical support assistance is available by calling 1-800-327-2370. Ask to speak to the Gemini API
Solutions Coordinator. You will receive a case number and a return call from the support team.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 7 of 166
Certification of Third Party Vendor Software
Dealers selling and/or promoting a “UPS -capable” shipping system to a UPS customer must certify that system through our company. Systems sold to a UPS customer that are not certified are not eligible for support. We will provide vendor companies with the technical specifications, a test interface, and other support deemed necessary to develop and certify a shipping system. Certification is the ultimate shipper’s assurance that UPS believes the vendor system will label, manifest, route, and rate their freight accurately.
A quick certification is possible when developers use the Gemini API for only the basic functions of:
• Shipment numbers (with or without consolidation)
• Manifesting
• Labeling
Some business environments will require more complex patterns of Gemini API transactions and such solutions may require more “technical design” discussions with the Gemini API Coordinator and a lengthier certification process.
Responsibilities
Should shipping systems experience problems due to integration or configuration issues, UPS will make every effort to advise the dealer or developer immediately and work together to resolve the problem.
UPS will not be responsible for the cost of integrating, configuring, or any modifications necessary to bring the system into compliance with our company’s specifications.
UPS encourages dealers to ensure that they cover all possible maintenance and training issues with the end user thoroughly at the time of purchase.
Business Rules
For the complete version of our company’s freight rules and limitations, see “Terms and Conditions of Contract” at https://www.ups.com/media/en/AirFreight_TandC.pdf
Disclaimer
All statements made in this document are subject to change without notification. No part of this document should be considered an agreement to provide support or maintenance to any shipping system. Our company’s support is limited to verifying the accuracy of data submitted to and received from our company.
UPS is not responsible for the purchase, scheduling of installation, installation, or maintenance of any shipping system at any customer site unless representatives of UPS and the developer and/or dealer performing the installation specifically indicate this by an agreement in writing and sign the agreement. UPS will not act as project coordinator for the installation of the system at the customer site. All coordination of the purchase, installation, and maintenance of the system are the responsibility of the end user. Please refer to End User License Agreement and disclaimer information after the Glossary.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 8 of 166
Process Descriptions
The following are descriptions of some common terms that help illustrate how UPS processes shipments. Understanding these concepts will help you better understand how to interface the API commands with your system flow.
Orders
An order is a piece or pieces of freight processed at one time to a given consignee. A freight order will most likely be something like a “sales order” in your system. In your system, an order may be comprised of several line items of various products to be shipped to one destination address. In our freight system, the details that we need to know are not the details of the products, but the details of the packaging of the products – how many “boxes” (freight handling units) will our driver pickup when we get the freight and what are the dimensions and weight of each set of identical boxes.
Consolidation of Orders Together into Shipments
Consolidation is the function of putting together all the orders going to the same consignee (destination address) on the same day with the same service settings. This consolidation is optional, but most shippers choose it because it results in fewer separate shipments per day and thus a lower overall transportation freight charge.
With consolidation “on”, when order data is submitted, the Gemini system will automatically scan previously submitted orders from the same shipper going to the same consignee today, and assign the same shipment number to the new order as assigned to the other “like” orders. This means that any orders processed in the morning to consignee XYZ will have the same shipment number as the freight in an order processed in the afternoon to the same consignee (as long as an end-of-day final process command has not been done yet.)
You may choose to take advantage of consolidation in order to aggregate your shipment weight. Therefore, you may pay less per pound because your shipment is heavier. Consolidation totals the weights of all pieces in a shipment. This process raises the overall shipment weight. Raising the overall shipment weight may potentially save you money because of your price-per-pound rates at a higher weight may be lower, depending on the weight breaks in your contract.
UPS cannot provide a unique shipment number for each order within a shipment or each package on an order because of our consolidation method. However, you can provide reference values for each order, and you can track by those reference values within a consolidated shipment. If you need to track your freight orders by shipment number, you cannot use consolidation. If you need to track each freight piece by a unique shipment number, you will have to enter only one piece per order and have consolidation “off”.
Rules for Consolidation
Our company’s consolidation method applies the same shipment number to all pieces in a shipment. A shipment consists of all pieces for delivery to the same recipient; shipped on the same day, delivered on the same day, and using the same payment, service types, and special instructions. For example, if you process and do an order submit command for three pieces to ABC Company in the morning, and then later in the afternoon, do an order submit for seven pieces to ABC Company, if all shipments have the same payment type and service, then all 10 pieces will carry the same shipment number.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 9 of 166
Consolidation will be stopped on a particular shipment number when you “close out” a shipment by submitting an End of Day (EOD) command. Using a similar example as above, if you process and complete an order submit command for three pieces to ABC Company in the morning, and then in the early afternoon you think all the freight has been processed so you do an End of Day command, you will get a manifest for all the freight processed to that point and consolidation will stop for those shipment numbers. Later in the afternoon, if someone brings seven pieces more to ABC Company, that OrderSubmit command will result in a new shipment number since the previous shipment was closed out.
Using consolidation requires the system to search all prior shipments for the current shipping date as you process each new order to see if it qualifies for consolidation. This process can cause system response to be slower if you have many orders and shipments pending final processing.
Criteria for Consolidation
The following is the criteria UPS uses to determine whether to consolidate a shipment:
1. Ship date
2. Status
3. Check-to-Shipper (you cannot specify a Check-to-Shipper value if you want consolidation to work)
4. Identical consignee (you cannot make any changes to the consignee including the consignee ID)
5. Product type
6. Service type
7. Payment type
8. Special instructions, which include the following:
• Hold at airport for pickup (HAPU)
• Saturday pickup
• Lift-gate required
• Two-man delivery
• Inside delivery
• Delivery duties paid/delivery duties unpaid (DDP/DDU)
• Customs clearance
• Delivery to door
9. Declared value currency code
10. Insured value currency code
11. Customs value currency code
12. Unit of measure
13. Hazmat indicator
14. Third-party billing account, if payment type is third party
15. Description, if used as container reference
All of the above criteria on a given order must be identical to the other orders for consolidation to occur.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 10 of 166
Shipping Labels
Each freight piece (moveable unit, such as a pallet or a single box) must have a shipping label attached. The shipping label must contain certain basic information about the shipment and its destination.
Labels can be created with two API commands (OrderSubmit and PrintLabel). The format of the returned label is chosen by the user, and can be any of the following:
• DATA stream (XML tags and data) that the user will format into an acceptable format for UPS
• PDF format - Shipping labels returned as PDFs are base 64 encoded and then returned as a payload within the XML return string. If using this method, customer systems must translate the base 64 encoding back into the appropriate file type before printing
UPS pre-printed label stock may be obtained from your local UPS office, in North America only. For a list of service centers in your area, see https://ids.ups.com/directory.
For additional details on label content and format, refer to the UPS Guide to Labeling for Air and Ground Freight.
Final Processing of Shipments
The final step in creating a shipment (after submitting the order data and printing a label), is to upload the shipment data to the UPS freight system.
This final step is often referred to as “End of Day” (EOD) processing because often the step is completed at the end of the shipper day. But it might also be completed at the end of a shift, when a trailer has been filled, or at any other logical break in the shipper’s freight handling process.
Once the EOD has been completed on a shipment, the shipment and its associated orders will have a status of “POSTED”.
This processing of data returns a detailed manifest of all the shipments uploaded in that batch. It is this manifest that must be signed by the shipper and the driver, and is the legal document for transport of the freight. Usually this step is completed before the UPS driver or agent takes possession of the freight. The exception would be multiple pickups during a day and the use of interim manifests as the legal transport document. (See below in the section on Manifest Printing.)
A shipping location may complete the EOD process as often as they wish; multiple times a day if that makes sense in the shipper’s operations. However, there are two considerations about the timing and frequency of sending EOD commands:
1. The EOD process will “break” consolidation. An order that is submitted after the EOD process is completed will not consolidate with any shipment that has already been posted and uploaded.
2. Any orders that have been submitted and labeled on a particular calendar day must be processed through the final EOD step before midnight of that same calendar day. If the calendar day changes before the EOD has been completed, some exception processing must be done on those labeled orders/shipments before they can continue to be processed and uploaded to the UPS freight system. (See the discussion on Order Postponement.)
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 11 of 166
Manifest and Interim Manifest Printing
A manifest is a detailed list of labeled shipments.
A final manifest is created with the EOD final processing and uploading of shipments, and contains the details of ALL the shipments uploaded to the UPS freight system during the EOD processing.
An interim manifest is an optional step and can be created if it makes sense in the shipper’s processes. The interim manifest will contain a list of all the shipments in labeled status not on a previous interim manifest. A common usage of an interim manifest is for shippers who may have multiple freight pickups per day. When the first batch of freight to be picked up is ready (a trailer load, perhaps), an interim manifest is created; it will be a list of what is on that truck. When a second trailer is ready to go, another interim manifest is created, which lists only the material in the second batch. When the last pickup of freight for the day is ready, the EOD process is completed, and all the data is then uploaded (interim manifest or not) and a final total manifest is created that covers all the freight that has been uploaded.
The Gemini Interface provides shipment manifests and interim manifests in a Portable Document Format (PDF) viewable with the Adobe® Acrobat® Reader.
Manifests returned as PDFs are base 64 encoded and then returned as a payload within the XML return string. If using this method, customer systems must translate the base 64 encoding back into the appropriate PDF file type before printing.
Summary of Typical Steps That Occur When Invoking Commands
Following is the order of operations that customers will typically go through when invoking Gemini commands. The Gemini system will return detailed information regarding orders, shipments, labels, and manifests to your system. We highly recommend that you set up the system you are integrating with Gemini to save all the information that Gemini passes back.
First, a customer’s system may choose to submit an OrderRate command. This command does not save shipment data within UPS. It is simply a rate quote function that users can use when deciding to which carrier they want to tender their freight.
Next, once a customer has decided to tender their freight to UPS for shipment, the customer will submit an order by using the OrderSubmit command.
Gemini will then validate the order submission. If the order is valid and does not need any special authorizations from UPS, Gemini will save the order and create a UPS label. Gemini sends the label, along with the shipment and order numbers, back to the customer within an XML return string.
If the customer decides that the freight was labeled incorrectly, the customer can use the OrderCancel command to submit a cancellation of the order. The customer system must pass back the order number of the specific order that the customer wants to cancel.
You can do the same thing at the shipment level. If a customer decides to cancel an entire shipment, the customer will submit a ShipmentCancel command and pass in the shipment number that the customer wants to cancel.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 12 of 166
Depending upon the shipping volume of a customer, we may dispatch drivers to a customer location many times a day to pick up freight that is to move via UPS. When this occurs, a driver will ask the customer to generate an interim manifest so that both the customer and the UPS driver have a record of the freight that our company received. To generate an interim manifest, the customers systems will need to execute the PrintManifest command and must pass in the manifest_type parameter of INTERIM.
The return message will include the interim manifest number. Your system should save this number
for future reference or reprints. Gemini creates the manifest as an Adobe® Acrobat® PDF document and encodes it in base 64 for transmission within the body of the return string.
At the end of the shipping day, the customer must initiate a process to close all shipments and orders and to produce a final manifest. This operation is a two-step process. First, a customer’s system must execute the EODSubmit command that officially closes all shipments and transmits the shipping data to the UPS core enterprise systems. This command will return a manifest number that the customer’s system will use in the next step. Second, once the customer’s system has successfully executed the End of Day command, it will need to call the PrintManifest command. It must also pass the manifest_type parameter of EOD and the manifest_number that the EODSubmit command returned.
The return message will include the final manifest number. Your system should save this number for
future reference or reprints. Gemini creates the manifest as an Adobe® Acrobat® PDF document and encodes it in base 64 for transmission within the body of the return string.
Customer Process Flow Narrative
1. (Optional) The customer will submit a potential order for a rate quote (command OrderRate).
2. Gemini will then return a rate quote for that order.
3. The customer will choose to tender freight to UPS or another carrier. If the customer chooses UPS as the carrier, the customer submits order information (OrderSubmit).
4. Gemini will validate (accept or reject) the order information. Gemini will reject malformed orders or orders that require authorization codes. It will then send back the appropriate error return string to the user system. For orders that are valid, Gemini will generate labels, if requested in the command. It will return the labels in the requested format in the return data string, or to the specified destination printer.
5. The customer will save data that Gemini API returned. The customer will also distribute the returned information to the appropriate internal system or the requesting end user.
6. Repeat steps 1 through 5 for all shipments.
7. The customer may request an interim manifest (PrintManifest) with the parameter INTERIM.
8. Gemini will validate (accept or reject) the PrintManifest command information. For accepted information, Gemini will generate interim manifests and return the manifests as base 64 encoded Adobe® Acrobat® PDF documents embedded in the success return string.
9. The customer will save data that Gemini returned, including the Adobe® Acrobat® PDF documents. The customer will also distribute the returned information to the appropriate internal system (the requesting end user).
10. The customer may submit more orders to UPS (OrderSubmit) by repeating steps 1 through 5.
11. The customer may cancel an order or a shipment (OrderCancel or ShipmentCancel) unless the customer has already included it on an interim manifest. (An interim manifest implies that the freight has been given to the carrier driver and has begun its processing with the carrier. To cancel an order at this point, the carrier must be called and notified.)
12. Gemini will validate the OrderCancel or ShipmentCancel command request and perform operations as necessary.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 13 of 166
13. The customer will submit an End of Day request (EODSubmit) to close the shipping day.
14. Gemini will then validate the EODSubmit command request and perform operations as necessary.
15. The customer will then request an End of Day manifest (PrintManifest) with the parameter EOD.
Gemini will then generate final manifests. It will return the manifests as base 64 encoded Adobe® Acrobat® PDF documents embedded in the success return string.
The customer will then save data that Gemini returned, including the Adobe® Acrobat® PDF documents. The customer will also distribute the returned information to the appropriate internal system (the requesting end user).
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 14 of 166
Command Overview List
Following is a list of the commands that developers can use. The sequence of the list is approximately the sequence the commands might be used within an application (see following section on best practices.) The details for each command’s format and fields are in Appendix B.
Command Description
UserAuthenticate Retrieves a complete list of shipper account numbers, names and addresses for a given user ID
GetCurrencyCodes Retrieves the available currency codes
GetCountries Searches for countries and the associated country codes
GetServices Searches for services offered by our company from a shipper’s location to a consignee’s location
GetPaymentTypes Searches for payment types and the associated payment codes for a specified shipper
GetCityData Searches for cities within a country and the associated major airport city and tariff destination code
GetAirportCities Searches for major airport cities within a country served by our company (except U.S. and Canada)
OrderRate Retrieves a rate quote based on hypothetical order parameters without regard to consolidation rules
OrderSubmit Submits an order, with label data in the return.
OrderSave Saves orders into the Gemini system without returning label information. Label can be printed later with PrintLabel command.
OrderPostpone Postpones an order by changing the ship date of the order to a future date. This action will break consolidation with other orders/shipments staying on the current ship date. This action will also change the status of the order to open, so a label will have to be regenerated on the new ship date.
PostponeAll Postpones all orders for a single shipper from a single ship date to another future date
OrderCancel Cancels a single order
OrderSearch Searches for a unique order or a set of orders with given criteria and parameters
ShipmentCancel Cancels a single shipment
PrintLabel Prints (or reprints) a label
PrintManifest Prints an interim manifest or an End of Day (final) manifest
EODSubmit Initiates the End of Day process that closes all labeled shipments and orders for the current shipping day and transmits the data to the UPS enterprise systems. Sets the status of the orders/shipments to “posted”. No further processing is allowed on posted orders/shipments.
ConsigneeSave Saves consignee data under a unique id for one shipper account, for later reference.
ConsigneeSearch Searches previously saved consignee records based on specified criteria.
Update Updates the application, rating data, and shipper configuration files by downloading the newest versions – or explicitly specified versions – from the UPS web servers
Figure 1: Summary of Commands
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 15 of 166
Best Practices
There are some background tables that you can use to generate lists of “choices” for your users to pick appropriate values for their shipment, or to validate the data that they provide. If you use values and combinations from these “verified” lists, when the actual order data is submitted, there will be lower chance of rejection for data content reasons.
These data tables are called “static” data because they do not change often … but they do change unpredictably as business environments change. So, if your application is not designed to query these data types real-time with each order, it is wise to periodically and frequently download the data your shippers will need, so that you are sure you are working with the more current and correct data values.
Some of these static data lists are the same for every order, no matter what the origin or destination. These are country lists (names and codes), and currency codes.
The other data lists will return different subsets that are valid, depending on some characteristics of the order, usually origin point and destination city/country. These lists can vary depending on criteria are:
Payment types — although the only choices are “prepaid” (paid by shipper), “collect” (paid by consignee), and “3rd party” (paid by someone other than the shipper or consignee), some destination points do not support 3rd party payment types.
Services — the list of valid choices is based on origin point and destination point. Shipments within the US and Canada have different service choices than those that originate or have delivery in a country other than US or Canada. And some particular country pairs (US/Mexico, or intra-Europe) have special options.
Cities — commonly shipped-to cities outside the US and Canada is a very large list. It is best to just query the “known” cities after the user has entered the destination country, to give them a list of city names to choose from. When one of the “known” cities is picked, then the routing code will be known by the API and no additional routing information is needed.
Airport cities — when the shipper needs the destination point to be a city that is not in the “known” city list for a particular country, then the API will need to know what airport city is closest to the destination city so that freight routing can be determined. The user will have to select from a list of airports that UPS services in the destination country.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 16 of 166
Programmers’ Best Practice for Calling Commands
As the best practice, you should use the following order of operations when calling the Gemini API commands. You will use the least amount of resources by calling commands in this order.
1. When you load the application, call GetCountries and then GetCurrencyCodes.
2. When the user has picked the ship-from and ship-to countries, call GetServices, and then GetPaymentTypes.
3. Next, you can load GetCityData using the LIKE criteria operator as explained on page 41. This allows the user to see a list of cities based on the first three letters of the ship-to destination (consignee) city name. If the user cannot find the city name, you should then present the GetAirportCities list for them to choose the closest airport to their destination city. For more information about using the GetCityData command for shipments outside the United States and Canada, see the GetCityData section on page 41.
4. Next, optionally call OrderRate if a rate estimate is needed. Note that what will be returned is a rate estimate, not a rate quote. Not all ancillary services can be included in this online rate function, so the final charge for any given shipment may not exactly match the rate returned from this command.
5. Both OrderRate and OrderSubmit have nearly identical formats. Put everything you know about the order into one command structure. Do not call these commands iteratively for each piece. Otherwise, the user will not receive an accurate rate. The best practice is to package the data into as few commands as possible.
6. Now you are ready to do the OrderSubmit with the same set of data provided in OrderRate, if you did a rate command.
7. Use PrintLabels, if you did not have the label returned as part of the OrderSubmit command.
8. Use PrintManifest with type “interim” if you have the situation where interim manifests are needed. This is rare. This step is important to shippers because, if a shipper wants to tender freight to our company at multiple times throughout the day, we can take the freight. Otherwise, the shipper has to wait for the end of day process (EODSubmit). Asking for EODSubmit will break consolidation for other freight tendered that day.
9. Finally, call EODSubmit. If the API is executing in a local server mode and not via web services, this command is dependent upon an active Internet connection. Problems with the connection will keep EODSubmit from processing. When an error occurs during the end of day process, you will get back a non-zero in the return.
10. When the EODSubmit is successful, finish up with a PrintManifest (type “final”) command to print the manifest generated.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 17 of 166
System Overview and Design
Gemini uses XML/HTTP technology that allows your systems and our company’s systems to communicate across the Internet. Gemini streamlines your shipping processing by providing you with timely information and by automating order processing, management reporting, and shipment tracking.
Gemini Interface Architecture
The Gemini Interface is a COM-based interface exposed as a web service that UPS customers can call directly through the Internet by using SOAP (Simple Object Access Protocol). Customers will pass a single input parameter that consists of:
• A header that describes the function that the system will perform
• A body section that includes the data necessary to perform the function
Customers must pass the input parameter as XML and must exactly match the specified schema for the format. The Gemini Interface component will parse the input string and call the necessary Gemini API functions to accomplish the function. It will then format a return XML string that the system will pass back to the caller. The return string will include the status, any returned data (including labels and manifests), and any error information.
Figure 2: Architectural Overview
E2k
Workstation
Server Gemini
Workstation
1. Customer's system
generates shipment data
in XML messages using
Gemini command format.
2. Customer's system
uses SOAP to transmit
XML messages across
the Internet to Gemini.
3. Gemini receives SOAP
messages to process and
uses COM components to
communicate with E2k.
4. Gemini command
results get packaged as
SOAP XML and returned
to customer's system.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 18 of 166
Gemini Interface Design
The primary process is a WCF service with a single method that accepts a string parameter and returns a string response. Customers will call this method via the Internet using SOAP.
Parameter — the parameter is a string that consists of a header and a body that the system
passes to the Gemini Web Service method.
Header — the header includes an identifier for the caller and for the command that the customer wants to execute.
Body — the body includes the information required to make a call to the Gemini Web Service API.
Service — the WCF service parses the input string, validates the caller, and calls the
appropriate internal function to handle the requested command. The service passes the body of the input string to the internal functions and is responsible for making the necessary internal Gemini calls to accomplish the given command.
Public Method — the public method returns a string that includes all return information needed by the caller, including a status, return values, and any errors that occurred.
SOAP Protocol
Gemini supports the Simple Object Access Protocol (SOAP). SOAP is an XML-based protocol that exchanges structured and typed information on the Web. The SOAP interface consists of a single function call with one parameter. It returns a string parameter. Users can use SOAP client libraries to call this function directly.
SOAP Envelope Header for Commands and Returns
Each command has an introductory statement that sets up the web services communication. The input must contain this exact information as shown below. The namespace strings look like URLs, but they are not URLs. Don’t worry if they are not valid URL’s to a browser.
<?xml version='1.0' encoding='UTF-8' ?>
<gemini xmlns='http://www.emeryworld.com/gemini'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.emeryworld.com/gemini
http://www2.emeryworld.com/GeminiAPI/Gemini.xsd'>
Each return (results, error/warning messages) also begins with a SOAP Envelope Header. The return envelope header looks like the following:
<?xml version='1.0' encoding='UTF-8' ?>
<geminiReturn xmlns='http://www.emeryworld.com/gemini/return'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.emeryworld.com/gemini/return
http://www2.emeryworld.com/GeminiAPI/Command-specific-nameReturn.xsd'>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 19 of 166
Security
SOAP delegates security to its transport layer, rather than dealing with security directly. Since SOAP runs on top of HTTP, it can make use of the security features built into HTTP.
SSL Encryption
Gemini uses encrypted SOAP calls that use Secure Socket Layer (SSL) to make calls to the Web Service. SSL protocol is required for UPS communications, since User IDs and Passwords are transmitted. The Gemini Web Service is only available on SSL and requires HTTPS connection for access. HTTP requests are not allowed.
Authorization/Authentication
In addition to transport layer security, requests to the Gemini Web Service must include the User ID and Password created during integration or provided by UPS. This provides added protection to our customers by guaranteeing that no one other than the appropriate customer may access a customer’s account.
The system authenticates messages sent to the API against the UPS security system. UPS gives each customer a unique user identification and password and assigns a list of accounts that the customer can access. Each message sent to UPS contains an ID, password, and shipper account. If the ID has rights to the shipper account, the message is processed. If the ID does not have rights, the system returns an error. UPS is responsible for authenticating requests for Gemini accounts and then creating and maintaining security records.
XML Header
The input string for each command has a common header that identifies the customer and the command the customer wishes to perform. The body of the input string is the specific information needed by the command that the function is executing. The XML format of the input string must follow the defined schema exactly. The format of the header is identical for all commands with the exception of the command type. The body of the input string also differs for each command.
To validate the XML, the system creates XML Schema Definition (XSD) files for each command. UPS provides these XSD files to users of the Gemini Interface for their own development and validation of the XML they generate.
Each command has a standard XML header that includes:
Field Required Type Maximum
Length Description
<header>
<site_id/> Y Numeric 8 UPS issues site_id to identify a customer’s location. Currently, Gemini web services API only uses site 82.
<user_id/> Y String 15
User ID is created in Gemini during integration. Use the request form to specify a desired User ID. UPS security system validates ID to provide authorization for commands.
<password/> Y String 15
Password associated with user ID
<command/> Y String - Specific name of the command being issued
</header>
Figure 3: Standard XML Header for Each Command
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 20 of 166
A sample header section follows:
<header>
<site_id>82</site_id>
<user_id>UserID</user_id>
<password>Password</password>
<command>OrderSubmit</command>
</header>
Note that the command segment contains the specific commands being executed and thus the header will vary in that segment for each command.
The body follows the header and is specific to each command.
Standard XML Format for Calling a Function
The following is the standard XML format for calling a function, using a specific command:
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name, see page 19 for content)
<body>
(Command-specific XML goes here. See each command for specifics.)
</body>
</gemini>
See section on page 14 for specific commands sent in the body of the XML document.
Each command returns an XML string that includes a status, possible error list, results data, and/or labels and manifests. A result code of zero (0) specifies a successful operation of the transaction command. A result code that is not zero specifies that an error or warning occurred.
Success Example
Following is an example of the XML return format for successful operations.
(SOAP envelope header for API Return, see page 18 for content)
<return>
<result>0</result>
<OrderCancel>
<description>
Order was successfully Cancelled.
</description>
<type>Success</type>
</OrderCancel>
</return>
</geminiReturn>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 21 of 166
Standard Error Return Fields
Following are the return fields and the field data types and descriptions for the usual Error fields in the various commands.
Field Type Maximum Length Description
<errors>
<error>
<number/> Integer 4 Numeric error value
<description/> String 200 Text description of error
<type/> String 10 Type of error (error or warning)
<error_detail/> String 250 Optional detailed information about error that occurred
</error>
</errors>
Figure 4: Error Return Fields
In the API return, if the error code is preceded with a minus sign ( – ), it signals an error and the previous command failed. If the error code does not have a minus sign, then the information should be considered a warning for future reference, but the command completed successfully.
Error Example
Following is an example of the XML return format for errors.
(SOAP envelope header for API Return, see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>1234</number>
<description>
This is a warning because it does not have a (–) prefix for the error.
</description>
<type>ERROR</type>
</error>
<error>
<number>-5678</number>
<description>
This is a failing error; the command did not complete.
</description>
<type>ERROR</type>
</error>
</errors>
</return>
</geminiReturn>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 22 of 166
Calling the Gemini Web Service API
Calling the Gemini Web Service API is a matter of:
1. Formatting the XML for the command you want to perform
2. Sending the formatted XML to the Gemini servers
3. Checking the result of the call
Formatting the XML
See the section on page 20 for a sample of XML that the Gemini Web Service API accepts. You may also use the Gemini.xsd and GeminiCommon.xsd files, which are available online, to validate your XML. The location is:
https://Gemini.ups.com/Gemini.xsd
https://Gemini.ups.com/GeminiCommon.xsd
You may copy the Gemini XSDs to another location for your own development. However, you must not move them or alter them in any way. If you do, the Gemini API will fail to work. Also, Gemini.xsd and GeminiCommon.xsd must be located in the same folder or directory.
Sending Formatted XML to the UPS Gemini Servers
Gemini uses Simple Object Access Protocol (SOAP) to accept XML command messages from customer systems. Web Service Description Language component (WSDL) files located at the following URLs accept requests.
• Testing https://Gemini.ams1907.com/Web.svc?wsdl
• Production https://Gemini.ups.com/Web.svc?wsdl
To learn more about using SOAP, and to get sample code and SOAP toolkits, check out the following web sites:
• http://msdn.microsoft.com/soap
• http://xml.coverpages.org/soap.html
• http://www.xml.com/pub/a/2000/02/09/feature/index.html
• http://www.oreilly.com/catalog/progwebsoap
The GemTest.exe is a simple Gemini client with a user interface that allows you to select an XML file as input, display the contents of that file, and send it to the Gemini Web Service using SOAP. It also displays the returned XML. The test harness is available on the Gemini web site.
Checking the Result
See section on page 20 for a sample of XML that Gemini returns. You can parse the return XML to pull out the return status, labels, and manifests, as well as any errors or return values.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 23 of 166
Installing the Gemini XML Test Harness
The Gemini 7.0 API Test Harness allows developers to experiment with and learn how to call the Gemini 7.0 Web Service. Using the XML Test Harness, you can set up your program to call a local component as if you were going to call the Gemini 7.0 API across the Internet. You can also use this product to confirm the accuracy of the XML messages you have constructed. The Gemini 7.0 Web Service API contains a single GeminiExecute() method accessible through SOAP. This method takes a single string parameter. This parameter should contain the Gemini command in XML format. The API Test Harness provides sample XML input files, together with results that Gemini would generate as return values.
List of XML Test Harness Files & XML Templates File Description
Gemini.xsd Schema of XML input to the Gemini API
GeminiCommon.xsd Schema common to both input and output XML
EODSubmitReturn.xsd Schema of GetAirportCitiesReturn output file
GetAirportCitiesReturn.xsd Schema of GetAirportCitiesReturn output file
GetCityDataReturn.xsd Schema of GetCityDataReturn output file
GetCountriesReturn.xsd Schema of GetCountriesReturn output file
GetPaymentTypesReturn.xsd Schema of GetPaymentTypesReturn output file
GetServicesReturn.xsd Schema of GetServicesReturn output file
OrderCancelReturn.xsd Schema of OrderCancelReturn output file
OrderPostponeReturn.xsd Schema of OrderPostponeReturn output file
OrderRateReturn.xsd Schema of OrderRateReturn output file
OrderSearchReturn.xsd Schema of OrderSearchReturn output file
OrderSubmitReturn.xsd Schema of OrderSubmitReturn output file
PrintLabelReturn.xsd Schema of PrintLabelReturn output file
PrintManifestReturn.xsd Schema of PrintManifestReturn output file
ShipmentCancelReturn.xsd Schema of ShipmentCancelReturn output file
UpdateReturn.xsd Schema of UpdateReturn output file
CheckAPIFile.vbs Additional test script file (easier to use than QuickTest)
QuickTest.vbs Simple test script file
ConsigneeSaveTemplate.xml ConsigneeSave command input template file
ConsigneeSearchTemplate.xml ConsigneeSearch command input template file
EODSubmitFromDoc.xml Sample EODSubmit command input file taken from this guide
EODSubmitTemplate.xml EODSubmit command input template file
GetAirportCitiesTemplate.xml GetAirportCities command input template file
GetCityDataTemplate.xml GetCityData command input template file
GetCountriesTemplate.xml GetCountries command input template file
GetCurrencyCodesTemplate.xml GetCurrencyCodes command input template file
GetPaymentTypesTemplate.xml GetPaymentTypes command input template file
GetServicesTemplate.xml GetServices command input template file
OrderCancel.xml Sample OrderCancel command input file
OrderCancelFromDoc.xml Sample OrderCancel command input file taken from this guide
OrderCancelTemplate.xml OrderCancel command input template file
OrderPostponeTemplate.xml OrderPostpone command input template file
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 24 of 166
OrderRate.xml Sample OrderRate command input file
OrderRateFromDoc.xml Sample OrderRate command input file taken from this guide
OrderRateTemplate.xml OrderRate command input template file
OrderSearchTemplate.xml OrderSearch command input template file
OrderSubmit.xml Sample OrderSubmit command input file
OrderSubmitFromDoc.xml Sample OrderSubmit command input file taken from this guide
OrderSubmitNeedLabels.xml Sample OrderSubmit command with request for labels input file
OrderSubmitTemplate.xml OrderSubmit command input template file
PostponeAllTemplate.xml PostponeAll command input template file
PrintLabel.xml Sample PrintLabel command input file
PrintLabelTemplate.xml PrintLabel command input template file
PrintManifest.xml Sample PrintManifest command input file
PrintManifest1.xml Additional sample PrintManifest command input file
PrintManifest2.xml Additional sample PrintManifest command input file
PrintManifest3.xml Additional sample PrintManifest command input file
PrintManifestTemplate.xml PrintManifest command input template file
ShipmentCancel.xml Sample ShipmentCancel command input file
ShipmentCancelTemplate.xml ShipmentCancel command input template file
UpdateTemplate.xml Update command input template file
Figure 5: List of Files included with the Gemini Test package
Installation is Simple 1. Extract the Gemini.zip available at https://Gemini.ups.com/Files/Gemini.zip 2. Navigate to C:\Program Files\Gemini and execute GemTest.exe 3. Test XML transactions on the Gemini Test servers.
How to "Debug" Your XML Input
Gemini.xsd and GeminiCommon.xsd define the Gemini API. These files are a formal specification, or schema, of the range of XML inputs that Gemini will accept. Each command and each element is described in Appendix B of this document. Using the schema, you can generate valid XML input to Gemini. This package helps to verify that the input is valid. Using this guide, you can generate XML inputs that Gemini can process.
If you feed an invalid XML string to the Gemini Web Service, the API will return an error string. The error return should contain enough information in order to "debug" the input string.
Example Invalid Input
For example, given the following input:
(SOAP envelope header, see page 18 for content)
<header>
<site_id>12345</site_id>
<user_id>UserID</user_id>
<password>Password</password>
<command>PrintFavor</command>
</header>
<body>
<print_label>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 25 of 166
<shipper_account_number>123456789</shipper_account_number>
<order_number>9066948910001</order_number>
<label_in>
<label_format>PDF</label_format>
<label_dest>RETURN</label_dest>
</label_in>
</print_label>
</body>
</gemini>
Example Error Return
For the above invalid input, the Gemini 7.0 Web Service API would return the following string:
(SOAP envelope header for API Return, see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-5302</number>
<description>Invalid XML (-5302)</description>
<type>ERROR</type>
<error_detail>
Parse Error: errorCode: -1072897660
filepos: 376 line: 10 linepos: 23
reason: enumeration constraint failed
The element: '{http://www.emeryworld.com/gemini}command'
has an invalid value according to its data type.
srcText: <command>PrintFavor</command>
</error_detail>
</error>
</errors>
</return>
</geminiReturn>
The error above states that the <command> element in the input is invalid. The Gemini.xsd file is the best place to find out what a valid <command> element should be. In it, we see that only the following commands are valid: OrderSubmit, OrderSearch, OrderRate, OrderCancel, OrderPostpone, PostponeAll, GetCountries, GetServices, GetAirportCities, GetCityData, GetCurrencyCodes, GetPaymentTypes, ShipmentCancel, UserAuthenticate, Update, ConsigneeSearch, ConsigneeSave, EODSubmit, PrintLabel, and PrintManifest. Therefore, the error return tells us that "PrintFavor" is not a valid command.
Example of Additional Error Return
If we then correct the error by replacing "PrintFavor" with "PrintLabel" and call the Gemini Web Service API with the corrected string, we would still get the following error string:
(SOAP envelope header for API Return, see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-5302</number>
<description>Invalid XML (-5302)</description>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 26 of 166
<type>ERROR</type>
<error_detail>
Parse Error: errorCode: -1072897660
filepos: 377 line: 12 linepos: 40
reason: pattern constraint failed.
The element: ' {http://www.emeryworld.com/gemini}
shipper_account_number' has an invalid value
according to its data type. srcText:
<shipper_account_number>ABC12345</shipper_account_number>
</error_detail>
</error>
</errors>
</return>
</geminiReturn>
This now tells us that our problem is with the <shipper_account_number>. Again, Gemini.xsd and GeminiCommon.xsd have the information on what a valid <shipper_account_number> should be:
<xsd:element name="shipper_account_number" type="AccountNumber" />
Elsewhere in the files, we see that the AccountNumber type is defined thus:
<xsd:simpleType name="AccountNumber">
<xsd:restriction base="xsd:string">
<xsd:pattern value="[0-9]{0,9}" />
</xsd:restriction>
</xsd:simpleType>
This tells us that:
1. It only allows integers in the account number.
2. The account number cannot be more than nine digits long.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 27 of 166
Labels and Label Information
Please refer to the UPS Guide to Labeling Supplement for Air and Ground Freight.
Manifest Documents
Manifests are available from the Gemini Web Service API in PDF format. UPS supports the production of manifests as PDF images that will embed in return messages.
Embedded PDF images
After you have submitted a successful EODSubmit or PrintManifest transaction, UPS Supply Chain Solutions will return an XML string with an embedded PDF image within the <data></data> tags. The
embedded image will be raw data using base 64 encoding.
XML Return Example
Following is the PrintManifest XML return format for successful operations.
(SOAP envelope header for API Return, see page 18 for content)
<return>
<result>0</result>
<data>
<manifest>
<manifest_number>M974503791</manifest_number>
<manifest_format>PDF</manifest_format>
<manifest_image>
JVBERi0xLjMKJeLjz9MKMSAwIG9iag0KPDwN
(…base 64 encoded PDF image…)
ZWRpYUJveCBbIDAgMCA2MTIgNzkyIF0NCi9SZ
</manifest_image>
</manifest>
</data>
</return>
</geminiReturn>
Integrated Shipment Tracking
UPS provides integrated tracking by way of our public Internet servers, not through Gemini. Please refer to the Flex Global View Quick Track Web Service guide.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 28 of 166
Appendix A: Service Codes
This list provides definitions for service names and codes. Business service offerings change from time to time. The GetServices command will provide a list of valid services from a particular origin point. Not all services are available from all points. Service codes presented include codes built from core services and special instructions.
Figure 6: Service Codes
Services Service Codes
Description
UPS Next Day Air® Freight 40 Guaranteed delivery by 12:00 noon or 5:00 p.m. on the next business day, depending on destination
UPS Next Day Air® Freight NGS
41 Delivery the next business day by 12:00 noon or 5:00 p.m., depending on destination.
UPS 2nd Day Air® Freight 42 Guaranteed delivery by 12:00 noon or 5:00 p.m. on the second business day, depending on destination
UPS 2nd Day Air® Freight NGS
43 Delivery by 12:00 noon or 5:00 p.m. on the second business day, depending on destination
UPS 3 Day FreightSM 44 Guaranteed delivery within three or four business days by 5:00 p.m., depending on
destination
UPS 3 Day FreightSM NGS 45 Delivery within three or four business days by 5:00 p.m., depending on destination
UPS ExpressSM Freight 46 Guaranteed door-to-door by end of day within one to three business days, depending on destination
UPS Air Freight DirectSM 47 Day-definite, airport-to-airport service, with delivery within one to three business days
UPS Air Freight Consolidated 48 Day-definite, airport-to-airport service, with delivery within three to five business days
Saturday Delivery 50 For time-critical shipments, UPS offers the convenience of Saturday Delivery
UPS Express® Freight w/Delivery
53 Consolidated airport-to-airport service for international destinations. Includes Delivery to Door and Customs Clearance.
UPS Express® Freight w/Clearance
54 Consolidated airport-to-airport service for international destinations, plus
CustomsClearance. UPS Express® Freight w/Delivery & Clearance
55 Fastest airport-to-airport service for international destinations, plus the special instruction of Delivery To Door and Customs Clearance.
UPS Air Freight Direct®
w/Delivery 56 Fastest airport-to-airport service for international destinations, plus Customs Clearance.
UPS Air Freight Direct® w/Clearance
57 Day-definite, airport-to-airport service, with delivery within one to three business days with Customs Clearance
UPS Air Freight Direct® w/Delivery & Clearance
58 Day-definite, airport-to-airport service, with delivery within one to three business days with Customs Clearance and Delivery to Door
UPS Air Freight Consolidated® w/Delivery
59 Day-definite, airport-to-airport service, with delivery within three to five business days with Delivery to Door
UPS Air Freight Consolidated® w/Clearance
60 Day-definite, airport-to-airport service, with delivery within three to five business days with Customs Clearance
UPS Air Freight
Consolidated® w/Delivery & Clearance
61 Day-definite, airport-to-airport service, with delivery within three to five business days with Customs Clearance and Delivery to Door
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 29 of 166
Appendix B: Command Formats and Details
This section gives the details of formats and segments for each individual API command.
UserAuthenticate
The UserAuthenticate transaction is the command to retrieve a complete list of authorized shipper account numbers, names, and addresses for a given user ID.
Record Layout
Following is the record layout for the UserAuthenticate command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<user_authenticate>
<shipper_account_number/> Y Numeric 9 Segment is required for XSD format; best to provide no value; any value provided will be validated against the table of account numbers authorized for this shipper, but will not change the ultimate output of the command
compared to giving no value.
</user_authenticate>
</body> Figure 7: UserAuthenticate Record Layout
XML Input
The developer may submit the UserAuthenticate command as an XML string.
UserAuthenticate Schema example
The definition of the UserAuthenticate XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<user_authenticate>
<shipper_account_number>123456789</shipper_account_number>
</user_authenticate>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the UserAuthenticate command.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 30 of 166
Field Type Maximum Length
Description
<result/> Numeric 1 0 = success 1 = failure
Errors String
<shippers> 1 to n nodes of installed shippers
<shipper>
<name/> String 40 Shipper’s name
<address_one/> String 40 Shipper’s address line one
<address_two/> String 40 Shipper’s address line two
<address_three/> String 40 Shipper’s address line three
<city/> String 35 Shipper’s city
<state_code/> String 4 Shipper’s state or province in abbreviated format
<postal_code/> String 15 Shipper’s Zip or postal code
<country_code/> String 2 Shipper’s country in abbreviated format
<shipper_account_number/> Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
</shipper>
</shippers>
</return> Figure 8: UserAuthenticate Return Fields
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the UserAuthenticate command. A result code that is not zero specifies that an error occurred.
UserAuthenticate Success example
Following is the UserAuthenticate XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<shippers>
<shipper>
<name><![CDATA[TEST SHIPPER 1 - US]]></name>
<address_one>< ![CDATA[101 N. MAIN ST]]></address_one>
<address_two><![CDATA[SUITE 502]]></address_two>
<address_three><![CDATA[]]</address_three>
<city><![CDATA[PORTLAND]]></city>
<state_code><![CDATA[OR]]></state_code>
<postal_code><![CDATA[97210]]></postal_code>
<country_code><![CDATA[US]]></country_code>
<shipper_account_number><![CDATA[000000001]]></shipper_account_number>
</shipper>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 31 of 166
<shipper>
<name><![CDATA[EMERY TEST SHIPPER]]></name>
<address_one><![CDATA[202 MAIN STREET]]</address_one>
<address_two><![CDATA[]]</address_two>
<address_three><![CDATA[]]</address_three>
<city><![CDATA[PORTLAND]]</city>
<state_code><![CDATA[OR]]</state_code>
<postal_code><![CDATA[97209]]</postal_code>
<country_code><![CDATA[US]]</country_code>
<shipper_account_number><![CDATA[000000002]]</shipper_account_number>
</shipper>
</shippers>
</return>
</geminiReturn>
UserAuthenticate Error example
Following is the UserAuthenticate XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
</return>
</geminiReturn>
GetPaymentTypes
The GetPaymentTypes transaction is the command to search for available payment types and the associated payment codes offered by UPS for the specified shipper.
Record Layout
Following is the record layout for the GetPaymentTypes command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<get_payment_types>
<shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
</ get_payment_types>
</body>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 32 of 166
Figure 9: GetPaymentTypes Record Layout
XML Input
The developer may submit the GetPaymentTypes command as an XML string.
GetPaymentTypes Schema example
The definition of the GetPaymentTypes XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<get_payment_types>
<shipper_account_number>123456789</shipper_account_number>
</get_payment_types>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the GetPaymentTypes command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success 1 = failure
Errors String
<payment_types>
<payment_type> 1 to n nodes of service data returned in search
<payment_name/> String 20 Prepaid, Collect, 3rd Party
<payment_code/> Numeric 2 Refer to Appendix G for codes
</payment_type>
</payment_types>
</return> Figure 10: GetPaymentTypes Return Fields
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the GetPaymentTypes command. A result code that is not zero specifies that an error occurred.
GetPaymentTypes Success example
Following is the GetPaymentTypes XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<payment_types>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 33 of 166
<payment_type>
<payment_name>Prepaid</payment_name>
<payment_code>1</payment_code>
</payment_type>
<payment_type>
<payment_name>Collect</payment_name>
<payment_code>2</payment_code>
</payment_type>
<payment_type>
<payment_name>3rd Party</payment_name>
<payment_code>3</payment_code>
</payment_type>
..........
</payment_types>
</return>
</geminiReturn>
GetCurrencyCodes
The GetCurrencyCodes transaction is the command to retrieve the currency codes available through Gemini.
Record Layout
Following is the record layout for the GetCurrencyCodes command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<get_currency_codes>
<shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
</get_currency_codes>
</body> Figure 11: GetCurrencyCodes Record Layout
XML Input The developer may submit the GetCurrencyCodes command as an XML string.
GetCurrencyCodes Schema example
The definition of the GetCurrencyCodes XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 34 of 166
<body>
<get_currency_codes>
<shipper_account_number>123456789</shipper_account_number>
</get_currency_codes>
</body>
</gemini>
Return Fields Following are the return fields and the field data types and descriptions for the GetCurrencyCodes command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success; 1 = failure
Errors String
<currencies>
<currency> 1 to n nodes of currency codes
<currency_code/> String 3 Three letters code for a given currency
<currency_name/> String 30 The full name for a currency
<currency_symbol/> String 1 The currency code symbol </currency>
</currencies> Figure 12: GetCurrencyCodes Return Fields
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the GetCurrencyCodes command. A result code that is not zero specifies that an error occurred.
GetCurrencyCodes Success example
Following is the GetCurrencyCodes XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<currencies>
<currency>
<currency_code></currency_code>
<currency_name>undefined</currency_name>
<currency_symbol></currency_symbol>
</currency>
<currency>
<currency_code>CAD</currency_code>
<currency_name>CANADA - DOLLAR</currency_name>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 35 of 166
<currency_symbol>Can$</currency_symbol>
</currency>
<currency>
<currency_code>EUR</currency_code>
<currency_name>EUROPEAN UNION - EURO</currency_name>
<currency_symbol>EUR</currency_symbol>
</currency>
<currency>
<currency_code>NCV</currency_code>
<currency_name>NO CUSTOMS VALUE</currency_name>
<currency_symbol></currency_symbol>
</currency>
<currency>
<currency_code>USD</currency_code>
<currency_name>UNITED STATES OF AMERICA - DOL</currency_name>
<currency_symbol>$</currency_symbol>
</currency>
...............
</currencies>
</return>
</geminiReturn>
GetCurrencyCodes Error example
Following is the GetCurrencyCodes XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
</return>
</geminiReturn>
GetCountries
The GetCountries transaction is the command to search for available countries served by UPS and the associated country codes.
Record Layout Following is the record layout for the GetCountries command, including the fields and the field parameters and descriptions.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 36 of 166
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<get_countries>
<shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
</get_countries>
</body> Figure 13: GetCountries Record Layout
XML Input The developer may submit the GetCountries command as an XML string.
GetCountries Schema example
The definition of the GetCountries XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<get_countries>
<shipper_account_number>123456789</shipper_account_number>
</get_countries>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the GetCountries command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success 1 = failure
Errors String
<countries>
<country> 1 to n nodes of country data returned in search
<country_name/> String 30 The full name for a country
<country_code/> String 2 2 characters country code
</country>
</countries>
</return> Figure 14: GetCountries Return Fields
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the GetCountries command. A result code that is not zero
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 37 of 166
specifies that an error occurred.
GetCountries Success example
Following is the GetCountries XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<countries>
<country>
<country_name>UNDEFINED</country_name>
<country_code> </country_code>
</country>
<country>
<country_name>AFGHANISTAN</country_name>
<country_code>AF</country_code>
</country>
<country>
<country_name>ALBANIA</country_name>
<country_code>AL</country_code>
</country>
<country>
<country_name>ALGERIA</country_name>
<country_code>DZ</country_code>
</country>
...............
</countries>
</return>
</geminiReturn>
GetServices
The GetServices transaction is the command to search for available services offered by UPS from a particular shipper’s location to a particular consignee’s location. If you do not pass in destination information, GetServices returns the full list of services.
Record Layout
Following is the record layout for the GetServices command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body> <get_services>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 38 of 166
<shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
<dest_country_code/> Y String 2 GetCountries returns
<dest_city/> String 30 UPS requires for all destinations outside of US and Canada
<dest_postal_code/> String 15 UPS requires for all destinations within US and Canada
</get_services>
</body> Figure 15: GetServices Record Layout
Note: The command GetServices does not support all services to the same location when used
on the command OrderSubmit. For example, GetServices may return “Saturday Delivery” when a United States or Canadian location is passed in. However, OrderSubmit only accepts Saturday Delivery as valid when orders and shipments have a shipment date that falls on a Friday.
XML Input The developer may submit the GetServices command as an XML string.
GetServices Schema example
The definition of the GetServices XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<get_services>
<shipper_account_number>123456789</shipper_account_number>
<dest_country_code>GB</dest_country_code>
<dest_city>LONDON</dest_city>
<dest_postal_code/>
</get_services>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the GetServices command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success 1 = failure
Errors String
<services>
<service> 1 to n nodes of service data returned in search
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 39 of 166
<service_name/> String 20 Refer Appendix “A”
<service_code/> Numeric 4 Refer Appendix “A”
</service> </services>
</return> Figure 16: GetServices Return Fields
XML Return Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the GetServices command. A result code that is not zero specifies that an error occurred.
GetServices Success example
Following is the GetServices XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<services>
<service>
<service_name>UPS Express® Freight</service_name>
<service_code>46</service_code>
</service>
<service>
<service_name>UPS Air Freight Direct®</service_name>
<service_code>47</service_code>
</service>
<service>
<service_name>Mexico Economy</service_name>
<service_code>49</service_code>
</service>
</services>
</return>
</geminiReturn>
GetAirportCities
The GetAirportCities transaction is the command to search for available major airport cities within a country served by UPS. This excludes the United States and Canada.
Record Layout
Following is the record layout for the GetAirportCities command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 40 of 166
XML header Site_id, user_id, password, command; see page 20
<body>
<get_airport_cities>
<shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
<country_code/> Y String 2 Country for which you requested list of major airport cities. GetAirportCities excludes US and Canada GetCountries returns. Examples: “US, CA”
</get_airport_cities>
</body> Figure 17: GetAirportCities Record Layout
XML Input
The developer may submit the GetAirportCities command as an XML string.
GetAirportCities Schema example
The definition of the GetAirportCities XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<get_airport_cities>
<shipper_account_number>123456789</shipper_account_number>
<country_code>IT</country_code>
</get_airport_cities>
</body>
</gemini>
Return Fields Following are the return fields and the field data types and descriptions for the
GetAirportCities command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success 1 = failure
Errors String
<airport_cities>
<airport_city> 1 to n nodes of major airport cities returned in search
<city_name/> String 35 Full name of city
<tariff_destination/> String 3 3 characters airport code
</airport_city>
</airport_cities>
</return> Figure 18: GetAirportCities Return Fields
XML Return
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 41 of 166
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the GetAirportCities command. A result code that is not zero specifies that an error occurred.
GetAirportCities Success example
Following is the GetAirportCities XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<airport_cities>
<airport_city>
<city_name>BARI</city_name>
<tariff_destination>BRI</tariff_destination>
</airport_city>
<airport_city>
<city_name>BERGAMO</city_name>
<tariff_destination>BGY</tariff_destination>
</airport_city>
<airport_city>
<city_name>BOLOGNA</city_name>
<tariff_destination>BLQ</tariff_destination>
</airport_city>
<airport_city>
<city_name>FLORENCE</city_name>
<tariff_destination>FLR</tariff_destination>
</airport_city>
<airport_city>
<city_name>MILAN</city_name>
<tariff_destination>MIL</tariff_destination>
</airport_city>
<airport_city>
<city_name>NAPLES</city_name>
<tariff_destination>NAP</tariff_destination>
</airport_city>
<airport_city>
<city_name>PALERMO</city_name>
<tariff_destination>PMO</tariff_destination>
</airport_city>
<airport_city>
<city_name>PISA</city_name>
<tariff_destination>PSA</tariff_destination>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 42 of 166
</airport_city>
<airport_city>
<city_name>ROME</city_name>
<tariff_destination>ROM</tariff_destination>
</airport_city>
.........
</airport_cities>
</return>
</geminiReturn>
GetCityData
The GetCityData transaction is the command to search for known cities offered by UPS within a particular country and a city’s associated major airport city and tariff destination code. For all countries other than the United States or Canada, you can retrieve a full list of cities. However, for points in the United States and Canada, you can only retrieve a single city that is associated with a postal code with each call. A postal code is required for all calls to GetCityData with a country_code set to "US" or "CA."
Narrow Query Parameters to Reduce Return Time
Warning! For some countries—such as Great Britain, France, and Germany—it can take
GetCityData up to two minutes to retrieve all cities. We advise that you call GetCityData once a day for each country or that you provide as much data as possible when using the command GetCityData. This narrows the query parameters and reduces the time it takes for GetCityData to return information to your program.
Only Use % with the Criteria Operator LIKE If you make a call to GetCityData with a partial city name and the use of the criteria_operator node, then GetCityData will pass back a partial list of cities that fit the matching criteria through the API.
The only available criteria operator for command GetCityData is “LIKE.” The default is set for the search to return an exact match equal to the city name. Only use percent (%) signs in the city name input string when using the LIKE operator. Using the percent signs without the LIKE operator will result in the Gemini API returning an inappropriate value.
Submit an Unknown City with the Associated Major City If you want to ship to a city that is not on the list of returned known cities, submit the unknown city name and the major city associated with the smaller city to get back the appropriate tariff destination point. For example, Calvenzano, Italy, is unknown to the UPS system, but you know that Calvenzano is just outside of Milan. Therefore, Milan is the major city associated with Calvenzano, so you pass in Milan with your call. Gemini will pass back the appropriate tariff destination point of “MIL.” Then you will use in the OrderSubmit command to form a complete transaction.
Record Layout Following is the record layout for the GetCityData command, including the fields and the field parameters and descriptions.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 43 of 166
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<get_city_data> <shipper_account_number/> Y
Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
<country_code/> Y String 2 Country for which you requested list of major airport cities. GetAirportCities excludes US and Canada
GetCountries returns. Examples: “US, CA”
<city/> String 30 Consignee’s or shipper’s city. Required for non-US/Canada addresses. Example: “Paris”
<criteria_operator/> String 10 Keyword operators for search only on city name field. Only supports LIKE. Default action is search that equals (EQ)
<major_city/> String 30 Optional parameter. Helps Gemini find unusual city locations near other major cities. Example: FRANKFURT for city TAUNUS, Germany
<postal_code/> String 15 Zip or postal code. Example: “15250-7232”
</get_city_data>
</body> Figure 19: GetCityData Record Layout
XML Input
The developer may submit the GetCityData command as an XML string.
GetCityData Schema example
The definition of the GetCityData XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<get_city_data>
<shipper_account_number>123456789</shipper_account_number>
<country_code>GB</country_code>
<city>LONDON</city>
<criteria_operator></criteria_operator>
<major_city>LONDON</major_city>
<postal_code/>
</get_city_data>
</body>
</gemini>
Return Fields
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 44 of 166
Following are the return fields and the field data types and descriptions for the GetCityData command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success 1 = failure
Errors String
<cities> 1 to n nodes of locations data returned in search
<city>
<city_name/> String 35 Actual name of city
<state_province_code/> String 2 2 characters state/province code <major_airport_city/> String 35 City’s associated major airport city
<tariff_destination/> String 3 3 characters major airport city code example “ATL”
<sort_code/> String 5 UPS specific routing indicator
<standard_service/> String 255 Best available standard service level description
</city>
</cities>
</return> Figure 20: GetCityData Return Fields
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the GetCityData command. A result code that is not zero specifies that an error occurred.
GetCityData Success examples
Following is the GetCityData XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<cities>
<city>
<city_name>LONDON</city_name>
<state_province_code/>
<major_airport_city>LONDON</major_airport_city>
<tariff_destination>LON</tariff_destination>
</city>
</cities>
</return>
</geminiReturn>
Example 1: Looking up US or Canadian points
Following is the GetCityData XML format for looking up United States and Canadian points.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 45 of 166
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<get_city_data>
<shipper_account_number>123456789</shipper_account_number>
<country_code>US</country_code>
<city></city>
<criteria_operator></createria_operator>
<major_city></major_city>
<postal_code>30309</postal_code>
</get_city_data>
</body>
</gemini>
Return for US and Canadian Points
Following is the GetCityData XML return format for looking up United States and Canadian points.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<cities>
<city>
<city_name>ATLANTA</city_name>
<state_province_code>GA</state_province_code>
<major_airport_city></major_airport_city>
<tariff_destination>ATL</tariff_destination>
<sort_code>V1</sort_code>
<standard_service>
A: Delivery by noon the next business day.
</standard_service>
</city>
</cities>
</return>
</geminiReturn>
Examle 2: Looking up points outside the US and Canada
Following is a GetCityData XML format for looking up points outside the United States and Canada.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 46 of 166
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<get_city_data>
<shipper_account_number>123456789</shipper_account_number>
<country_code>IT</country_code>
<city>CALVENZANO</city>
<criteria_operator/>
<major_city>MILAN</major_city>
<postal_code/>
</get_city_data>
</body>
</gemini>
Return for points outside the US and Canada return
Following is a GetCityData XML return format for looking up points outside the United States and Canada.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<cities>
<city>
<city_name>CALVENZANO</city_name>
<state_province_code/>
<major_airport_city>MILAN</major_airport_city>
<tariff_destination>MIL</tariff_destination>
</city>
</cities>
</return>
</geminiReturn>
Second example for looking up points outside the US and Canada
Following is a second GetCityData XML format for looking up miscellaneous points outside the United States and Canada.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<get_city_data>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 47 of 166
<shipper_account_number>123456789</shipper_account_number>
<country_code>IT</country_code>
<city>TREVIGLIO</city>
<criteria_operator/>
<major_city/>
<postal_code/>
</get_city_data>
</body>
</gemini>
Second example for looking up points outside the US and Canada return
Following is a second GetCityData XML return format for looking up miscellaneous points outside the United States and Canada.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<cities>
<city>
<city_name>TREVIGLIO</city_name>
<state_province_code/>
<major_airport_city>BERGAMO</major_airport_city>
<tariff_destination>BGY</tariff_destination>
</city>
</cities>
</return>
</geminiReturn>
Example for looking up like city names for non-US and Canadian points
Following is the GetCityData XML format for looking up like city names for points outside the United States and Canada.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<get_city_data>
<shipper_account_number>123456789</shipper_account_number>
<country_code>DE</country_code>
<city>FRANK%</city>
<criteria_operator>LIKE</criteria_operator>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 48 of 166
<major_city/>
<postal_code/>
</get_city_data>
</body>
</gemini>
Looking up like city names for non-US and Canadian points return
Following is the GetCityData XML return format for looking up like city names for points outside the United States and Canada.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<cities>
<city>
<city_name>FRANKENBERG</city_name>
<major_airport_city>FRANKFURT</major_airport_city>
<tariff_destination>FRA</tariff_destination>
<sort_code>FRA</sort_code>
</city>
<city>
<city_name>FRANKENTHAL</city_name>
<major_airport_city>FRANKFURT</major_airport_city>
<tariff_destination>FRA</tariff_destination>
<sort_code>FRA</sort_code>
</city>
<city>
<city_name>FRANKFURT</city_name>
<major_airport_city>FRANKFURT</major_airport_city>
<tariff_destination>FRA</tariff_destination>
<sort_code>FRA</sort_code>
</city>
</cities>
</return>
</geminiReturn>
Note: When using the LIKE criteria operator, you must use a wildcard character of “%.”
For example:
• If the CITY_NAME you are looking for begins with the word “FRANK,” then you would specify the string “FRANK%” for the CITY_NAME value.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 49 of 166
• If the CITY_NAME you are looking for contains the word “FRANK,” then you would specify the string “%FRANK%” for the CITY_NAME value.
• If the CITY_NAME you are looking for ends with the word “FRANK,” then you would specify the string “%FRANK.”
OrderRate
The OrderRate transaction is the command to retrieve a rate estimate based on hypothetical order parameters without regard to consolidation rules. OrderRate accepts the same parameters as OrderSubmit. However, it does not commit the information to our company’s systems. Only use the OrderRate transaction as a tool to retrieve a rate estimate. Note: Please refer to the specific record layout and XML sample input in the OrderSubmit section. (The only difference in the two commands is there are no < label_in/> nodes) for OrderRate. The return fields for OrderRate are different, of course, from the OrderSubmit return fields, in that rate detail is returned but shipment and order numbers are not.
Return Fields
Following are the return fields and the field data types and descriptions for the OrderRate command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success; 1 = failure
Errors String Each error consists of four fields: number, description, type, and detail. Refer to the Appendix for a list of error codes and warnings.
<rate>
<total/> Numeric Returned only if result = 0
<dim_weight/> Numeric Dimensional weight of order. Returned only if result = 0
<rated_weight/> Numeric Weight used to rate this order. Also, dimensional weight UPS Supply Chain Solutions uses to rate shipment Returned only if result = 0
<detail>
<rate_ detail> String Multi-dimensional list containing rate code, description, and amount
<code/> String 4 Specific UPS code for rating sub-component or fee
<description/> String 100 Required in record layout for export and non-US/Canada origin shipments. User-entered description of order or sub-component.
<amount/> Currency 9 Estimated rate for order and freight charges, added charges, amount of shipment, total of all charges on invoice, and surcharges or amount billed for pieces of service node or total for all service nodes
</rate_detail>
</detail>
</rate> Figure 21: OrderRate Return Fields
XML Return
SOAP returns XML that includes a status and possible error list. A result code of zero (0)
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 50 of 166
specifies a successful operation of the OrderRate command. A result code that is not zero specifies that an error occurred.
OrderRate Error example
Following is the OrderRate XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-1234</number>
<description>An error occured (-1234)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
<error>
<number>-5678</number>
<description>Another error occurred (-5678)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
</errors>
</return>
</geminiReturn>
OrderRate Success example
Following is the OrderRate XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<rate>
<total>19.33</total>
<dim_weight>1</dim_weight>
<rated_weight>14</rated_weight>
<detail>
<rate_detail>
<code>2</code>
<description>Airfreight</description>
<amount>13.20</amount>
</rate_detail>
<rate_detail>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 51 of 166
<code>7</code>
<description>Declared Value Fee</description>
<amount>3.75</amount>
</rate_detail>
<rate_detail>
<code>OC33</code>
<description>Fuel Surcharge</description>
<amount>2.38</amount>
</rate_detail>
<currency_code>USD</currency_code>
</detail>
</rate>
<return>
</geminiReturn>
OrderSubmit – This is the Primary Gemini 7.0 WEB API Command The OrderSubmit transaction is the command to submit an order. (This transaction layout is the same for transactions OrderRate and OrderSave, with the exception of the label_in node. See sections on those commands for specific information about input or return records layouts and content.)
OrderSubmit Record Layout
Following is the record layout for the OrderSubmit command, including the fields and the field parameters and descriptions.
Command: OrderSubmit Field
Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<shipment_number/> N String 10 Use when providing High Value or Gold Authorization code for a particular order/shipment.
<label_in> This “label” group is optional. If omitted no label would be returned as part of the order submit. Print Label command will have to be done later before final
processing of the order. <label_format/> Y String Choices are: PDF, DATA (XML string), or
COGNITIVE (Blaster thermal printer)
<label_dest/> Y String RETURN or name of print queue defined on the Gemini machine.
For format DATA, “RETURN” sends back an XML string for values that the user will format into an
acceptable UPS label. For other formats, “RETURN” sends back the label as base 64 encoded string.
</label_in>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 52 of 166
<order>
<order_number/> N String 15 Use when providing High Value or Gold Authorization code for a particular
order/shipment. <shipper_account _number/> Y Numeric 9 UPS assigned number. Used to indicate “owner”
of the freight order. <ship_date/> Y Date 10 mm/dd/yyyy format. Currently, required field but value
is ignored; system will use the system date here, as
expected ship date.
<consignee>
<id/> N String 20 Optional unique identifier for consignee;
non-null value here will be used as a factor in consolidating like orders to “same consignee” id.
<name/> Y String 40 Consignee’s name. Example: “ABC Manufacturing Co.”
<address_ one/> Y String 40 First line of the consignee’s address
<address_ two/> N String 40 Second line of the consignee’s address
<address _three/> N String 40 Third line of the consignee’s address
<city/> Y*
String 35 Consignee’s city. Required for non-US/Canada addresses. Example: “Paris”
<state _code/> N String 4 Consignee’s state or province in abbreviated format. Example: “PA” Will print on label but will not be used
for routing determination.
<postal_ code/> Y*
String 15 Consignee’s Zip or postal code. Required for orders to US, Canada and Puerto Rico. Optional for non-
US/Canada addresses. Example: “15250-7232” <country _code/> Y String 2 Consignee’s country in abbreviated format.
Examples: “US, CA. DE, FR”
<service_ center_code/>
Y*
String 5 On orders with destination outside US/CA, validation of destination will be against a table of known cities
in the destination country. If the city is not matched in the table, and this field is not present, the order will be rejected. If this field is present, this service
center code will be used for order routing, so it has to be correct or delivery will be delayed.
<consignee_account_number/> Y*
String 9 Required for Collect payment type
</consignee>
<contact_phone/> Y*
String 25 Contact’s phone number. Required for shipments with special instruction “HAPU”
<contact_name/> Y*
String 40 Contact person at consignee’s location. Required for shipments with special instruction “HAPU”
<contact_email/> N String 30 Contact’s e-mail address
<service/> Y String 6 Service type number. Associated service code will print on label (example: “AM” will print for service
number 1.
<product/> Y String 3 Only value 3 is allowed at this time (means “freight”)
<payment/> Y String 3 Payment type number. Associated payment code will print on label (example: “PPD” will print for payment number 1.
<third_party_billing>
<third_party_billing _acct/> Y*
Numeric 9 Bill to party’s account number. Required for
3rd Party payment type. Required if ‘3’ is selected as payment code. Cannot be same as shipper account number from above.
<third_party_billing_name/> Y* String 40 Required for 3rd
Party payment type
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 53 of 166
<third_party_billing_country/> Y* String 4 Required for 3rd
Party payment type
<third_party_pays_dest_fees/> Y*
Boolean 1 Required for 3rd
Party payment type if the shipper does not have a US or Canadian origin. Specifies if (1) the
3rd party is to pay the destination fees or (0) 3rd party does not pay destination fees
</third_party_billing>
<description/> Y*
String 30 Required in record layout for international orders. User-entered description of order contents.
<consignee_ reference/> N String 30 Meaningful value to Consignee to identify order.. <shipper_reference/> N String 30 Meaningful value to Shipper to identify order..
<items>
<total_weight/> Y* Double 7 Required if not specifying line item weights
<uom_metric/> Y Boolean 1 Units of measure. 0 = Imperial 1 = metric
Item (1..n (piece_count, length, width, height, weight) - Max 10 Line Items)
Y Array See Fig. 23 Item array definition: maximum of 10 line items. See the Items Array Record Layout.
</items>
<declared_value> <amount/> Y Currency Declared value OR insured value should be provided,
not both. If both are provided, insured value will be used and declared value will be ignored.
<authorization/> Y*
String 10
<currency_code/> Y* String 4 Required if user declared amount.
</declared_value> Required if declared value amount is equal to or greater
than $25,000 USD. Call 1-800-443-6379 in US & Canada; outside US/Canada contact the nearest Service Center or call 1-913-693-6212. Unique code required for
each shipment.
<insured_value> Required if insured value amount is equal to or greater than 500,000 USD. Call1-800-442-6379 in US/Canada or outside the US/Canada contact the nearest Service
Center or call 1-913-693-6212. Unique code required for each shipment.
<amount/> Y Currency - Declared value OR insured value should be provided, not both. If both are provided, insured value will be
used and declared value will be ignored. <authorization/> Y
* String 10
<currency_code/> Y* String 4 Required if use insured amount.
</insured_value>
<customs_value>
<amount/> Y*
Currency - Customs value amount. Required for all export orders. To/from US, Canada, and Australia, the amount must be larger than 0.
<currency_code/> Y* String 4 Required if use customs amount.
</customs_value>
<cts>
<amount/> N Currency Check to shipper amount. Can only be used on orders within US and Canada.
<currency_code/> Y*
String 4 Required if use check-to-shipper amount. Only choices are USD and CAD.
</cts>
<gold_authorization_code/> Y*
String 10 Required for Gold Priority services. Call 1-800-443-6379 in US/Canada or outside
US/Canada the nearest Service Center. Unique code required for each shipment.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 54 of 166
<country_of_original_manufacture>
<orig1/> Y*
String 2 First country of original manufacture. Required for shipments to Canada
<orig2/> N String 2 Second country of original manufacture, if any
<orig3/> N String 2 Third country of original manufacture, if any
<orig4/> N String 2 Fourth country of original manufacture, if any
<orig5/> N String 2 Fifth country of original manufacture, if any
</country_of_original_manufacture>
<special_instructions>
<hapu/> N*
Boolean 1 “HAPU” Hold at airport for pickup. Excludes Two-Man Delivery, Inside Delivery and Delivery-to-Door options
<saturday_pickup/> N Boolean 1 “SATPU” 1 = Saturday pickup. Selected automatically if UPS routinely scheduled to pick up shipments on
Saturday. Call local Service Center to make sure arrangements are approved.
<liftgate_req/> N Boolean 1 “LIFT” Lift-gate required. For shipment pickup or delivery at locations without standard truck loading docks.
<two_man_deliv/> N Boolean 1 “2Man” Two delivery persons required. Use when shipment requires two UPS drivers to successfully deliver it.
<inside_deliv/> N Boolean 1 “INSIDE” Inside delivery. Use when consignee requires UPS to move shipment to a location
within consignee’s facility other than the loading dock.
<notify_arrival/> N Boolean 1 “NOA” Notify on arrival at destination service center. UPS notifies consignee when shipment arrives at
airport. For domestic shipments only
<deliv_door/> N*
Boolean 1 “DELV2DOOR” Door-to-door delivery. For non-US/Canada deliveries only. UPS delivers US/Canada shipments to door unless customer specifies HAPU
<free_dom_ddp/> N *
Boolean 1 “FREEDOMDDP” Free domicile duty and delivery paid. For non-US/Canada shipments only
<free_dom_ddu/> N*
Boolean 1 “FREEDOMDDU” Free domicile duty and delivery unpaid. For non-US/Canada shipments only
<customs_clearance/> * Boolean 1 “CUSTCLEAR” UPS requests. For non-US/Canada shipments only
<gbl_number/> N String 8 Government bill of lading number
<remarks_to_consignee/> N String 30 Additional information for consignee. Text specified by customer
</special_instructions>
<hazmat>
<is_hazmat/> Y Boolean 1 0 = not hazardous. 1 = hazardous material. Customer must be pre-authorized to ship hazardous materials. Call the Gemini Help Desk (1-800-327-2370
or 1-702-408-3735) for additional information. <is_passenger_aircraft/> Y Boolean 1 0 = not passenger aircraft (cargo aircraft only). 1 =
passenger aircraft.
</hazmat>
</order>
</body> Figure 22: OrderSubmit Record Layout
Items Array Record Layout Following is the record layout for the Items array, including the fields and the field parameters
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 55 of 166
and descriptions. The Items array is a field in the OrderSubmit record layout.
Field Required Type Maximum Length
Description
<item>
<piece_count/> Y Numeric 4 Total number of freight pieces in submitted order. Maximum value = 1000 pieces. In return, number of pieces for item node or service node. May also be total number of pieces for service node, all service
nodes, collected for shipping day, or collected for stop
<length/> Y Decimal 4 Length of individual piece in this group.
<width/> Y Decimal 4 Width of individual piece in this group.
<height/> Y Decimal 4 Height of individual piece in this group.
<weight/> Y* Decimal 5 Weight of individual piece in this group. Will be multiplied by above piece count to determine total weight. Omit if providing total weight in
main body of the command (<total_weight>). Weight of pieces is required if <total_weight> is not provided.
</item> Figure 23: Items Array Record Layout
XML Input The developer may submit the OrderSubmit command as an XML string.
OrderSubmit Schema example
The definition of the OrderSubmit XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<label_in>
<label_format>DATA</label_format>
<label_dest>RETURN</label_dest>
</label_in>
<order>
<shipper_account_number>1</shipper_account_number>
<ship_date>07/07/2009</ship_date>
<consignee>
<id>3</id>
<name>ONE CONSIGNEE</name>
<address_one>1234 MAIN STREET</address_one>
<address_two />
<address_three />
<city>GRESHAM</city>
<state_code>OR</state_code>
<postal_code>97030</postal_code>
<country_code>US</country_code>
<service_center_code />
</consignee>
<contact_phone>000-123-4567</contact_phone>
<contact_name>MIKE</contact_name>
<contact_email />
<service>41</service>
<product>3</product>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 56 of 166
<payment>1</payment>
<third_party_billing_acct />
<description>LOTS OF STUFF</description>
<consignee_reference />
<shipper_reference />
<items>
<total_weight>60</total_weight>
<uom_metric>0</uom_metric>
<item>
<piece_count>3</piece_count>
<length>15</length>
<width>12</width>
<height>35</height>
<weight>20</weight>
</item>
</items>
<declared_value>
<amount>1000</amount>
<authorization />
<currency_code>USD</currency_code>
</declared_value>
<insured_value>
<amount />
<authorization />
<currency_code />
</insured_value>
<customs_value>
<amount />
<currency_code />
</customs_value>
<cts>
<amount />
<currency_code>USD</currency_code>
</cts>
<gold_authorization_code />
<delivery_deadline />
<country_of_original_manufacture>
<orig1>CA</orig1>
<orig2 />
<orig3 />
<orig4 />
<orig5 />
</country_of_original_manufacture>
<special_instructions>
<hapu />
<saturday_pickup />
<liftgate_req />
<two_man_deliv />
<inside_deliv />
<notify_arrival />
<deliv_door>0</deliv_door>
<free_dom_ddp />
<free_dom_ddu />
<customs_clearance>0</customs_clearance>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 57 of 166
<gbl_number />
<remarks_to_consignee />
</special_instructions>
<hazmat>
<is_hazmat>0</is_hazmat>
<is_passenger_aircraft>1</is_passenger_aircraft>
</hazmat>
</order>
</body>
</gemini>
OrderSubmit Return Fields
Following are the return fields and data types for the OrderSubmit command.
Field Type Maximum Length
Description
<result/> Numeric 1 0 = success 1 = failure
<data>
<shipment_number/> String 10 Use in record layout when shipment has High Value Authorization code. Returned by successful call to OrderSubmit command. Returned only if result = 0
<order_number/> String 15 Returned by command OrderSubmit. Returned only if result = 0.
<labels>
<label_format/> String 10 Choices are: PDF, DATA (XML string), or COGNITIVE (Blaster thermal printer)
<label_data/> String Only if result = 0. depending on the destination requested, label output will be in the RETURN data string or sent to a defined printer queue
</labels> </data> Figure 24: OrderSubmit Return Fields
XML Return
SOAP returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the OrderSubmit command. A result code that is not zero specifies that an error occurred.
OrderSubmit Error example
Following is the OrderSubmit XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-1234</number>
<description>An error occurred (-1234)</description>
<type>ERROR</type>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 58 of 166
<error_detail>More error information might be here</error_detail>
</error>
<error>
<number>-5678</number>
<description>Another error occurred (-5678)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
</errors>
</return>
</geminiReturn>
OrderSubmit Success example
Following is the OrderSubmit XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<data>
<shipment_number>9065926617</shipment_number>
<order_number>9065926610001</order_number>
<labels>
<label_format>DATA</label_format>
<label_data>
------Label Data-------------
</label_data>
</labels>
</data>
</return>
</geminiReturn>
Specifications for High Value or Gold Priority Orders
Following is the specification for an order with a declared value or insured value greater than authorization trigger amount or with a requested Gold service.
The current trigger values are:
Declared value: 25,000 USD or equivalent
Insurance value: 500,000 USD or equivalent
UPS requires that shipments with a declared value or an insured value equal to or greater than a certain value receive pre-authorization from UPS before a customer can submit that
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 59 of 166
shipment. UPS also requires pre-authorization for shipments using Gold services
To receive an authorization code while processing orders through the Gemini API system, customers must call to get a code for each order on the day that it will be processed. In the US/Canada, call 1-800-443-6379 and ask the Service Representative to issue the appropriate code. Outside US/Canda, contact your local UPS Supply Chain Service office. Service representatives will ask you to provide a shipment number that they can associate with the code they will provide you.
Because Gemini is an order processing system and not a shipment entry system, customers must submit the order to Gemini first. Then Gemini will return a message to the customer with a shipment number and order number that the customer can use when calling the Service Desk.
OrderSubmit Process flow narrative
The following narrative lists the process flow for the OrderSubmit command for a “high value” or Gold Service order:
1. The customer will submit an order (command OrderSubmit).
2. Gemini will then deny OrderSubmit and return a message with the shipment number and order number. The message will state that an authorization code is required.
3. The customer will then call the appropriate service location to request an authorization code, and give the shipment number to the Service Representative.
4. Then the customer will resubmit the order with the shipment number, order number, and authorization code included as attributes within the OrderSubmit command.
5. Gemini will then validate the order and return a label.
OrderSubmit Examples with Calls in XML
The following are examples with calls in XML for
• The OrderSubmit command with a “high” declared value;
• Command OrderSubmit error return with the shipment number in the return;
• Command OrderSubmit with the shipment number and Declared Value Authorization Code; and a successful label return.
Example 1: OrderSubmit Without High Declared Value Authorization Code
This is the command OrderSubmit without a High Declared Value Authorization Code.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<label_in>
<label_format>DATA</label_format>
<label_dest>RETURN</label_dest>
</label_in>
<order>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 60 of 166
<shipper_account_number>1</shipper_account_number>
<ship_date>07/07/2009</ship_date>
<consignee>
<id>3</id>
<name>ONE CONSIGNEE</name>
<address_one>1234 MAIN STREET</address_one>
<address_two />
<address_three />
<city>GRESHAM</city>
<state_code>OR</state_code>
<postal_code>97030</postal_code>
<country_code>US</country_code>
<service_center_code />
</consignee>
<contact_phone>000-123-4567</contact_phone>
<contact_name>MIKE</contact_name>
<contact_email />
<service>41</service>
<product>3</product>
<payment>1</payment>
<third_party_billing_acct />
<description>LOTS OF STUFF</description>
<consignee_reference>CONSIGNEE REF</consignee_reference>
<shipper_reference>SHIPPER REF</shipper_reference>
<items>
<total_weight>14</total_weight>
<uom_metric>0</uom_metric>
<item>
<piece_count>1</piece_count>
<length>5</length>
<width>5</width>
<height>5</height>
<weight>14</weight>
</item>
</items>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 61 of 166
<declared_value>
<amount>25100</amount>
<authorization />
<currency_code>USD</currency_code>
</declared_value>
<insured_value>
<amount />
<authorization />
<currency_code />
</insured_value>
<customs_value>
<amount />
<currency_code />
</customs_value>
<cts>
<amount />
<currency_code>USD</currency_code>
</cts>
<gold_authorization_code />
<delivery_deadline />
<country_of_original_manufacture>
<orig1>CA</orig1>
<orig2 />
<orig3 />
<orig4 />
<orig5 />
</country_of_original_manufacture>
<special_instructions>
<hapu />
<saturday_pickup />
<liftgate_req />
<two_man_deliv />
<inside_deliv />
<notify_arrival />
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 62 of 166
<deliv_door>0</deliv_door>
<free_dom_ddp />
<free_dom_ddu />
<customs_clearance>0</customs_clearance>
<gbl_number />
<remarks_to_consignee />
</special_instructions>
<hazmat>
<is_hazmat>0</is_hazmat>
<is_passenger_aircraft>1</is_passenger_aircraft>
</hazmat>
</order>
</body>
</gemini>
Example 2: OrderSubmit Error return with shipment number and order number
This is the command OrderSubmit error return with the shipment number in the return.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-4536</number>
<description>
High value authorization code is required for
declared values greater than 25000 USD.(-4536)
</description>
<type>ERROR</type>
<error_detail></error_detail>
</error>
</errors>
<data>
<shipment_number>9065926408</shipment_number>
<order_number>9065926400001</order_number>
</data>
</return>
</geminiReturn>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 63 of 166
Example 3: OrderSubmit with shipment number and Declared Value Authorization Code
This is the command OrderSubmit with the shipment number and the Declared Value Authorization Code.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<shipment_number>9065926408</shipment_number>
<label_in>
<label_format>DATA</label_format>
<label_dest>RETURN</label_dest>
</label_in>
<order>
<order_number>9065926400001</order_number>
<shipper_account_number>1</shipper_account_number>
<ship_date>07/07/2009</ship_date>
<consignee>
------Data-------------
<declared_value>
<amount>25100</amount>
<authorization>123abc1234</authorization>
<currency_code>USD</currency_code>
</declared_value>
------Data-------------
</order>
</body>
</gemini>
Successful label return
This is the successful label return code.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<data>
<shipment_number>9065926617</shipment_number>
<order_number>9065926610001</order_number>
<labels>
<label_format>DATA</label_format>
<label_data>
------Label Data-------------
</label_data>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 64 of 166
</labels>
</data>
</return>
</geminiReturn>
OrderSave
OrderSave, similar to OrderRate is a function of the OrderSubmit transaction. The modification of the OrderSubmit allows a customer to input shipping data to be processed at a later date or time. This modification of OrderSubmit places the orders in an "Open" status. There may be times when you desire to save an order into Gemini, receive back a shipment number and order number, and then return to processing and labeling the order at a later time or from a different location. To accomplish this, use the OrderSubmit transaction without the <label/> nodes.
OrderSave Function
With the exception of the label_in node, the OrderSave command is identical to the OrderSubmit command on page 53. If you remove the label_in node, Gemini does not attempt to process a label
and, consequently, leaves the submitted Order with a status of open and, therefore, saved for a user to return to later and process as they wish. Remove the Label_In node from OrderSubmit Transaction to "save" orders/shipments.
<label_in>
<label_format>DATA</label_format>
<label_dest>RETURN</label_dest>
</label_in>
XML Input
OrderSave Schema example
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<order>
<shipper_account_number>123456789</shipper_account_number>
<ship_date>07/07/2009</ship_date>
<consignee>
<id>3</id>
<name>ONE CONSIGNEE</name>
<address_one>1234 MAIN STREET</address_one>
<address_two />
<address_three />
<city>GRESHAM</city>
<state_code>OR</state_code>
<postal_code>97030</postal_code>
<country_code>US</country_code>
<service_center_code />
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 65 of 166
</consignee>
<contact_phone>000-123-4567</contact_phone>
<contact_name>MIKE</contact_name>
<contact_email />
<service>41</service>
<product>3</product>
<payment>1</payment>
<third_party_billing_acct />
<description>LOTS OF STUFF</description>
<consignee_reference />
<shipper_reference />
<items>
<total_weight>14</total_weight>
<uom_metric>0</uom_metric>
<item>
<piece_count>1</piece_count>
<length>1</length>
<width>1</width>
<height>1</height>
<weight>1</weight>
</item>
</items>
<declared_value>
<amount>100</amount>
<authorization />
<currency_code>USD</currency_code>
</declared_value>
<insured_value>
<amount />
<authorization />
<currency_code />
</insured_value>
<customs_value>
<amount />
<currency_code />
</customs_value>
<cts>
<amount />
<currency_code>USD</currency_code>
</cts>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 66 of 166
<gold_authorization_code />
<delivery_deadline />
<country_of_original_manufacture>
<orig1>CA</orig1>
<orig2 />
<orig3 />
<orig4 />
<orig5 />
</country_of_original_manufacture>
<special_instructions>
<hapu />
<saturday_pickup />
<liftgate_req />
<two_man_deliv />
<inside_deliv />
<notify_arrival />
<deliv_door>0</deliv_door>
<free_dom_ddp />
<free_dom_ddu />
<customs_clearance>0</customs_clearance>
<gbl_number />
<remarks_to_consignee />
</special_instructions>
<hazmat>
<is_hazmat>0</is_hazmat>
<is_passenger_aircraft>1</is_passenger_aircraft>
</hazmat>
</order>
</body>
</gemini>
OrderSave success example
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<data>
<shipment_number>9065926540</shipment_number>
<order_number>9065926540001</order_number>
</data>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 67 of 166
</return>
</geminiReturn>
OrderPostpone
The OrderPostpone transaction is the command to postpone an order by changing the ship date of the order to another future date.
Record Layout Following is the record layout for the OrderPostpone command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<order_postpone>
<shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
<order_number/> Y Decimal The order number to postpone
</order_postpone>
</body> Figure 25: OrderPostpone Record Layout
XML Input
The developer may submit the OrderPostpone command as an XML string. OrderPostpone Schema example
The definition of the OrderPostpone XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<order_postpone>
<shipper_account_number>123456789</shipper_account_number>
<order_number>9065926730001</order_number>
</order_postpone>
</body>
</gemini>
Return Fields
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 68 of 166
Following are the return fields and the field data types and descriptions for the OrderPostpone command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success; 1 = failure
Errors String Figure 26: OrderPostpone Return Fields
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the OrderPostpone command. A result code that is not zero specifies that an error occurred.
OrderPostpone Success example
Following is the OrderPostpone XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
</return>
</geminiReturn>
OrderPostpone Error example
Following is the OrderPostpone XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
</return>
</geminiReturn>
PostponeAll
The PostponeAll transaction is the command to postpone all OPEN orders for a single shipper from a single ship date to another future date. Only orders with status “open” will be postponed.
Record Layout
Following is the record layout for the PostponeAll command, including the fields and the field parameters and descriptions.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 69 of 166
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<postpone_all>
<shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
<old_date/> N Date The ship date the OPEN orders have now. (mm/dd/yyyy).
<new_date/> Y Date The date the ship date on the OPEN orders will be change to (postponed to). (mm/dd/yyyy) The new date
must be greater than the old date; and the new date must be “today” or future (cannot be a date in the past).
</postpone_all>
</body> Figure 27: PostponeAll Record Layout
XML Input
The developer may submit the PostponeAll command as an XML string.
PostponeAll Schema example
The definition of the PostponeAll XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<postpone_all>
<shipper_account_number>123456789</shipper_account_number>
<old_date>07/01/2009</old_date>
<new_date>07/02/2009</new_date>
</postpone_all>
</body>
</gemini>
Return Fields Following are the return fields and the field data types and descriptions for the PostponeAll command.
Field Type Maximum Length Description
<result/> Numeric 1 0=success; 1=failure
Errors String Figure 28: PostponeAll Return Fields
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the PostponeAll command. A result code that is not zero
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 70 of 166
specifies that an error occurred.
PostponeAll Success example
Following is the PostponeAll XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
</return>
</geminiReturn>
PostponeAll Error example
Following is the PostponeAll XML return format for errors.
<return>
<result>1</result>
</return>
</geminiReturn>
--OR--
<return>
<result>1</result>
<errors>
<error>
<number>-1525</number>
<description>
No records were found. No orders were postponed. (-1525)
</description>
<type>ERROR</type>
<error_detail></error_detail>
</error>
</errors>
</return>
</geminiReturn>
OrderCancel
The OrderCancel transaction is the command to cancel a single order.
Record Layout
Following is the record layout for the OrderCancel command, including the fields and the field parameters and descriptions.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 71 of 166
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<order_cancel>
<shipper_account_number/> Y Long 9 Account number used when order was created.
<order_number/> Y Decimal Number of order to be canceled.
</order_cancel>
</body> Figure 29: OrderCancel Record Layout
XML Input
The developer may submit the OrderCancel command as an XML string.
OrderCancel Schema example
The definition of the OrderCancel XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<order_cancel>
<shipper_account_number>123456789</shipper_account_number>
<order_number>9065926840001</order_number>
</order_cancel>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the OrderCancel command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success 1 = failure Figure 30: OrderCancel Return Fields
XML Return
SOAP returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the OrderCancel command. A result code that is not zero specifies that an error occurred.
OrderCancel Error example
Following is the OrderCancel XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 72 of 166
<result>1</result>
<errors>
<error>
<number>-1234</number>
<description>An error occured (-1234)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
<error>
<number>-5678</number>
<description>Another error occurred (-5678)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
</errors>
</return>
</geminiReturn>
OrderCancel Success example
Following is the OrderCancel XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
</return>
</geminiReturn>
OrderSearch
The OrderSearch transaction is the command to search for a unique order or a range of orders within given criteria and parameters.
OrderSearch Record Layout
Following is the record layout for the OrderSearch command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<order_search>
<shipper_account_number/> Y Numeric 9 Orders “belonging” to this account number will be searched.
<criteria_list> Node that contains all search parameters
<criteria> 1 to n nodes of search criteria
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 73 of 166
<criteria_field/> Y String 30 Search applied to this data field within Gemini. See Possible Criteria Fields on page 73
<criteria_operator/> Y String 10 Keyword operators for search. See Possible Criteria Operators section on page 73
<criteria_value/> Y String 40 Search applied to this value. If date, use format mm/dd/yyyy
<criteria_value2/> Y String 40 Secondary value field for use with BTWN (between) operator only
</criteria>
</criteria_list>
</order_search>
</body> Figure 31: OrderSearch Record Layout
XML Input
The developer may submit the OrderSearch command as an XML string.
OrderSearch Schema example
The definition of the OrderSearch XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<order_search>
<shipper_account_number>123456789</shipper_account_number>
<criteria_list>
<criteria>
<criteria_field>ORDER_STATUS</criteria_field>
<criteria_operator>NOTEQ</criteria_operator>
<criteria_value>8</criteria_value>
</criteria>
<criteria>
<criteria_field>SHIP_DATE</criteria_field>
<criteria_operator>BTWN</criteria_operator>
<criteria_value>07/01/09</criteria_value>
<criteria_value2>07/07/09</criteria_value2>
</criteria>
</criteria_list>
</order_search>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the OrderSearch
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 74 of 166
command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success; 1 = failure
Errors String <orders> <order> 1 to n nodes of order data returned in search <shipment _number/> String 10 Only if result = 0 <order_ number/> String 15 Only if result = 0
<consignee> <id/> String 20 <name/> String 40 Consignee’s name <address_one/> String 40 Consignee’s address
<address_two/> String 40 <address_three/> String 40 <city/> String 35 Required for international orders <state_code/> String 4 Consignee’s state or province in abbreviated format <postal_code/> String 15 Required for US/Canada addresses.
<country_code/> String 2 Consignee’s country in abbreviated format <service_center_code/> String 5 </consignee> <ship_date/> String 10 Current date or later in mm/dd/yyyy format <status_code/> Integer 2 Returns numeric value for status or orders
<status/> String 25 Returns text description of status <description/> String 30 User-entered order description <manifest_number/> String 10 Gemini creates <interim_manifest_tmst/> String 25 Interim manifest time stamp and unique identifying value
<shipper_reference/> String 30 Shipper requests. Number customer uses to identify order <consignee_reference/> String 30 Consignee requests. CBL number, when available <uom_metric/> Boolean 1 Units of measure. 0 = Imperial 1 = metric
<items>
<total_weight> Double 7 * Required if not specifying line item weights
<weight_format> Measurement type. Either “LB” or “KG”
<total_piece_count> Integer 4 Total number of freight pieces in submitted order, must be presented if <piece_count> is not specified
<item>
<piece_count/> Integer 4 Total number of freight pieces in submitted order
<length/> Decimal 4 Length of shipment. Always in inches
<width/> Decimal 4 Width of shipment. Always in inches
<height/> Decimal 4 Height of shipment. Always in inches
<weight/> Decimal 5 * Combined weight of pieces on this line of items array. Required when user does not specify total weight.
</item>
</items>
</order> </orders> </return>
Figure 32: OrderSearch Return Fields
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 75 of 166
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the OrderSearch command. A result code that is not zero specifies that an error occurred. The amount of orders returned is limited to 5000.
OrderSearch Success example
Following is the OrderSearch XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<orders>
<order>
<shipment_number>9066948869</shipment_number>
<order_number>9066948860001</order_number>
<consignee>
<id>3</id>
<name>ONE CONSIGNEE</name>
<address_one>1234 ANY STREET</address_one>
<address_two />
<address_three />
<city>NEW YORK</city>
<state_code>NY</state_code>
<postal_code>10202</postal_code>
<country_code>US</country_code>
<service_center_code/>
</consignee>
<ship_date>6/30/2009</ship_date>
<status_code>8</status_code>
<status>Posted</status>
<description>LOTS OF STUFF</description>
<manifest_number>M934567890</manifest_number>
<interim_manifest_tmst/>
<shipper_reference>SHIPPER REF</shipper_reference>
<consignee_reference>CONSIGNEE REF</consignee_reference>
<uom_metric>0</uom_metric>
<items>
<total_weight>14</total_weight>
<weight_format>0</weight_format>
<total_piece_count>2</total_piece_count>
<item>
<piece_count>1</piece_count>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 76 of 166
<length>10</length>
<width>10</width>
<height>10</height>
<weight>10</weight>
</item>
</items>
</order>
</orders>
</return>
</geminiReturn>
Possible Criteria Operators
Criteria Operators Description
EQ Equal to expression
NOTEQ Not Equal to
BTWN Between (use <criteria_value/> and <criteria_value2/>)
LIKE Like the expression Figure 33: Possible Criteria Operators
Note: When using the LIKE criteria operator, you must use a wildcard character of “%.” For example:
• If the SHIPPER_REF you are looking for begins with the word “‘RED,” then you would
specify the string “RED%” for the criteria value.
• If the SHIPPER_REF you are looking for contains the word “ORANGE,” then you would specify the string “%ORANGE%” for the criteria value.
• If the SHIPPER_REF you are looking for ends with the word “BLUE,” then you would specify the string “%BLUE.”
Possible Criteria Fields for OrderSearch
• SHIP_DATE
• SHIPPER_REF
• CONSIGNEE_REF
• ORDER_STATUS
Order status values
Order_Status Status Descriptions
-9 Canceled by postponement
-8 Canceled and posted
-7 Canceled and posting
-6 Canceled
0 New
1 Open
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 77 of 166
4 Previously labeled
5 Labeled
6 Closed
7 Posting
8 Posted
99 Posted manual Figure 34: Order Status Values
ShipmentCancel
The ShipmentCancel transaction is the command to cancel a single shipment.
Record Layout
Following is the record layout for the ShipmentCancel command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<shipment_cancel>
<shipper_account_number/> Y Long 9 UPS assigned number. Used to indicate “owner” of the freight order.
<shipment_number/> Y Double - Returned by successful call to OrderSubmit command
</shipment_cancel>
</body> Figure 35: ShipmentCancel Record Layout
XML Input
The developer may submit the ShipmentCancel command to the GeminiExecute() function as an XML string.
ShipmentCancel Schema example
The definition of the ShipmentCancel XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<shipment_cancel>
<shipper_account_number>123456789</shipper_account_number>
<shipment_number>9065886027</shipment_number>
</shipment_cancel>
</body>
</gemini>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 78 of 166
Return Fields
Following are the return fields and the field data types ShipmentCancel command.
Field Type Description
<result/> Numeric 0 = success; 1 = failure Figure 36: ShipmentCancel Return Fields
XML Return
SOAP returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the ShipmentCancel command. A result code that is not zero specifies that an error occurred.
ShipmentCancel Error example
Following is the ShipmentCancel XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-1234</number>
<description>An error occurred (-1234)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
<error>
<number>-5678</number>
<description>Another error occurred (-5678)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
</errors>
</return>
</geminiReturn>
ShipmentCancel Success example
Following is the ShipmentCancel XML return format for successful operations. (SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
</return>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 79 of 166
</geminiReturn>
PrintLabel
The PrintLabel transaction is the command to print or reprint a label.
Record Layout
Following is the record layout for the PrintLabel command, including the fields and the field parameters and descriptions.
Field Required
Type Maximum
Length h
Description
XML header Site_id, user_id, password, command; see page 20 <body> <print_label> <shipper_account_number/> Y Numeri
c 9 UPS assigned number. Used to indicate “owner” of
the freight order. <order_number/> Y Decimal - Order number for which label(s)will be printed. <label_in> <label_format/> Y String Choices are: PDF, DATA (XML string), or
COGNITIVE (Blaster thermal printer)
<label_dest/> Y String RETURN or name of print queue defined on the Gemini machine.
For format DATA, “RETURN” sends back an XML string for values that the user will format into an acceptable UPS label. For other formats, “RETURN”
sends back the label as base 64 encoded string. </label_in> </print_label> </body>
Figure 37: PrintLabel Record Layout
XML Input
The developer may submit the PrintLabel command as an XML string.
PrintLabel Schema example
The definition of the PrintLabel XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<print_label>
<shipper_account_number>123456789</shipper_account_number>
<order_number>9066948910001</order_number>
<label_in>
<label_format>PDF</label_format>
<label_dest>RETURN</label_dest>
</label_in>
</print_label>
</body>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 80 of 166
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the PrintLabel command.
Field Type Description
<result> Numeric 0 = success 1 = failure Figure 38: PrintLabel Return Fields
XML Return
SOAP returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the PrintLabel command. A result code that is not zero specifies that an error occurred.
PrintLabel Error example
Following is the PrintLabel XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-1234</number>
<description>An error occurred(-1234)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
<error>
<number>-5678</number>
<description>An error occurred(-1234)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
</errors>
</return>
</geminiReturn>
PrintLabel Success example
Following is the PrintLabel XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 81 of 166
<data>
<shipment_number>9066948913</shipment_number>
<labels>
<label_format>PDF</label_format>
<label>
9j/4AAQSkZJRgABAQAAAQABAAD/2wBDA
....base 64 encoded PDF image....
rRQB5V/wyd8EP+iN/D//AMJex/8AjVea
</label>
</labels>
</data>
</return>
</geminiReturn>
PrintManifest
The PrintManifest transaction is the command to print or reprint a manifest.
Record Layout
Following is the record layout for the PrintManifest command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20 <body> <print_manifest> <shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner” of the
freight order. <manifest_type/> Y String 7 “EOD” for End of Day manifest or “INTERIM” for
interim manifest <manifest_number/> Y String Gemini creates. Corresponds to shipping day If
reprinting manifest, the INTERIM manifest number returned by earlier call to PrintManifest or EOD manifest number returned by EODSubmit
<manifest_in> <manifest_format/> Y String 3 “PDF,” “DATA” or “TEXT.” Gemini returns same
format sent in call to PrintManifest <manifest_dest/> Y String 6 1) “RETURN” sends back PDF in return value as a
base 64 encoded string
2) “DATA” returns information as XML
3) Name of local print queue set up on Gemini machine prints to that queue. Required for “TEXT” format
</manifest_in> </print_manifest> </body>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 82 of 166
Figure 39: PrintManifest Record Layout
XML Input The developer may submit the PrintManifest command as an XML string.
PrintManifest Schema example
The definition of the PrintManifest XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<print_manifest>
<shipper_account_number>123456789</shipper_account_number>
<manifest_type>EOD</manifest_type>
<manifest_number>M967546181</manifest_number>
<manifest_in>
<manifest_format>CSV</manifest_format>
<manifest_dest>RETURN</manifest_dest>
</manifest_in>
</print_manifest>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the PrintManifest command.
Field Type Maximum Length
Description
<result/> Numeric 1 0 = success; 1 = failure <data> <manifest> <manifest_number/> String 22 Gemini creates. Corresponds to shipping day If reprinting manifest,
the INTERIM manifest number returned by earlier call to PrintManifest or EOD manifest number returned by EODSubmit
<manifest_format/> String 3 “PDF,” “DATA” or “TEXT.” Gemini returns same format sent in call to PrintManifest
<manifest_image/> String Base 64 encoding of manifest created if manifest destination is “RETURN” in PrintLabel call
</manifest> </data> Figure 40: PrintManifest Return Fields
XML Return
SOAP returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the PrintManifest command. A result code that is not zero specifies that an error occurred.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 83 of 166
PrintManifest Error example
Following is the PrintManifest XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-1234</number>
<description>An error occurred(-1234)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
<error>
<number>-5678</number>
<description>Another error occurred(-5678)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
</errors>
</return>
</geminiReturn>
PrintManifest Success example Following is the PrintManifest XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<data>
<manifest>
<manifest_number>M974503746</manifest_number>
<manifest_format>PDF</manifest_format>
<manifest_image>
JVBERi0xLjMKJeLjz9MKMSAwIG9iag0KPDwNCi9
..... base 64 encoded PDF image ......
bGQNCi9Gb250RmlsZTIgMTMxIDAgUg0KL0Zvb
</manifest_image>
</manifest>
</data>
</return>
</geminiReturn>
EODSubmit
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 84 of 166
The EODSubmit transaction is the command to initiate the End of Day process that closes all shipments and orders for the current shipping day, finalizes consolidation, invoices the day’s shipping with UPS, and posts all shipment data into our company’s central enterprise servers. Note: A shipping day is defined by time elapsed since the customer last ran the End of Day process. If the customer does not transmit the EODSubmit command by 2 a.m. Eastern time, our company’s servers will automatically close and process the day’s shipments. The Gemini Web Servers can be set to run the End of Day process automatically at a specified time as a fail safe. For example, in the event that customer’s systems or users are unable to submit the End of Day command, the Gemini Web Servers will still send the day’s shipment data to our company’s enterprise systems at the time specified by the user. If this feature is something you are interested in or require, please advise your UPS contact person and this feature will be set up for your account.
Record Layout
Following is the record layout for the EODSubmit command body, including the fields and the field parameters and descriptions.
Field Required Type Maximum
Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<eod_submit>
<shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner” of the freight order.
<ship_date/> N Date 10 Specifies when freight will be tendered. Current date or later in mm/dd/yyyy format. Currently, UPS ignores this attribute in EODSubmit, but it is reserved for future use. Any orders labeled “today” will be processed.
</eod_submit>
</body> Figure 41: EODSubmit Record Layout
XML Input
The developer may submit the EODSubmit command to the SOAP Listener on the Gemini Web Servers as an XML string.
EODSubmit Schema example
The definition of the EODSubmit XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<eod_submit>
<shipper_account_number>000000001</shipper_account_number>
<ship_date>03/08/2009</ship_date>
</eod_submit>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 85 of 166
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the EODSubmit command.
Field Type Maximum
Length Description
<result/> Numeric 1 0 = success 1 = failure
<manifest_number/> String 10 Gemini creates. Corresponds to shipping day If reprinting manifest, the INTERIM manifest number returned by earlier call to
PrintManifest or EOD manifest number returned by EODSubmit
<shipment_count/> Numeric 5 Number of shipments for service node, collected for stop, total count of shipments for all service nodes or total number of shipments
collected for shipping day. Also, number of shipments assigned to shipping day’s manifest
<order_count/> Numeric 5 Number of orders assigned to shipping day’s manifest Figure 42: EODSubmit Return Fields
XML Return
The SOAP Listener returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the EODSubmit command. A result code that is not zero specifies that an error occurred.
EODSubmit Error example
Following is the EODSubmit XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-1234</number>
<description>An error occurred (-1234)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
<error>
<number>-5678</number>
<description>Another error occurred (-5678)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
</errors>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 86 of 166
</return>
</geminiReturn>
EODSubmit Success example
Following is the EODSubmit XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<eod_return>
<shipment_count>5</shipment_count>
<order_count>5</order_count>
<manifest>
<manifest_number>M967546247</manifest_number>
<manifest_format></manifest_format>
<manifest_image></manifest_image>
</manifest>
</eod_return>
</return>
</geminiReturn>
Update
The Update transaction is the command to update the Gemini application and to rate files and shipper configuration data that is installed on the local Gemini system.
Record Layout Following is the record layout for the Update command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body> <update_request> <shipper_account_number/> N Long 9 UPS assigned number. Used to indicate “owner” of the
freight order. <update_type/> Y Long 2 Number specifying the type of update you want to run
on your local Gemini system. See Figure 44: Update
Types <app_version/> * * If you request update type 4 (software update) and
want a specific application version installed on your system, state version. Leave blank to get latest version
</update_request> </body> Figure 43: Update Record Layout
Type Description
1 Shipper and site configuration update. (Synchronize databases for all shippers installed on the site)
2 Rate file updates. (All rating files for all shippers)
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 87 of 166
4 Software update. (Downloads and installs application files and stored procedures on the client Gemini system) Figure 44: Update Types
XML Input
The developer may submit the Update command as an XML string.
Update Schema example
The definition of the Update XML schema is as follows. (SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<update_request>
<shipper_account_number>123456789</shipper_account_number>
<update_type>4</update_type>
<app_version>7.0.1.6</app_version>
</update_request>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the Update command.
Field Type Maximum Length Description
<result/> Integer 1 0 = success; 1 = failure
Errors String Each error consists of four fields: number, description, type, and detail. Figure 45: Update Return Fields
XML Return
The Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the Update command. A result code that is not zero specifies that an error occurred.
Update Error example
Following is the Update XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 88 of 166
<number>-1234</number>
<description>An error occurred (-1234)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
<error>
<number>-5678</number>
<description>Another error occurred (-5678)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
</errors>
</return>
</geminiReturn>
Update Success example
Following is the Update XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
</return>
</geminiReturn>
ConsigneeSave
The ConsigneeSave transaction is the command to save consignees into the Gemini system by shipper account.
Record Layout
Following is the record layout for the ConsigneeSave command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20
<body>
<consignee_save>
<shipper_account _number/> Y Numeric 9 UPS specifies
<consignee> Y 1 to n nodes of consignees
<id/> N String 20 Optional unique identifier for this consignee
<name/> Y String 40 Consignee’s name
<address_ one/> Y String 40 First line of the consignee’s address
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 89 of 166
<address_ two/> N String 40 Second line of the consignee’s address
<address _three/> N String 40 Third line of the consignee’s address
<city/> Y* String 35 * Required for international orders
<state _code/> N String 4 State or province code
<postal_ code/> Y* String 15 * Required for US/Canada addresses.
<country _code/> Y String 2
<service_ center_code/> Y* String 5 * Required for international orders
<consignee_account_number/> Y* Integer 9 * Required for collect payment type
</consignee>
</consignee_save>
</body> Figure 46: ConsigneeSave Record Layout
XML Input
The developer may submit the ConsigneeSave command as an XML string.
ConsigneeSave Schema example
The definition of the ConsigneeSave XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<consignee_save>
<shipper_account_number>123456789</shipper_account_number>
<consignee>
<id>ABC123</id>
<name>ABC Company Name</name>
<address_one>123 Test Loop</address_one>
<address_two>Suite 88</address_two>
<address_three/>
<city>Boston</city>
<state_code>MA</state_code>
<postal_code>02150</postal_code>
<country_code>US</country_code>
<service_center_code/>
<consignee_account_number/>
</consignee>
</consignee_save>
</body>
</gemini>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 90 of 166
--OR— (SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<consignee_save>
<shipper_account_number>123456789</shipper_account_number>
<consignee>
<id>XYZ123</id>
<name>XYZ Company Name</name>
<address_one>123 Test Loop</address_one>
<address_two>Suite 88</address_two>
<address_three/>
<city>Bankok</city>
<state_code/>
<postal_code/>
<country_code>TH</country_code>
<service_center_code>BKK</service_center_code>
<consignee_account_number/>
</consignee>
</consignee_save>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the
ConsigneeSave command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success; 1 = failure
Errors String Figure 47: ConsigneeSave Return Fields
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the ConsigneeSave command. A result code that is not zero specifies that an error occurred.
ConsigneeSave Success example
Following is the ConsigneeSave XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 91 of 166
<result>0</result>
</return>
</geminiReturn>
ConsigneeSave Error example Following is the ConsigneeSave XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>1</result>
<errors>
<error>
<number>-1234</number>
<description>An error occured (-1234)</description>
<type>ERROR</type>
<error_detail>More error information might be here</error_detail>
</error>
</errors>
</return>
</geminiReturn>
ConsigneeSearch
The ConsigneeSearch transaction is the command to search for consignees that are saved in the Gemini system for the specified shipper account.
Record Layout Following is the record layout for the ConsigneeSearch command, including the fields and the field parameters and descriptions.
Field Required Type Maximum Length
Description
XML header Site_id, user_id, password, command; see page 20 <body> <consignee_search> <shipper_account_number/> Y Numeric 9 UPS assigned number. Used to indicate “owner”
of the freight order. <criteria_list> Node that contains all search parameters <criteria> 1 to n nodes of search criteria <where_operator/> N String
<criteria_field/> Y String 30 Data field within Gemini to which the search is applied. See Criteria Fields for ConsigneeSearch on page 90
<criteria_operator/> Y String 10 Keyword operators for search. See Possible Criteria Operators for ConsigneeSearch on page 91
<criteria_value/> Y String 40 Value to which search is applied
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 92 of 166
<criteria_value2/> Y String 40 Secondary value field for use with BTWN (between)
operator only </criteria> </criteria_list> </consignee_search> </body> Figure 48: ConsigneeSearch Record Layout
XML Input
The developer may submit the ConsigneeSearch command as an XML string.
ConsigneeSearch Schema example
The definition of the ConsigneeSearch XML schema is as follows.
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<consignee_search>
<shipper_account_number>123456789</shipper_account_number>
<criteria_list>
<criteria>
<where_operator></where_operator>
<criteria_field>CONSIGNEE_ID</criteria_field>
<criteria_operator>EQ</criteria_operator>
<criteria_value>ABC123</criteria_value>
<criteria_value2></criteria_value2>
</criteria>
</criteria_list>
</consignee_search>
</body>
</gemini>
--OR—
(SOAP envelope header, see page 18 for content)
(XML header, including specific command name – see page 19 for content)
<body>
<consignee_search>
<shipper_account_number>123456789</shipper_account_number>
<criteria_list>
<criteria>
<where_operator></where_operator>
<criteria_field>NAME</criteria_field>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 93 of 166
<criteria_operator>LIKE</criteria_operator>
<criteria_value>%COMPANY%</criteria_value>
<criteria_value2></criteria_value2>
</criteria>
</criteria_list>
</consignee_search>
</body>
</gemini>
Return Fields
Following are the return fields and the field data types and descriptions for the
ConsigneeSearch command.
Field Type Maximum Length Description
<result/> Numeric 1 0 = success; 1 = failure
Errors String
<consignees>
<consignee> 1 to n nodes of Consignee data returned in the search
<id/> String 20
<name/> String 40
<address_ one/> String 40
<address_ two/> String 40
<address _three/> String 40
<city/> String 35
<state _code/> String 4
<postal_ code/> String 15
<country _code/> String 2
<service_ center_code/> String 5
<consignee_account_number/> Integer 9
</consignee>
</consignees>
</return> Figure 49: ConsigneeSearch Return Fields
XML Return
Gemini API returns XML that includes a status and possible error list. A result code of zero (0) specifies a successful operation of the ConsigneeSearch command. A result code that is not zero specifies that an error occurred.
ConsigneeSearch Success example
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 94 of 166
Following is the ConsigneeSearch XML return format for successful operations.
(SOAP envelope header for API Return – see page 18 for content)
<return>
<result>0</result>
<consignees>
<consignee>
<id>XYZ123</id>
<name>XYZ COMPANY NAME</name>
<address_one>123 TEST LOOP</address_one>
<address_two>SUITE 88</address_two>
<address_three></address_three>
<city>BANKOK</city>
<state_code></state_code>
<postal_code></postal_code>
<country_code>TH</country_code>
<service_center_code>BKK</service_center_code>
<consignee_account_number>0</consignee_account_number>
</consignee>
<consignee>
<id>ABC123</id>
<name>ABC COMPANY</name>
<address_one>123 TEST LOOP</address_one>
<address_two>SUITE 88</address_two>
<address_three></address_three>
<city>BOSTON</city>
<state_code>MA</state_code>
<postal_code>02150</postal_code>
<country_code>US</country_code>
<service_center_code></service_center_code>
<consignee_account_number>0</consignee_account_number>
</consignee>
</consignees>
</return>
</geminiReturn>
ConsigneeSearch Error example
Following is the ConsigneeSearch XML return format for errors.
(SOAP envelope header for API Return – see page 18 for content)
<return>
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 95 of 166
<result>1</result>
<errors>
<error>
<number>-5336</number>
<description>No matching consignee(s) found. (-5336)</description>
<type>ERROR</type>
<error_detail></error_detail>
</error>
</errors>
</return>
</geminiReturn>
Criteria Fields for ConsigneeSearch
• CONSIGNEE_ID
• NAME
• ADDRESS_ONE
• CITY
• STATE_CODE
• COUNTRY_CODE
• POSTAL_CODE
• SERVICE_CENTER_CODE
• CONSIGNEE_ACCOUNT_NUMBER
Possible Criteria Operators for ConsigneeSearch
• NOTLIKE
• BTWN
• EQ
• NOTEQ
• LIKE
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 96 of 166
Appendix C: XML Schema Document (XSD)
Gemini.xsd
Gemini.xsd schema can be found at: https://gemini.ups-scs.com/Gemini.xsd
GeminiCommon.xsd
GeminiCommon.xsd schema can be found at: https://gemini.ups-scs.com/Geminicommon.xsd.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 97 of 166
Appendix D: Master API Error Code List
The Master API Error Code List is a numerical list of error codes, descriptions of the errors, and the content area that may return the error.
In the API return, if the error code is preceded with a minus sign (–), it signals an error and the previous command failed. If the error code does not have a minus sign, then the information should be considered a warning, for future reference, but the command completed successfully.
Error Code
Description Error group
100 Gemini cannot verify the consignee address you entered. Please verify that the consignee address has been entered correctly.
Shipment
200 Gemini cannot verify the shipper address. Please contact the Gemini helpdesk. Shipment
300 The service is not valid for the consignee and shipper you have selected. Please call local service center for special delivery.
Shipment
400 Gemini has encountered an unexpected error. Please contact the Gemini helpdesk. Shipment
900 An unknown Error has occurred. Utility
909 No qualified rates for category. Utility
910 No rate found for Origin/Destination. Utility
911 No rate found for Weight. Utility
912 No rate found for Product. Utility
913 No rate found for Dim and Weight. Utility
914 No rate found for Declared Value Utility
915 No rate found for specified service. Utility
916 AdErrorExpandAliasGemPlusDirectory Utility
917 AdErrorGetwwwRootDirectory Utility
918 AdErrorExpandAliaswwwRootDirectory Utility
919 AdErrorGetRateDataDirectory Utility
920 Unable to open file: <account>.rdb. Utility
921 Unable to open file: General.rdb. Utility
922 Unable to open file containing /Other Charges/. Utility
980 Unable to Get Config Data Utility
981 Unable to Set Config Data Utility
987 AdErrorConvertLinearUnit Utility
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 98 of 166
Appendix D: Master API Error Code List
988 AdErrorConvertWeight Utility
989 Invalid currency code. Utility
990 AdErrorGetCurrencyFactorOut Utility
991 AdErrorDBSelectItem Utility
992 AdErrorGetGeminiSiteID Utility
993 AdErrorGeiminiSiteOverflow Utility
994 AdErrorRound Utility
999 Invalid User Utility
1001 Unable to connect to database. Make sure RDS is installed and ODBC is set up correctly. Consignee
1002 Consignee already exists. Consignee
1003 AdErrorCheckShipments Consignee
1004 The consignee does not have a valid Account Number. Consignee
1005 Consignee already exists. Consignee
1006 3rd-Party Account number is not found. Consignee
1007 Third party billing account number may not equal the shipper account number. Consignee
1010 Unable to open consignee table in CreateNew. Consignee
1011 Unable to insert consignee table in CreateNew. Consignee
1012 Unable to update consignee record in Update. Consignee
1013 Unable to get consignee list in GetConsigneeList. Consignee
1014 Consignee not found. Consignee
1015 Failed to remove consignee. Consignee
1016 CreateNew reports shipper account number is blank. Consignee
1017 CreateNew reports consignee ID is blank. Consignee
1018 Failed to update consignee. Consignee
1019 GetConsignee reports missing consignee keys. Consignee
1020 Unable to open default record in CreateDefault. Consignee
1021 Default already exists in CreateDefault. Consignee
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 99 of 166
Appendix D: Master API Error Code List
1022 Insert default failed in CreateDefault. Consignee
1023 No existing defaults in GetDefault. Consignee
1025 Unable to delete default. Consignee
1026 Update default record failed in UpdateDefault. Consignee
1027 Unable to update consignee default. Consignee
1030 Unable to validate consignee ID. Consignee
1031 Entered Consignee information is incomplete or invalid. Consignee
1032 Unable to move consignee arguments to recordset. Consignee
1033 Unable to move consignee properties to recordset. Consignee
1034 Unable to validate default argument keys. Consignee
1035 Unable to validate default arguments. Consignee
1036 Unable to set default recordset to properties. Consignee
1037 Unable to set default properties to recordset. Consignee
1038 Billing account country code is required. Consignee
1039 Billing account name is required. Consignee
1040 Unable to delete consignee with existing shipments in Delete. Consignee
1041 Unable to update consignee with shipments. Consignee
1042 Unable to create new consignee IDs in Copy. Consignee
1043 More than 1000 temporary consignees already exist. Consignee
1044 Consignee ID too long. Consignee
1045 Billing account has an invalid account number. Consignee
1046 Consignee has an invalid postal code. Consignee
1047 Unable to return the selected consignee defaults search. Consignee
1048 Invalid United States postal code for the current consignee. United States postal codes are required in numeric format (12345).
Consignee
1049 Invalid Canadian postal code format for the current consignee. Canadian postal codes are required in the format Letter-Number-Letter-Number-Letter-Number (A1B2C3)
Consignee
1051 Consignee ID too long. Consignee
1052 Consignee Name too long. Consignee
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 100 of 166
Appendix D: Master API Error Code List
1053 Consignee Address 1 too long. Consignee
1054 Consignee Address 2 too long. Consignee
1055 Consignee Address 3 too long. Consignee
1056 Consignee City too long. Consignee
1057 Consignee State too long. Consignee
1058 Consignee Postal code too long. Consignee
1059 Consignee Country code too long. Consignee
1060 Consignee Service center code too long. Consignee
1061 Could not access Interface component. Consignee
1062 Tariff Destination point is invalid. Consignee
1063 Default description too long. Consignee
1064 Default shipper reference too long. Consignee
1065 Default consignee reference too long. Consignee
1066 Default contact phone country code too long. Consignee
1067 Could not access mass distribution data. Consignee
1068 An unknown error occured while validating the consignee being added to the mass distribution list.
Consignee
1069 Consignee country must be US (non-Puerto Rico) to be added to a mass distribution list. Consignee
1070 Default contact last name too long. Consignee
1071 Default contact first name too long. Consignee
1072 Default contact middle name too long. Consignee
1073 Default contact email address too long. Consignee
1074 Default currency code too long. Consignee
1075 Default linear unit of measure too long. Consignee
1076 Default weight unit of measure too long. Consignee
1078 Provided Country Code not found. Consignee
1079 Default country of original manufacture too long. Consignee
1080 Default received at location too long. Consignee
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 101 of 166
Appendix D: Master API Error Code List
1081 Default mode of entry too long. Consignee
1082 Default other special description too long. Consignee
1083 A passed argument was invalid. Consignee
1084 A Valid State Code is required. Consignee
1085 AdErrorDBOpenShipper Consignee
1086 AdErrorUnableToSaveXmlFile Consignee
1087 AdErrorUnableToLoadXmlFile Consignee
1088 Service Center is Required. Consignee
1089 AdErrorDBConsigneeSearch Consignee
1090 Remove nulls failed. Consignee
1091 The consignee is already associated with the current Mass Distribution List Consignee
1092 Consignee Name is Required. Consignee
1093 Consignee Address Line One is Required Consignee
1094 Consignee City is Required Consignee
1095 Consignee Postal Code is Required Consignee
1096 Consignee Country Code is Required Consignee
1097 Invalid Account Number Consignee
1099 City name could not be found, therefore destination service center code is required. Consignee
1150 AdErrorMLMissingParam Mass Dist
1151 AdErrorRemoveMLConsignee Mass Dist
1152 AdErrorInsertMLConsignee Mass Dist
1153 AdErrorCreateMassList Mass Dist
1154 AdErrorGettingMassList Mass Dist
1155 AdErrorDeleteMassList Mass Dist
1156 An error occurred while retrieving mass distribution lists. Mass Dist
1201 Unable to connect with database. Commodity
1202 CreateNew reports commodity already exists. Commodity
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 102 of 166
Appendix D: Master API Error Code List
1210 Unable to open commodity record in CreateNew. Commodity
1211 Unable to insert commodity record in CreateNew. Commodity
1212 Unable to update commodity in Update. Commodity
1214 GetCommodity unable to find an existing commodity to get. Commodity
1215 Unable to delete commodity in Delete. Commodity
1216 CreateNew reports shipper account number is blank. Commodity
1217 CreateNew reports consignee key is blank. Commodity
1219 Unable to get new commodity ID in CreateNew. Commodity
1220 DeleteCommodityGroup unable to delete commodity group record. Commodity
1221 UpdateCommodityGroup failed to update commodity group record. Commodity
1222 Unable to open default commodity table in AddDefaultConsigneeCommodity. Commodity
1223 Unable to insert default commodity in AddDefaultConsigneeCommodity. Commodity
1224 AddDefaultConsigneeCommodity reports default consignee commodity already exists. Commodity
1225 GetDefaultCommodity reports no existing default commodity to get. Commodity
1226 RemoveDefaultConsigneeCommodity unable to remove record. Commodity
1227 RemoveDefaultShipperCommodity unable to remove record. Commodity
1228 Unable to remove default group commodity in RemoveDefaultGroupCommodity. Commodity
1229 AdErrorGetNewCommodityId Commodity
1230 Unable to get new commodity group ID in CreateCommodity. Commodity
1231 Unable to validate commodity. Commodity
1232 Unable to set commodity recordset to properties. Commodity
1233 Unable to set commodity properties to recordset. Commodity
1234 Unable to validate commodity group keys. Commodity
1235 Unable to validate commodity group. Commodity
1236 Unable to open commodity group table in CreateCommodityGroup. Commodity
1237 Unable to insert commodity group into table in CreateCommodityGroup. Commodity
1238 CreateCommodityGroup reports commodity already exists. Commodity
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 103 of 166
Appendix D: Master API Error Code List
1239 Unable to retrieve commodity table. Commodity
1240 Unable to retrieve commodity group. Commodity
1241 Remove nulls failed. Commodity
1242 GetCommodityGroup reports no existing commodity groups to get. Commodity
1244 AdErrorDeleteCommodityGroup Commodity
1245 AdErrorDeleteCommodityGroupCommodities Commodity
1246 Dimensional length cannot exceed 300 inches or 762 centimeters. Commodity
1247 Dimensional width cannot exceed 300 inches or 762 centimeters. Commodity
1248 Dimensional height cannot exceed 300 inches or 762 centimeters. Commodity
1250 AdErrorConvertingUom Commodity
1253 Serial number too long. Commodity
1254 Harmonized serial number too long. Commodity
1256 Description too long. Commodity
1257 Commodity group description too long. Commodity
1301 Unable to retrieve shipper_site data from database for this shipper. Shipper
1303 AdWarningRegionalGatewayTooLong Shipper
1304 AdErrorReadCurrentShipDate Shipper
1305 Unable to save cost center. Shipper
1306 A cost center already exists with this name. Please enter a different cost center name. Shipper
1310 Unable to open shipper table in CreateNew. Shipper
1311 Unable to insert shipper table in CreateNew. Shipper
1312 Unable to update shipper table in Update. Shipper
1313 Unable to get shipper list from database. Shipper
1314 No Shipper Accounts Found. Shipper
1323 GetDefault reports no existing defaults. Shipper
1338 Unable to validate shipper arguments. Shipper
1339 Unable to remove nulls. Shipper
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 104 of 166
Appendix D: Master API Error Code List
1340 AdErrorDBRetrieveShippers Shipper
1341 Invalid Shipper Account Number. Shipper
1342 AdErrorDBRetrieveUnpostedOrders Shipper
1343 AdErrorChangeOrderShipDate Shipper
1344 AdErrorCreateOrderObject Shipper
1345 AdErrorDBUpdateCurrentShipDate Shipper
1350 Unable to call points to validate account number. Shipper
1351 Invalid account number Shipper
1352 Name too long. Shipper
1353 Address 1 too long. Shipper
1354 Address 2 too long. Shipper
1355 Address 3 too long. Shipper
1356 City too long. Shipper
1357 State too long. Shipper
1358 Postal code too long. Shipper
1359 Country code too long. Shipper
1361 AdErrorShipperSiteAlreadyExists Shipper
1363 Description too long. Shipper
1364 Shipper reference too long. Shipper
1365 Consignee reference too long. Shipper
1366 Default contact phone country code too long. Shipper
1370 Inbound SC Code too long. Shipper
1371 Outbound SC Code too long. Shipper
1372 Division too long. Shipper
1373 Regional hub too long. Shipper
1374 Regional hub code too long. Shipper
1379 Country of original manufacture too long. Shipper
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 105 of 166
Appendix D: Master API Error Code List
1380 Default contact last name too long. Shipper
1383 Default contact email address too long. Shipper
1384 Currency code too long. Shipper
1385 Service center code too long. Shipper
1386 Phone country code too long. Shipper
1390 Contact last name too long. Shipper
1393 Contact email address too long. Shipper
1394 EIN too long. Shipper
1395 Contract number too long. Shipper
1396 Received at location too long. Shipper
1397 Mode of entry too long. Shipper
1398 Default other special description too long. Shipper
1399 Invalid argument passed. Shipper
1401 AdErrorDBConnect Order
1403 Unable to get order number key in GetNewOrderNumber. Order
1404 Unable to get new shipment number in CopyShipment. Order
1405 Unable to open shipment from database in CopyShipment. Order
1406 Unable to insert shipment into database in CopyShipment. Order
1408 Unable to insert shipment in CreateNew. Order
1409 Unable to get new order number in CreateNew. Order
1410 Unable to open order in Copy. Order
1411 Unable to insert order in CreateNew. Order
1412 Unable to update order header in Copy. Order
1413 Unable to select order from database in Copy. Order
1414 No existing order in Copy. Order
1415 Unable to copy shipment in Copy. Order
1417 Unable to get items in Copy. Order
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 106 of 166
Appendix D: Master API Error Code List
1418 Unable to open items in Copy. Order
1419 Unable to insert item in Copy. Order
1420 Unable to update item in Copy. Order
1421 Unable to get orders in UpdateOrderHeader. Order
1422 Unable to select shipment in DeleteShipment. Order
1423 Unable to delete shipment in DeleteShipment. Order
1424 Unable to delete SLI in Delete. Order
1425 Unable to delete order in Delete. Order
1426 Unable to delete shipment in Delete. Order
1431 Unable to select item from database in GetNewItemNumber. Order
1434 No existing shipment in ValidateShipment. Order
1454 Unable to delete SLI line item in Delete. Order
1460 Unable to select mass dist order in GetHistoryList. Order
1461 Found multiple shipments with matching shipment number (big problem). Order
1462 The shipment number subimitted has already been used. Order
1465 Unable to load order in LoadOrderHeader. Order
1467 Unable to open mass dist in GetHistoryList. Order
1478 Unable to set shipment status in Delete. Order
1479 Unable to select shipment status in SetShipmentStatus. Order
1488 Unable to retrieve shipment in GetNewTemporaryShipmentNumber Order
1489 Unable to get new shipment number in InsertShipment. Order
1490 Unable to check order status in Delete. Order
1491 Order has been labeled. Unable to delete. Order
1492 Unable to update status in Delete. Order
1493 Order has been labeled. Unable to delete. Order
1501 Database reported error copying shipment. Order
1502 Unable to delete hazmat commodity in Delete. Order
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 107 of 166
Appendix D: Master API Error Code List
1503 Unable to delete hazmat in Delete. Order
1504 Unable to delete rating detail in Delete. Order
1505 Unable to delete rating in Delete. Order
1506 Unable to delete line item in Delete. Order
1511 Unable to copy order in ChangeOrderShipDate. Order
1512 Unable to delete order in ChangeOrderShipDate. Order
1513 Unable to delete new order in ChangeOrderShipDate. Order
1514 Unable to postpone. Shipment attached to order already posted to the Freight System. Order
1515 Unable to get shipment orders in ChangeShipmentShipDate. Order
1516 No orders for shipment in ChangeShipmentShipDate. Order
1517 ChangeOrderShipDate failed from ChangeShipmentShipDate. Order
1518 The new ship date cannot be before than the current system date. Order
1523 Could not access interface component. Order
1524 Unable to update order header shipment number in ChangeShipmentNumber. Order
1525 No records were found. No orders were postponed. Order
1526 One or more orders failed to postpone. Order
1527 3rd-Party Acct number is required when payment type is 3 (Third-Party Billing). Order
1534 Unable to open new shipment in InsertShipment. Order
1537 Database reported error deleting hazmat commodity in DeleteShipment. Order
1538 Unable to update order status in DeleteShipmentOrder. Order
1539 Unable to select shipment order status from database in Delete. Order
1554 Order and label printer .dll versions do not match. Order
1555 Unable to select order status in AssignShipmentNumber. Order
1558 Remove Nulls failed in GetHistoryList. Order
1560 Order posting. Unable to delete. Order
1561 Shipment posting. Unable to delete. Order
1563 AdErrorInvalidService Order
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 108 of 166
Appendix D: Master API Error Code List
1581 AdErrorDBUpdateShipmentCustomsValue Order
1582 Invalid order number. Order
1585 AdErrorDBSelectSLI Order
1586 AdErrorDBResetSLIPrintDate Order
1589 AdErrorDBSelectShipmentOrderCancelledStatus Order
1600 Invalid consignee address passed. Label Printer
1601 Invalid service code passed. Label Printer
1602 Invalid postal/zip code passed. Label Printer
1603 Invalid destination sort code passed. Will use TD derived from city name or zip. Label Printer
1604 Invalid date passed. Label Printer
1605 Invalid origin sort code passed. Will use origin derived from city name or zip. Label Printer
1606 Invalid payment type passed. Label Printer
1607 Invalid piece count passed. Label Printer
1608 Invalid weight passed. Label Printer
1609 Invalid description passed. Label Printer
1610 Invalid shipment number passed. Label Printer
1611 Invalid input. Label Printer
1612 Invalid shipper address. Label Printer
1613 Unable to generate big service code Label Printer
1614 Points object was inaccessible. Destination sort code and gateway required. Label Printer
1615 The points object was unable to find a sort code that matched the consignee address. Label Printer
1616 The points object reported an error. Label Printer
1617 Printer specific object inaccessible. Label Printer
1618 Printer specific object reported an error. Label Printer
1619 The information on your specified printer does not exist in the registry. Label Printer
1620 Input exceeds maximum length Label Printer
1621 The points object returned multiple matches for the zip/postal code or city passed in. Label Printer
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 109 of 166
Appendix D: Master API Error Code List
1622 A special service that does not need to be printed on the label was passed. Label Printer
1623 The information on your specified printer does not exist in the registry. Label Printer
1697 Label type specified in hardware options not supported by this printer specific object. Label Printer
1698 Internal parameter error Label Printer
1699 Error 27.Unable to find the printer. Make sure it on, plugged into the correct port, and has labels. If all else fails try turning it off for a few seconds and then turn it back on.
Label Printer
1700 An unexpected error occurred while creating label. Label Printer
1701 Unable to create label. An error occurred while attempting to load the GIF generation object. Label Printer
1702 Unable to create label. An error occurred attempting to save GIF label to disk. Label Printer
1703 Unable to create label. An error occurred while attempting to locate the company logo graphic. Label Printer
1704 The label type selected is not supported with the current printer. Label Printer
1705 Unable to create label. An error occurred while attempting to locate the HAZMAT label graphic. Label Printer
1706 The currently selected printer does not support the printing of graphics. Label Printer
1707 Unable to create label. The label type selected is not supported on the printer chosen. Label Printer
1720 Unable to create label. An error occurred while trying to process instructions for PDF generation. Label Printer
1721 The Free Adobe Acrobat Reader version 5.0 or greater is required to print PDF documents. You can download the installation program for this application from www.adobe.com.
Label Printer
1725 Unable to create label. An error occurred while trying to load object responsible for processing PDF instructions.
Label Printer
1730 Unable to create label. Unsuccessful in creating a connection to the Cognitive Blaster. Label Printer
1740 Unable to create label. An error occurred while attempting to load the MS XML 4.0 or later parser.
Label Printer
1750 Unable to create label. The barcode font necessary for label creation does not appear to be installed on this computer.
Label Printer
1780 Unable to create label. An error occurred while attempting to load the Base64 Encoding object. Label Printer
1800 Entered zip/postal code or city/state/country combination was not found. Points
1801 Unable to find the data file in the location specified by the registry. Points
1802 The data file is either corrupt or is not the same version as the object. Points
1803 Invalid parameter to the points object. Points
1804 Had problems looking through registry for the location of the data file. Points
1805 Parameter too long. Points
1806 Could not find the shipper object. There may be problems determining the gateway on international shipments.
Points
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 110 of 166
Appendix D: Master API Error Code List
1807 Shipper object reported errors. There may be problems determining the gateway on international shipments.
Points
1899 Invalid account number. Points
1909 No qualified rates for category. Rate
1910 No rate found for Origin/Destination. Rate
1911 No rate found for Weight. Rate
1912 No rate found for Product. Rate
1913 No rate found for Dim and Weight. Rate
1914 No rate found for Declared Value Rate
1915 No rate found for specified service. Rate
1920 Unable to open file: <account>.rdb. Rate
1921 Unable to open file: General.rdb. Rate
1922 Unable to open file containing /Other Charges/. Rate
1923 Unable to open rate database. Rate
1924 Internal Error. (memalloc) Rate
1925 Internal Error. (safearraycreate) Rate
1926 Unable to find International rating data. Rate
1927 Invalid input Rate
1928 Unable to open file: Currency.bin. Rate
1929 Unable to open file: Fuel_Exempt.txt. Rate
1930 Unable to get points info. Rate
1931 Unable to get origin TD from points. Rate
1932 Could not get destination TD from points. This is likely because you are shipping to a city not in the Gemini database.
Rate
1933 Exception caught in calling Points object. Rate
1934 Unable to get /Other Charges/. Rate
1935 Internal Error. (VBS wrapper call to GetRate failed.) Rate
1936 Invalid parameter. (wrong Variant type) Rate
1937 Invalid parameter. (expected BSTR variant) Rate
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 111 of 166
Appendix D: Master API Error Code List
1938 Invalid parameter. (expected array variant) Rate
1939 Invalid parameter. (wrong number of elements in array) Rate
1940 Unknown product. Rate
1941 Unknown service. Rate
1942 Total Weight must be greater than 0. Rate
1943 Total Weight must be less than 100,000 lbs. Rate
1944 Piece Count must be greater than 0. Rate
1945 Length must be greater than 0. Rate
1946 Width must be greater than 0. Rate
1947 Dimensional weight equated to over 99 999lbs. Rate
1948 Total piece must be less than 1,000. Rate
1949 Declared value over 100.00 USD on a document. Rate
1950 Saturday delivery not available to destination. Rate
1952 Unable to open EC01 file for Origin. Rate
1953 Unable to open EC02 file for Origin. Rate
1954 Unable to open file: FDCharge.bin. Rate
1955 Unable to open file: Drayage.bin. Rate
1956 Unable to open file: Intldims.bin. Rate
1957 Unable to open file: Sector.txt Rate
1958 Unable to open CXR file. Rate
1959 Unable to open file: EC<sc_code>.bin Rate
1960 Error converting line items. Rate
1961 Error getting dimensional weight factor. (Probable bad rate file.) Rate
1962 Error getting minimum invoice. (Probable bad rate file.) Rate
1963 Error getting base charge. Rate
1964 Error getting declared value fee. (Probable bad rate file.) Rate
1965 Error getting document rates. (Probable bad rate file.) Rate
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 112 of 166
Appendix D: Master API Error Code List
1966 Error getting airfreight rate. (Probable bad rate file.) Rate
1967 Error getting oversize charges. (Probable bad rate file.) Rate
1970 Service is not available to Destination Rate
1971 Unable to open file: CA_bound.bnd. Rate
1972 No CA file found for Origin. Rate
1973 Unable to rate Order/Shipment at this time. Please call UPS for a rate quote. Rate
1980 Internal error. (Error array full.) Rate
1981 Too many other charges. Rate
1982 Internal Error: unable to get file path from Registry. Rate
1983 Unable to calculate Forward at Destination charges which may result in an inaccurate rate. Rate
1984 Destination not found in Drayage Table. Rate
1985 Gemini does not currently support Canada to Canada rating. Rate
2301 Unable to connect with database. End Of Day
2302 Unable to retrieving shipper from database. End Of Day
2303 Unable to retrieving shipment count from database. End Of Day
2304 Unable to update new block range. End Of Day
2305 Unable to retrieve shipper site from database. End Of Day
2306 Unable to retrieve Gemini site from database. End Of Day
2307 Unable to retrieve updated shipper from database. End Of Day
2308 Unable to retrieve updated consignee from database. End Of Day
2309 Unable to retrieve updated hazmat commodity from database. End Of Day
2310 Unable to retrieve manifest from database. End Of Day
2311 Unable to retrieve shipments from database. End Of Day
2312 Unable to retrieve orders from database. End Of Day
2313 Unable to retrieve items from database. End Of Day
2314 Unable to update shipment status in database. End Of Day
2315 Unable to update order status in database. End Of Day
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 113 of 166
Appendix D: Master API Error Code List
2316 Unable to retrieve SLI from database. End Of Day
2317 Unable to retrieve SLI line from database. End Of Day
2318 Unable to retrieve hazmat from database. End Of Day
2319 Unable to retrieve hazmat item from database. End Of Day
2320 Unable to retrieve shipper manifest from database. End Of Day
2321 Unable to retrieve updated config site from database. End Of Day
2322 Unable to retrieve updated config shipper from database. End Of Day
2323 Unable to set status to posting in database. End Of Day
2324 Unable to set order status to posting in database. End Of Day
2325 Unable to set status to canceled in database. End Of Day
2326 Unable to set order status to canceled in database. End Of Day
2327 Unable to update shipment manifest in database. End Of Day
2328 Unable to reset order status to closed in database. End Of Day
2329 Unable to reset status to closed in database. End Of Day
2330 Unable to retrieve updated shipper site from database. End Of Day
2331 Unable to set manifest shipments this stop in database. End Of Day
2332 Unable to select shipments for manifest in database. End Of Day
2333 Unable to retrieve table updates in database. End Of Day
2334 Unable to update manifest in database. End Of Day
2335 Unable to retrieve shipment manifest in database. End Of Day
2336 Unable to delete manifest number in database. End Of Day
2337 Unable to reset shipper manifest number in database. End Of Day
2338 Unable to reset shipment status in database. End Of Day
2339 Unable to reset order status in database. End Of Day
2340 Unable to set manifest number in database. End Of Day
2341 Unable to set status cancelled posted in database. End Of Day
2342 Unable to set order cancelled posted in database. End Of Day
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 114 of 166
Appendix D: Master API Error Code List
2343 Unable to insert manifest number in database. End Of Day
2344 Unable to create utility object. End Of Day
2345 Unable to create GP server object. End Of Day
2346 Unable to establish RDS connection. End Of Day
2347 Unable to allocate new block range from Gemini server. End Of Day
2348 Unable to download static data from Gemini server. End Of Day
2349 Unable to update last upgrade from RDS server. End Of Day
2350 Unable to get server file version info from RDS server. End Of Day
2351 Unable to get Gemini http server name from registry. End Of Day
2352 Unable to get config shipment allocation days. End Of Day
2353 Unable to get config sng shipment number allocation percent. End Of Day
2354 No shipper found. End Of Day
2355 Unable to get last connect. End Of Day
2356 Could not get shipment to do. End Of Day
2357 Unable to update last connect. End Of Day
2358 Unable to get new manifest number. End Of Day
2359 Unable to release manifest number. End Of Day
2360 End of day processing failed. End Of Day
2361 Unable to add new manifest number. End Of Day
2362 Unable to get download temp directory from registry. End Of Day
2363 Error in http file download. End Of Day
2364 Warning setting the file date/time. End Of Day
2365 No shipper returned from database. End Of Day
2366 Out of manifest numbers. End Of Day
2367 No shipments to post. End Of Day
2368 Error converting manifest number to string. End Of Day
2369 Error comparing manifest number to next. End Of Day
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 115 of 166
Appendix D: Master API Error Code List
2370 Warning manifest number not release. End Of Day
2371 Unable to open file (API failed). End Of Day
2372 Unable to set file time (API failed). End Of Day
2373 Unable to convert creation date/time to file date/time. End Of Day
2374 Unable to close file (API failed). End Of Day
2375 Unable to get system time to file time (API failed). End Of Day
2376 Unable to check shipment manifest number allocation. End Of Day
2377 Fabio new fab. End Of Day
2378 Unable to write shipments to Disk. End Of Day
2379 ExportShipmentGetfileName failed. End Of Day
2380 ExportDataCreateFabioObject failed. End Of Day
2381 ExportDataPrepareShipment failed. End Of Day
2382 ExportDataPrepareOrder failed. End Of Day
2383 ExportDataPrepareItems failed. End Of Day
2384 ExportDataFabioSetNotify failed. End Of Day
2385 ExportDataFabioNewShipment failed. End Of Day
2386 ExportDataFabioSetSpecialServices failed. End Of Day
2387 ExportDataFabioSetCustomsValue failed. End Of Day
2388 ExportDataFabioSetCtsAmount failed. End Of Day
2389 ExportDataFabioSetBillToAccountNumber failed. End Of Day
2390 ExportDataFabioSetGoldAuthorization failed. End Of Day
2391 ExportDataFabioSetAttention failed. End Of Day
2392 ExportDataFabioSetIntl failed. End Of Day
2393 ExportDataFabioSetDeclaredValue failed. End Of Day
2394 ExportDataFabioSetInsuredValue failed. End Of Day
2395 ExportDataFabioStoreShipment failed. End Of Day
2396 ExportShipmentDataToFileShipments failed. End Of Day
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 116 of 166
Appendix D: Master API Error Code List
2397 ExportDataSetSpecialInstructions failed. End Of Day
2398 ExportDataSetScheduleBNumber failed. End Of Day
2399 Error persisting recordset as XML. End Of Day
2400 Windows reported problem with registry. Scale
2401 Windows was unable to find the serial port specified in hardware options. For a usual Gemini computer, this should be COM1.
Scale
2402 No response from the scale. Make sure it is properly hooked up and turned on. Scale
2403 Unexpected response from the communications port. Make sure the specified com port in options has a scale hooked up to it.
Scale
2404 Internal error. (Unexpected.) Scale
2405 Invalid parameter. Scale
2406 Scale returned a negative weight. Make sure your scale has been zeroed and has the items you want to ship on it.
Scale
2501 Unable to connect with the database. SOD
2502 Unable to retrieve static shipper. (database problem) SOD
2503 Unable to change fields on the server table. SOD
2504 Unable to retrieve shipment count. (database problem) SOD
2505 Unable to allocate new shipment numbers (RDS). SOD
2506 Unable to update database with allocated shipment numbers. *CRITICAL ERROR* SOD
2507 Unable to update Config info for the site. SOD
2508 Unable to update Config info the shipper. SOD
2509 Unable to create new consignee. SOD
2510 Unable to update hazmat commodity table. SOD
2511 (Block size range) SOD
2512 (Block size factor) SOD
2513 Unable to retrieve information on shipper specified by client. SOD
2514 Shipper Account number specified by client not found. SOD
2515 Unable to retrieve existing block of shipment numbers. SOD
2516 Old block of shipment numbers not found. SOD
2517 Unable to update old block of shipment numbers. SOD
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 117 of 166
Appendix D: Master API Error Code List
2518 Unable to retrieve an available block of shipment numbers. SOD
2519 Unable to retrieve a new block of shipment numbers. SOD
2520 No available blocks of shipment numbers. SOD
2521 Unable to update an available block of shipment numbers. SOD
2522 Unable to update an allocated block of shipment numbers. SOD
2523 Unable to retrieve the specified Gemini site (Database problem) SOD
2524 Specified client site not found in server database. SOD
2525 Unable to update manifest. SOD
2526 Problem retrieving static payment types. SOD
2527 Problem retrieving static products. SOD
2528 Problem retrieving static services. SOD
2529 Problem retrieving static status codes. SOD
2530 Server system time and client system time are more than 29 minutes different (taking into account time zones). Check your system date and time.
SOD
2531 Unable to retrieve shipper site info. (Database problem) SOD
2532 Unable to find shipper site. SOD
2533 Unable to update shipper. SOD
2534 Unable to update consignee. SOD
2535 Unable to update SLI line item. SOD
2536 Unable to update shipment. The shipment has already been uploaded. Call the Gemini Help Desk. Repeating the same process will not change the result.
SOD
2537 Unable to update order. SOD
2538 Unable to update line item. SOD
2539 Unable to update status code. SOD
2540 Unable to update shipper last upload time. (Database problem) SOD
2541 Unable to open server table. (Database problem) SOD
2542 Unable to add new record to server table. SOD
2543 Unable to update server table. SOD
2544 Unable to allocate array. SOD
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 118 of 166
Appendix D: Master API Error Code List
2545 Unable to create order object. SOD
2546 Internal error occurred in ifer5 record loop. SOD
2547 Internal error occurred in ifer5 record field loop. SOD
2548 Unable to extract a field of the ifer5. SOD
2549 No shipper account number specified. SOD
2550 No ship date. SOD
2551 Unable to allocate order number. SOD
2552 No shipment number specified. SOD
2553 Unable to create new order. SOD
2554 Unable to update order. SOD
2555 Internal error in ifer5 line item loop. SOD
2556 Internal error in ifer5 line item field loop. SOD
2557 Unable to extract line item field. SOD
2558 No piece count. SOD
2559 Unable to add item. SOD
2560 Unable to create consignee object. SOD
2561 Unable to update SLI. SOD
2562 Problem retrieving static country codes. SOD
2563 Problem retrieving static province codes. SOD
2564 Problem retrieving static configuration codes for shipper. SOD
2565 Problem retrieving static configuration codes for site. SOD
2566 Problem retrieving static state codes. SOD
2567 Gemini file not found. SOD
2568 Unable to retrieve gemini file. (Database problem.) SOD
2569 Unable to get file version info. (WIN32 API returned error.) SOD
2570 Unable to update last upgrade time. (Database problem) SOD
2571 Unable to change shipment status to posted. SOD
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 119 of 166
Appendix D: Master API Error Code List
2572 Unable to change order status to posted. SOD
2573 Unable to get web server absolute path from registry. SOD
2574 Unable to get web server download directory from registry. SOD
2575 Unable to create third party consignee. SOD
2576 Unable to update last connect time. (Database problem) SOD
2577 Unable to get a file date/time or size. SOD
2578 Unable to retrieve group site. SOD
2579 Warning: Site is not a group member. SOD
2580 Unable to retrieve group member group. (Database problem) SOD
2581 (File update delete duplicates.) SOD
2582 Invalid Gemini Site Code. SOD
2583 Unable to delete temporary consignee. SOD
2584 Previous existing order. SOD
2585 Unable to delete existing order items. SOD
2586 Unable to redim array. SOD
2587 Unable to increment generic array. SOD
2588 Unable to increment SLI array. SOD
2589 Unable to redim SLI array. SOD
2590 Unable to create SLI object. SOD
2591 SLI object couldn't create SLI. SOD
2592 Unable to get temporary consignee key. SOD
2593 Unable to get next temporary consignee key. SOD
2594 Unable to get manifest number. SOD
2595 Unable to get third party key. SOD
2596 Shipment number check digit was invalid. SOD
2597 Unable to create new notify consignee. (notify other.) SOD
2598 Unable to update hazmat table. SOD
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 120 of 166
Appendix D: Master API Error Code List
2599 Unable to add/update server table. SOD
2602 Unable to get site configuration data from database. Config
2603 Unable to get shipper configuration data from database. Config
2604 Config key not found. Config
2605 Shipper configuration not found. Using site Config. Config
2606 Unable to select shipper from database. Config
2607 Shipper specified to SetConfigData does not exist. Config
2608 Unable to retrieve Gemini site from database. Config
2609 Site specified to SetConfigData does not exist. Config
2610 Unable to get configuration data from database. Config
2611 Unable to insert configuration data into database. Config
2612 Unable to update configuration data in database. Config
2613 Unable to get printer list. Config
2614 Unable to get printer type list. Config
2615 Unable to get printer info. Config
2616 Please select a printer or port for the current label format. Config
2617 Printer ID required. Config
2618 Unable to update printer info. Please ensure current user has administrative rights. Config
2619 Unable to delete printer. Config
2620 Unable to get printer usage info. Config
2621 Unable to update printer usage info. Config
2622 Unable to get scale list. Config
2623 Unable to get scale type list. Config
2624 Unable to get scale info. Config
2625 Scale ID required in SetConfigData. Config
2626 Unable to update scale info. Config
2627 Unable to delete scale. Config
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 121 of 166
Appendix D: Master API Error Code List
2628 Unable to get scale usage info. Config
2629 Unable to update scale usage info. Config
2630 Unable to get scale type info. Config
2631 Scale Type ID required. Config
2632 Unable to open site configuration from database. Config
2701 Unable to connect with database. Static Data
2710 Unable to open country list from database in GetCountryList. Static Data
2711 GetCountryList reports no existing country list to get. Static Data
2712 Unable to open country name from database in GetCountryName. Static Data
2713 GetCountryName reports no existing country name to get. Static Data
2714 Unable to open state list from database in GetStateList. Static Data
2715 GetStateList reports no existing state list to get. Static Data
2716 Unable to open state name from database in GetStateName. Static Data
2717 GetStateName reports no existing state name to get. Static Data
2718 Unable to open province list from database. Static Data
2719 GetProvinceList reports no existing province list to get. Static Data
2720 Unable to open province name from database in GetProvinceName. Static Data
2721 No existing province name in database in GetProvinceName. Static Data
2722 Unable to open service list from database in GetServiceList. Static Data
2723 GetServiceList reports no existing service list to get. Static Data
2724 Unable to open service name from database in GetServiceName. Static Data
2725 GetServiceName reports no existing service name to get. Static Data
2726 Unable to open product list from database in GetProductList. Static Data
2727 GetProductList reports no existing product list to get. Static Data
2728 Unable to open product name from database in GetProductName. Static Data
2729 GetProductName reports no existing product name to get. Static Data
2730 Unable to get payment type list from database in GetPaymentTypeList. Static Data
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 122 of 166
Appendix D: Master API Error Code List
2731 GetPaymentTypeList reports no existing payment type to get. Static Data
2732 Unable to open payment type name from database in GetPaymentTypeName. Static Data
2733 GetPaymentTypeName reports no existing payment type name to get. Static Data
2734 Unable to open status list from database in GetStatusList. Static Data
2735 GetStatusList reports no existing status list to get. Static Data
2736 Unable to open status name from database in GetStatusName. Static Data
2737 GetStatusName reports no existing status name to get. Static Data
2738 GetE2kValues reports error while searching service array. Static Data
2739 GetE2kValues reports error while searching product array. Static Data
2740 GetE2kValues reports error while searching payment type array. Static Data
2741 GetE2kValues reports error while searching status array. Static Data
2742 GetE2kValues unable to open service center list from database. Static Data
2743 GetE2kValues reports no existing service center list to get. Static Data
2744 GetE2kValues reports error while searching service center array. Static Data
2745 Unable to get COMAT info from Config in GetPaymentTypeList. Static Data
2746 AdErrorRemovenulls Static Data
2747 Country code is invalid. Static Data
2748 Unable to access Currency Codes in database Static Data
2749 Invalid Currency Code. Static Data
2750 Unable to retrieve country code with the country name provided. Static Data
2800 A Customs Value is required for Export Documents. SLI
2801 A Description is required for all Export Document Line Items SLI
2802 Line item description must begin with a letter A=Z or a number. SLI
2803 AdErrorConvertUnitCostCurrency SLI
2804 AdWarningCurrencyCodeNotFound SLI
2805 AdErrorDBUpdateShipment SLI
2806 AdErrorGetSliLine SLI
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 123 of 166
Appendix D: Master API Error Code List
2807 AdErrorGetShipmentInfo SLI
2808 AdErrorConvertTotalCostCurrency SLI
2809 Unable to open SLI from database in CreateNew. SLI
2810 Unable to create SLI in CreateNew. SLI
2811 Unable to insert SLI into database in CreateNew. SLI
2812 Line item description cannot equal FREIGHT ALL KINDS, FAK, PARTS, VARIOUS, STUFF, MULTIPLE, GENERAL FREIGHT, GENERAL CARGO, THING, THINGS, MISC, or
MISCELLANEOUS. Description must be more specific.
SLI
2813 AdErrorGetNextSiteKeySliLineGroup SLI
2814 GetSli reports no existing SLI to get. SLI
2815 Database unable to delete SLI in Delete. SLI
2816 Unable to update SLI in database in Update. SLI
2818 Unable to open SLI line item from database in CreateSliLine. SLI
2819 Unable to insert SLI line item into database in CreateSliLine. SLI
2820 CreateSliLine reports SLI line item already exists. SLI
2821 GroupDescription already exists. SLI
2822 GetSliLine reports no existing SLI line item to get. SLI
2823 Unable to delete SLI line item from database in DeleteSliLine. SLI
2824 Unable to update SLI line item in UpdateSliLine. SLI
2825 The USML (U.S. Munitions List) Code is invalid. SLI
2826 USML (U.S. Munitions List) Codes are only allowed for Military shipments (M indicator instead of D or F).
SLI
2830 GetSliDefault reports NoDefaultSliKey. SLI
2831 Intermediate consignee country is not valid. SLI
2832 Invalid country of ultimate destination. SLI
2835 Unable to validate arguments. SLI
2836 Unable to set recordset to properties. SLI
2839 Unable to create update text. SLI
2840 Unable to validate SLI line item. SLI
2841 Unable to retrieve SLI line item. SLI
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 124 of 166
Appendix D: Master API Error Code List
2842 Unable to get new SLI line number. SLI
2843 Remove Nulls failed. SLI
2844 AdErrorDBOpenSliLineGroupDesc SLI
2845 Failed to save export document data. Shipment does not exist. SLI
2846 AdErrorOrderSumNotFound SLI
2847 The Shipper Reference Number contains too many characters. SLI
2851 A Validated General License Is Required For Export Documents. SLI
2852 Broker name too long. SLI
2853 Broker address line 2 too long. SLI
2854 Broker address line 1 too long. SLI
2855 Broker address line 3 too long. SLI
2856 Broker city name too long. SLI
2857 Broker state code too long. SLI
2858 Broker postal code too long. SLI
2859 Broker country code too long. SLI
2861 Country of Ultimate Destination too long. SLI
2862 Currency code too long. SLI
2863 Validated general license number too long. SLI
2864 ECCN too long. SLI
2865 Special instructions too long. SLI
2866 Domestic/Foreign indicator too long. SLI
2867 Domestic/Foreign indicator invalid. SLI
2868 Schedule B number too long. SLI
2869 Description too long. SLI
2870 Insured value initials too long. SLI
2871 Authorized officer name too long. SLI
2872 No existing SLI default. SLI
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 125 of 166
Appendix D: Master API Error Code List
2873 Unable to open SLI line item default in GetSliLineCommodity. SLI
2874 GetSliLineCommodity reports no existing SLI line item default. SLI
2875 Unable to open SLI line item commodity in DeleteSliLineCommodity. SLI
2876 No existing SLI line commodity in DeleteSliLineCommodity. SLI
2877 Unable to delete SLI line commodity from database in DeleteSliLineCommodity. SLI
2878 Unable to update SLI line commodity in UpdateSliLineCommodity. SLI
2879 VaidateSliLineGroup failed. SLI
2880 Line group description too long. SLI
2881 Unable to open SLI line item group in CreateSliLineGroup. SLI
2882 CreateSliLineGroup reports a group of SLI line items with the same name already exists. SLI
2883 Unable to insert SLI line group into database in CreateSliLineGroup. SLI
2884 CreateSliLineGroup reports no existing SLI line group. SLI
2885 Database unable to delete the SLI line group in DeleteSliLineGroup. SLI
2886 Unable to update SLI line group in database. SLI
2887 AdErrorNoExistingSliLine SLI
2889 Customs value currency code is invalid. Please enter a customs value currency. SLI
2890 Argument invalid. SLI
2891 Title for signatory is too long. SLI
2892 Validated General License Number required. SLI
2893 ECCN required. SLI
2894 CopySliLine reports existing SLI line item has zero quantity. SLI
2895 AdErrorDBUpdateDefaultSli SLI
2896 Unable to convert insured value currency in CreateUpdateText. SLI
2897 CreateUpdateText reports an insured value with no currency type. SLI
2898 Unable to convert shipping weight in CopySliLine. SLI
2899 Existing SLI has unit cost but no currency type in CopySliLine. SLI
2939 AdErrorCreateUpdateText Registry Manager
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 126 of 166
Appendix D: Master API Error Code List
3300 Unable to find any consignee data to import. Import Export
3301 The consignee file was corrupt or in a bad format. Import Export
3302 Unable to find the Gemini 5.0 Consignee object. (consignee.dll) Import Export
3500 Error downloading file. End Of Day
3501 Error loading XML into recordset. End Of Day
3502 Error in GetRateFilesAsXml Gemini server call. End Of Day
3503 Error: Downloaded file size mismatch with server file size. End Of Day
3504 Warning: DeleteFileIfExists failed (file might be locked). End Of Day
3505 Error retrieving the latest Gemini version from Gemini server. End Of Day
3506 Warning: file copy. End Of Day
3507 Error in RAS connect. End Of Day
3508 Error exporting shipment data to file. End Of Day
3509 Error getting shipper list. End Of Day
3510 Error deleting existing file. End Of Day
3511 Error updating shipment totals. End Of Day
3512 Error updating payment type. End Of Day
3513 Error updating product. End Of Day
3514 Error updating service. End Of Day
3515 Error updating status. End Of Day
3516 Error updating state. End Of Day
3517 Error updating country. End Of Day
3518 Error updating currency. End Of Day
3519 Error updating shipper. End Of Day
3520 Error updating shipper site. End Of Day
3521 Error updating Config shipper. End Of Day
3522 Error updating shipments this stop. End Of Day
3523 Error writing shipments to disk - Disk is full. End Of Day
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 127 of 166
Appendix D: Master API Error Code List
3524 User cancelled call to Gemini Server. End Of Day
3525 This site has already been installed. You must contact the Gemini Help Desk to reinstall this site. End Of Day
3526 An invalid update_type request was passed to the UpdateGemini command. End Of Day
3527 An error occurred getting commands from Gemini Server. End Of Day
3529 An error occurred while trying to establish an Internet connection. End Of Day
3530 An error occurred while trying to do SOAP proxy authentication. End Of Day
3531 An error occurred while trying to retrieve the WSDL file path. End Of Day
3532 An error occurred during EndOfDay Initialize process. End Of Day
3533 An error occurred during EndOfDay Terminate process. End Of Day
3534 An error occurred while trying update the AutoEndOfDay timestamp. End Of Day
3535 An error occurred while calling the Gem_Server ServerUpdate method. End Of Day
3536 An error occurred while calling the Gem_Server GetRatingFilesAsXML method. End Of Day
3537 An error occurred while calling the Gem_Server InstallGemini method. End Of Day
3538 An error occurred while retrieving the ServerName and SiteID. End Of Day
3539 An error occurred while calling the Gem_Server UploadAndPostOrdersAsXML method. End Of Day
3540 An error occurred while getting the End Of Day record counts. End Of Day
3541 An error occurred while creating the Gemini Business Objects. End Of Day
3542 Unable to create SOAP Client component. End Of Day
3543 Unable to initialize Gemini Server component. End Of Day
3544 Error setting Proxy User/Password End Of Day
3545 Error setting SOAP Timeout End Of Day
3546 Error setting Gemini Server name End Of Day
3547 Unable to create Network Share on EOD Server End Of Day
3548 EOD Processing did not occur. EOD Processing is not allowed from Workgroup Clients. End Of Day
3549 Unable to execute call to Server. End Of Day
3550 This shipper is currently in the process of posting orders. The end of day process may not be run again until the shipper is finished posting.
End Of Day
3551 An error occurred in the DoMaintenance function. End Of Day
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 128 of 166
Appendix D: Master API Error Code List
3553 An error occurred while creating the server proxy object. End Of Day
3554 EOD Servername is not set in Database End Of Day
3555 EOD Server does not have Gemini Share End Of Day
3556 EOD Server does not have any matching files. End Of Day
3557 Error copying file from EOD Server. End Of Day
3560 Error creating Gemini 7 format IFER5 End Of Day
3561 Error copying Gemini 7 format IFER5 to destination. End Of Day
3570 An unknown error occurred posting Gemini 7 IFER5 data to Server End Of Day
3571 An error occurred loading XML while posting Gemini 7 IFER5 data to server. End Of Day
3572 An error occurred reading XML while posting Gemini 7 IFER5 data to server. End Of Day
3573 Unable to create Gemini Server component while posting Gemini 7 IFER5 data to Server. End Of Day
3574 An error occurred calling Gemini Server component while posting Gemini 7 IFER5 data to server. End Of Day
3575 ERROR in EWW_GEM_ServerProxy.cServerProxy.PostGem6Ifer5() End Of Day
3600 Unable to increment notify consignee key array. SOD
3601 Unable to increment third party key array. SOD
3602 Unable to increment manifest number array. SOD
3603 No shippers for specified site. SOD
3604 Unable to clone file recordset. SOD
3605 Cannot locate Gemini install program. SOD
3606 Unable to get DRate from SC-Code. SOD
3607 Unable to update SC-Code. SOD
3608 Unable to delete SC-Code. SOD
3609 Unable to find a rate file that matched your service center. SOD
3610 Unable to update rating origin service center. SOD
3611 Unable to delete tariff origin service center. SOD
3612 Unable to access DRates. SOD
3613 Unable to insert DRates. SOD
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 129 of 166
Appendix D: Master API Error Code List
3614 Unable to delete DRates. SOD
3615 Unable to get Drate. SOD
3616 Unable to expand rating version directory. SOD
3617 Unable to get shipper rating information. SOD
3618 A file you might need could not be found on the server. SOD
3619 SC-Code not found. SOD
3620 Unable to sort SC-Codes. SOD
3621 Unable to read SC-Code file. SOD
3622 Unable to get shipper DRate. SOD
3623 Unable to change or set shipment manifest number. SOD
3624 Unable to expand alias. SOD
3625 Unable to expand shipper alias. SOD
3626 Unable to update expanded shipper alias. SOD
3627 Unable to delete master shipper alias. SOD
3628 Unable to create points object. SOD
3629 Unable to get tariff destination from points object. SOD
3630 Unable to find your outbound SC-Code. SOD
3631 Unable to find shipper postal code. SOD
3632 Unable to encrypt install code. (internal error) SOD
3633 Error calling encrypt install code function. SOD
3634 Invalid install code. SOD
3635 Database error checking shipper. SOD
3636 Shipper does not exist in server. It needs to be added by the help desk. SOD
3637 Error generating site id. SOD
3638 Error getting info to generate site id. SOD
3639 Error adding new site code to database. SOD
3640 Internal error generating new site. SOD
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 130 of 166
Appendix D: Master API Error Code List
3641 Internal error generating new site code. SOD
3642 Internal error adding site to database. SOD
3643 Database returned error getting shipper site info. SOD
3644 Unable to add shipper to site. SOD
3645 Unable to update site information. SOD
3646 Database returned error getting site. SOD
3647 A system call to get time-zone information on the server failed. SOD
3648 Error creating shipper account. SOD
3649 The version of Gemini that was requested is not newer than the version already installed. SOD
3650 Database returned error code retrieving static shipper site. SOD
3651 Unable to update shipper site information. SOD
3652 Unable to update hazmat commodity information. SOD
3653 The latest version of Gemini is already installed. SOD
3654 Unable to update last download time. SOD
3655 An initialization error occurred on the server. SOD
3656 Database returned error while inserting consignee. SOD
3657 Unable to create temporary consignee. SOD
3658 Database returned error while updating consignee. SOD
3659 Gemini Server - Invalid Manifest XML SOD
3660 Gemini Server - Invalid Shipment XML SOD
3661 Gemini Server - Invalid Order XML SOD
3662 Gemini Server - Invalid Line item XML SOD
3663 Gemini Server - Invalid SLI XML SOD
3664 Gemini Server - Invalid SLI Line item XML SOD
3665 Unable to update your last connect to server time. SOD
3666 Error occurred allocating new shipment block range. SOD
3667 Error occurred allocating new manifest block range. SOD
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 131 of 166
Appendix D: Master API Error Code List
3668 Your current version is too old to update automatically. Please contact the Gemini Help Desk as soon as possible to update your Gemini.
SOD
3669 The server could not determine the base version. Please contact the Gemini Help Desk. SOD
3670 No shipments posted. SOD
3676 Unable to get requested shipper record. SOD
3677 No shipper data found for specified account number. SOD
3701 Unable to connect with database. Server Account
3702 No sites found. Server Account
3703 Unable to open box in AddFile. Server Account
3704 Internal error removing nulls from database output. Server Account
3733 Database returned error updating group relationships. Server Account
3734 Database returned error updating group relationship members. Server Account
3735 Database returned error updating site/group relationships. Server Account
3736 Database returned error updating group/file relationships. Server Account
3737 Cancelled Add File. Server Account
3738 Database returned error getting file. Server Account
3739 Database returned error trying to delete group. Server Account
3740 Unable to get Config data. Server Account
3741 Unable to create Config object. Server Account
3742 Added file not found. Server Account
3743 Database returned error while trying to insert file to be downloaded. Server Account
3744 Database returned error while trying to delete file to be downloaded. Server Account
3745 Database returned error while checking for file existence. Server Account
3746 Database returned error trying to update file information. Server Account
3747 Database returned error trying to get a group of files. Server Account
3748 Unable to init group information. Server Account
3749 Database returned error trying to retrieve group members. Server Account
3750 Database returned error trying to retrieve groups. Server Account
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 132 of 166
Appendix D: Master API Error Code List
3751 Database returned error trying to insert groups. Server Account
3752 Group member already exists. Server Account
3753 Group to delete not found. Server Account
3754 Database returned error deleting group. Server Account
3755 Database returned error updating group. Server Account
3756 Database returned error deleting group relationships. Server Account
3757 Group unable to be found in add to group. Server Account
3758 Database returned error inserting group. Server Account
3759 Database returned error deleting group relationships in remove from group. Server Account
3760 Database returned error trying to insert site. Server Account
3761 Database returned error trying to delete site. Server Account
3762 Site to delete not found. Server Account
3763 Database unable to delete site/group relationships. Server Account
3764 Database unable to delete site/Config relationships. Server Account
3765 Database returned error deleting site. Server Account
3766 Database returned error trying to update site. Server Account
3768 Database returned error getting groups of sites. Server Account
3769 Database returned error getting groups of files for site. Server Account
3770 Unable to get files for the group(s) attached to the site. Server Account
3771 Database returned error trying to get file information for group. Server Account
3772 Unable to get sub groups of the group you selected. Server Account
3773 Database returned error trying to add shipper to site. Server Account
3774 Shipper site not found. Server Account
3775 Database returned error during insert of shipper site. Server Account
3776 Database returned error remove shipper/site relationship. Server Account
3777 Unable to get subgroups of group. Server Account
3778 Database returned error trying to get sites using group. Server Account
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 133 of 166
Appendix D: Master API Error Code List
3779 No sites are using the specified group. (This is ok but the group is serving no purpose at the moment.)
Server Account
3780 Unable to get groups using file. Server Account
3781 Unable to get sites using group. Server Account
3782 Database returned error getting group. Server Account
3783 Database returned error getting group. Server Account
3784 Unable to get parent groups of group. Server Account
3785 Site not found. Server Account
3786 Database returned error trying to remove site from group. Server Account
3788 Internal code told to remove a site from group when the site was not a member of that group. Server Account
3789 Database returned error trying to remove from group. Server Account
3790 Item specified to remove from group is not in group. Server Account
3791 Database returned error trying to insert site to group. Server Account
3792 No shippers using site. (Ok but site is not doing anything.) Server Account
3793 Database returned error getting shippers using site. Server Account
4101 No Shipments/Orders were found for the manifest requested. AR Manifest
4102 Unable to get orders for this manifest from database. AR Manifest
4103 Unable to get shipper information from the database. AR Manifest
4104 Unable to update the manifest print date in the database. AR Manifest
4105 AdErrorLoadReport AR Manifest
4106 Error printing Manifest detail page. AR Manifest
4107 Unable to get Consignee info from database. AR Manifest
4108 Unable to get service summary. AR Manifest
4109 Unable to get manifest summary. AR Manifest
4110 Unable to get manifest shipments. AR Manifest
4111 Unable to get manifest shipment sum from database. AR Manifest
4112 Unable to get manifest order sum from database. AR Manifest
4113 Unable to get manifest items from database. AR Manifest
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 134 of 166
Appendix D: Master API Error Code List
4114 Unable to update print date in database. AR Manifest
4115 Unable to determine whether metered invoice should be printed. AR Manifest
4116 Unable to print manifest summary page. AR Manifest
4117 Unable to print manifest invoice page. AR Manifest
4118 Error creating manifest invoice. AR Manifest
4119 Error getting Config data to determine if shipper ref prints. AR Manifest
4120 AdErrorShipRefOnInvoice AR Manifest
4121 DB error getting cancelled shipments for manifest. AR Manifest
4122 DB error getting cancelled orders for manifest. AR Manifest
4123 DB error getting cancelled line items for manifest. AR Manifest
4124 Unable to print detail of cancelled shipments. AR Manifest
4125 DB error getting order data for service summary. AR Manifest
4126 DB error getting order level manifest summary data. AR Manifest
4127 There were no shipments found for this manifest. AR Manifest
4128 There were no cancelled shipments found for this manifest. AR Manifest
4129 AdErrorBadaryError AR Manifest
4130 User cancelled the manifest print. AR Manifest
4131 Passed-in default printer name not found in printer list! AR Manifest
4132 Unable to display list of available printers. Please make sure a printer is installed on this system. AR Manifest
4133 Unable to get GPC_Rating data from database. AR Manifest
4134 Unable to open file for CSV report. AR Manifest
4135 Error Opening XML File to extract manifest data. AR Manifest
4136 AdErrorGetCommonData AR Manifest
4137 Unable to create Base64 Encoding object. AR Manifest
4138 Unable to Base64 Encode Manifest. AR Manifest
4139 Unable to create UTL PDF object. AR Manifest
4140 UTL PDF object failed to create PDF Manifest. AR Manifest
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 135 of 166
Appendix D: Master API Error Code List
4141 Unable to set printer. Determine if the machine performing the printing has network access to the printer.
AR Manifest
4142 Unable to create MS XML DOM object. Confirm XSXML 2.0 or greater is installed. AR Manifest
4143 No shipments were found at this time to complete an Interim Manifest. AR Manifest
4144 The output format selected for this manifest is currently not supported. AR Manifest
4145 The destination type selected for this manifest is currently not supported. AR Manifest
4146 Problem encountered attempting to create XML data manifest. AR Manifest
4147 Unable to build Shipment Detail portion of XML data for manifest return. AR Manifest
4148 Unable to build Shipment Summary portion of XML data for manifest return. AR Manifest
4149 Unable to build Shipment Invoice portion of XML data for manifest return. AR Manifest
4151 The Free Adobe Acrobat Reader version 5.0 or greater is required to print PDF documents. You can download the installation program for this application from www.adobe.com.
AR Manifest
4152 Please close file and attempt to print again. AR Manifest
4153 Error Creating CSV Manifest AR Manifest
4154 Unable to build Shipment Detail portion of CSV data for manifest return. AR Manifest
4155 Unable to build Shipment Summary portion of CSV data for manifest return. AR Manifest
4156 Unable to build Shipment Invoice portion of CSV data for manifest return. AR Manifest
4199 Unexpected error occurred while creating manifest. AR Manifest
4201 Unable to get dangerous goods info from database. AR Hazmat
4202 Unable to get dangerous goods commodity info from database. AR Hazmat
4203 Unable to get shipper record from database. AR Hazmat
4205 Unable to load report. AR Hazmat
4206 Unable to print report. AR Hazmat
4207 Unable to get consignee. AR Hazmat
4208 Unable to get shipper reference number from database. AR Hazmat
4209 Unable to update dangerous goods print date in database. AR Hazmat
4210 AdErrorDBInsertHazmat AR Hazmat
4301 Unable to get Shipment from GP_SHIPMENT table. AR SLI
4302 Status of Shipment must be at least /Labeled/ to print. AR SLI
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 136 of 166
Appendix D: Master API Error Code List
4303 Unable to retrieve Order summary information. AR SLI
4304 Unable to get Order. AR SLI
4305 Unable to get Items. AR SLI
4306 Unable to get Service Code from GP_STATIC_SERVICE table. AR SLI
4307 Unable to get Shipper. AR SLI
4308 Unable to get Consignee. AR SLI
4309 Unable to get Third Party. AR SLI
4310 Unable to update Print Date for SLI. AR SLI
4311 Unable to get SLI info from GP_SLI. AR SLI
4312 SLI Line Items are required. AR SLI
4314 AdErrorDBGetCountryName AR SLI
4315 SLI Print Job cancelled by user. AR SLI
4316 SLI Print Job cancelled by user. AR SLI
4317 Unable to display list of available printers. Please make sure a printer is installed on this system. AR SLI
4318 Unable to print document. Please call Gemini Help Desk for assistance. AR SLI
4319 Unable to print document. Please call Gemini Help Desk for assistance. AR SLI
4321 Unable to print document. Please call Gemini Help Desk for assistance. AR SLI
4322 Please close any open PDF files and attempt to print again. AR SLI
4323 Please close any open PDF files and attempt to print again. AR SLI
4324 Please close any open PDF files and attempt to print again. AR SLI
4410 Fabio Error - Unable to write shipments to file. End Of Day
4500 Had an unhandled error. Shipment
4501 Customs value must be greater than or equal to 1 when currency is USD. Shipment
4502 Failed to get shipment number. Shipment
4503 Failed to get a new order number. Shipment
4504 Failed to check shipment consolidation. Shipment
4505 Could not access Consignee component. Shipment
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 137 of 166
Appendix D: Master API Error Code List
4506 Could not access Shipper component. Shipment
4507 Could not access Points component. Shipment
4508 Description is required for current shipper. Shipment
4509 Failed to delete old shipment number. Shipment
4510 Failed to save shipment. Shipment
4511 Failed to insert the order record. Shipment
4512 Failed to save rate data. Shipment
4513 Failed to delete existing items. Shipment
4514 Failed to insert rates. Shipment
4515 Update failed. Shipment
4516 Failed to insert rate detail. Shipment
4517 Failed to delete rate detail. Shipment
4518 Failed to save default settings. Shipment
4519 Failed to insert the dimensions. Shipment
4520 Could not find the record. Shipment
4521 Could not get new shipment number. Shipment
4522 Numbers not allocated yet. Shipment
4523 Is out of shipment numbers. Shipment
4524 Failed to find shipper. Shipment
4525 Unable to create Utility component. Shipment
4526 Failed to find order. Shipment
4527 Failed to get item. Shipment
4528 Could not process parameters. Shipment
4529 Has invalid value array. Shipment
4530 Ship date is not a valid date. Shipment
4531 Ship date does not equal current system date. Shipment
4532 Description is required. Please enter a description. Shipment
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 138 of 166
Appendix D: Master API Error Code List
4533 High value authorization code is required for insured values greater than or equal to 500 000 USD.
Shipment
4534 Insured value must be less than 10 000 000 USD. Shipment
4535 Insurance value must be greater than 0 of the specified insurance value currency. Shipment
4536 High value authorization code is required for declared values greater than 25 000 USD. Shipment
4537 Declared value must be less than or equal to 100 USD for this product. Shipment
4538 Customs value is required to this location. Please enter a customs value. Shipment
4539 Customs value must be greater than 0 of the specified customs value currency. Shipment
4540 Consignee contact name and phone required for HAPU. Shipment
4541 Saturday delivery only allowed on Friday shipments. Shipment
4542 GOLD Priority service is not available. Shipment
4543 Remarks to consignee (text) is required. Shipment
4544 When hazardous material is selected, an aircraft type must be specified. Please specify an aircraft type.
Shipment
4545 Total shipment piece count must be less than 100,000. Shipment
4546 Total weight must be greater than or equal to 1lb. or .1 kg. Shipment
4547 Total shipment weight cannot exceed 99,999 LBS. Shipment
4548 Consignee does not exist. Shipment
4549 Euro 48 service is not available. Shipment
4550 Saturday delivery is not available for international shipments. Shipment
4551 Saturday pickup is not available for international shipments. Shipment
4552 Third party billing account is missing or invalid. Shipment
4553 Gold authorization code is required for this service. Shipment
4554 Gold authorization code is required for this service. Shipment
4555 Gold services only available for contiguous 48 states. Shipment
4556 Liftgate required is not available for international shipments. Shipment
4557 Product must be freight for Ground service. Shipment
4558 Ground service only available for contiguous 48 states. Shipment
4559 Total piece count must be greater than 0. Shipment
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 139 of 166
Appendix D: Master API Error Code List
4560 Line item piece count must be less than 1,000. Shipment
4561 Dim length must be greater than 0. Shipment
4562 Dim width must be greater than 0. Shipment
4563 Dim height must be greater than 0. Shipment
4564 Two man delivery is not available for international shipments. Shipment
4565 Gold authorization code is not valid. Shipment
4566 When hazardous material is selected, payment type must be Prepaid. Shipment
4567 The current shipper is not authorized to ship hazardous material. Shipment
4568 Inside delivery is not available for international shipments. Shipment
4569 High value authorization code is not valid. Shipment
4570 Delivery to door is only available for international shipments. Shipment
4571 Economy service is not available. Shipment
4572 Shipment number is not valid. Shipment
4573 Account number is not valid. Shipment
4574 AM service not available. Shipment
4575 Service Code 2 is invalid. Shipment
4576 Gold Priority AM service not available. Shipment
4577 Second Day service not available. Shipment
4578 Gold P Second Day service not available. Shipment
4579 Free Domicile is not available to this location. Shipment
4580 Gold P Deferred service not available. Shipment
4581 Gold P Daylight service not available. Shipment
4582 Gold Priority Plus service not available. Shipment
4583 Express CX service not available. Shipment
4584 Customs value exceeds Express Service limit. Shipment
4585 Weight exceeds Express Service limit. Shipment
4586 Preferred CA service not available. Shipment
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 140 of 166
Appendix D: Master API Error Code List
4587 Standard EC service not available. Shipment
4588 Standard Plus XE service not available. Shipment
4589 Standard with Delivery service not available. Shipment
4590 Standard with Delivery Clearance service not available. Shipment
4591 Standard with Clearance service not available. Shipment
4592 Preferred with Delivery service not available. Shipment
4593 Preferred with Delivery Clearance service not available. Shipment
4594 Preferred with Clearance service not available. Shipment
4595 Next Day service is not available. Please select another service. Shipment
4596 Guaranteed Ground service is not available. Shipment
4597 Saturday Delivery service not available. Shipment
4598 09:30 service not available. Shipment
4599 09:30 service is not available to this point. Shipment
4600 Had an unhandled error. Postal
4601 Failed to connect to the USPS database. Postal
4610 Could not access the Utility component. Postal
4611 Could not find a USPS drop location. Postal
4612 Failed to generate USPS tracking number. Postal
4613 Failed to access USPS drop address. Postal
4710 Got a bad shipper account. Gem IUSPS
4711 Failed to access Shipment component. Gem IUSPS
4712 Failed to access Shipper component. Gem IUSPS
4713 Could not find Shipper information. Gem IUSPS
4714 Failed to access Consignee component. Gem IUSPS
4715 Could not find Consignee information. Gem IUSPS
4716 Failed to access Service Points component. Gem IUSPS
4717 Failed to access Label Printing component. Gem IUSPS
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 141 of 166
Appendix D: Master API Error Code List
4718 Failed to access Client component. Gem IUSPS
4719 Failed to access Manifest component. Gem IUSPS
4720 Failed to access Order component. Gem IUSPS
4721 Could not enumerate shipments. Gem IUSPS
4722 Cannot reprint labels for shipments that have not previously been labeled. Gem IUSPS
4723 Failed to access Postal component. Gem IUSPS
4724 Could not understand Date format. Gem IUSPS
4725 Could not call Label Printing component. Gem IUSPS
4800 Had an unhandled error. Data Kernel
4801 Could not create DataKernel. Data Kernel
4802 Could not open database connection. Data Kernel
4803 Database error has occurred Beginning Transaction Data Kernel
4804 Database error has occurred Committing Transaction Data Kernel
4805 Database error has occurred Rolling Back Transaction Data Kernel
4810 Could not execute SQL query. Data Kernel
4820 An error occurred while initializing the database backup/restore. Data Kernel
4821 An error occurred while performing the database backup. Data Kernel
4822 An error occurred while retrieving the database name during the database backup/restore. Data Kernel
4823 An error while trying to set the Gemini database access to single_user. Data Kernel
4824 An error while detaching the Gemini database to perform backup/restore. Data Kernel
4825 An error while building the backup file names during database backup/restore. Data Kernel
4826 An error while copying the database during database backup/restore. Data Kernel
4827 An error while restoring the Gemini database. Data Kernel
4828 An error while trying to remove the existing database during database restore. Data Kernel
4829 An error while re-attaching the Gemini database during backup/restore. Data Kernel
4830 Could not update ADO batch. Data Kernel
4831 An error while retrieving the database file paths during backup/restore. Data Kernel
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 142 of 166
Appendix D: Master API Error Code List
4832 Could not connect to Gemini database to perform backup/restore. Data Kernel
4833 An error occurred while retrieving the requested database backup files. Data Kernel
4834 Error in backup/restore. An invalid network path was given. Data Kernel
4835 Error in backup/restore. An invalid backup file name or path was given. Data Kernel
4836 Error occurred in SuggestFileName routine. Data Kernel
4837 This backup filename already exists. Please use another backup filename. Data Kernel
4839 Gemini database files that are being backed up and restored must end in .mdf. Please check that this is the correct database file to restore.
Data Kernel
4850 Could not set stored procedure parameter. Data Kernel
4851 Could not execute stored procedure. Data Kernel
4852 Could not read stored procedure /out/ parameter. Data Kernel
5001 AdWarningRecordsetEOF Interface
5002 AdWarningConsolidationIsOn Interface
5003 AdErrorDBConnect Interface
5004 AdErrorCreateManifestObject Interface
5005 AdErrorCreateClientObject Interface
5006 AdErrorCreateReportsObject Interface
5007 AdErrorCreateConfigObject Interface
5008 AdErrorCreateShipperObject Interface
5009 Unable to retrieve a country name for the code supplied. Interface
5013 AdErrorCreateEWW_GEM_SHIPMENTObject Interface
5014 AdErrorCreateLabelPrinter Interface
5015 AdErrorCreateLabelPrinter Interface
5016 AdErrorCreatingScaleObject Interface
5017 AdErrorCreateCustomerProxy Interface
5019 AdErrorUpdateIsInvoicedIndFailed Interface
5020 AdErrorBadValueArray Interface
5021 AdWarningUploadToServerFailed Interface
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 143 of 166
Appendix D: Master API Error Code List
5022 AdErrorInvalidGeminiSiteCode Interface
5023 The production database does not appear to be attached to SQL Server. Interface
5024 The test database does not appear to be attached to SQL Server. Interface
5025 The demo database does not appear to be attached to SQL Server. Interface
5027 An error occurred trying to update the shipment ship date. Interface
5030 AdErrorGetNextConsignee Interface
5036 This order was successfully saved. An error occurred while printing label(s). If label format is .pdf, close Adobe window and print label from the History screen.
Interface
5037 AdErrorBadParam Interface
5038 Shipment number is not valid. Interface
5039 Shipment number is not valid for this order due to consolidation restrictions. Interface
5046 AdErrorGetNextProduct Interface
5048 AdErrorGetNextService Interface
5050 AdErrorGetNextPayment Interface
5051 AdErrorGetNextCurrency Interface
5052 AdErrorGetNextCountry Interface
5053 AdErrorInvalidOrderNumber Interface
5054 AdCantCreatePointsComponent Interface
5055 AdErrorBadRateArray Interface
5056 AdInvalidPaymentType Interface
5057 AdInvalidService Interface
5058 AdErrorArray Interface
5059 AdErrorBadRateOCCostArray Interface
5060 AdErrorCreatingRatingObject Interface
5061 AdErrorBadRateOCCodeArray Interface
5062 AdErrorGetNextMassDistList Interface
5063 AdErrorGetNextCommodityGroupList Interface
5064 AdErrorGetNextListOfCommoditiesForGroup Interface
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 144 of 166
Appendix D: Master API Error Code List
5065 AdErrorGetNextEOD Interface
5066 AdErrorGetNextHistory Interface
5067 AdErrorGetNextMassDistLoad Interface
5068 AdErrorGetNextShipper Interface
5069 AdErrorGetNextSliLineGroup Interface
5070 Error retrieving SLI Line Item. Interface
5071 AdErrorSliCreateArrays Interface
5072 AdErrorGetNextCostCenter Interface
5073 Unable to print label because of invalid destination. Please check hardware settings for labels and attempt to reprint.
Interface
5074 Unable to print label because a printer name was not supplied. Interface
5075 This order cannot be labeled because it is cancelled or not found. Interface
5076 Only shipments from today can be labeled. Interface
5080 Problems getting GP_SHIPPER record from gemsp_GetShipper Interface
5081 Problems creating Microsoft XML Parser. Interface
5082 Problems getting E2K Service Code from gemsp_GetE2KServiceCode Interface
5083 Problems getting E2K Payment Term Code from gemsp_GetE2KPaymentTermCode Interface
5084 Problems getting E2K Package Type Code from gemsp_GetE2KPackageTypeCode Interface
5085 Problems determining the correct E2K Commodity Code Interface
5086 Problems getting Origin or Destination tariff point from pointscall() Interface
5087 Problems getting GP_CONSIGNEE record from gemsp_GetConsignee Interface
5088 Problems creating the Pieces segment of XMLDOM Interface
5089 Problems creating the Charges segment of XMLDOM Interface
5090 Problems reading registry value LOG_E2K_CALLS Interface
5091 Problems creating EWW_RAT_Proxy.CEWWRATProxy object Interface
5092 Problems calling GetRateQuote() Interface
5093 Problems unpacking XML results from E2K Rating call Interface
5094 Problems creating the IndicatorCodes segment of XMLDOM Interface
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 145 of 166
Appendix D: Master API Error Code List
5095 Unable to retrieve a rate for this shipment Interface
5096 Offline rating is only available for values declared in US Dollars. Interface
5097 An error has occurred in the temporary work area for order save. Please submit your order data again. If the same error re-occurs, contact the Gemini Help Desk.
Interface
5098 An error has occurred in the temporary work area for order save. Please submit your order data again. If the same error re-occurs, contact the Gemini Help Desk.
Interface
5099 An unexpected error occurred. If this continues, please contact the Gemini Help Desk. Interface
5200 Express Document service is not available. Shipment
5201 Failed to get open shipments. Shipment
5202 Description cannot equal FREIGHT ALL KINDS, FAK, PARTS, VARIOUS, STUFF, MULTIPLE, GENERAL FREIGHT, GENERAL CARGO, THING, THINGS, MISC, or MISCELLANEOUS.
Description must be more specific.
Shipment
5203 Failed to get unprinted SLI list. Shipment
5204 Failed to get shipments to post. Shipment
5205 Failed to delete rate. Shipment
5206 Failed to insert rate. Shipment
5207 Failed to delete rate detail. Shipment
5208 Failed to insert rate detail. Shipment
5209 Failed to update shipment rate. Shipment
5210 This destination cannot be Saturday Delivery unless HAPU (Hold at Airport for Pick-Up) is selected. You must select special instruction HAPU or select a different service type.
Shipment
5211 Saturday delivery only available when the shipdate is a Friday. Shipment
5212 Declared value must be numeric and greater than or equal to 0. Shipment
5213 International shipments must have either a declared value or insured value. Shipment
5214 Could not access Interface component. Shipment
5215 Total Weight exceeds 500 LBS. Shipment
5216 Dim Height is oversized. Shipment
5217 Dim Width is oversized. Shipment
5218 Dim Length is oversized. Shipment
5219 Found no Shipments. Shipment
5220 Ship date is later than the current system date. Shipment
5221 Payment type selected is not valid. Shipment
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 146 of 166
Appendix D: Master API Error Code List
5222 Description must begin with a letter A=Z or a number. Shipment
5223 Third party country must be US, CA or Puerto Rico when shipment is US, CA or Puerto Rico. Shipment
5224 When hazardous material is selected for this destination, service type must be Standard or Mexico Economy.
Shipment
5225 Failed to save insured value to database. Shipment
5226 Failed to save insured value to database. Shipment
5227 Service is not defined. Shipment
5228 Product is not defined. Shipment
5229 Selected service is not allowed with hazardous materials shipments. Only AM and Next Day services are allowed with hazardous materials. Saturday Delivery service is allowed when
shipping on Fridays.
Shipment
5230 Delivery Deadline is invalid. Shipment
5231 Delivery Deadline is invalid. Shipment
5232 Collect shipments are not allowed with this service and destination. Shipment
5233 Collect shipments are not allowed with this service and destination. Shipment
5234 AdErrorValidateAryVals Shipment
5235 Contact Name and Contact Phone required on Notify On Arrival shipments. Shipment
5236 Check To Shipper cannot exceed 50,000 USD Shipment
5237 Country of Origin is required for Canadian consignees. Shipment
5238 Unable to validate tariff destination and/or city of destination. Shipment
5240 Economy Service is not allowed between these points. Please select another service. Shipment
5241 Inside Delivery, Two Man Delivery and Delivery To Door are not allowed when HAPU is selected. Shipment
5242 Piece weights are required when total weight not entered. Shipment
5243 Only ten items are allowed per order. Shipment
5244 Error occurred saving default field skip values. Shipment
5245 Rating is not available for the payment type selected. Shipment
5246 An error occurred checking default field skip values. Shipment
5247 Shipper is not authorized for COMAT payment type. Shipment
5248 Confirmed Delivery service is not available for international shipments. Shipment
5249 Notify on Arrival is only available for domestic shipments. Shipment
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 147 of 166
Appendix D: Master API Error Code List
5250 Country of Original Manufacture is invalid. Shipment
5251 Collect payment type is not allowed with this service. Shipment
5252 Free Domicile is not available with this payment type. Shipment
5253 Declared value currency code is invalid. Shipment
5254 Insured value currency code is invalid. Shipment
5255 Customs value currency code is invalid. Shipment
5256 Check to shipper currency code is required. Shipment
5257 This product type is not available to the current destination. Shipment
5258 An error has occurred cleaning up the temporary work area. Please call the Gemini Help Desk. Shipment
5259 Error Checking if shipment is international. Shipment
5260 Error occurred validating product. Shipment
5261 Error Setting the Total Weight. Shipment
5262 Rating for this service is not supported. Shipment
5263 Rating from your location is not supported. Shipment
5264 Error occurred getting shipment number. Shipment
5265 Error occurred getting order status. Shipment
5266 Error occurred getting shipment status. Shipment
5267 Error occurred updating shipment status. Shipment
5268 Error occurred updating order status. Shipment
5269 Error occurred returning status code. Shipment
5270 Declared Value must be less than 3,000,000 USD. Shipment
5271 Shipment number is not valid for this order due to consolidation restrictions. Shipment
5272 Consolidation of this order has created a total declared value which requires an authorization code. High value authorization code is required for declared values greater than or equal to 25,000 USD.
Shipment
5273 Consolidation has created an Insurance Value over 500,000 USD which requires an authorization code.
Shipment
5274 Whole number required for piece count. Shipment
5275 One or more open orders are consolidated with labeled orders. These open orders must be labeled, postponed or canceled before processing shipments.
Shipment
5276 A maximum of one item is allowed for the current product selected. Shipment
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 148 of 166
Appendix D: Master API Error Code List
5277 Shipments with a Declared Value greater than or equal to 25,000 USD are not allowed in Mass Distributions.
Shipment
5278 Shipments with an Insurance Value greater than or equal to 500,000 USD are not allowed in Mass Distributions.
Shipment
5279 Insurance value must be greater than or equal to 1 when currency code is USD. Shipment
5280 NCV is not a valid currency code when shipping to or from the United States, Canada or Australia.
Shipment
5281 A city name is required for the consignee provided. Shipment
5282 A postal code is required for the consignee provided. Shipment
5283 Check To Shipper is not allowed for shipments outside of the United States and Canada. Shipment
5284 Insured Value is not allowed for intra United States/Canada shipments. Shipment
5285 Customs Value is not allowed for intra United States shipments (except Puerto Rico). Shipment
5286 Unable to recreate Ifer5 disk. Error retrieving item information. Shipment
5287 Unable to recreate Ifer5 disk. Error retrieving export document information. Shipment
5288 Unable to recreate Ifer5 disk. Error retrieving export document line item information Shipment
5289 Unable to recreate Ifer5 disk. Error retrieving HAZMAT information. Shipment
5290 Unable to recreate Ifer5 disk. Error retrieving HAZMAT item information. Shipment
5291 Unable to recreate Ifer5 disk. Error retrieving shipment information. Shipment
5292 Unable to recreate Ifer5 disk. Error retrieving order information. Shipment
5293 An error occurred while getting default values. Shipment
5294 An error occurred while getting default values. Shipment
5295 An error occurred while saving default settings. Shipment
5296 No default settings found. Shipment
5297 Check To Shipper can only be declared as Canadian or US Dollars. Shipment
5298 Customs value currency code NCV is not allowed when a value greater than 0 is entered. Shipment
5299 Had an unknown error. Shipment
5301 Invalid Input Format Gemini API
5302 Invalid XML Gemini API
5303 Invalid Command Gemini API
5304 Security Failed - Invalid User/Password Gemini API
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 149 of 166
Appendix D: Master API Error Code List
5305 Invalid CSV Gemini API
5306 Unable to Load XML Template File Gemini API
5307 Order not found Gemini API
5308 Shipment not found Gemini API
5309 Order does not belong to shipper Gemini API
5310 Shipment does not belong to shipper Gemini API
5311 Security Failed - User does not have access rights for this shipper Gemini API
5312 Invalid Label Format Gemini API
5313 Invalid Password Gemini API
5314 Cannot connect to security (LDAP) server. Contact the Help Desk. Gemini API
5315 User not found on security (LDAP) server. Contact the Help Desk. Gemini API
5316 Unknown security (LDAP) server error. Contact the Help Desk. Gemini API
5317 Gemini Updates are not allowed on this computer. Gemini API
5318 Security Failed - User/Shipper does not have rights in this region. Gemini API
5319 Order Search requires at least one set of criteria. Gemini API
5320 No matching shipment data found. Gemini API
5321 Order Search failed. Gemini API
5322 Invalid Date passed to OrderSearch. Gemini API
5323 Invalid Order Search Criteria Field Gemini API
5324 Unable to retrieve shipper information. Gemini API
5325 A city name is required for destinations outside the United States and Canada. Gemini API
5326 A Postal Code is required for destinations in the US and Canada. Gemini API
5327 A Major Airport City is required for the requested destination. Gemini API
5328 Major Airport City search only available for locations outside the United States and Canada. Gemini API
5329 A valid Country Code is required. Gemini API
5330 No Matching Cities were found in search. Gemini API
5331 City Name is required for search. Gemini API
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 150 of 166
Appendix D: Master API Error Code List
5332 Invalid Shipper Account Number Gemini API
5333 Like searches for city data are only available for locations outside the United States and Canada. Gemini API
5334 Security does not appear to be active on this server. Gemini API
5335 Consignee Search requires at least one set of criteria. Gemini API
5336 No matching consignee(s) found. Gemini API
5337 Invalid Consignee Search criteria field. Gemini API
5338 Invalid Consignee Search criteria operator. Gemini API
5339 Command is not enabled at this time. Gemini API
5340 Order cannot be updated. Order Status must be equal to Open, Labeled, or Closed. Gemini API
5341 The search parameter(s) provided returned over 5000 orders. Please change the parameter(s) to narrow your search return.
Gemini API
7000 Contact name and phone number are required when Check To Shipper amount is greater than 0. Shipment
7001 Confirm Delivery is no longer supported. Please contact the Gemini Help Desk or your local service center for other arrangements.
Shipment
7002 The order you are attempting to update is already posted and therefore closed to changes Shipment
7003 Invalid contact phone number. Phone number format must be ###-###-####. Shipment
7004 Order rejected because a previously submitted order with the same shipper reference value exists.
Shipment
7005 Order rejected because a previously submitted order with the same consignee reference value exists.
Shipment
7006 Dimensional values cannot exceed 300in (762cm). Shipment
7007 Dimensional values cannot exceed 300in (762cm). Shipment
7008 Dimensional values cannot exceed 300in (762cm). Shipment
7009 Length of Shipper Reference field is less than Default for this shipper. Shipment
7010 HAPU is not allowed with this Service. Shipment
7011 Guaranteed Express Freight Service is not allowed between these points. Please select another service.
Shipment
7012 You must select HAPU to receive guaranteed service outside the guaranteed area. Shipment
43013 AdWarningGetDestinationZipTableLookup Internal
43016 AdWarningUserCancelled Internal
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 151 of 166
Appendix E: Error Groups Following is a summary of the error code categories. The error code categories correspond to the errors that each command may return.
MIN error # MAX error # Error Group Description
100 499 Shipment
900 999 Utility
1000 1099 Consignee
1100 1199 Mass Dist
1200 1299 Commodity
1300 1399 Shipper
1400 1499 Order
1500 1599 Order
1600 1799 Label Printer
1800 1899 Points
1900 1999 Rate
2300 2399 End Of Day
2400 2499 Scale
2500 2599 SOD
2600 2699 Config
2700 2799 Static Data
2800 2899 SLI
2900 2999 Registry Manager
3300 3399 Import Export
3500 3599 End Of Day
3600 3699 SOD
3700 3799 Server Account
4100 4199 AR Manifest
4200 4299 AR Hazmat
4300 4399 AR SLI
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 152 of 166
Appendix E: Error Groups
4400 4499 End Of Day
4500 4599 Shipment
4600 4699 Postal
4700 4799 Gem IUSPS
4800 4899 Data Kernel
5000 5099 Interface
5200 5299 Shipment
5300 5399 Gemini API
7000 7099 Shipment
43000 43100 Internal
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 153 of 166
Appendix F: Java Coding Examples and Class Definitions
The Java API for Gemini allows you to make calls to the Gemini SOAP server from Java. This allows for platform compatibility, especially in the Unix environment. The API consists primarily of three major classes:
• WebServiceClient
• GeminiSOAPClient
For making the SOAP calls to the Gemini SOAP server, the API makes use of the WASP API from SystiNet. However, you only need to make a few calls, so this section just outlines WASP. For more information on WASP, consult the API documentation for WASP.
This section demonstrates and instructs in the use of the Java API of Gemini, not the Gemini API in general. Neither does it address what comprises a valid XML message to send to the SOAP server. Those topics are covered in other sections of this document.
WebServiceClient
The WebServiceClient class is a basic command line demonstrating how to use the XmlValidator and the GeminiSOAPClient. You have the option of passing XML either to the XmlValidator, for checking XML against a schema, or to the Gemini SOAP server, for verifying connection status and XML validity against a schema.
Sending and Validating XML
To validate XML, you start the application and pass at least one of two arguments. The first argument is required. This argument is the path of the XML file that you want to validate. The second argument is either LOCAL or SOAP. This argument instructs the client to validate the XML with the SOAP server or to use the local validator classes. The default for the second argument is LOCAL.
Once the client has finished the validation check, it prints the results to the screen. For the SOAP server, the result is the message that the server returns. For the local validator, the result is either an error message or a message stating, “Document is valid.”
In order for schema validation to work, the XML file must point to a valid schema by using either the schemaLocation property or the noNamespaceSchemaLocation property in the XML file.
Installation and Startup
To install the class files, place the following JAR files on your class path and the JDK 1.3:
• GeminiJavaAPI.jar
• xerces.jar
• dom4j.jar
• wasp.jar
• debug.jar • BCEL.jar
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 154 of 166
Then, assuming the location of your java.exe file is in your PATH environment variable, the following line of code on the command line or in a script file will validate an XML file.
java SystiNetClient.WebServiceClient
C:\\UPS\\Gemini\\OrderCancel.xml SOAP
Note: In order to use the SOAP server validation, you must correctly configure the
geminiSoap.properties file correctly. See the GeminiSOAPClient section on for a
description.
GeminiSOAPClient
The GeminiSOAPClient allows you to pass an XML string to a SOAP server. Then it returns any response from the server in the form of an XML-formatted message. You use the geminiSOAP properties file to configure the client. The contents of the file are as follows:
• serviceHost=Host URL (Ex. http://mwa66a05/soaplisten)
• servicePage=page location for the SOAP server if necessary (Ex. /GeminiWeb.asp)
• wsdlURL=Location of the wsdl file.This is either a url or a file location.
(Ex. file:\\JavaStuff\\sampledir\\SystiNetClient\\GeminiWeb.wsdl)
Following is a sample of the GeminiSOAPClient code.
GeminiSOAPClient soapClient = new
GeminiSOAPClient(); String xml = someXML;
String result = soapClient.GeminiExecute(xml);
JAVA Class Definitions
Class/Interface Definition
actionPerformed(ActionEvent) public void actionPerformed(java.awt.event.ActionEvent actionEvent)
Method in class SystiNetClient.WebServiceClient. Specified by: actionPerformed in interface java.awt.event.ActionListener
Browse javax.swing.JButton browse
Serialized field.
Chooser javax.swing.JFileChooser chooser
Serialized field. Button for executing a call.
Execute javax.swing.JButton execute
Serialized field. Button for displaying the file selection dialog.
fileLocation javax.swing.JTextField fileLocation
Serialized field. File chooser.
GeminiExecute(String) public java.lang.string GeminiExcecute(java.lang.String xml) Method in class
EmeryXmlValidator.XmlValidator. Emulates the call made to Gemini module using
SOAP. Parses XML passed in to method to validate that it is correct. XML message should point to a valid XML schema: the schemaLocation property or the noNamespaceSchemaLocation property. Specified by:
GeminiExecute in interface SystiNetClient.iface.CinterfaceSoapPort
Main(String[]) public static void main (java.lang.String[] argv)
Static method in class EmeryXmlValidator.XmlValidator. Exists so validator can run from command line. Parses and validates a single argument that is the location of the XML file. Argument can be a file location or URL.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 155 of 166
Main(String[]) public static void main(java.lang.String[] args) throws
java.lang.Exception
Static method in class SystiNetClient.WebServiceClient. No arguments passed for starting the program.
Messages javax.swing.JTextArea messages
Serialized field. Text box displaying path and file name of selected file.
msgReceiver Int msgReceiver
Serialized field. Static value for validator.
radioSOAP javax.swing.JRadioButton radioSOAP
Serialized field. Radio button for XmlValidator call.
radioVal javax.swing.JRadioButton radioVal
Serialized field. Text area displaying return messages.
readFile(String) public static java.lang.String readFile (java.lang.String filePath)
Static method in class EmeryXmlValidator.XmlValidator. Used to read XML from a file. XML returned to calling method as a string.
RECEIVER_SOAP public static int RECEIVER_SOAP
Static variable in class SystiNetClient.WebServiceClient.
RECEIVER_VALIDATOR public static int RECEIVER_VALIDATOR
Static variable in class SystiNetClient.WebServiceClient. Static value for SOAP.
soapClient SystiNetClient.GeminiSOAPClient soapClient
Serialized field.
Validator EmeryXmlValidator.XmlValidator validator
Serialized field. Indicates where to pass the XML: to SOAP server or validator.
WebServiceClient Class SystiNetClient.WebServiceClient.
WebServiceClient() public WebServiceClient()
Constructor for class SystiNetClient.WebServiceClient. Radio button for SOAP call.
windowActivated(WindowEvent) public void windowActivated(java.awt.event.WindowEvent windowEvent)
Method in class SystiNetClient.WebServiceClient. Specified by: windowActivated in interface java.awt.event.WindowListener
windowClosed(WindowEvent) public void windowClosed(java.awt.event.WindowEvent windowEvent)
Method in class SystiNetClient.WebServiceClient. Specified by: windowClosed in
interface java.awt.event.WindowListener
windowClosing(WindowEvent) public void windowClosing(java.awt.event.WindowEvent windowEvent)
Method in class SystiNetClient.WebServiceClient. Specified by: windowClosing in interface java.awt.event.WindowListener
windowDeactivated(WindowEvent) public void windowDeactivated(java.awt.event.WindowEvent windowEvent)
Method in class SystiNetClient.WebServiceClient. Specified by: windowDeactivated in interface java.awt.event.WindowListener
windowDeiconified(WindowEvent) public void windowDeiconified(java.awt.event.WindowEvent windowEvent)
Method in class SystiNetClient.WebServiceClient. Specified by: windowDeiconified in interface java.awt.event.WindowListener
windowIconified(WindowEvent) public void windowIconified(java.awt.event.WindowEvent windowEvent)
Method in class SystiNetClient.WebServiceClient. Specified by: windowIconified in interface java.awt.event.WindowListener
windowOpened(WindowEvent) public void windowOpened(java.awt.event.WindowEvent windowEvent)
Method in class SystiNetClient.WebServiceClient. Specified by: windowOpened in interface java.awt.event.WindowListener
XmlValidator Class EmeryXmlValidator.XmlValidator.
XmlValidator() Constructor for class EmeryXmlValidator.XmlValidator. Creates new XmlValidator.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 156 of 166
Appendix G: Payment Types
Payment Types Payment
Codes Undefined 0
Prepaid 1
Collect 2
3rd
Party Billing 3
3rd Party OTH/SHP 5
3rd Party OTH/CON 6
3rd OTH/SHP w/DDP 7
3rd OTH/SHP s/DDU 8
3rd OTH/CON w/DDP 9
3rd OTH/CON w/DDU 10
Prepaid with DDP 11
Prepaid with DDU 12
Payment types 5 through 12 are used when a basic payment type 1 through 3 is selected with specific special instructions, typically international in nature. For example; A payment type of "Prepaid" is selected on a US Export Shipment and Deliver Duties Paid is selected from special instructions, the payment type used in your transaction is 11.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 157 of 166
Glossary
Bill of Lading
The document issued on behalf of the carrier describing the kind and quantity of the shipped goods, the shipper, the consignee, the ports of loading and discharge, and the carrying vessel. It serves as a document of title, a contract of carriage, and a receipt for goods. See also Commercial Bill of Lading (CBL) and Government Bill of Lading (GBL).
Bill To
A person or company, other than the shipper or consignee, responsible for a shipment's freight charges. See also Third Party Billing.
Business Days
For the United States, Monday through Friday, except Federal holidays. For the Commonwealth of Puerto Rico, Monday through Friday, except Federal holidays and Commonwealth of Puerto Rico holidays. If the Federal holiday or Commonwealth of Puerto Rico holiday is a normal business day for the contractor, it shall be offered to the shipper as a normal business day and no holiday charges will apply.
Check to Shipper (CTS)
The amount, if any, that the consignee must send to the shipper in order to receive the freight. Cannot exceed $50,000 USD.
COM
Component Object Model. The OLE object-oriented programming model that defines how objects interact within a single process or between processes. In COM, clients have access to an object through interfaces implemented on the object. See also COM Object and Interface.
COM Object
An object that conforms to the OLE Component Object Model (COM). A COM object is an instance of an object definition that specifies the object's data and one or more implementations of interfaces on the object. Clients interact with a COM object only through its interfaces. See also COM and Interface.
COMAT
Company material sent between company locations.
Commercial Bill of Lading (CBL)
A document provided by the contractor. Used to identify goods to be transported and as a method of billing for services. Also known as a Bill of Lading or Air Waybill.
Commercial Form
A commercial uniform bill of lading, a commercial express receipt, or any other commercial instrument constituting a contract of carriage subject to the terms and conditions set forth in Standard Form 1103, U.S. Government Bill of Lading (41 CFR 101-41.302-3). See also Government Bill of Lading (GBL), Commercial Bill of Lading (CBL), and Bill of Lading. Commercial Forms and Procedures (CF&P)
A shipment made using commercial forms and commercial billing procedures instead of a
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 158 of 166
Government Bill of Lading (SF 1103) and its related billing procedures (41 CFR 101-41.304-2).
See also Commercial Form, Government Bill of Lading (GBL), and Electronic Commercial Forms and Procedures (CF&P).
Consignee
The party who is to receive the goods, usually the buyer. The person or corporation to whom articles are shipped.
Consolidated Shipment
See Shipment.
Contractor
See Third Party Logistics Contractor.
Customer
A person, corporation, unit, or depot shipping freight through UPS.
Customs Clearance
International procedure for declaring goods at the Customs office to gain authorized entry of those goods into a country.
Dangerous Goods
See Hazardous Material (Hazmat).
Day
A calendar day, unless otherwise specified. See also Shipping Day, Business Days, and End of Day.
Delivery
The act of transferring possession, such as the transfer of property from shipper to carrier, one carrier to another, or carrier to consignee.
Dimensional Weight (Dim Weight)
The weight calculated by measuring the length x width x height of a package. Used when calculating the rate of oversized pieces and for rating a shipment that has low density (for example, bulky light items. Also referred to as cubic weight.
Door-to-Door
Transportation of a shipment from the shipper's premises (factory, store, warehouse, etc.) to the consignee's premises (as opposed to airport-to-airport). See also Express and Expedited Service.
Electronic Commercial Forms and Procedures (CF&P)
A paperless system where a shipment is initiated electronically (EDI or direct link to contractor’s computer system). See also Commercial Forms and Procedures (CF&P) and Electronic Data Interchange (EDI). Electronic Data Interchange (EDI)
The electronic exchange of transportation information by means of electronic transmission of the information in lieu of the creation of a paper document.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 159 of 166
End of Day
The time when the customer transmits the command to initiate the End of Day process. The End of Day time for each customer is configurable at the shipper level. However, if the customer does not transmit the command to initiate the End of Day process by 2 a.m. Eastern Time, our company’s servers will automatically close and process the day’s shipments.
End of Day Processing
Closes all shipments and orders for the current shipping day.
Gemini API
Gemini Application Programming Interface. The Gemini shipment entry business objects developed by UPS.
Gemini Interface
The component system described by this document.
Gold Priority
Guaranteed, time-specific service to points in the United States and Canada. Allows you to select the exact time of delivery. Requires advanced arrangements through the UPS Service Center. Call 1-800-443-6379.
Government Bill of Lading (GBL)
A government document (Standard Form 1103) used to procure transportation and related services from commercial carriers. See also Bill of Lading and Commercial Bill of Lading (CBL).
HAPU
Hold at Airport for Pickup. Excludes Two-Man Delivery, Inside Delivery, and Delivery-to-Door options.
Hardcopy
Information provided in paper format.
Hazardous Material (Hazmat)
A substance or material that the Secretary of Transportation has determined to be capable of posing an unreasonable risk to health, safety, and property when transported in commerce and that has been so designated. The term includes hazardous substances, hazardous wastes, marine pollutants, elevated temperature materials, materials designated as hazardous under the provisions of the Code of Federal Regulations (CFR) Title 49, Parts 172.101 and 172.102, and materials that meet the defining criteria for hazard class and divisions in CFR Title 49, Part 173. Customer must call the Gemini Help Desk (1-800-327-2370 or 1-702-408-3735) to request authorization.
High-Value Shipment
Any shipment having a declared or insured value higher than the current unauthorized limit values (declared value - 25,000 USD; insurance value – 500,000 USD).
Interface
A group of related functions that provide access to a COM object. Each OLE interface defines a contract that allows objects to interact according to the COM. While OLE provides many interface implementations, developers designing OLE applications can also implement
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 160 of 166
most interfaces. See also COM and COM Object.
Internet
A large collection of interconnected computer networks.
Label
A hardcopy form that contains the data about the shipment to which it is attached. It contains, but is not limited to, the shipment number, shipper reference number, shipper address, dimensions, consignee, consignee address, date, service type, piece count, and shipment number bar code.
Manifest
An itemized list by Bill of Lading number of the kind and quantity of all loaded cargoes. Documentation used for multiple package shipments on the same CBL or electronic CF&P, in lieu of individual bills of lading for each shipment. See also Bill of Lading, Commercial Bill of Lading (CBL), and Electronic Commercial Forms and Procedures (CF&P).
Next Business Day
The business day following the day of pickup. See also 0930 and AM.
Order
One or more line items associated with the same order reference number and represented in the same manifest record associated with a shipment. One or more orders can be associated with the same shipment. See also Shipment.
Oversized Piece
Shipments containing pieces measuring in excess of 120 inches (304.80 centimeters) in length, 84 inches (213.35 centimeters) in width, 76 inches (193.04 centimeters) in height, or that are otherwise restricted by their height/contour/profile from fitting our single, standard “A” container.
Pickup
The act of calling for freight by truck at the shipper's shipping dock for transporting goods to the carrier's terminal.
Receipt
A signature by the consignee verifying delivery of a package has been made.
Saturday Delivery
Saturday delivery to AM points in the United States and Canada. Requires advanced arrangements Call 1-800-443-6379 in US/Canada, or outside US/Canada your nearest Service Center.
Second Business Day
The second business day following the day of pickup.
Service Guide
A guide or publication issued by a commercial carrier that is applicable to the public, explaining the various services the carrier offers as customary commercial practice.
Shipment
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 161 of 166
All orders processed throughout the Gemini shipping session with the same consignee, payment
type, service level, special instructions, and assigned shipment number. A shipment contains one or more orders. See also Order.
Shipper
The customer who sends a shipment to the consignee. Shipping Day
The time elapsed since the last End of Day process has been run. See also End of Day Processing and End of Day.
SOAP
Simple Object Access Protocol. An XML-based protocol that is designed to exchange structured and typed information on the Web.
Third Party Billing
The designated payer of an invoice other than the shipper or consignee.
Third Party Logistics Contractor
A contractor who provides warehousing, shipping, and arranged transportation services under contract.
Third Party Systems Coordinator
Certifies third-party shipping software packages or in-house systems for UPS shipments.
Time-Specific Service
Service to points in the United States and Canada that allows you to select the exact time of delivery. See also Gold Priority.
Two-Man Delivery
Shipments requiring pickup or delivery of packages of excessive weight or size that cannot be handled by one individual.
UOM
Units of measure. Either Imperial or metric.
Urgent Pack or Envelope
Complimentary packaging provided by UPS for worldwide delivery of business correspondence, contracts, and reports.
Web Site
Space allocated to an organization or individual on a network, which may be accessed through the Internet. See also Internet.
Weight Break
The weight of a cargo shipment at which a lower per pound (or per kilogram) rate becomes effective. XML
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 162 of 166
Extensible Markup Language. Universal format for working with structured data on the Web.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 163 of 166
Gemini Application Disclaimer and End User License Agreement
All statements made in this document are subject to change without notification. No part of this document should be considered an agreement to provide support or maintenance to any shipping system. This document outlines the requirements that a developer must meet to receive continued support of a third-party shipping system at a UPS customer site, regardless of any agreements made between the customer and the software vendor. Our support is limited to verifying the accuracy of data submitted to our company and to providing the appropriate files and data necessary to ensure rates and routing information in the system are current.
UPS is committed to assisting developers of third-party shipping systems with getting their product certified and marketed rapidly. Certification is your assurance that UPS believes that your system will accurately rate and route the customers’ freight and provide accurate data to our company’s systems, resulting in high customer satisfaction for both companies. Although UPS is eager to provide support for developers, the scope of support does have limits as outlined below.
UPS is not responsible for the purchase, scheduling of installation, installation, or maintenance of any shipping system at any customer site unless representatives of UPS and the developer and/or dealer performing the installation specifically indicate this by an agreement in writing and sign the agreement. UPS will not act as project coordinator for the installation of the system at the customer site. All coordination of the purchase, installation, and maintenance of the system are the responsibility of the end user. GEMINI END USER LICENSE AGREEMENT IMPORTANT-READ CAREFULLY: This UPS, Inc. End-User License Agreement ("EULA") is a legal agreement between you (either an individual or a single entity) and UPS, Inc. Corporation for the UPS, Inc. Software product identified above, which includes computer software and may include associated media, printed materials, and "online" or electronic documentation ("SOFTWARE PRODUCT"). The SOFTWARE PRODUCT also includes any updates and supplements to the original SOFTWARE PRODUCT provided to you by UPS, Inc.. Any software provided along with the SOFTWARE PRODUCT that is associated with a separate end-user license agreement is licensed to you under the terms of that license agreement. By installing, copying, downloading, accessing or otherwise using the SOFTWARE PRODUCT, you agree to be bound by the terms of this EULA. If you do not agree to the terms of this EULA, do not install or use the SOFTWARE PRODUCT; you may, however, return it to your place of purchase for a full refund. SOFTWARE PRODUCT LICENSE The SOFTWARE PRODUCT is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The SOFTWARE PRODUCT is licensed, not sold.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 164 of 166
1. GRANT OF LICENSE. This EULA grants you the following rights: * Applications Software. You may install and use one copy of the SOFTWARE PRODUCT, or any prior version for the same operating system, on a single device, workstation, terminal, handheld PC, pager, "smart phone," or other digital electronic device ("DEVICE"). If you run a business or enterprise, you may permit the primary user of the DEVICE on which the SOFTWARE PRODUCT is installed to make a second copy for his or her exclusive use on a portable DEVICE owned by you so long as you provide such portable DEVICE to such primary user solely for his or her use in connection with your business or enterprise and not for personal or home use. * Storage/Network Use. As an alternative to the rights granted in the previous paragraph, you may install a copy of the SOFTWARE PRODUCT on a storage device, such as a network server, and allow individuals to access and use the SOFTWARE PRODUCT from other DEVICES over an internal network; however, you must acquire and dedicate a license for the storage device upon which the SOFTWARE PRODUCT is installed and each separate DEVICE from which the SOFTWARE PRODUCT is accessed and used. This license does not give you a right to allow third parties to access and use the SOFTWARE PRODUCT via the Internet or an external network. A license for the SOFTWARE PRODUCT may not be shared or used concurrently on different DEVICES. * Registration. You may be required to register your copy of the SOFTWARE PRODUCT to continue using it. This registration obligation is further described in the SOFTWARE PRODUCT documentation. * Reservation of Rights. All rights not expressly granted are reserved by UPS, Inc.. 2. DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS. * Limitations on Reverse Engineering, Decompilation, and Disassembly. You may not reverse engineer, decompile, or disassemble the SOFTWARE PRODUCT, except and only to the extent that such activity is expressly permitted by applicable law notwithstanding this limitation. * Separation of Components. The SOFTWARE PRODUCT is licensed as a single product. Its component parts may not be separated for use on more than one DEVICE. * Trademarks. This EULA does not grant you any rights in connection with any trademarks or service marks of UPS, Inc.. * Rental. You may not rent, lease, or lend the SOFTWARE PRODUCT. * Support Services. UPS, Inc. may provide you with support services related to the SOFTWARE PRODUCT ("Support Services"). Use of Support Services is governed by the UPS, Inc. policies. Any supplemental software code provided to you as part of the Support Services shall be considered part of the SOFTWARE PRODUCT and subject to the terms and conditions of this EULA. With respect to technical information you provide to UPS, Inc. as part of the Support Services, UPS, Inc. may use such information for its business purposes, including for product support and development. UPS, Inc. will not utilize such technical information in a form that personally identifies you. * Software Transfer. The initial licensee of the SOFTWARE PRODUCT may make a one-time permanent transfer of this EULA and SOFTWARE PRODUCT only directly to an end user. This transfer must include all of the SOFTWARE PRODUCT (including all component parts, the media and printed materials, any upgrades, this EULA, and, if applicable, the Certificate of Authenticity). Such transfer may not be by way of consignment or any other indirect transfer.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 165 of 166
The transferee of such one-time transfer must agree to comply with the terms of this EULA, including the obligation not to further transfer this EULA and SOFTWARE PRODUCT. * Termination. Without prejudice to any other rights, UPS, Inc. may terminate this EULA if you fail to comply with the terms and conditions of this EULA. In such event, you must destroy all copies of the SOFTWARE PRODUCT and all of its component parts. 3. COPYRIGHT. All title and copyrights in and to the SOFTWARE PRODUCT (including but not limited to any images, photographs, animations, video, audio, music, text, and "applets" incorporated into the SOFTWARE PRODUCT), the accompanying printed materials, and any copies of the SOFTWARE PRODUCT are owned by UPS, Inc. or its suppliers. All title and intellectual property rights in and to the content which may be accessed through use of the SOFTWARE PRODUCT is the property of the respective content owner and may be protected by applicable copyright or other intellectual property laws and treaties. This EULA grants you no rights to use such content. If this SOFTWARE PRODUCT contains documentation which is provided only in electronic form, you may print one copy of such electronic documentation. You may not copy the printed materials accompanying the SOFTWARE PRODUCT. 4. DUAL-MEDIA SOFTWARE. You may receive the SOFTWARE PRODUCT in more than one medium. Regardless of the type or size of medium you receive, you may use only one medium that is appropriate for your single DEVICE. You may not install or use the other medium on another DEVICE. You may not loan, rent, lease, or otherwise transfer the other medium to another user, except as part of the permanent transfer (as provided above) of the SOFTWARE PRODUCT. 5. BACKUP COPY. After installation of one copy of the SOFTWARE PRODUCT pursuant to this EULA, you may keep the original media on which the SOFTWARE PRODUCT was provided by UPS, Inc. solely for backup or archival purposes. If the original media is required to use the SOFTWARE PRODUCT on the DEVICE, you may make one copy of the SOFTWARE PRODUCT solely for backup or archival purposes. Except as expressly provided in this EULA, you may not otherwise make copies of the SOFTWARE PRODUCT or the printed materials accompanying the SOFTWARE PRODUCT. MISCELLANEOUS If you acquired this SOFTWARE PRODUCT in the United States, this EULA is governed by the laws of the State of California. If you acquired this SOFTWARE PRODUCT in Canada, unless expressly prohibited by local law, this EULA is governed by the laws in force in the Province of Ontario, Canada; and, in respect of any dispute which may arise hereunder; you consent to the jurisdiction of the federal and provincial courts sitting in Toronto, Ontario. If this SOFTWARE PRODUCT was acquired outside the United States, then local law may apply. Should you have any questions concerning this EULA, or if you desire to contact UPS, Inc. for any reason, please contact the UPS, Inc. subsidiary serving your country.
© Copyright 2018 United Parcel Service of America, Inc. All rights reserved. Page 166 of 166
LIMITED WARRANTY LIMITED WARRANTY FOR SOFTWARE PRODUCTS ACQUIRED OUTSIDE THE US AND CANADA. FOR THE LIMITED WARRANTIES AND SPECIAL PROVISIONS PERTAINING TO YOUR PARTICULAR JURISDICTION, PLEASE REFER TO YOUR WARRANTY BOOKLET INCLUDED WITH THIS PACKAGE OR PROVIDED WITH THE SOFTWARE PRODUCT PRINTED MATERIALS. LIMITED WARRANTY FOR SOFTWARE PRODUCTS ACQUIRED IN THE US AND CANADA. UPS, Inc. warrants that (a) the SOFTWARE PRODUCT will perform substantially in accordance with the accompanying written materials for a period of ninety (90) days from the date of receipt, and (b) any Support Services provided by UPS, Inc. shall be substantially as described in applicable written materials provided to you by UPS, Inc. support engineers will make commercially reasonable efforts to solve any problem issues. Some states and jurisdictions do not allow limitations on duration of an implied warranty, so the above limitation may not apply to you. To the extent allowed by applicable law, implied warranties on the SOFTWARE PRODUCT, if any, are limited to ninety (90) days. CUSTOMER REMEDIES. UPS, Inc.’s and its suppliers' entire liability and your exclusive remedy shall be, at UPS, Inc.'s option, either (a) return of the price paid, if any, or (b) repair or replacement of the SOFTWARE PRODUCT that does not meet UPS, Inc.'s Limited Warranty and which is returned to UPS, Inc. with a copy of your receipt. This Limited Warranty is void if failure of the SOFTWARE PRODUCT has resulted from accident, abuse, or misapplication. Any replacement SOFTWARE PRODUCT will be warranted for the remainder of the original warranty period or thirty (30) days, whichever is longer. Outside the United States, neither these remedies nor any product support services offered by UPS, Inc. are available without proof of purchase from an authorized international source. No other warranties. To the maximum extent permitted by applicable law, UPS, inc. And its parent corporation(s), affiliates, subsidiaries, agents, contractors or suppliers disclaim all other warranties and conditions, either express or implied, including, but not limited to, implied warranties of merchantability, fitness for a particular purpose, title, and non-infringement, with regard to the software product, and the provision of or failure to provide support services. This limited warranty gives you specific legal rights. You may have others, which vary from state/jurisdiction to state/jurisdiction. Limitation of liability. To the maximum extent permitted by applicable law, in no event shall UPS, inc. Or its parent corporation(s), affiliates, subsidiaries, agents, contractors or suppliers be liable for any special, incidental, indirect, or consequential damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss) arising out of the use of or inability to use the software product or the provision of or failure to provide support services, even if UPS, inc. Has been advised of the possibility of such damages. In any case, UPS, inc.'s entire liability under any provision in of this eula shall be limited to the greater of the amount actually paid by you for the software product or u.s.$5.00; provided, however, if you have entered into a UPS, inc. Support services agreement, UPS, inc.'s entire liability regarding support services shall be governed by the terms of that agreement. Because some states and jurisdictions do not allow the exclusion or limitation of liability, the above limitation may not apply to you.