Spree Commerce

Try It Now

Posts in category ‘Developer Resources’

The State of Extensions 2014

Posted on September 15, 2014 by Jeff Dutil

Over the course of Spree’s lifetime, there have been many extensions written. Some consist of features desired in Spree, and some consist of features removed from Spree. Many extensions were even written by Rails Dog before Spree Commerce was founded.

Over time, many of the extensions published to the Spree Spree Github Organization have been deprecated, become irrelevant, and been abandoned as community usage fell. This has lead to a lot of confusion about what is and isn’t officially supported by Spree Commerce. I’d like to take the time to clear up this confusion by announcing deprecated extensions, and what will be officially supported extensions going forward.

There are several reasons for these decisions, and we feel it will ultimately benefit the community. After all it was the Spree community who came up with the idea for the spree-contrib Github Organization at the last SpreeConf.


Providing a more centralized location to find Spree extensions, and a way for people to share their extensions is a big deal. We’ve seen lots of people trying to tackle the same problems, and releasing their own versions of extensions that never get found. This causes people to reinvent the wheel over and over again. We don’t want to see the extension ecosystem so fragmented that a dozen different people write their own Avatax or SOLR extensions. We believe making it easier for the community to collaborate on a single canonical project will make for better extensions with more support and less wasted time.


We want to broaden the committer base of many of these extensions, so that neglected extensions can be maintained by trusted developers outside of Spree Commerce. We don’t want to be standing in the way of the community upgrading extensions, and intend to make maintenance of extensions much easier and with a lower barrier to entry.

Managing Expectations

We think it’s important to manage community expectations by making it easier to tell what we support and what we don’t. There are lots of good extensions that we simply don’t support, but people still find useful. Luckily many of them live on, and are regularly updated by the community. Some extensions are not so lucky to have the community support, and when someone comes along trying to use a broken extension, it can understandably make them upset. We don’t always have the time to respond though, and we don’t want to leave people hanging on a response from us when we’re not even participating in the projects anymore.

Managing Time & The 80/20 Rule

We’ve had a long-standing 80/20 rule for Spree, and we believe it applies to the extensions we choose to officially support as well. When we receive new feature requests our rule of thumb is that if 80% of the people need this feature it’s probably worth inclusion. If something is a nice-to-have feature, but we only think 20% of people would use it then it’s probably not worth inclusion. Trying to please everyone, and simultaneously provide every feature is unsustainable. It also results in poor quality code.

Our goal is to provide the community with the best minimal, extensible, and flexible solutions that we can. In order to do that we’re focusing on what’s important to everyone, and will leave it up to the community to help us provide and support everything else.

Official Extensions:


Moving to spree-contrib:


Interested in contributing?

If you’re interested in contributing or helping to maintain any of these extensions please file an issue on the project, and we may grant you access depending on the extension. You may continue filing issues, and pull requests over on their new home in the spree-contrib organization as you normally would though.

Have an extension you’d like listed in spree-contrib?

If your extension serves a purpose not already covered by an extension or is a better alternative, we would be interested in providing it greater community support and visibility.

Some notable cases where we can already see this happening:

1. Thanks to Bonobos for providing a modern take on store credits & virtual gift cards.
2. Thanks to Ryan Bigg for providing a modern take on PayPal Express.

Follow Spree Commerce!

Novel Ways of Deploying Spree Featuring Dokku

Posted on April 24, 2014 by Bruno Buccolo

Dokku: The Smallest PaaS Implementation

Dokku is a new tool to deploy apps that has been getting a lot of attention lately. According to Jeff Lindsay, creator of Dokku and avid open source contributor, Dokku is the smallest PaaS implementation you’ve ever seen. After an easy setup on any host, you’ll have git push deployments and component based architecture. This post will explain how to test it out with a fresh Spree install.

Getting a Fresh Spree Install

This section will cover how to setup a clean Spree install. If you want to skip this process, just clone buccolo/spree_dokku then head over to Setting up Dokku .

The process is simple. We start by installing Rails, which will create a new Rails project.

$ gem install rails -v 4.0.4
$ rails new spree
$ cd spree/

Now add some goodies to the Gemfile:

gem 'pg'
gem 'rails_12factor'
gem 'spree', github: 'spree/spree', branch: '2-2-stable'
gem 'spree_auth_devise', github: 'spree/spree_auth_devise', branch: '2-2-stable'

Bundle up and add some sample data. Also pre-compile your assets to avoid a Dokku bug

$ bundle
$ bundle exec rails g spree:install --migrate=true --sample=true --seed=true
$ bundle exec rake assets:precompile

