solidus_shipstation

This gem integrates ShipStation with Solidus. It enables ShipStation to pull shipments from the system and update tracking numbers.

This integration is a fork of spree_shipstation that adds Solidus and Rails 4.2+ compatibility.

Installation

Add solidus_shipstation to your Gemfile:

gem 'solidus_shipstation', github: 'solidusio-contrib/solidus_shipstation'

Bundle your dependencies and run the installation generator:

bin/rails generate solidus_shipstation:install

Configuration

Configuring solidus_shipstation

Configure your ShipStation integration:

# config/initializers/solidus_shipstation.rb

SolidusShipstation.configure do |config|
  # Choose between Grams, Ounces or Pounds.
  config.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.
  config.username = "smoking_jay_cutler"
  config.password = "my-awesome-password"

  # Capture payment when ShipStation notifies a shipping label creation.
  # Set this to `true` and `Spree::Configrequire_payment_to_ship` to `false` if you
  # want to charge your customers at the time of shipment.
  config.capture_at_notification = false
end

You may also need to configure some options of your Solidus store:

# config/initializers/solidus_shipstation.rb
Spree.config do |config|
  # Set to false if you're not using auto_capture (defaults to true).
  config.require_payment_to_ship = true

  # Set to false if you're not using inventory tracking features (defaults to true).
  config.track_inventory_levels = true
end

Configuring ShipStation

To configure or create a ShipStation store, go to Settings -> Stores -> Add Store, then scroll down and choose the Custom Store option.

Enter the following details:

Username: the username defined in your config.
Password: the password defined in your config.
URL to custom page: https://yourdomain.com/shipstation.xml.

There are five shipment states for an order (= shipment) in ShipStation. These states do not necessarily align with Solidus, but you can configure ShipStation to create a mapping for your specific needs. Here's the default mapping:

ShipStation description	ShipStation status	Solidus status
Awaiting Payment	`unpaid`	`pending`
Awaiting Shipment	`paid`	`ready`
Shipped	`shipped`	`shipped`
Cancelled	`cancelled`	`cancelled`
On-Hold	`on-hold`	`pending`

Usage

There's nothing you need to do. Once properly configured, the integration just works!

Gotchas

There are a few gotchas you need to be aware of:

If you change the shipping method of an order in ShipStation, the change will not be reflected in Solidus and the tracking link might not work properly.
When shipstation_capture_at_notification is enabled, any errors during payment capture will prevent the update of the shipment's tracking number.

Development

Testing the extension

First bundle your dependencies, then run bin/rake. bin/rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using bin/rake extension:test_app.

bin/rake

To run Rubocop static code analysis run

bundle exec rubocop

When testing your application's integration with this extension you may use its factories. Simply add this require statement to your spec_helper:

require 'solidus_shipstation/factories'

Running the sandbox

To run this extension in a sandboxed Solidus application, you can run bin/sandbox. The path for the sandbox app is ./sandbox and bin/rails will forward any Rails commands to sandbox/bin/rails.

Here's an example:

$ bin/rails server
=> Booting Puma
=> Rails 6.0.2.1 application starting in development
* Listening on tcp://127.0.0.1:3000
Use Ctrl-C to stop

Updating the changelog

Before and after releases the changelog should be updated to reflect the up-to-date status of the project:

bin/rake changelog
git add CHANGELOG.md
git commit -m "Update the changelog"

Releasing new versions

Your new extension version can be released using gem-release like this:

bundle exec gem bump -v 1.6.0
bin/rake changelog
git commit -a --amend
git push
bundle exec gem release

igorbp/solidus_shipstation