Store 2 is a complete rewrite, and includes some major changes. While front-end templates should continue to work without any changes, third party PHP extensions or custom SQL queries will likely need to be rewritten.
As there is a large update script, please back up your files and database before starting the update process.
Store 2 requires at least PHP 5.3 and ExpressionEngine 2.6. ExpressionEngine should be upgraded before installing Store 2.
You must also set an encryption key in your config.php file, if you have not already done
so. Please see the Installation page for instructions on how to do this.
A number of variables in the checkout have been renamed, to make Store more consistent with other shopping carts and libraries. All existing template variables will continue to work, and will simply update the new variables instead.
billing_name and shipping_name have been split into separate first and last name
fields (for example billing_first_name and billing_last_name).
The billing_name and shipping_name variables are still fully supported as a shortcut
to retrieve or set the full name, and the name will be automatically split.billing_address3 and shipping_address3 have been renamed to billing_city and
shipping_city respectively. The old variables will continue to work but are deprecated.billing_region and shipping_region have been renamed to billing_state and
shipping_state respectively. The old variables will continue to work but are deprecated.The Product Tag (add to cart form) now requires that an item_qty field is submitted. Prior
to Store v2, this field could be left out and it would default to a quantity of 1. If you
want a simple add to cart button and don’t want to provide a quantity input to your customers,
then you need to add a hidden field to your add to cart form:
<input type="hidden" name="item_qty" value="1" />
If your add to cart button is not working after upgrading to Store 2, the most likely explanation is that you need to add this field to your form.
Store 2 brings huge improvements to our sales and discounts functionality. Sales may now be created globally, and applied to individual products, or entire categories of products. Sales may also be restricted to certain member groups (for example, you could give members in the “Wholesale” member group a blanket 20% discount on all products in a specific category).
“Promo Codes” have been renamed to “Discounts”, and are also much more flexible. Discounts can automatically apply to certain orders, or can optionally require the customer to enter a promotional code during checkout to receive the discount. Discounts can also be configured to apply to orders of products over a certain quantity, which means you can configure bulk pricing discounts, or “buy one get one free” promotions.
The difference between Sales and Discounts is as follows:
Sale prices can no longer be configured on the publish page, and all active sale prices will be migrated to the new sale system during the update process.
Store 2 now allows for multiple taxes per order, and individual taxes may be applied to specific categories of products (using the built-in ExpressionEngine entry categories). Because of this more powerful tax system, the old “tax exempt” option has been removed from the publish page. If you have previously configured “tax exempt” products, you must create a new category for them which does not have any taxes applied to it instead.
Store 2 also brings some much needed improvements to how tax-inclusive pricing is handled. Previously, all prices were entered excluding tax in the control panel, and then tax was added when prices were displayed on the front end. However, this led to complex rounding issues which needed to be accounted for in the checkout. It also made handling of promotional prices complicated, as they could only be applied to the pre-tax prices.
In Store 2, prices are entered in the control panel exactly as you want them to be displayed. Taxes may be configured as “included in price”, which indicates that the tax should not be added to the order total. For example, say you create a product which sells for $20.00, and a tax of 10% which is included in the price. In the checkout, when the customer purchases this item, they will see the item price as $20.00, a tax of $1.82, and an order total of $20.00.
If you have previously entered your products with tax-exclusive prices in the control panel, these will need to be adjusted. First, you should check the “included in price” option for your configured tax rate. Then, you can either manually adjust the product prices, or if you have many products, run a raw SQL query on your databae to bulk update them. For example:
UPDATE `exp_store_products` SET `price` = `price` * 1.1
Store 2 includes a new concept of “order adjustments”. Adjustments include discounts, shipping charges, and taxes which are applied to an order during checkout.
It is now possible to loop through and display all adjustments inside your checkout template. For example:
<table>
{adjustments}
<tr>
<td>{adjustment:name}</td>
<td>{adjustment:type}</td>
<td>{adjustment:amount}</td>
</tr>
{/adjustments}
</table>
If you are already displaying discounts, shipping, and taxes using the existing variables
{order_discount}, {order_shipping}, and {order_tax}, there is no need to update
your existing template. These variables will simply display the sum of any adjustments for
their respective type.
Store 2 includes a new, more powerful payment library called Omnipay. The new payment library is open source, and is already being used in hundreds of projects worldwide. It can be used in any PHP project, not just CodeIgniter (as our previous CI-Merchant library was).
Before upgrading, we recommend taking note of your payment gateway settings. While most payment gateway settings should be automatically upgraded, there is a chance these may be lost in the upgrade and you will need to reconfigure them.
Most officially supported gateways have been included, but any third-party gateways will need to be rewritten in the new format. If you have written a custom payment gateway for Store 1.x, please take a look at the Omnipay documentation for details on the new payment gateway format. If you were using an Expresso-developed payment gateway with 1.x which is not included in 2.x, please contact us for an upgraded version.
Store 2 has a much more flexible shipping library, which allows plugins to return multiple rates per order (for example, to display only those rates applicable to the current shipping destination). Shipping plugins are now treated as separate extensions and use the standard ExpressionEngine extension mechanism.
If you have developed your own shipping plugin, it will need to be updated to work with the new shipping plugin format. For more details, please see the Extension Hooks documentation.
Store 2 includes all new extension hooks. Third party extensions will not automatically be compatible, so should be upgraded or disabled before installing Store 2.