Spree Commerce

Try It Now

Spree 0.40.3 Released

Posted on February 17, 2011 by Sean Schofield

Spree 0.40.3 has been officially released. This is a minor patch release with a few fixes. All users should consider an immediate upgrade due to the recently announced security vulnerability in previous versions of Rails. Spree now requires Rails 3.0.4 which resolves this problem.

We also made an important fix for anyone using payment gateways that do not support a credit card profile (this includes the standard Authorize.net gateway.) If you are developing on a version of Spree 0.30.x with one of these gateways you’ve probably already experienced difficulties submitted the card details to the gateway. Theses issues are solved in version 0.40.3 along with a separate issue related to voids.

If you’re running a version of Spree less than 0.30.0 or if you are using Authoriz.net CIM then you are not affected by this problem (but upgrading is still recommended due to the security fix mentioned above.)

New spree_social extension

Posted on February 15, 2011 by Brian Quinn

Spree’s social integration has taken a great leap forward recently with the release of the spree_social extension. Development has been underway since late last year and was carried out primarily by one of the more recent Rails Dog pack members John Brien.

Current Features

The current release focuses on integrating Spree’s authenication system with major social networks and community sites, it provides the basis for several new social features to follow in the coming months. When configured users can auto-login to a Spree store using their Facebook, Twitter or GitHub accounts, with Google/GMail, LinkedIn and Yahoo! support to come soon.

Core Changes

spree_social necessitated several major core improvements including a migration to Devise (and the retirement of authlogic), which was previously released as part of Spree 0.40.0. This has given Spree a more open and extendable authenication platform that developers can now use to extend Spree in new and exciting ways.


Installation is very straightforward and well documented in the extensions README. Each authentication source can be configured via the administration system (see Configuration > Social Network Providers), and is flexible to support several combinations of providers in development and production modes.

spree_social is already in-the-wild and has been deployed in several production Spree stores, for more visit: https://github.com/spree/spree_social. You will also see it in the new and improved Spree demo which will be launching soon.

PayPal Express support updated for 0.40.x

Posted on February 10, 2011 by Brian Quinn

We’re glad to announce that Spree’s PayPal Express extension has been updated to support the latest edge version of Spree, which will soon be released as 0.40.3.

eCheck & IPN Support

The 0.11.x version of the extension has had basic eCheck and Instant Payment Notification support for sometime now, and this release also makes these features available for the 0.40.3 and later versions of Spree. See the documentation for more on configuring eCheck & IPN support.

Less Code

As part of this update the code has been reworked and we’ve reduced and simplied the code extensively. All Active Merchant monkey-patches have been completely removed and we’re now depending directly on the release version of ActiveMerchant (1.9.0). We’ve also refactored the checkout controller additions to use the new standard decorator approach.


This release also includes some initial specs covering the Checkout controller features, with more specs to follow for IPN shortly.


Finally spree_paypal_express has been renamed and given a new home under the Spree organization on GitHub, to bring in line with the other recently updated official extensions.

The newly updated extension can be found here

Spree Checkout - An Introduction

Posted on January 24, 2011 by Zac Williams

One of the more frequently discussed topics on the Spree Google Group is the checkout process in Spree. It is one of the most basic and important features of any e-commerce application, but it can also be very complicated under the hood. This post attempts to break down the various aspects of the checkout process in Spree.


In Spree, the checkout process is driven by the CheckoutController. The CheckoutController is unique within Spree in that it is not a typical RESTful controller. There is no ‘checkouts’ table, nor is there a Checkout model. The default CheckoutController implements a couple of actions (edit and update) that, at the most basic level, advance the state of an Order object.

Order Model

The Order model is a typical ActiveRecord class that encapsulates the attributes and business logic of an order. For purposes of this post, relevant bits of the Order model are: the definition of the states, events, and transitions (and related callbacks) for the Order state machine. (The Order model utilizes the state_machine gem to define the states, transitions, etc. For more information on state_machine, please see the state_machine Github page.) Below is the state_machine block for the Order model from Spree v0.40.2.


