Solidus provides a flexible system to calculate shipping by accommodating a wide range of shipment pricing: from simple flat rate calculations to more complex calculations related to product properties, but sometimes we found ourselves in situations where the shipping needs are way more complex, for example, dealing with addresses and different carriers.
In order to handle those scenarios, we can use a shipping API like EasyPost which provides a quick and powerful solution for handling parcel shipping and logistics process. With EasyPost you can track packages, verify addresses, buy labels, etc. In this blogpost, I will guide you through the process of adding EasyPost into your Solidus store.
Add the Solidus EasyPost extension
In your Gemfile add the following:
gem 'solidus_easypost'
Then in your terminal:
rake railties:install:migrations
rake db:migrate
And finally create a new file in config/initializers/easy_post.rb with the following content:
EasyPost.api_key = 'YOUR_API_KEY_HERE'
Getting your EasyPost API Key
In order to use EasyPost with Solidus, you need to create an account, go to EasyPost Signup and create your account, then copy your test api key into the previously created file.
Adding carriers to your EasyPost account
EasyPost allows you to retrieve shipping rates, buy labels, and track shipments from different carriers. Follow this guide to add your preferred carriers to your EasyPost account .
Customizing EasyPost
Now you are ready to start retrieving shipping rates based on carriers and addresses. By default the Solidus EasyPost extension makes the shipping methods unavailable to users, that’s why you first need to make a checkout to let Solidus know how many shipping methods you have available in your EasyPost account.
After trying to check out for the very first time with EasyPost you will see in the Solidus Admin Shipping section some new Shipping Methods like in the following image:
Go ahead and enable the ones that suit your needs the best.
Buying Shipping labels
By default, the Solidus Extension also buys the Shipping label when clicking the Ship button in the Solidus admin. If you want to avoid this behavior just add this configuration into the easypost.rb file:
Solidus::EasyPost::CONFIGS[:purchase_labels?] = false
Adding support for international Shipping
When shipping internationally, you go through the same steps as shipping domestically, except that you need to add customs information to your shipment. EasyPost uses this information to automatically generate the necessary customs forms for your shipment. You need to pass customs information whenever you are shipping between two countries.
The Solidus EasyPost Extension does not have support for international shipping by default, however, we can add it by following the next steps:
Creating customs items
To add information about your package’s contents, you need to create a CustomsItem object for each type of item you are shipping. If you have multiples of the same item in the package, you do not need to create a new CustomsItem for each one of them. You just need to specify the number of items when creating the CustomsItem object.
When creating a CustomsItem you need to provide the following:
- description = A brief description of the item
- quantity = Number of items contained in the package
- weight = Total weight in ounces of all the items of that type in the package
- value = Total value in US dollars of all the items of that type in the package
- hs_tariff_number = The six-digit code for your item as specified by harmonized system for tariffs. (We talk a bit more about this below).
- origin_country = Where the item was manufactured or assembled.
Solidus provides most of this information in the Shipment object, we are only missing the HS Tariff Number, this is the harmonization code associated with whatever product you are shipping. You can search for them onhttp://hts.usitc.gov/.
In order to add this value only once to every product we ship, we are going to add the following migration:
rails g migration AddHsTariffNumberToProducts hs_tariff_number:string
Now we need to add a form to allow users to fill in this value. In the app/views/spree/admin/orders/_shipment.html.erb Solidus Admin view we added the following:
Then, in the Shipment section of the Solidus Admin, you will see the form where you need to add the information required for customs
Once we have all the information required by the customs item, we need to proceed to create the object by decoratingapp/models/spree/shipment_decorator.rb with the following method:
You can find more information about extension decorators in the Solidus documentation here
Create a Customs Info Form
Once you have created the CustomsItem objects for the items you are shipping, you need to associate them with the customs form that we will be adding to your shipment. We call this form the CustomsInfo object. You will need only one CustomsInfo object per shipment.
In the same shipment decorator add
If your store does not have suppliers, you can add any name you prefer in the customs_signer field.
Create Shipment and Attach Customs Info
Now that you have created the required customs information, you can now create your international shipment. The only difference between domestic and international shipment is that you need to also pass the CustomsInfo object when creating an international shipment.
Finally, we just need to call either our easypost_international_shipment method or the easypost_shipment method provided by the Solidus EasyPost extension. We do this in the Shipment decorator we created before
Now you can start shipping internationally with EasyPost (if your carrier supports this option). Remember that carriers like USPS only ship internationally if you are a US-based business.
For more information about all the capabilities of the EasyPost API check out these docs here
Hopefully this blog will help you to start shipping with real-time carrier rates on Solidus. Thank you for reading!
