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:

ShipHawk Terminology

Term	Definition
Source	The system you are integrating ShipHawk with (typically an ERP system).
App	The name of the solution that contains the code that enables integration and interaction between Source and ShipHawk. “Connector” or “Plug-in” may be used interchangeably with App.
Order	In ShipHawk, an Order is the object in ShipHawk that represents an order that is ready for shipment.
Shipment	In ShipHawk a Shipment is the object that represents a shipment.
Proposed Shipment	A Proposed Shipment is an object in ShipHawk 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 generates Proposed Shipments asynchronously as Orders are created in ShipHawk. 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, the object that represents the location used to fulfill an Order.
Merchant	The business enterprise using ShipHawk 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

In ShipHawk, 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 sync with the ERP object that represents what’s ready to be fulfilled to create the Order object in ShipHawk, 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.

Create Your Integration Plan

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

Sync’ing of the ERP objects for shipment (e.g., item fulfillment or shipment objects) to ShipHawk Orders using an API request.
Sync’ing of ShipHawk shipments to the ERP shipment objects (e.g., item fulfillment or shipment objects) using webhooks or by pulling data from the ShipHawk API.
Rating of sales orders.
Providing an integration configuration screen on the ERP user interface, including the API configuration settings, ERP to ShipHawk 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. You’ll need to consider how you will manage the connection settings, including authentication and synchronization configuration between the ERP and ShipHawk. In addition, you should consider the mapping of the ERP’s order/shipment and line item fields to ShipHawk so that the ShipHawk orders can be created seamlessly. Likewise, you’ll need to consider how the integration will update the ERP with the shipment details from ShipHawk. Finally, it’s important to plan how you will log all the integration’s interactions between the ERP and ShipHawk.

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

Get Your ShipHawk API Key

Obtain your developer API Key in ShipHawk. In your ShipHawk account, set this up through Settings > Settings > Developer API > Create API Key. If you do not yet have a ShipHawk license, schedule a call with a member of our team to learn more.
Setup at least one Carrier Account in ShipHawk. FedEx or UPS is recommended. In your ShipHawk 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 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.

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

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.

Plan How To Update ERP with Shipment Data from ShipHawk

The recommended method for writing shipment data back to the Source is to setup and subscribe to ShipHawk 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 in batches. Existing endpoints can not be used for that because of inefficiency and potential issues with reaching ShipHawk 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.

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