Overview
The Spree checkout process has been designed for maximum flexibility. It’s been redesigned several times now, each iteration has benefited from the feedback of real-world deployment experience. It is relatively simple to customize the checkout process to suit your needs. Secure transmission of customer information is possible via SSL and credit card information is never stored in the database.The Checkout Flow DSL
Spree comes with a new checkout DSL that allows you succinctly define the different steps of your checkout. This new DSL allows you to customize just the checkout flow, while maintaining the unrelated admin states, such as “canceled” and “resumed”, that an order can transition to. Ultimately, it provides a shorter syntax compared with overriding the entire state machine for theSpree::Order
class.
The default checkout flow for Spree is defined like this, adequately demonstrating the abilities of this new system:
remove_transition
method of the Checkout DSL. The resulting transitions between states look like the image below:
These two helper methods are provided on Spree::Order
instances for your convenience:
checkout_steps
- returns a list of all the potential states of the checkout.has_step?
- Used to check if the current order fulfills the requirements for a specific state.
checkout_steps
method, which will return the steps in an array.
Default Checkout Steps
The Spree checkout process consists of the following steps. With the exception of the Registration step, each of these steps corresponds to a state of the Order object:- Registration Optional - only if using spree_auth_devise extension, can be toggled through the
Spree::Auth::Config[:registration_step]
configuration setting - Address Information
- Delivery Options Shipping Method
- Payment
- Confirmation
Registration
This section only applies when using
spree_frontend
and spree_auth_devise
gems.Spree::Order
state machine. The spree_auth_devise
gem (an extension that comes with Spree Starter by default) adds the check_registration
before filter to all actions of Spree::CheckoutController
except for obvious reasons the registration
and update_registration
actions, which redirects to a registration page unless one of the following is true:
Spree::Auth::Config[:registration_step]
preference is nottrue
- user is already logged in
- the current order has an email address associated with it
Disabling guest checkout
To completely disable guest checkout and require registration for checkout, you need to change Spree configuration inconfig/initializers/spree.rb
:
Address Information
This step allows the customer to add both their billing and shipping information. Customers can click the “use billing address” option to use the same address for both. The address fields include a select box for choosing state/province. If there are no states configured for a particular country, the select box will be replaced by a text field instead. The list of countries that appear in the country select box can also be configured. Spree will list all countries by default, but you can configure exactly which countries you would like to appear. The list can be limited to a specific set of countries by setting the Store’s checkout zone. Spree assumes that the list of billing and shipping countries will be the same. You can always change this logic via class decorator if this does not suit your needs.Delivery Options
During this step, the user may choose a delivery method. Spree assumes the list of shipping methods to be dependent on the shipping address.Payment
This step is where the customer provides payment information. This step is intentionally placed last in order to minimize security issues with credit card information. Credit card information is never stored in the database so it would be impossible to have a subsequent step and still be able to submit the information to the payment gateway. Spree submits the information to the gateway before saving the model so that the sensitive information can be discarded before saving the checkout information. Spree stores only the last four digits of the credit card number along with the expiration information. The full credit card number and verification code are never stored in the Spree database. Several gateways such as ActiveMerchant and Beanstream provide a secure method for storing a “payment profile” in your database. This approach typically involves the use of a “token” which can be used for subsequent purchases but only with your merchant account. If you are using a secure payment profile it would then be possible to show a final “confirmation” step after payment information is entered. If you do not want to use a gateway with payment profiles then you will need to customize the checkout process so that your final step submits the credit card information. You can then perform authorization before the order is saved. This is perfectly secure because the credit card information is not ever saved. It’s transmitted to the gateway and then discarded like normal. Spree discards the credit card number after this step is processed. If you do not have a gateway with payment profiles enabled then your card information will be lost before it’s time to authorize the card. For more information about payments, please see the Payments guide.Confirmation
This is the final opportunity for the customer to review their order before submitting it to be processed. Users have the opportunity to return to any step in the process using either the back button or by clicking on the appropriate step in the “progress breadcrumb.” This step is disabled by default, but can be enabled by two ways:-
globally for all orders by setting a preference in
config/initializers/spree.rb
: -
conditionally for specific orders by overriding the
confirmation_required?
method inSpree::Order
, eg.
Adding Logic Before or After a Particular Step
The state_machines gem allows you to implement callbacks before or after transitioning to a particular step. These callbacks work similarly to Active Record Callbacks in that you can specify a method or block of code to be executed prior to or after a transition. If the method executed in a before_transition returns false, then the transition will not execute. So, for example, if you wanted to verify that the user provides a valid zip code before transitioning to the delivery step, you would first implement avalid_zip_code?
method, and then tell the state machine to run this method before that transition, placing this code in a file called app/models/spree/order_decorator.rb
:
delivery
step if valid_zip_code?
returns false.
Modifying the checkout flow
To add or remove steps to the checkout flow, you can use the insert_checkout_step and remove_checkout_step helpers respectively. Theinsert_checkout_step
method takes a before
or after
option to determine where to insert the step:
remove_checkout_step
will remove just one checkout step at a time:
checkout_flow
helper: