Report Toaster + Mechanic: Shipping Cost Integrations
Updated: Feb 16, 2022
Now that our integration with Mechanic is up and running, we have started putting it to use for our customers.
The first order of business was to create some Report Toaster tasks to retrieve shipping costs and assign them to Shopify orders.
Shipping Costs On The Rise
Report Toaster is one of the few apps that report the actual costs from shipping. As these costs keep increasing, it's even more important that merchants are able to track them. And as we wrote about in an earlier blog entry, determining your profit or loss from shipping is a key component of calculating the net profit from an order.
We'll look at each of these in turn.
As you may know, ShipStation is one of the most popular shipping platforms for Shopify and other eCommerce channels. As such, they have a public API that can be used to retrieve information about shipments, making this integration fairly straightforward. Let's break it down, Dr. Jack style!
Warning: The following content contains actual code. It is not intended for the technically faint of heart :-).
The screenshot above should look familiar if you've used Mechanic.
Here is the area where the task options are defined. This example is pretty straightforward, as the only options accepted are the API username and password for accessing the merchant's ShipStation account.
Also, note that the subscriptions use the shopify/orders/fulfilled webhook, which is fired each time an order is fulfilled (shipped).
From there, we can move to the fun part! In the code above, we call the ShipStation API with the order number which was just fulfilled to retrieve the shipment information.
(Note that we remove a potential "#" sign from the order number, as ShipStation does not include them.)
Once the result is returned from the ShipStation API, we parse it and update Report Toaster with any corresponding shipping costs. A few things to note here:
We use the built-in report_toaster action which is now available in Mechanic. Within that action, we use the update operation.
We use the order id instead of the order number, as Report Toaster can more directly access the order based on the order id. We could just have easily used the order number and the end result would have been the same.
We calculate the shipping cost to include the cost of any insurance, if applicable.
We are processing the updates one at a time, as there are very few instances when a single order produces multiple shipments. Our next example will show how updates can be batched to save processing time.
That's all there is to it! For anyone familiar with Mechanic, this would be considered a very straightforward task.
Pirate Ship is also used by many merchants, both Shopify and otherwise, to create shipments. However, they take a more no-frills approach and do not have an API available. So we had to get a bit more creative with this one!
Pirate Ship does allow a list of shipments to be exported as a CSV file, which includes the Shopify order number as well as the cost of each shipment. Using this file, we can update Report Toaster with the shipping costs.
Let's get back into some code!
Similar to the previous example, we will take a look at the Mechanic task options for this integration. Again these are pretty simple:
Order name column: The column name within the CSV file that represents the order number. By default, in the Pirate Ship export, this is "Order ID".
Order name prepend pound sign: Whether the pound sign needs to be added to the order number. When using Pirate Ship, this option should be checked, as their export does not include it. Of course, if the merchant does not use the pound sign, this option should be checked off.
Shipping cost column: The column name within the CSV file that represents the shipping cost. By default, in the Pirate Ship export, this is "Cost".
In the Subscriptions area, we will use the mechanic/emails/received event.
When a merchant installs Mechanic, an account specific email address is assigned (firstname.lastname@example.org). By using this event we can process any email sent to the Mechanic address.
Once we receive an email, the task code takes over. It simply iterates through each attachment, converting the CSV file to JSON. It then locates the order name and shipping cost for each entry in the file and adds them to a hash of updates to be processed.
Once we have all of our updates, we call the report_toaster action and that's it. Some cool things about this task:
It can be used with any CSV file, as long as it contains the order number and shipping cost somewhere in the file.
An email can include one or more attachments and each will get processed.
All of the updates are collected and then sent to Report Toaster in a single batch. This drastically reduces the time needed to process the updates.
Long Story Short
In summary, while tracking your shipping costs is important, it's not possible using the tools available in Shopify. However, as you can see from the above, we just showed you two very different ways to accomplish this using Report Toaster and Mechanic.
If you need to retrieve shipping costs from a source other than ShipStation or Pirate Ship, chances are they will have an API or make an export available, so these tasks should be reusable across third-party providers.
That's it for now. We will return soon with more cool stuff you can do with Report Toaster + Mechanic.