Now, start Rails and take a moment to admire your new Spree store. You can learn more about how to start using Spree in our Getting Started Guide

Everything is set, now we’ll need a Dokku server to deploy this to.

Setting up Dokku

Dokku is pretty easy to install. To make things even faster, we’ll use Digital Ocean, because it provides an Ubuntu application image with Dokku ready to go. Look for the image Dokku-v0.2.1 on Ubuntu 13.04. It’s recommended to use a server with at least 1GB of RAM, so you don’t swap.

After the server has been bootstrapped, visit the IP address on the browser to set-up Dokku. You can either configure DNS right know by pointing it to your new server, or manually configure the /etc/hosts in your machine so it looks good and you save yourself some trouble:

If you haven’t already, create a git project and commit your Spree store:

$ git init
$ git add .
$ git commit -am "Ready for Dokku"

Now, I promised you git push deploys a la Heroku, so let’s have it:

$ git remote add dokku dokku@sudokku.io:spree
$ git push dokku
Counting objects: 5, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 484 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
----- Building spree ...
       Ruby app detected


===== Application deployed:

Behind the curtains Dokku is creating a new Docker container and installing our app on it. Notice how we just added a new remote to our git repo and pushed. A Dokku server can serve many apps, making it a really good tool to deploy simple apps. If Ruby is not your thing, no problem; Dokku also supports NodeJS, Java, Scala, Python, Clojure and others!

Now let’s check our app in production, shall we?

