Client Login.

Justin Long // ExpressionEngine Expert

Initial Setup of Exp:resso Store

Written by: Justin Long | On: December 2, 2012

Initial Setup of Exp:resso Store

Wow! it has already been 3 months since my initial planning post was published. The last 3 months have been a complete whirlwind. I was able to attended EECI in Austin where I got to meet a ton of people from the community that I had previously only known through Twitter or Skype and was able reconnect with some old friends. I have been truly blessed this year to work with some amazing clients but I am looking forward to a lesser client load over the next couple of months to work on some exciting personal projects (including this series) that I have been putting off for way to long.

I want to pre-warn you that this article has a lot of content in it. You will need some time to read it but the actual workload of this article is very light so if you are following along don't be intimidated.

Installing Store

You will need to download the latest version of Store (1.6.1 currently). Once you have the latest version unzipped to your desktop you will need to move the "store" folder into you third_party folder. If you have not moved it with a config setting it will be located in system/expressionengine/third_party. You will then need to move the store theme folder into your themes/third_party/ folder.  Now we will need to login to the CP and install Store. Navigate to Add-Ons >> Modules. Find Store in the list and click install, on the next screen you will want to make sure that you select install for the Fieldtype too. Once you have completed the install process you will see that Store has created a new link in your header navigation. 

Settings in the Control Panel

In the settings area you will notice that there are 12 items in the left sidebar. In this part of the series I am going to talk about the General, Order Fields, Payment Methods (my next post will go into details on setting up a few different gateways), Shipping Methods, Countries/Regions, Tax Rates, Conversion Tracking, and Security tabs.

General Tab

Currency Symbol:
This field will control all output of the currency for Store fields on your site. Since I am based in the US I am going to be leaving mine as "$".
Currency Suffix:
If you currency has a suffix you can enter it here. I will be leaving it blank.
Currency Decimal Places:
Controls how many numbers are after the decimal place. I am going to leave it set to "2" for the US.
Currency Decimal Symbol:
Allows you to control the decimal symbol. The default "." works for me.
If you are going to be using "," as your decimal symbol you need to add
to your index.php and admin.php file to prevent database issues.
Currency Thousands Separator:
Allows you to control the symbol that appears for numbers in the thousands. I am going to be leaving the "," symbol.
Currency Code:
This will determine what currency Store uses to charge your customers. You will want to make sure that you are using the ISO 4217  standard for country codes. I will be using "USD".
Weight Units:
Allows you to set if weight will be measured in Pounds or Kilograms. I will be using "lb.".
Dimension Units:
Allows you to set the default unit that your products will be measured in Centimeters, Meters, Inches, or Feet. Since I am based in the US and most of my items are smaller I am going to set the base to "in".
Store Email Sender Address:
This will be the email address all Store related emails will show as the sender, if left blank it will revert to ExpressionEngine Default.
Store Email Sender Name:
This will be the name shown to your customers for all Store related emails, if left blank it will revert to the ExpressionEngine default.
Enable Store menu:
This is set to "yes" by default and will create the menu tab for all members that have access to Store. If you are using something like Zoo Flexible Admin to create customized menu items you may want to se this to no. I am going to leave it set to yes.
Default Shipping Address:
This will allow you to set a default shipping address for your customers. For example if you have "Shipping Address same as Billing Address" set you will be able to update Billing Address fields and it will also update the shipping address fields. The flip would be true if you select "Billing Address same as Shipping Address". You also have the ability to select "None" which means that a user would need to enter both a shipping and billing address. This doesn't however prevent you from having a checkbox on your checkout templates to copy the data from billing to shipping or visa-versa. For this tutorial I am going to select "none" but I will reference the other methods in a few parts of the tutorial to indicate behaviors that will be different then having "none" selected.
Credit Card Payment Method:
You have the options of Purchase (Authorize & Collect) or Authorize Only. For most stores you will want to select the Purchase option as it doesn't require you to manually capture payments before the transaction is finalized. I am going to be using the "Purchase (Authorize & Collect)" option for this series.
Round item prices after tax:
If you want to show a price including tax on the front-end of your site you will want to select "yes". For this example I will not know the taxes as they are being set based upon a users location so I am going to leave this set to "no".
Require member account to place orders:
Depending on the need of your site you can require that users must be logged into make a purchase. This will allow Store to link all purchases to the correct member id. This will allow you to easily create an account section to show current/past orders. In this series I don't want to require that users create a member account (even though I am going to encourage them to create one) to checkout so I am going to leave this set to "no".
Empty cart on member logout:
By default this is set to "Yes" which will empty the cart if a logged in user were to logout. I honestly can't think of a reason to set this to "no" so I will be leaving this set to "Yes".  
Cart Expiry Timeout:
By default this will cause your cart to be emptied of items every 24 hours if you do not complete an order. During development I like to lower this time down closer to an hour or two so that it clears more frequently when I am testing. For this series I am setting the expiry period to "90" minutes.
Require SSL connection for checkout and order tags:
By default this is set to "no" if you are allowing users to create member accounts I highly recommend that you have an SSL certificate even if you are using an off-site gateway. If you are using an on-site gateway you will be required to have an SSL certificate setup anyways. This setting will force all of your order and checkout tags to be server over HTTPS instead of HTTP. I have an SSL Certificate setup on my domain so I am going to set this to "Yes"

