The general upgrade process is outlined in the Upgrading section of the Shopp User Guide. This article provides technical notes and instructions for upgrading a Shopp 1.2 installation successfully to version 1.3 with the least amount of website interruptions. The Upgrading guide includes steps for performing a one-click upgrade through the WordPress Admin plugin manager. This article will focus on performing a manual upgrade and will require that you have all of the following before beginning:
- A WordPress Admin login
A login name and password with the Administrator role.
- A WordPress or other website backup solution
BackupBuddy or VaultPress are good WordPress plugin solutions. Other solutions may be provided by your web hosting provider that provide a whole website solution.
- FTP software
An FTP client to transfer files to your WordPress/Shopp installation.
- FTP login details
You will need the following details: FTP server name, FTP user name, FTP password.
- Maintenance mode software solution (optional)
For a professional website downtime experience for customers, temporarily privatizing the website during the Shopp upgrade process is recommended, but is not required.
The primary steps for a professional, successful upgrade includes the following:
- Download Shopp 1.3
- Setup the website into a maintenance mode (if able)
- Backup the website database and all website files
- Deactivate Shopp 1.2
- Replace Shopp version 1.2 files with Shopp 1.3 files
- Activate Shopp 1.3
- Upgrade custom templates (if necessary)
- Deactivate website maintenance mode (if active)
If possible, these steps should first be performed on a staging site before they are performed on a production site to ensure that everything functions as expected in the test environment. This will help identify problems early and will also provide the practice needed to develop a procedures guide for updating the live site.
Although included in the Upgrading section, backing up is so important that it deserves mentioning over and over.
Every upgrade should begin with a full backup. During any upgrade procedure for your e-commerce store, it is essential that you have a backup of your website database and all of the files for your website.
It is aslso essential that you know how to restore from backup by practicing the procedure. A backup is worthless if you do not know how to restore from it.
Shopp 1.3 includes a significant amount of internal rewiring. For websites that use custom programming this should be a red flag to review the custom code and ensure the following:
- Custom code should only use the functions provided by the Developer API or Theme API
- Custom code does not rely on any previously deprecated Developer API or Theme API functions
- Custom code does not rely on any internal objects or classes
- Custom code does not rely on action or filter hooks that have been deprecated
If you know you have custom code for Shopp in use on your Shopp 1.2 installation, but do not know if you have code that fts into any of the guidelines above, contact the developer responsible for the custom code. The official Shopp Support Team on the Help Desk cannot help you migrate custom code as the support team can only support official code distributed with Shopp 1.3. The support team may, however, be able to help you identify problem code, but the team cannot re-program the custom code for you.
Inclusive Tax Changes
In all Shopp versions prior to Shopp 1.3, installations using the Inclusive Tax setting would save product prices as tax exclusive amounts. Shopp 1.3 changes that approach and now saves the prices as entered in the admin. In order for the store to operate in a predictable way, all prices in storefronts using Inclusive Tax will be adjusted during the upgrade process by adding the tax back in to the prices.
While great care has been taken to upgrade different tax configurations correctly. There may be some tax settings that will not match during the upgrade and leave some prices unadjusted. This can happen specifically when tax rate settings are configured with complex conditions. Tax rates that use multiple conditions that are setup to match all of the conditions will not match during the upgrade and any product prices will not be adjusted for these tax settings. Tax conditions this specific will likely affect a very small number of products.
If your Shopp 1.2 installation used Inclusive Tax, be sure to review all product prices after the upgrade to Shopp 1.3 to verify they are correct. You may need to individually adjust some prices after the upgrade.
Google Checkout support ended November 2013 and is no longer included in Shopp as of 1.3. Additionally, PayPal Express Checkout has been removed from the core plugin and is now part of the PayPal Pro add-on for Shopp. The move was required to comply with PayPal distribution requirements for the PayPal Payments Pro service. If you wish to continue using PayPal Express Checkout without purchasing the PayPal Pro add-on, do not upgrade to Shopp 1.3, remain on Shopp 1.2.9. If you wish to upgrade to Shopp 1.3, you will need to purchase the PayPal Pro add-on to receive PayPal Express Checkout updates. If you upgraded to 1.3 unaware of the PayPal Express Checkout change, please contact Customer Service on the Help Desk for assistance.
Shopp Support Keys
Shopp 1.3 removed the support key code field from the setup screen. Shopp Support Keys are now distributed as a separate plugin you will need to download and install. To install a support key, download the support key plugin from your Shopp Store Account.
For owners of multiple keys, each key will be available as a separate Shopp Support Key download. The plugin is individualized with a certificate containing the key embedded inside it. Simply download the plugin and install it into WordPress. Activate the key and the Shopp installation will be activated with the server giving you access to the support team on that installation along with one-click updates to early access Shopp updates and Shopp add-ons from shopplugin.com.
Download Shopp 1.3
Shopp 1.3 can be downloaded from the Shopp website, or from your Shopp Store Account dashboard under the Downloads menu. It may also be downloaded from the WordPress plugin repo, but be warned that the the WordPress repo may be significantly behind in updates compared to the version available from the Shopp website.
The Shopp download is packaged in a compressed ZIP file. Uncompress the ZIP file to access the Shopp files inside it. Be sure to keep track of where the Shopp files are downloaded on your computer so that you do not have to scramble to find them later.
Activate Maintenance Mode (optional)
Setting the website to a maintenance mode is optional, but can improve the public perception of the quality of your website and protect your website database during the upgrade process. The goal of this step is to: communicate to your customers or potential customers and protect your website database from being altered by website visitors while you are upgrading the Shopp data in the database.
This step is not required, but is highly recommended. In some cases this is not worth the effort especially if the site does not receive much web traffic. For example, if the site is not yet public, or is public but has no marketing driving traffic to the site, or because the site was recently just started. In these cases, you may opt to save time by not setting up the maintenance mode.
Additionally, if you are not particularly experienced with setting up a maintenance message for your website, you may not wish to take the time to find a maintenance solution. However, it can be useful to know how to quickly setup a maintenance mode for your website for future maintenance needs.
There are several ways to setup maintenance mode for your website. Here are some of the popular approaches:
- Install and setup a WordPress that provides maintenance mode functionality
- Install and setup a theme designed specifically to provide a pre-launch message.
- For Apache web server hosted websites, use a
.htaccessfile to redirect others to a static HTML page.
Exact setup of any of these solutions is outside the scope of this article. If you are interested in specific step-by-step setup of a maintenance mode for your website, you are encouraged to do a web search for wordpress maintenance mode
Activate maintenance mode prior to backup, that way, if a restoration of the website is required, maintenance mode is already setup and active after you restore from backup giving you a margin to ensure everything is working before making the website available again.
Using your selected backup solution, make a full backup of all of the website files and the entire website database. Ensure that you are familiar with how to restore the website from the backup file following your backup solution’s instructions.
- Login to the WordPress Admin
- In the menus, locate and click the Plugins menu
- Find Shopp in the list of active plugins and click the Deactivate link to deactivate Shopp.
Replace Shopp Files
There are some important steps to take before replacing the Shopp files.
Move Custom Add-ons
Shopp 1.3 introduces support for a separate content directory for all of your Shopp add-ons. Create a new directory under
shopp-addons so that you end up with a directory path of
wp-content/shopp-addons/. It is highly recommended that you move all of your purchased and custom Shopp add-ons to this new directory. Shopp 1.3 will auto-detect them and load them like normal. Within
wp-content/shopp-addons/, you do not need to maintain separate sub-directories for
When moving payment gateways, be sure to leave
TestMode under the
shopp/gateways/ directory so that the new versions that are shipped in Shopp 1.3 will be used.
The shipping and storage addons that ship with the plugin are in a sub-directory named
core/. Leave the addons in
shopp/shipping/core/ in place so that they will be replaced with the new versions in Shopp 1.3.
Future upgrades of Shopp after 1.3 will not require you to perform this step any longer.
Replace Shopp 1.2
For this step, there are any number of ways to go about it. Here are some options:
- Download your Shopp 1.2 files to your computer using your FTP software (for backup).
- Move the Shopp 1.2 files out of the WordPress
wp-content/pluginsdirectory. For example, move the
wp-content/outside of the
- Simply remove the Shopp 1.2 files by deleting the
Upload Shopp 1.3
With the Shopp 1.2 files out of the way, upload all of the files from uncompressed ZIP file you downloaded earlier. Typically, the Shopp files will be uncompressed into a folder/directory named
shopp. Simply upload the
shopp folder/directory using your FTP software to your WordPress installation under
wp-content/plugins/ where your Shopp 1.2 files were located.
Wait for the upload to complete transferring all of the files. This can take anywhere from a couple minutes to 10 minutes depending on your connection.
Activate Shopp 1.3
Once the upload is complete you can activate Shopp again:
- Login to the WordPress Admin
- In the menus, locate and click the Plugins menu
- Find Shopp in the list of active plugins and click the Activate link.
Shopp 1.3 will automatically detect your Shopp 1.2 data and upgrade it to the new data structures needed for Shopp 1.3.
Verify The Upgrade
At this stage, it is important to perform a data integrity and configuration check to ensure the upgrade went smoothly. Here is a brief checklist you can use to verify everything upgraded smoothly:
- Check that all products show up in the Shopp product manager.
- For Shopp 1.2 installations using Inclusive Tax, verify that product prices were adjusted properly.
- Verify that your payment systems show up under Shopp → System &rarr Payments
- Verify that all of your shipping options show up under Shopp → System &rarr Shipping and be sure that rates for shipping calculators are still correct.
- Verify that all of your tax settings show up with the correct rates and correct target market settings, correct conditional rules (if used) and local tax rates (if used).
If there are problems, you will need to decide if the problems are too much to manually correct or adjust for (by adjusting prices, or setting up payment systems again). If so, you may wish to restore your Shopp 1.2 installation from backup. Before you do, be sure to document your issues with as much detail as possible so that they can be reported to the support team. Reporting your issues to the support team may not result in a direct resolution to your specific problem, but it can help the team correct the issues for the future or develop better upgrade guide documentation for others.
When to restore from backup
If you are missing a handful of products, or categories that you are confident you can re-enter quickly and easily, restoring and trying again may be overkill. On the other hand, if you are missing more than a few products or categories, or they are not assigned to the correct category, it is worth restoring and trying again or restoring and contacting the support team for assistance.
If certain store configuration settings are lost, particularly with shipping systems or payment systems, you may want to restore from backup.
Upgrade Custom Templates
If your website uses customized Shopp content template files (files located in your WordPress theme under a
shopp/ directory), you will want to ensure that you follow the Upgrading guide to upgrade the necessary templates for new Shopp 1.3 functionality.
When you are satisfied that the site is ready for use, deactivate your maintenance mode system so that the site is available to the public once again.
Congratulations on a successful migration to Shopp 1.3!