Creating a UPS Shipping Label with UPS API & ColdFusion
Monday 01 December 2014 11:12 AM
UPS recently updated their API documentation. Compared to the previous documentation, this version is a very good improvement. If you plan to use UPS API, begin by creating a UPS account. Get an API access Key and finally the most important setp - download the API documentation and go through it carefully. UPS has far too many options and scenarios than I could explain in a single post. (follow these links for UPS Address Verification and City Validation functions)
There are three aspects to creating a UPS Shipping label: ShipConfirm, ShipAccept and Void. First, send in your request for a shipping label and then UPS confirms your request by sending back a label. At that point, you have to either accept the label or void it. You need to complete those three steps before you can move in-to Production API. Following CFC constantans ShipConfirm, ShipAccept and Void function.
UPS's shipping business is complex and API is as well. This CFC does not cover every aspect of UPS API, but let you create labels and help you get production access. Please read each argument’s Hint attribute for details. I have added as much information as I can in there. Similar to my FedEX CFC, all access keys and passwords are stored in the Application file. Also, this CFC will write log files in every step of the communication process in the folder called Log, including request XMLs, returned XMLs, actual labels and other files that come with that, like high value reports, etc..
I copied and pasted the list of arguments here, if you want to have a quick look at them. Click on the download button at the end of the post to download the CFC file.
1: <!--- To Address ---> 2: <cfargument name="Company" type="string" required="Yes" /> 3: <cfargument name="Name" type="string" required="Yes" /> 4: <cfargument name="Address1" type="string" required="Yes" /> 5: <cfargument name="City" type="string" required="Yes" /> 6: <cfargument name="State" type="string" required="Yes" /> 7: <cfargument name="ZIP" type="string" required="Yes" /> 8: <cfargument name="Phone" type="string" required="No" default="" /> 9: <cfargument name="Attention" type="string" required="No" default="" /> 10: <cfargument name="Address2" type="string" required="No" default="" /> 11: <cfargument name="Address3" type="string" required="No" default="" /> 12: <cfargument name="EMailAddress" type="string" required="No" default="" /> 13: <cfargument name="Country" type="string" required="No" default="US" hint="ISO Standard 3166 Country Code" /> 14: <cfargument name="IsResident" type="boolean" required="No" default="false" /> 15: <!--- Service ---> 16: <!--- For Complete Code List : Shipping Package XML Developers Guide.pdf - Appendix F - Service Codes ---> 17: <!--- United States Domestic Shipments ---> 18: <!--- 1.UPS Next Day Air / 2.UPS Second Day Air / 3.UPS Ground / 12.UPS Three-Day Select ---> 19: <!--- 13.UPS Next Day Air Saver / 14.UPS Next Day Air Early A.M. SM / 59.UPS Second Day Air A.M ---> 20: <!--- 65.UPS Saver ---> 21: <cfargument name="ServiceCode" type="numeric" required="No" default="03" /> 22: <cfargument name="ServiceDesc" type="string" required="No" default="UPS Second Day Air" /> 23: <!--- package Details ---> 24: <cfargument name="pkgType" type="numeric" required="No" default="02" hint="01:Letter /02:Custom package /03:Tube /04:PAC /21:UPSexpressBox" /> 25: <cfargument name="pkgDescription" type="string" required="No" default="" /> 26: <cfargument name="pkgLength" type="string" required="Yes" hint="Inch in US, CM rest of the world" /> 27: <cfargument name="pkgWidth" type="string" required="Yes" hint="Inch in US, CM rest of the world" /> 28: <cfargument name="pkgHeight" type="string" required="Yes" hint="Inch in US, CM rest of the world" /> 29: <cfargument name="pkgWeight" type="string" required="Yes" hint="Inch in LB, Kg rest of the world" /> 30: <cfargument name="InsuranceValue" type="string" required="No" hint="Inch in LB, Kg rest of the world" /> 31: <!--- Services ---> 32: <cfargument name="SaturdayDelivery" type="boolean" required="No" default="false" hint="Saturday Delivery or not" /> 33: <cfargument name="VerbConfirmName" type="string" required="No" default="" hint="To confirm delivery of your shipment, a UPS representative will call the preferred contact telephone number listed on your UPS Next Day Air® Early A.M.® package." /> 34: <cfargument name="VerbConfirmPhone" type="string" required="No" default="" hint="To confirm delivery of your shipment, a UPS representative will call the preferred contact telephone number listed on your UPS Next Day Air® Early A.M.® package." /> 35: <!--- Pickup Details ---> 36: <cfargument name="SaturdayPickup" type="boolean" required="No" default="false" /> 37: <cfargument name="PickupDate" type="string" required="No" default="" /> 38: <cfargument name="PickupTimeEarly" type="string" required="No" default="0800" hint="Earliest Time to Pick Up (HHmm Time Format)" /> 39: <cfargument name="PickupTimeLate" type="string" required="No" default="1600" hint="Late Time to Pick Up (HHmm Time Format)" /> 40: <cfargument name="PickupName" type="string" required="No" default="" hint="Name of the person to contact for pickup" /> 41: <cfargument name="PickupPhone" type="string" required="No" default="" hint="Phone number of the pickup room" /> 42: <cfargument name="PickupRoom" type="string" required="No" default="" /> 43: <cfargument name="PickupFloor" type="string" required="No" default="" /> 44: <cfargument name="PickupLocation" type="string" required="No" default="" /> 45: <!--- Credit Card Billing - Leave Blank if not in use ---> 46: <cfargument name="CCNumber" type="string" required="No" default="" hint="Leave Blank if not in use" /> 47: <cfargument name="CCType" type="string" required="No" default="" hint="Leave Blank if not in use" /> 48: <cfargument name="CCExpirationDate" type="string" required="No" default="" hint="Leave Blank if not in use" /> 49: <cfargument name="CCSecurityCode" type="string" required="No" default="" hint="Leave Blank if not in use" /> 50: <cfargument name="CCAddress1" type="string" required="No" default="" hint="Leave Blank if not in use" /> 51: <cfargument name="CCAddress2" type="string" required="No" default="" hint="Leave Blank if not in use" /> 52: <cfargument name="CCAddress3" type="string" required="No" default="" hint="Leave Blank if not in use" /> 53: <cfargument name="CCCity" type="string" required="No" default="" hint="Leave Blank if not in use" /> 54: <cfargument name="CCState" type="string" required="No" default="" hint="Leave Blank if not in use" /> 55: <cfargument name="CCZIP" type="string" required="No" default="" hint="Leave Blank if not in use" /> 56: <cfargument name="CCCountry" type="string" required="No" default="US" hint="Leave Blank if not in use - ISO Standard 3166 Country Code" /> 57: <!--- Third Party Billing - Leave Blank if not in use ---> 58: <cfargument name="BillAccount" type="string" required="No" default="" hint="Leave Blank if not in use" /> 59: <cfargument name="BillZip" type="string" required="No" default="" hint="Leave Blank if not in use" /> 60: <cfargument name="BillCountry" type="string" required="No" default="US" hint="Leave Blank if not in use - ISO Standard 3166 Country Code" /> 61: <!--- UPS Access Settings ---> 62: <cfargument name="License" type="string" required="No" default="#application.UPSLicense#" hint="UPS License Key" /> 63: <cfargument name="Account" type="string" required="No" default="#application.AccountNumber#" hint="UPS Account ID" /> 64: <cfargument name="UserId" type="string" required="No" default="#application.UPSUserId#" hint="UPS UserName" /> 65: <cfargument name="Password" type="string" required="No" default="#application.UPSPassword#" hint="UPS Password" /> 66: <!--- Shipper Address ---> 67: <cfargument name="MyCompany" type="string" required="No" default="Ups Store" /> 68: <cfargument name="MyName" type="string" required="No" default="John Doe" /> 69: <cfargument name="MyAttention" type="string" required="No" default="" /> 70: <cfargument name="MyAddress1" type="string" required="No" default="518 Old Post Rd Ste 7" /> 71: <cfargument name="MyAddress2" type="string" required="No" default="" /> 72: <cfargument name="MyAddress3" type="string" required="No" default="" /> 73: <cfargument name="MyCity" type="string" required="No" default="Edison" /> 74: <cfargument name="MyState" type="string" required="No" default="NJ" /> 75: <cfargument name="MyZIP" type="string" required="No" default="08817" /> 76: <cfargument name="MyPhone" type="string" required="No" default="" /> 77: <cfargument name="MyEMailAddress" type="string" required="No" default="" /> 78: <cfargument name="MyCountry" type="string" required="No" default="US" hint="ISO Standard 3166 Country Code" /> 79: <!--- From Address ---> 80: <cfargument name="FromCompany" type="string" required="No" default="#arguments.MyCompany#" /> 81: <cfargument name="FromName" type="string" required="No" default="#arguments.MyName#" /> 82: <cfargument name="FromAttention" type="string" required="No" default="#arguments.MyAttention#" /> 83: <cfargument name="FromAddress1" type="string" required="No" default="#arguments.MyAddress1#" /> 84: <cfargument name="FromAddress2" type="string" required="No" default="#arguments.MyAddress2#" /> 85: <cfargument name="FromAddress3" type="string" required="No" default="#arguments.MyAddress3#" /> 86: <cfargument name="FromCity" type="string" required="No" default="#arguments.MyCity#" /> 87: <cfargument name="FromState" type="string" required="No" default="#arguments.MyState#" /> 88: <cfargument name="FromZIP" type="string" required="No" default="#arguments.MyZIP#" /> 89: <cfargument name="FromPhone" type="string" required="No" default="#arguments.MyPhone#" /> 90: <cfargument name="FromEMailAddress" type="string" required="No" default="#arguments.MyEMailAddress#" /> 91: <cfargument name="FromCountry" type="string" required="No" default="#arguments.MyCountry#" hint="ISO Standard 3166 Country Code" /> 92: <!--- Notification (From) Settings ---> 93: <cfargument name="NotifyFromEmail" type="string" required="No" default="" hint="From Email Address for Notifications" /> 94: <cfargument name="NotifyFromName" type="string" required="No" default="" hint="From Name for Notifications" /> 95: <cfargument name="UndeliEmail" type="string" required="No" default="" hint="Email Address to notify Undeliverable" /> 96: <!--- Shipment Notification ---> 97: <cfargument name="ShipNotifyEmail" type="string" required="No" default="" hint="Shipment Notification to Email" /> 98: <cfargument name="ShipNotifyMemo" type="string" required="No" default="" hint="Shipment Notification to Email Memo" /> 99: <cfargument name="ShipNotifySubject" type="string" required="No" default="" hint="Shipment Notification Email Subject" /> 100: <!--- Delivery Notification ---> 101: <cfargument name="DelivNotifyEmail" type="string" required="No" default="" hint="Delivery Notification to Email" /> 102: <cfargument name="DelivNotifyMemo" type="string" required="No" default="" hint="Delivery Notification Email Memo" /> 103: <cfargument name="DelivNotifySubject" type="string" required="No" default="" hint="Delivery Notification Email Subject" /> 104: <!--- Return Notification ---> 105: <cfargument name="RetnNotifyEmail" type="string" required="No" default="" hint="Return Notification to Email - Return Notification (valid for shipment with UPS 1-Attempt and UPS 3-Attempt Return Services)" /> 106: <cfargument name="RetnNotifyMemo" type="string" required="No" default="" hint="Return Notification Email Memo" /> 107: <cfargument name="RetnNotifySubject" type="string" required="No" default="" hint="Return Notification Email Subject" /> 108: <!--- Optional/General Settings ---> 109: <cfargument name="CurrencyCode" type="string" required="No" default="USD" hint="ISO Standard 4217 Currency Codes" /> 110: <cfargument name="comment" type="string" required="No" default="" /> 111: <cfargument name="validate" type="string" required="No" default="nonvalidate" hint="(nonvalidate/validate) validate shipping address" /> 112: <cfargument name="RefCode" type="string" required="No" default="" hint="Supplied by the customer. Can use for Tracking." /> 113: <cfargument name="RefValue" type="string" required="No" default="" hint="Supplied by the customer. Can use for Tracking." /> 114: <cfargument name="KeepLogs" type="string" required="No" default="Yes" hint="Save Log of XML Communication" /> 115: <cfargument name="OrderID" type="string" required="No" default="#CreateUUID()#" hint="Log files will created under OrderID" /> Sample Call
1: <cfset ups = createObject('component','ups')> 2: <cfset createLabel = ups.shipping( 3: Company = 'UPS Store', 4: Name = 'Manager', 5: Address1 = '5 HANOVER SQUARE', 6: City = 'NEW YORK', 7: State = 'NY', 8: ZIP = '10004', 9: Phone = '7188601338', 10: EMailAddress = 'email@address.here', 11: 12: pkgType = '02', 13: pkgLength = '22', 14: pkgWidth = '20', 15: pkgHeight = '18', 16: pkgWeight = '6.1', 17: InsuranceValue = '1000', 18: 19: PickupDate = dateadd('d',3,now()), 20: PickupName = 'John Smith', 21: PickupPhone = '2345678920', 22: OrderID = 6 23: )> 24: <cfdump var="#createLabel#"> 25: <cfoutput><img src="Log/Label/label#createLabel.TrackingNumber#.gif" /></cfoutput> Updated : Dec 1 2014
Posted by Saman W Jayasekara at Sunday 19 December 2010 12:31 PM
.
Shipping API
.
ColdFusion
James Moberg
Wednesday 01 April 2015 06:50 PM
I received a couple of "The XML document is well formed but the document is not valid" errors too... it was due to a couple of "FromEMailAddress" nodes that ended with "/EmailAddress" instead of "/FromEMailAddress".
Jaana Gilbert
Monday 24 March 2014 09:57 AM
I've tried to get this one to work, but it looks like there have been changes in the UPS end that states..
errorSeverity: Hard
errorCode: 10002
errorDescription: The XML document is well formed but the document is not valid
errorLocation: ShipmentConfirmRequest/Shipment/Shipper/Address
What version of the API was this code for? I'd love to get it to work :)
Marcus Melo
Wednesday 17 September 2014 10:46 AM
Jaana,
It's been a few months but I started implementing the UPS and I aldo had the same issue, in order to fix it make sure the <Address> element has a capital A.
Wednesday 14 November 2012 12:17 PM
Thanks for sharing the code! It was very helpful! The only issue I am running into is when I'm storing the label. When I try to display the image, FireBug says "Image corrupt or truncated". When I open the image on the server it displays an "X" where the label show be (so it looks like the file is corrupted). Any thoughts as to what I might be doing wrong? Thanks!
Wednesday 14 November 2012 04:00 PM
Do you receive all other files (logs, value report, etc..) correctly?
Rob D
Sunday 21 October 2012 06:23 AM
We're having performance issues with this API. it sometimes takes up to 1 minute for it to return, and sometimes it doesn't return at all. we're also using the Endicia API for USPS labels and that's rock solid, so i don't believe it's our network. anyone else having these issues or know a solution?
Asim
Friday 13 November 2015 09:29 AM
Rob is it possible to share your examples that you use to call Endicia APIs?
I have similar requierments for a project where I need to create bridge with Endidia and generate shipping labels.
TIA
Misha
Friday 18 November 2011 09:35 AM
Thanks for sharing this code, really helpful!
Is any suggestions or thoughts, how the label can be printed on label printer via ColdFusion?
Thanks
Rob D
Sunday 21 October 2012 06:29 AM
We're printing from firefox. I set the width attribute in the IMG tag to 360 and turned off all margin, header and footer in Page Setup
Friday 18 November 2011 09:45 AM
If your printer is connected to coldfusion server, you can use <CFPRINT> tag.
Misha
Friday 18 November 2011 11:03 AM
Thanks Sam, CFPRINT can print only PDF. I know it is possible export image to PDF, but that will be a challange to print a PDF on label printer........ not sure, but I think I need find a way print a raw data to the printer......... plus all printers are shared printers.......
Show/Hide Line Numbers . Full Screen . Plain