I have had a few people contact me about the process of setting up / creating an SSL certificate for use during development. I will be covering that in a separate post.
Order Invoice Path:
This will create a link in the Orders control panel that will allow your admins to easily jump to a customers invoice. You will need to specify the template on the front-end that you want the admin to be directed to. Since I am not 100% what my final url structure will be I am going to leave this blank for now.

Here is a screen grab of my final setup for the General Tab

Order Fields

If you are going to be allowing your members to create member accounts you will want to make sure that you make it as easy as possible to store their profile data. Store allows you to map the data that is collected during the checkout process and save it for future purchases. You will need to decide how you want to handle the storage of your Visitors data. You can store the data in Custom Member fields and use no other add-ons (I don't recommend this option). You can leverage an add-on that gives you more control of custom member fields output such as Exp:resso FreeMember ($0) or Solspace User ($99.95). Yet another option would be to use an add-on that allows you to store member data as channel entries, if you want/need to collect complex data from your customers this is the way to go. At the moment Store supports direct integration with Zoo Visitor ($59.99) alternatively you could use Profile:Edit ($49.99) but it will require additional setup on your part. In this series I am going to be using ZooVisitor for my members data.

Before you can setup Store to capture your members’ data you need to make sure the containers fields are there. Since I am using ZooVisitor I need to make sure that it is installed first and setup properly. Now you need to create the member fields to store the customer’s data. To do that I will need to navigate to Admin > Channel Administration > Channel Fields > Zoo Visitor Fields. By default you will see that ZooVistor has already created 6 fields, you can delete all of them accept member_account if you want. To add additional fields you will create them just like creating any other channel fields with a text input fieldtype. For simplicity I name all of my custom fields the same as the fields in Store that I am going to be mapping them to. Here is what my completed custom fields look like:

If you are using default member fields you will need to navigate to Member > Member Fields and create the custom member fields.

Now that you have all of your member fields setup you will need to go back to your Store Settings page and to the Order Fields section. As you can see from the screen grab that when you now select the dropdown all of the custom fields that you created show up and can be selected. In my screenshot I have created both ZooVistor fields and default Member fields just so you can see them both displayed. After you have linked all of your fields and save you should see something like this:

The great thing about getting this setup is you do not need to perform any conditionals or add additional code to your templates to get the values to display or change. You simply markup your fields and Store will automatically display the content if the user is logged in and has saved data.

Payment Methods

This is obviously one of the most important configuration steps of the entire process because we need to get paid somehow. Store allows you to setup multiple gateways if you need to. In this tutorial I am going to be setting up PayPal Express and Depending on which gateways you select you will have different credentials that you will need to enter. I am going to be publishing a more in-depth article that will give detailed setup instructions for a few popular gateways. If you have any specific ones you want me to cover make sure to leave a comment down below.

To create a new Payment Plugin to use with Store you need to simply click the "Add Payment Method" button. Then you will need to select which Payment Plugin you are using, the Name & Short Name should autofill once you have selected a plugin type and the lower section will change to allow you to enter the gateway specific details. Once you save you will see your newly created plugin displayed. You will need to repeat the same process for any additional payment gateways you need to create.

Countries / Regions

I wanted to skip over Shipping Methods really quick because settings that you set here will be reflected on the Shipping Methods page. By default Store has all countries enabled. If you do not want this to be the case you can disable any countries that you want. In this example I am going to only enable The United States and Canada. (I will publish an article at a later date that deals with other countries and the process behind that.) By default Store already has regions setup for the United States and Canada. Some countries will require that you add your own which is very straightforward. Simply click on the Country in question and you will be presented with all of the previously created regions and the ability to enter the Region name and Region Code. For example in the US you would see Ohio - OH. Once you have all of the countries and regions setup you optionally have the ability to select a default Country and Region. This will allow you to show estimated shipping rates or taxes without requiring the user to enter any information. If the user is logged in and has information stored that will of course override the default location that you have setup. In this series I am going to set the Default Country to the United States but going to leave the default region blank.  

Shipping Methods

If you will be shipping items to your customers you will need to setup at least one Shipping Method. There are currently 5 shipping methods available for Store Default Shipping Plugin, Australia Post, UPS, USPS, and FedEx. I will go over setting up each of them individually. To configure each of the plugins you need to start by clicking the "Add Shipping Method" button. You will be presented with a configuration page.

Default Shipping Plugin
By default this is the option that will be selected in the dropdown. To enable it all you have do is give it a name and click "Submit". You will be directed back to the Shipping Methods page, if you were to click on your newly created shipping method you will see a page where you can set up Shipping Rules. There are a few things to remember when you are setting up your shipping rules.  
  • The last rule in the list needs to be a catch-all rule because Store will go through your shipping rules in order and stop when it meets the first rule to match the customers cart. If it gets all the way though and you do not have a catch-all rule Store will display an error.
  • Rules are evaluated and matched in the order they are shown in the settings page.
  • Only one rule will be applied to a customers cart.
To add a new Shipping Rule click the "Add Shipping Rule" button. You will be presented with a page like this:  The first 3 options (Country, Region, & Postcode) will allow you to limit who is eligible for each shipping rule that you create. The next 6 options can be broken down into 3 groups (Quantity Total, Price Total, & Weight Total) you can use a combination of any of the 6 fields but personally I prefer to keep my shipping rules as simple as possible so I am going to only use Weight Totals to setup my shipping rules. There is one exception to this I am going to give all of my customers that spend over $100 free shipping.

The first rule I am going to setup is the free shipping rule. You will see that by default Store already has a rule created for you. We will need to edit that one. To set this rule up we simply need to add "100" to the "Minimum Order Total" field and save it. The second rule I am going to create is for orders with a total weight under 20lbs with a base rate of $5 and $1 for every pound the order weighs. So an order of 7lbs would have a $5 base charge and $7 for the weight for a total of $12. My setup looks like this. For my third rule I want to create a rule for all orders over 20lbs with a base rate of $7 and a $1.50 for every pound and a limit of $60 max for shipping charges no matter the weight. You can see my setup in the image below.  The last rule I am going to create is going to be are catchall rule. For this I am going to just assign a $5 base rate.  You might notice that some of your shipping rules don't always appear in the order that you created them or in the order that you might want. By default Store is going to weight your shipping rules based upon their complexity. So a rule that has a country and region specified will be shown (and ultimately evaluated during checkout) before a rule that just has a country specified. This makes sense as Store will only apply one rule per cart so more specific rules should be evaluated first usually. However in the example above I want to provide free shipping for orders over $100, which has very few options, selected so it will be evaluated later. Luckily Store as of version 1.6 has a priority field that will allow you to override the default functionality. For my free shipping rule I want it to be evaluated first so I am going to assign a value of 400 in the "Priority" field forcing Store to evaluate the rule first. If you have multiple rules with the same priority Store will revert back to the default way of handling rule based upon complexity.
Australia Post
Unlike the default shipping plugin above you will need to create a new method for each service type you would like to offer. You will want to give each shipping method a descriptive name. For example if you are going to be selecting Express shipping as the service I would give it a similar name as the method name. Once you have given the shipping method a name and save you will be directed to the next step: You will need to enter the Postcode from where you will be shipping items from in the "Source Postcode" field. Then select the service type that you want orders rate to be calculated at and you can optionally enter a surcharge that you want applied on top of the calculated rate.
Like the Australia Post plugin above the UPS plugin requires that you create a new instance of the plugin for each shipping variation that you want to offer your customers. To access the API you will need to have a UPS Account  for the shipping method to work properly. After you have logged into your account you can request API information you will want to copy the Access Key, User ID, and Password for your API application. If you have multiple UPS shipping methods you will need to reenter these details for each subsequent method. You will then have to select the Pickup Type, Delivery Type, Package Type, and if the packages will be insured or not. You will also be required to fill out the City, Zip and Country from where the items will be shipped.  Repeat for each additional UPS method you need to create.
You will need to register an account with USPS (do this early because they can take 2-3 days to actually set up your account) for the plugin to be able to calculate the rates properly. Unlike the UPS plugin above you will only your username to calculate rates. Like the UPS plugin you will need to create a new method for each shipping service you would like to offer to your customers. In addition to your username and shipping zip code you will need to select a Service Type, Mail Type, Container Type, Size, and Machineable.
You will need to register an account with FedEx Developer account. You will need to grab your API Key, Password, Account Number, and Meter Number as they will be required for every instance of the FedEx shipping plugin you create. You will then need to select the Dropoff Type, Service Type, and Packaging Type. You will also need to fill out the City, Zip, and Country that the items will be shipped from.

Tax Rates

You will be able to setup all of the taxes that will be applied to your customers. Like the default shipping plugin only one tax rate will be applied to each order, and the more specific the tax rule the higher up it will be evaluated by Store. For example if I have a rule for a 10% tax applied to the United States and I have a second rule that charges Florida at a rate of 7% the rule for Florida will be evaluated for Florida first then the US afterwards.

To set up a new rule you will want to click on the "Add Tax Rate" button. You will need to give your Tax Rate a name, which can be shown in the template, I like to name mine after the State that the rate applies to. You can then select a Country and Region based upon the countries and regions we enabled earlier. You will then need to enter the tax rate as a percentage 10% or 6.5% oppose to a decimal. You can then decide if the tax rate is also applied to the shipping cost or just the purchased items. Here is my completed tax rule for Florida: Here is all my current taxes:

Conversion Tracking

Store has built in Google Analytics tracking if you have chosen to have it enabled. For this to work properly you must have your normal tracking code JavaScript in the head of your site, the e-commerce tracking code will be added automatically on the orders summary page to let Google know that an order has been placed. This will only be added on the first view however to prevent duplicate data being sent to Google if the user is viewing the orders summary additional times.

You also have the option to add any additional analytics or conversion tracking code to be automatically added to your order summary page after a successful order. Most of the variables that are available in the Orders tag pair will be able to be parsed in your tracking code. For example you can use the {order_total_val} or {order_date} variables.


The security tab allows you to control who access to certain features in Store. By default any member group that has been granted to Modules and Store will be able to see the Dashboard, Orders, Inventory and Reports section if you have the menu tab enabled. Also by default Super Admins will always be able to access the Settings page and add Manual Payments in the Control Panel. For all other member groups that also have CP access you will need to manually assign them access to the Settings and Manual Payments feature.

Wrap Up

Store is now setup and ready to use, well almost… In the next entry of this series we will be covering Payment Processors and the setup process for each gateway. At the moment I have already written examples for PayPal Express, PayPal Pro, and Stripe but if you have one that you would like me to cover leave it in the comments below and I will try to get it added.

As always if you have any comments or questions post them in the comments below or send me a message.

Next entry >>> <<< Previous entry


<<< Go back to entry list