Spree/ShipStation Integration

TravisCI Code Climate

This gem integrates ShipStation with Spree. It enables ShipStation to pull shipments from the Spree store and update tracking numbers. This integration is ported from the Solidus extention https://github.com/boomerdigital/solidus_shipstation and made compatible with Spree 3 and Rails 5.1+.

See below for more documentation on the ShipStation API or how shipments and orders work in Spree:

Integration Overview

spree_shipstation exposes two API endpoints for ShipStation's Custom Store API to pull data from:

GET /shipstation
Will return an XML formatted, paginated list of order/shipment details for the requested time frame and conforms to ShipStation's specifed XML schema. However, in practice, ShipStation will use a narrow time frame (1 day) to request order updates. You can configure how often data is pulled in the ShipStation UI.

# GET Example

POST /shipstation
This endpoint allows ShipStation to send updates on a shipment. Below are the parameters you can expect to receive from ShipStation:

 "service"=>"USPS Priority",
# POST Example


Add spree_shipstation to your Gemfile:

gem 'spree_shipstation', github: 'matthewkennedy/spree_shipstation'

Then, bundle install

$ bundle install

Configure your ShipStation integration:

# config/initializers/spree.rb
Spree.config do |config|

  # ShipStation Configuration
  # choose between Grams, Ounces or Pounds
  config.shipstation_weight_units = "Grams"

  # ShipStation expects the endpoint to be protected by HTTP Basic Auth. Set the
  # username and password you desire for ShipStation to use
 if Rails.env.production?
  # You should set these in your Heroku Config Variables
  config.shipstation_username = ENV['SHIPSTATION_USERNAME']
  config.shipstation_password = ENV['SHIPSTATION_PASSWORD']
  config.shipstation_username = "MyUserName"
  config.shipstation_password = "MySuperSecurePassword123"

  # Turn on/off SSL requirepments for testing and development purposes
  config.shipstation_ssl_encrypted = !Rails.env.development?

  # Captures payment when ShipStation notifies a shipping label creation, defaults to false
  config.shipstation_capture_at_notification = false


Configuring ShipStation

To configure or create a ShipStation store, go to Settings and select Stores. Then click Add Store, scroll down and choose the Custom Store option.

  • For Username, enter the username defined in your config
  • For Password, enter the password defined in your config
  • For URL to custom page, enter your URL: https://mydomain.com/shipstation.xml

There are five primary shipment states for an order/shipment in ShipStation. Order is ShipStation's terminology, Spree uses Shipments. These states do not necessarily align with Spree, but in the store configuration you can create a mapping for your specific needs.

ShipStation mapping depends on your store's configuration. Please see the notes above regarding config/initializers/spree.rb and adjust your states accordingly.

ShipStation Status Title | ShipStation Status | Spree::Shipment#state
Awaiting Payment | unpaid | pending (won't appear in API response)
Awaiting Shipment | paid | ready
Shipped | shipped | shipped
Cancelled | cancelled | cancelled
On-Hold | on-hold | pending (won't appear in API response)

Payment Capture

By default the shipments exported are only the ones that have the state of ready, for Spree that means
that the shipment has backordered inventory units and the order is paid for. By setting
require_payment_to_ship to false and shipstation_capture_at_notification to true
this extension will export shipments that are in the state of pending and will
try to capture payments when a shipnotify notification is received.


Be sure to bundle your dependencies and then create a dummy test app for the specs to run against.

$ bundle
$ bundle exec rake test_app

To run tests:

$ bundle exec rspec spec

To run tests with guard:

$ bundle exec guard


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -m 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Future Work

  • Write better tests.


No comments yet

Please login to add comment.