Major/New Features

Rails 5.1 support

Spree 3.3 is now compatible with Rails 5.1 compared to 3.2 which used to run on Rails 5.0. Thanks to that you can start using all of the new great features available in Rails 5

Contributed by Josh Powell & Spark Solutions & John Hawthorn

Ruby 2.4 support

Spree now works with Ruby 2.2 (>= 2.2.7), 2.3.x and 2.4.x.

Contributed by Spark Solutions tracker integration

We’ve extended Tracker system to include other trackers besides Google Analytics. First of the bunch is Segment which enables you to connect your store with over 200 analytics engines, CRMs, live chats, remarketing platforms, A/B systems and much more. Now in Spree out of the box! No additional development required!

Developed during a Spree hackaton.

Contributed by Spark Solutions

Preventing duplicate values for number fields

We’ve added unique indexes and uniqueness validation on number field for those models:

  • CustomerReturn
  • Order
  • Payment
  • Reimbursement
  • ReturnAuthorization
  • Shipment
  • StockTransfer

This change will fix records with duplicate numbers. Migration scripts we’re take care of that.

WARNING migration process can take considerable amount of time, depending on volume of your data

Contributed by Spark Solutions

Added missing indexes and unique indexes

Besides number fields we’ve added multiple regular & unique indexes that were missing. This will keep data consistency of your app in check and also will boost it performance.

Contributed by Spark Solutions

Add quantity to inventory units and split on demand

Optimising Shipments and Inventory Units.

  • Creates a single inventory_unit per state, per line_item, per stock_location with a quantity field indicating inventory units in that state.
  • Adds a return_quantity field in ReturnAuthorization indicating the number of units to be returned/exchanged.
  • Split inventory unit to extract the portion/quantity that needs to be returned. This might be further split depending upon stock availability at the time of generating return.
  • Changes prioritizer and adjuster to maximise the number of on_hand items from available stocks in multiple stock_locations
  • Change splitters/weight.rb to use Worst Fit algo.

Contributed by Vinsol

Better Store Credits management in customer Frontend and Admin Panel

Store credit removal feature on spree front-end for partially paid order (with store credit payments). User can remove its store credit payment if additional payment is required/

Admin user can do the same from Admin Panel.

Contributed by Vinsol


Update your Rails version to 5.1

Please follow the official Rails guide to upgrade your store.

Update Gemfile

gem 'spree', '~> 3.3.0'
gem 'spree_auth_devise', '~> 3.3'
gem 'spree_gateway', '~> 3.3'

Update your extensions

We’re changing how extensions dependencies work. Previously you had to match extension branch to Spree branch. Starting from Spree 3.2 release master branch of all spree-contrib extensions should work with Spree >= 3.1 and < 4.0. Please change your extensions in Gemfile eg.:


gem 'spree_braintree_vzero', github: 'spree-contrib/spree_braintree_vzero', branch: '3-1-stable'


gem 'spree_braintree_vzero', github: 'spree-contrib/spree_braintree_vzero'

Run bundle update

Install missing migrations

rails spree:install:migrations
rails spree_auth:install:migrations
rails spree_gateway:install:migrations

Run migrations

rails db:migrate

Other Gotchas

Include UserMethods in your User class

With this release we’re not including this automatically. You need to do it manually if you’re not using spree_auth_devise.

You need to include Spree::UserMethods in your user class, eg.

class User
  include UserAddress
  include UserMethods
  include UserPaymentSource

Update aws-sdk gem to >= 2.0

Spree 3.3 comes with paperclip 5.1 support so if you’re using Amazon S3 storage you need to change in your Gemfile, from:

gem 'aws-sdk', '< 2.0'


gem 'aws-sdk', '>= 2.0'

and run bundle update aws-sdk

In your paperclip configuration you also need to specify s3_region attribute eg.

Seel also RubyThursday episode walkthrough of upgrading paperclip in your project.

Add jquery.validate to your project if you’ve used it directly from Spree

If your application.js file includes line //= require jquery.validate/jquery.validate.min you will need to add it this file manually to your project because this library was removed from Spree in favour of native HTML5 validation.

Noteworthy Changes

Also please review each of the noteworthy changes, and ensure your customizations or extensions are not effected. If you are affected by a change, and have any of your own tips please submit a PR to help the next person!

Full Changelog

You can view the full changes using Github Compare.

Noteworthy Changes