Spree 3 to ShipStation Extension
Last updated on: April 13 at 01:42 PM
source code bug trackerThis 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:
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
localhost:3000/shipstation?action=export&end_date=12%2F31%2F2016+00%3A00&format=xml&start_date=01%2F01%2F2016+00%3A00
POST /shipstation This endpoint allows ShipStation to send updates on a shipment. Below are the parameters you can expect to receive from ShipStation:
{
"SS-UserName"=>"this-is-my-username",
"SS-Password"=>"this-is-my-password",
"action"=>"shipnotify",
"order_number"=>"R1334232",
"carrier"=>"UPS",
"service"=>"USPS Priority",
"tracking_number"=>"12312312001303",
"format"=>"xml"
}
# POST Example
localhost:3000/shipstation?action=shipnotify&order_number=ABC123&carrier=USPS&service=USPS+Priority&tracking_number=123456&format=xml
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']
else
config.shipstation_username = "MyUserName"
config.shipstation_password = "MySuperSecurePassword123"
end
# 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
end
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.
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) |
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
git checkout -b my-new-feature
)git commit -m 'Add some feature'
)git push origin my-new-feature
)tags | spree versions |
---|---|
master | >= 3.1.0, < 4.0 |