UPSXML Shipping Module for Zen Cart 1.5.3 and later
Version 1.7.9, by lat9
Current Support Thread at Zen Cart Forums: https://www.zen-cart.com/showthread.php?222903-UPS-XML-Support-Thread
Contributers and Copyrights
- Original Copyright (c) 2003 Torin Walker, torinwalker@rogers.com
- Insurance Support 2005 Joe McFrederick, jomcfred@oldeparsonage.com
- Modified for zen-cart 1.2.5d by Dennis Sayer - July 9, 2005, dennis.s.sayer@brandnamebatteries.com
- Updated for zen-cart 1.5.1 by Brian Gundlach - June 10, 2014, Brian@gundlach-marketing.com
- Copyright (C) 2017-2020, Vinos de Frutas Tropicales (lat9)
Description
This module provides the eCommerce Zen Cart community with the long-awaited XML version of the UPS Rates and Services gateway. It supports multiple (storefront) languages, multiple geographic origins and implements the
most necessary features offered by the UPS Rates and Services system. The module connects to UPS, retrieves a list of available shipping methods and prices and presents them to the customer.
Settings are changed in a store's Zen Cart admin interface under Modules->Shipping>United Parcel Service (upsxml). The administrative interface shows shipper- (not customer-) related variables such as package type and origin in English, but customer-facing product names (the name UPS uses to describe its services, such as Express Plus or Ground) can be multi-lingual.
Installation
This plugin currently has no core-file overwrites; you should always backup your cart's database and files prior to making any changes.
- Unzip the plugin's package file, which you've most likely already done if you're reading this!
- Copy the plugin's new files, from the zip-file's distribution:
- /includes/classes/xmldocument.php
- /includes/languages/english/modules/shipping/upsxml.php
- /includes/modules/shipping/upsxml.php
- /includes/templates/template_default/images/icons/shipping_ups.gif
- If you do not already have UPS access credentials:
- UPS Rates account username
- UPS Rates account password
- UPS Rates Access Key
then
- Register at UPS for an account: https://wwwapps.ups.com/doapp/signup?sysid=myups
- Once you're registered, Request an Access Key using this link: https://www.ups.com/upsdeveloperkit?loc=en_US
- Write down the XML Access Key; you will need that key to enable the UPS XML shipping module.
- Log into your Zen Cart admin and use the Modules->Shipping tool to configure and enable the shipping-module for your store's use.
Configure and Test the Shipping Module
In admin, choose Modules->Shipping and activate the new United Parcel Service (upsxml) module. Edit the module and set your service options:
- Enable UPS Shipping
- Tax Class
- Shipping Zone
- Sort order of display
- Pickup Method
- Packaging Type
- Customer Classification Code
- Shipping Origin (determines what UPS shipping-method names are displayed to the customer)
- Origin City (required for some countries)
- Origin State/Province (the two-letter ISO-3166 code)
- Origin Country (the two-letter ISO-3166 code)
- Origin Zip/Postal Code
- UPS Currency Code
- Unit Weight
- Unit Length
- Quote Type
- Handling Fee
- Enable Insurance
- Shipping Methods
- Shipping Delay
- UPS Rates Access Key (obtain from UPS)
- UPS Rates Username (obtain from UPS)
- UPS Rates Password (obtain from UPS)
- UPS Rates "Shipper Number" (obtain from UPS)
- UPS XML Display options (to identify whether time-in-transit and package weight are displayed to the customer).
- Enable debug?
- Test or Production Mode
If you have any questions regarding the above settings, please refer to the documentation provided to you by UPS when you signed up for and received your access key.
Once configured, make sure that the results your store receives are what you expect:
- Test by setting your customer destination to all sorts of different places and running through the shipping process several times. Please test thoroughly before committing to its use.
- If you fail to get quotes, an error message will usually tell you why. Make sure your origin information is correct and use the proper two-letter codes for your country and state/province.
- If you still don't get any quotes, you can enable logging which will record the request/response of the transactions and any cURL errors. Starting with v1.7, just update the shipping method's debug via your admin's Modules->Shipping, editing the upsxml module.
Version History
- 1.7.9, 2020-07-29 (lat9)
- BUGFIX: Time-in-transit missing if shipping-method name is translated.
- The following files were changed:
- /includes/languages/english/modules/shipping/upsxml.php.
- /includes/modules/shipping/upsxml.php.
- 1.7.8, 2020-06-29 (lat9)
- BUGFIX: Shipping-method names couldn't be translated.
- The following files were changed:
- /includes/modules/shipping/upsxml.php.
- Note: This update appends the UPS Service Code to the names of the individually-selectable shipping methods. If you are upgrading, it's very, very important to go to your admin's Modules->Shipping for your existing configuration to be updated. Otherwise, your customers won't receive UPS quotes.
- 1.7.7, 2019-10-23 (lat9)
- BUGFIX: Correct PHP notice when viewing in admin's Modules->Shipping.
- CHANGE: Display "New version available" information only when viewing the admin's Modules->Shipping.
- BUGFIX: Correctly offer "Next Day Air Early", if configured and provided in the UPS quote.
- BUGFIX: Sort quotes returned in ascending cost order.
- The following files were changed:
- /includes/modules/shipping/upsxml.php.
- 1.7.6, 2019-09-29 (lat9)
- BUGFIX: Correct insurance not recognized when using the shipping estimator.
- The following files were changed:
- /includes/modules/shipping/upsxml.php.
- 1.7.5, 2019-09-07 (lat9)
- BUGFIX: Correctly use UPS-supplied messages, if present, on a quote error.
- BUGFIX: Restore 'MODULE_SHIPPING_UPSXML_RATES_ORIGIN' setting, "lost" in v1.7.4.
- The following files were changed:
- /includes/modules/shipping/upsxml.php.
- 1.7.4, 2019-08-24 (lat9)
- BUGFIX: Remove unwanted directory-separator from UPS icon.
- BUGFIX: Remove single-quotes from numeric fields inserted on shipping-method installation.
- The following files were changed:
- /includes/modules/shipping/upsxml.php.
- 1.7.3, 2019-06-26 (lat9, benharold)
- BUGFIX: Correct undefined constants' issues (required for PHP 7.2+)
- CHANGE: Updated the shipping method's debug log filename to include the date on which the log was made.
- BUGFIX: Don't return methods if an error is reported by UPS.
- CHANGE: Remove support for Zen Carts prior to 1.5.3.
- The following files were changed:
- /includes/classes/xmldocument.php
- /includes/languages/english/modules/shipping/upsxml.php
- /includes/modules/shipping/upsxml.php.
- 1.7.2, 2018-01-22 (lat9)
- BUGFIX: Don't issue the invalid "Currency Code" message until the module is installed and enabled.
- BUGFIX: Don't request negotiated rates if the ship-to state has not been set (i.e. when used by the shipping-estimator).
- The following files were changed:
- /includes/modules/shipping/upsxml.php.
- 1.7.1, 2017-10-08 (lat9)
- BUGFIX: An invalid "Currency Code" resulted in invalid results returned when negotiated rates were enabled.
- The following files were changed:
- /includes/classes/xmldocument.php
- /includes/languages/english/modules/shipping/upsxml.php
- /includes/modules/shipping/upsxml.php.
- 1.7, 2017-09-23 (lat9)
- CHANGE: Updated /includes/classes/xmldocument.php for PHP 7.0+ interoperability.
- CHANGE: Added a "Shipper Number" field to the configuration. This value is needed if your store wants to receive your UPS-negotiated rates.
- CHANGE: Added configuration settings, allowing you to control whether or not the weight and/or transit-time displays should be included.
- CHANGE: Added a configuration setting to allow you to control whether or not the plugin's debug output is to be activated.
- CHANGE: Updated the plugin's "title", displaying the current version only during admin configuration.
- CHANGE: Refactoring for PSR2 and more strict PHP/MySQL versions.
- 1.6.1
- simply changed mysql_ function to mysqli_ for zen cart 1.5.5 and future PHP compatibility
- 1.5.1
- updated CURL implementation
- fixed PHP compatibility issues with PHP 5.3 and newer
- changed suggested logfile location to /logs/ folder
- removed the need to duplicate the xmldocument.php into the admin folder
- added Customer Classification Code 00 to get account rates (requires that you actually have negotiated rates)
- Compatible with Zen Cart 1.5.1, 1.5.2, 1.5.3, 1.5.4, 1.5.5
- 1.5:
- Updated Mexico Origin module names in language file
- included a logfile & logfile path, settings
- changed appropriate ups urls in install
Credits and Early Change History
- Updated/modified/repackaged for osCommerce 2.2 MS2 by Stuart Owens 11/14/04
- Time in Transit fixed by Greg MacLellan 11/15/04
- A few bugfixes and installation added to upsxml.php JanZ 11/27/04 (1.1.3)
- Bugfix for ship in cart: Jackie Edwards (1.1.3a)
- More options for cURL (CLI support added and logging of cURL errors) JanZ 12/18/04 (1.1.4)
- Updated/modified/repackaged for zen-cart 1.2.5d by Dennis Sayer 07/09/2005
Thanks to the many other authors who laid down their efforts in contributions from which has produced this. Your efforts are greatly appreciated:
- Original Contribution and updates - Torin Walker
- Time In Transit capability - Donna Gordon
- Bug fixes - Fox Morrey
- Admin selectable methods and bug fixes - Jan Zonjee/Stuart Owens
- Modified for zen-cart 1.2.5d by Dennis Sayer
- Tested for zen-cart 1.3+ by Dennis Sayer
- V1.5 testing, bugfixes and installation update - Brian Gundlach
- small fix for zen cart 1.5.5x and future PHP compatibility - lankeeyankee
A Note from Dennis Sayer
Thank you to Torin Walker for giving this code a GNU General Public License. I have removed your comments to web sites that no longer exist. I have also changed or deleted text that is not related to zen-cart.