Aww :(

What happened? Let’s use Dokku itself to debug, but first a quick alias to speed things up:

$ alias dokku='ssh -t root@sudokku.io dokku'

$ dokku logs spree
(erb):9:in `rescue in <main>': Invalid DATABASE_URL (RuntimeError)
        from (erb):6:in `<main>'

Right! We haven’t even configured a database yet! The Dokku way of solving this is by installing a Postgres Plugin. Now not only will we be able to deploy apps effortlessly, we’ll also be able to create Postgres containers. Installing a plugin is easy:

$ ssh root@sudokku.io

$ cd /var/lib/dokku/plugins
$ git clone https://github.com/Kloadut/dokku-pg-plugin
$ dokku plugins-install
$ logout

Now that we’ve installed the plugin, we can just run some commands to have a Postgres container created for us. The plugin also makes it easy to ‘connect’ a database container to our app container: by calling postgresql:link, the plugin will set DATABASE_URL environment variable and reload our app.

$ dokku postgresql:create spree-pg
$ dokku postgresql:link spree spree-pg
----- Setting config vars and restarting spree
DATABASE_URL: postgres://root:1234@
----- Releasing spree ...
----- Release complete!
----- Deploying spree ...
----- Checking status of PostgreSQL
      Found image postgresql/spree database
      Checking status... ok.
----- Deploy complete!

----- spree linked to postgresql/spree-pg database

Our database is ready. All we have to do now is run the migrations and create the admin user. For the sake of the example, we’re also setting an environment variable to demonstrate how easy it is and to skip configuring SSL: just to log into our app.

$ dokku run spree bundle exec rake db:migrate
$ dokku run spree bundle exec rake spree_auth:admin:create
$ dokku config:set spree RAILS_ENV=development

Whenever you change an environment variable, Dokku takes care of restarting your app. So you should be able to head over to the app to see it live. The screenshot below shows Spree’s admin screen:


Dokku is a pretty exciting tool that makes it really easy to deploy apps and attach services on-demand. You can see by the version number (0.2.1) that it might be too early to use it for complex scenarios. After all, it’s not fair to compare it to other large hosting providers, especially because the hosted PaaS solutions shine when it comes to reliability and scalability.

Further Reading

Why don’t online retailers collect sales tax?

Posted on January 09, 2013 by Erin Granville

Sales tax is already due on online purchases within the U.S. — but as you probably know, most online retailers don’t collect it. Why not?

It all comes back to location, location, location.

Sales tax is levied by the state, paid by state residents, and — usually — collected by the retailer at the point of purchase. The retailer then sends the sales tax collected to the state.

For most purchases, this system has worked well for over sixty years. But it becomes more complicated when the customer and the retailer are not located in the same state.

No matter what, sales tax must be remitted to the state where the customer lives. Otherwise — if, say, a retailer sends it instead to his or her own state — it’s taxation without representation. Customers are the ones who pay sales tax, and if that tax were sent outside their home states, they’d be paying taxes to support a state where they cannot vote and have no say in how those tax dollars are spent.

So a retailer who collects sales tax must be able to calculate the sales tax due for the customer’s home state and remit the tax collected to that state. No big deal when the retailer and customer are located in the same state, but it becomes more complicated for online and catalog retailers, who can sell to anywhere in the country. To collect sales tax on each purchase, these retailers need to know sales tax rates outside their own states.

Supreme Court Rulings

States have tried in the past to require these retailers to collect sales tax from their residents. Two cases ended up before the Supreme Court, both long before online shopping was a reality: National Bellas Hess v. Illinois Department of Revenue (1967) and Quill v. North Dakota (1992). In both, the Supreme Court said that a state cannot require an out-of-state retailer to collect sales tax unless the retailer has a physical presence in the state, because it would be too difficult.

Fast forward to today: Online retailers, like catalog retailers, are selling to residents of states where they have no physical presence. So the Supreme Court decisions apply to online retailers as well. If they don’t have a physical presence in a state, they don’t have to collect sales tax for that state.

Interestingly, though, the Supreme Court said in its Quill decision that Congress should really be the one to say whether states can require out-of-state retailers to collect sales tax.

Congress has declined to take up the issue until now, but most observers agree that that will soon change. In the next post in this series, we’ll look at some of the ways Congress may choose to address online sales tax and how that could transform the sales tax landscape.

About the Author

Erin Granville is Communications Editor at FedTax, the proud creators of Tax Cloud.

TaxCloud is a free, easy-to-use sales tax management service for retailers. It handles every aspect of sales tax, from calculation to collection to filing—all at no cost for retailers.

TaxCloud can be easily integrated into most accounting, order management, and shopping cart systems. It has been evaluated by states and an independent review board and has been designated one of only six Certified Service Providers in the nation.

Check out the Spree Tax Cloud extension written by Spree Community member Jerrold Thompson to integrate TaxCloud with your Spree store.

  • Join the discussion: How have you dealt with sales tax issues for your e-commerce store?

Upcoming Changes to Checkout Customization

Posted on July 11, 2012 by radar

A lot of our users have complained about how hard it is to customize the checkout flow of Spree. Some of our users wanted to remove the delivery step when
shoppers had only digital goods in their cart. Others wanted to remove all the steps except for address. Another group wanted to be able to add steps to the
checkout process in between the currently existing steps.

Currently, you need to override the entire state machine inside the Spree::Order class to do this, even including events that you shouldn’t need to care
about, such as cancel and return authorizations.

We’ve recently had a long discussion about this on an issue brought up by one of our users, Colin Gemmell. In this
instance, Colin wanted to re-define the state machine, but ran into problems where in doing so, it would raise spammy warnings about method redefinitions.
It would seem that the current practice of overriding the entire state machine is a bad idea.

So to fix this, we thought about the problem for quite a while. What we’ve come up with after quite a lot of thinking about it is a tidy DSL that will allow you to define the checkout flow for orders in a Spree store. This DSL is built on top of the DSL that the state_machine gem provides, and looks like this:

Order.class_eval do
  checkout_flow do
    go_to_state :address
    go_to_state :delivery
    go_to_state :payment, :if => lambda { payment_required? }
    go_to_state :confirm, :if => lambda { confirmation_required? }
    go_to_state :complete
    remove_transition :from => :delivery, :to => :confirm

This new DSL is all about not redefining the entire state machine. Everyone who’s attempted to customize the checkout process has inevitably done so because they wanted to alter the checkout flow. That’s what this new DSL will allow you to do. Rather than editing the entire state machine, the new DSL will only define the transitions that are to happen during the next event, which is what is used during the checkout process.

This new checkout_flow is used to define the flow of the checkout around each Order object. The go_to_state method will define a transition from the previous state into the new state. If the go_to_state call has an if on the end of it, it will keep track of all states until it finds a state that does not have a conditional. Once that happens, transitions will be defined for the intermediary states.

The remove_transition method will remove the transition specified, if it exists.

To understand this better, take a look at this handy image:

Given the above state machine, the following transitions will be defined:

  • Cart to Address
  • Address to Delivery
  • Delivery to Payment
  • Delivery to Confirm
  • Delivery to Complete
  • Payment to Confirm
  • Payment to Complete
  • Confirm to Complete

The “Delivery to Confirm” transition will be removed by the remove_transition call however, meaning that it will be impossible for orders to transition from delivery to confirm.

We believe this will make it easier for people to customize the state machine than has ever been possible before. Look for it in the next Spree release!

Spree Command Line Tool

Posted on January 12, 2012 by cmar

We have moved the spree binary to its own gem. The new spree_cmd gem includes a rewritten binary to add Spree to an existing Rails application.

Start by installing the latest release candidate for Spree. Then install Spree into a new Rails app with the command line tool. It will modify your Gemfile, copy migrations, set up your initailizers and generate sample data.

<p>$ gem install spree -v=1.0.0.rc2 &#8212;pre<br />
$ rails new my_store<br />
$ cd my_store<br />
$ spree install &#8212;edge</p>

If you would like to add spree without being prompted you can pass the --auto_accept option.

The Spree gem has lots of dependencies (which are normally handled when using bundler.) If you have trouble installing the Spree gem try installing spree_cmd directly and use the following alternative approach.

<p>$ gem install spree_cmd &#8212;pre<br />
$ rails new my_store<br />
$ cd my_store<br />
$ spree_cmd install &#8212;edge</p>

The extension generator has been moved to spree_cmd as well. It will generate a folder with all the setup needed to integrate your extension with a Spree application.

$ spree extension my_ext

It will generate a Versionfile for you. This is used to designate which version of your extension will work with different releases of Spree. Read more about Versionfiles

If you are going to release your extension publicly. Please register your extension

Updated Contribution Guidelines

Posted on August 31, 2009 by Sean Schofield

We have recently updated the contribution guidelines in our online documentation. Please be sure to review this document before you start working on a contribution to Spree. The highlights are as follows:

  • Always create an issue in Lighthouse before coding
  • Create one branch for each LH ticket
  • Please do not send Github pull requests
  • Use the optional Github service hook to inform us of your patch when done (see the guide for details)
  • The Spree guides themselves are open source, see the instructions on how to contribute fixes (typos, outdated examples, etc.)

Updating Searchlogic

Posted on July 30, 2009 by paulcc

Spree core now uses Searchlogic version 2.1.13 (unless a new version appears whilst I am writing). This has meant a few changes to how search and pagination are set up, but also allowed a few details of Spree to be improved at the same time. Extension developers will benefit too – the new gem is much more flexible, and easy to use. Marcin (Swistak) suggested that it might even go a fair way to providing the functionality we wanted in product groups, and I think he has a good point.

So, what’s new? Searchlogic has been completely rewritten in version 2, and uses a different approach to version 1. It now focuses more on key functionality and less on reinventing the wheel, e.g. control of pagination has passed back to the pagination gems. As a result, the code has gone from  ~2300 loc to ~420 loc. However, several useful bits of functionality have been added. For more information, see the github project and the rdoc documentation.

I think there’s two sides to this new version. Firstly, it provides a wide set of named scopes which you can use alongside existing ones. These are all dynamically generated, and able to follow model structure – including all associations, and to apply a range of tests to the fields identified. Here’s some examples from the documentation:

  • Within a model, filtering by various tests on fields:
    User.username_equals(&#8220;bjohnson&#8221;)<br />
    User.username_begins_with(&#8220;bjohnson&#8221;)<br />
  • Using associations (note the change of naming convention):
  • Scopes for ordering:
  • List modifiers, eg test on a list of values for any or all hits – this is very useful (and more efficient than doing it yourself)
    User.email_like_any([&#8220;joe&#8221;, &#8220;bill&#8221;])

Secondly, there’s the search aspect. This allows searches to be defined on top of some base scope, and customized in various ways. The search option names follow the same pattern as the named scopes above, and can be chained together or set separately. For example:

search = User.search(:username_equals =&gt; &#8220;bjohnson&#8221;, :age_less_than =&gt; 30)<br />
search.email_contains(&#8220;bjohnson&#8221;)<br />
search.age_gt = 20</p>

Gotcha #1: it isn’t possible in this version to over-ride the a search in the base scope by supplying options to the search, eg. check out the following example. It could be a bug.

scope = Product.ascend_by_master_price<br />
search = scope.search().order(&#8220;descend_by_master_price&#8221;)<br />

As for a chain of named scopes, you can get results out of a search with all, first, etc – or use some pagination library like will_paginate to handle limited fetches. See app/controllers/admin/product_controller.rb for an example of this in use.

Form handling is also much easier. There’s no need to include 'admin' in the submit path (it is detected automatically), and no need for fields_for to access associated records – you just need to adjust the field names to follow the new naming convention, eg for product search, you can search for variants_sku_contains to look for a substring in the sku field of any of the product’s variants. Particularly note how the check boxes have been brought within the searchlogic framework: the concepts represented by the check boxes map directly to one of the new-format searchlogic queries, so naming the box after the relevant condition is all you need to do.

Finally, if you are migrating from an earlier version, you need to run rake spree:upgrade and check that the will_paginate gem is listed in config/environment.rb, and also ensure that config/initializers/searchlogic.rb has been removed.