Solidus/ShipStation Integration

Update: This repository is no longer maintained. Please check out an active fork: https://github.com/boomerdigital/solidus_shipstation

This gem integrates ShipStation with Solidus, a fork of Spree. It enables ShipStation to pull shipments from the system and update tracking numbers. This integration is a fork of http://github.com/DynamoMTL/spree_shipstation to make compatible with Solidus and Rails 4.2+.

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

• ShipStation Custom Store Overview
• ShipStation Custom Store Dev Guide
• Spree::Order State Machine
• Spree::Shipment States

Integration Overview

solidus_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

Setup

Add solidus_shipstation to your Gemfile:

gem "solidus_shipstation", github: 'boomerdigital/solidus_shipstation'

Then, bundle install

$ bundle

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. You should also place these
  # values in to your `secrets.yml` file to make they configurable between stage/production
  # environments for testing purposes.
  config.shipstation_username = "smoking_jay_cutler"
  config.shipstation_password = "my-awesome-password"

  # 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

  # Spree::Core related configuration
  # Both of these Spree::Core configuration options will affect which shipment records
  # are pulled by ShipStation
  config.require_payment_to_ship = true # false if not using auto_capture for payment gateways, defaults to true
  config.track_inventory_levels = true # false if not using inventory tracking features, defaults to true
end

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, Solidus uses Shipments. These states do not necessarily align with Solidus, 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.

Caveats

1. Removed #send_shipped_email, which was previously available in spree_shipstation
2. If you change the shipping method of an order in ShipStation, the change will not be reflected in Spree and the tracking link might not work properly.
3. Removed the ability to use Spree::Order.number as the ShipStation order number. We now use Spree::Shipment.number. This was previously available in spree_shipstation
4. When capture of payments is enabled any error will prevent the update of the tracking number.

Testing

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

Contributing

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

• Improve documentation
• Update legacy development patterns (ex: class_eval)
• Update XML generation and parsing