<p>state_machine :initial =&gt; &#8216;cart&#8217;, :use_transactions =&gt; false do</p>
event :next do
transition :from =&gt; &#8216;cart&#8217;, :to =&gt; &#8216;address&#8217;
transition :from =&gt; &#8216;address&#8217;, :to =&gt; &#8216;delivery&#8217;
transition :from =&gt; &#8216;delivery&#8217;, :to =&gt; &#8216;payment&#8217;
transition :from =&gt; &#8216;payment&#8217;, :to =&gt; &#8216;confirm&#8217;
transition :from =&gt; &#8216;confirm&#8217;, :to =&gt; &#8216;complete&#8217;
event :cancel do
transition :to =&gt; &#8216;canceled&#8217;, :if =&gt; :allow_cancel?
event :return do
transition :to =&gt; &#8216;returned&#8217;, :from =&gt; &#8216;awaiting_return&#8217;
event :resume do
transition :to =&gt; &#8216;resumed&#8217;, :from =&gt; &#8216;canceled&#8217;, :if =&gt; :allow_resume?
event :authorize_return do
transition :to =&gt; &#8216;awaiting_return&#8217;
before_transition :to =&gt; &#8216;complete&#8217; do |order|
rescue Spree::GatewayError
if Spree::Config[:allow_checkout_on_gateway_error]
after_transition :to =&gt; &#8216;complete&#8217;, :do =&gt; :finalize!
after_transition :to =&gt; &#8216;delivery&#8217;, :do =&gt; :create_tax_charge!
after_transition :to =&gt; &#8216;payment&#8217;, :do =&gt; :create_shipment!
after_transition :to =&gt; &#8216;canceled&#8217;, :do =&gt; :after_cancel


The most important event during checkout (in fact the only event called during a normal checkout) is the ‘next’ event. By examining the code above, you will notice that the ‘next’ event transitions the order through the various checkout steps: ‘cart’, ‘address’, ‘delivery’, ‘payment’, ‘confirm’ and ‘complete’.

Checkout routes

Assuming a customer has at least one item in their cart, they should be able to access the first checkout step at http://my-spree-store.com/checkout. Looking at the routes file in Spree Core, you will see that a GET request on /checkout/:state route’s to the CheckoutController’s edit action. Leaving the :state parameter blank will pre-populate the :state parameter with ‘address’:


<p>match &#8216;/checkout/update/:state&#8217; =&gt; &#8216;checkout#update&#8217;, :as =&gt; :update_checkout<br />
match &#8216;/checkout/:state&#8217; =&gt; &#8216;checkout#edit&#8217;, :as =&gt; :checkout_state<br />
match &#8216;/checkout&#8217; =&gt; &#8216;checkout#edit&#8217;, :state =&gt; &#8216;address&#8217;, :as =&gt; :checkout</p>

Rendering the checkout form

When the checkout/edit.html.erb template is rendered, a form is built that renders fields defined in a partial named with the same value of @order.state. For example http://my-spree-store.com/checkout/address renders checkout/edit.html.erb, which in turn renders [checkout/address.html.erb](https://github.com/railsdog/spree/blob/v0.40.2/core/app/views/checkout/address.html.erb).

Checkout Form Submission

Navigating through the various checkout screens by submitting the form performs a PUT request to the CheckoutController’s ‘update’ action. The first thing the ‘update’ action does after loading the order, update the order’s attributes with params[:order]. Assuming this is successful, the ‘next’ method is called on the updated order object, and the request is redirected to the next step in the checkout.

The Final Checkout Step

The final checkout step is the the ‘confirm’ step. During this step (http://my-spree-store.com/checkout/confim) the customer is allowed to review their order details one last time before placing the order. When the customer submits the form from this step, one final CheckoutController#update is executed, and the order transitions to the ‘complete’ state. At this point, the request is redirected back to the order_path and the checkout is complete.

state_machine callbacks

The Order state machine also defines various callbacks. For example, there is an after_transition callback that executes the Order#finalize! when an order transitions to the ‘complete’ state. I will leave it as an exercise for the reader to follow-up on what these callbacks actually do, but it is worth pointing out that they are present.

CheckoutController callbacks

In addition to the callbacks in the Order state_machine, there are also various callbacks that are executed before transitioning to/from various states. Again, the reader should investigate further, but you may want to start with load_order and update.