Overview

This ShipHawk TMS ERP Integration Guide is for ShipHawk partners and third-party developers building an integration between an ERP system and ShipHawk TMS.

To learn more about ShipHawk’s features and capabilities, see the ShipHawk Guide.

The page introduces key concepts and information for building an integration:

1 ShipHawk TMS Terminology
2 Understanding Orders in ShipHawk TMS
3 Integration Planning

ShipHawk TMS Terminology

Term	Definition
Source	The system you are integrating ShipHawk TMS with (typically an ERP system).
App	The name of the solution that contains the code that enables integration and interaction between Source and ShipHawk TMS. “Connector” or “Plug-in” may be used interchangeably with App.
Order	In ShipHawk TMS, an Order is the object in ShipHawk TMS that represents an order that is ready for shipment.
Shipment	In ShipHawk TMS a Shipment is the object that represents a shipment.
Proposed Shipment	A Proposed Shipment is an object in ShipHawk TMS that represents the intermediate state between an Order and a Shipment. A Proposed Shipment contains the details about how certain items from an Order should be shipped. ShipHawk TMS generates Proposed Shipments asynchronously as Orders are created in ShipHawk TMS. A Proposed Shipment is a mutable object that the warehouse team interacts with during fulfillment. In contrast, a Shipment (and its package details) is not editable once created: a Shipment can only progress to a status of ‘delivered’ or ‘cancelled’.
Warehouse	In ShipHawk TMS, the object that represents the location used to fulfill an Order.
Merchant	The business enterprise using ShipHawk TMS for its fulfillment process, such as an eCommerce company.
Customer	The Merchant’s customer: a buyer, consumer, or recipient the items being shipped.

Understanding Orders in ShipHawk TMS

In ShipHawk TMS, Orders represent one or more items/SKUs that are ready to be fulfilled (ready to be shipped).

In many ERPs, the concept of what’s been purchased is distinct from the concept of what’s ready to be fulfilled. For example, NetSuite has Sales Orders (what’s been purchased), and then Item Fulfillments (what’s ready to be fulfilled). While the Sales Order contains all of the items purchased, the Item Fulfillment contains only the particular items that are ready to be fulfilled at a particular time. Similarly, the Acumatica ERP has Sales Orders (what’s been purchased), and then Shipments (what’s ready to be fulfilled). ERPs typically use the term “sales orders” for what has been purchased by a customer, but different ERPs can have varying terms for what’s ready to be fulfilled for a given sales order.

You should have ShipHawk TMS sync with the ERP object that represents what’s ready to be fulfilled to create the Order object in ShipHawk TMS, to ensure you only fulfill the specific items that are ready (and in inventory) to be shipped.

Integration Planning

The following is a high-level summary of topics you should consider when planning an ERP integration with ShipHawk TMS.

Create Your Integration Plan

For developers, a high-level checklist of all working parts required for an ERP integration with ShipHawk TMS includes the following:

Sync’ing of the ERP objects for shipment (e.g., item fulfillment or shipment objects) to ShipHawk TMS Orders using an API request.
Sync’ing of ShipHawk TMS shipments to the ERP shipment objects (e.g., item fulfillment or shipment objects) using webhooks or by pulling data from the ShipHawk TMS API.
Rating of sales orders.
Providing an integration configuration screen on the ERP user interface, including the API configuration settings, ERP to ShipHawk TMS field mappings, logging, and other settings as needed.

As you think about building your integration, you should consider how you want to install (and uninstall) the app that connects the ERP and ShipHawk TMS. You’ll need to consider how you will manage the connection settings, including authentication and synchronization configuration between the ERP and ShipHawk TMS. In addition, you should consider the mapping of the ERP’s order/shipment and line item fields to ShipHawk TMS so that the ShipHawk TMS orders can be created seamlessly. Likewise, you’ll need to consider how the integration will update the ERP with the shipment details from ShipHawk TMS. Finally, it’s important to plan how you will log all the integration’s interactions between the ERP and ShipHawk TMS.

To plan in more detail, see the following pages that define the integration requirements:

Get Your ShipHawk TMS API Key

Obtain your developer API Key in ShipHawk TMS. In your ShipHawk TMS account, set this up through Settings > Settings > Developer API > Create API Key. If you do not yet have a ShipHawk TMS license, schedule a call with a member of our team to learn more.
Setup at least one Carrier Account in ShipHawk TMS. FedEx or UPS is recommended. In your ShipHawk TMS account, set this up through Settings > Carriers > Select Carrier. You will need this for testing later.

Review Settings and Field Mapping Requirements

Your application will need to store the ShipHawk TMS API Key and should consider supporting multiple environments, future API versions and enhancements, such as:

Production: https://shiphawk.com/api/*
Sandbox: https://sandbox.shiphawk.com/api/*

We recommend masking the API key for security purposes and allowing the user to specify the API URL so that future API changes or testing may be easily accomplished.

You will also notice that the settings can allow for a syncing entity decision. Be sure to sync with the shipment entity (Example: in Acumatica, the Shipment entity, in NetSuite, the Item Fulfillment entity).

Order and Order Line Item Mapping are critical when dealing with Source systems as many ERPs and order source systems provide a lot of flexibility for Merchants they support. You will want to create Order and Order Line Item level mapping so that fields in your Source system can be assigned to standard fields or order- / line-level reference fields in ShipHawk TMS.

Example: Here is an example of some basic field mapping in an Acumatica ERP integration with ShipHawk:

In addition to field mappings, you will want to code source_system as the “[ERP/Source Name]” and source_system_domain as a unique identifier for each [ERP/Source] account. This makes it easy to know which system is being interacted with and can display this information inside ShipHawk.

Plan Process for Syncing ERP to ShipHawk TMS

Create a process for sending the syncing entity object information as Orders to ShipHawk. This is usually done by a scheduled job (for instance, every 5-15 minutes) for all transactions that have a certain status or value prior to being available to sync to and have not already been sent to ShipHawk TMS.

Plan How To Update ERP with Shipment Data from ShipHawk TMS

The recommended method for writing shipment data back to the Source is to setup and subscribe to ShipHawk TMS Webhooks. Instead of creating scheduled jobs, you can improve performance by setting up a webhook, subscribing to the shipment.create_from_order event and specifying a callback URL of your choice.

For ShipHawk to ERP sync, we have two options:

Use webhooks (recommended)
Create a new endpoint for pulling status updates from ShipHawk TMS in batches. Existing endpoints can not be used for that because of inefficiency and potential issues with reaching ShipHawk TMS API Limits.

Use webhooks if possible. Otherwise, scheduled jobs should minimize unnecessary usage and potential API charges. If going this route, the connector should be a good steward of the ShipHawk API, limiting the number of calls made to ShipHawk TMS.

For more information on setting up webhooks, see Setting New Webhook in ShipHawk .