This ShipHawk ERP Integration Guide is for ShipHawk partners and third-party developers building an integration between an ERP system and ShipHawk.
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. |
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 ERP sales orders (send rating information from ShipHawk into the ERP).
✅ 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:
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 (e.g. 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.
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 per min made to ShipHawk.
To set up a new webhook, go to: ⚙️ (gear icon) > Settings > Webhooks > Actions > Create New Webhook. At a minimum, you will want to subscribe to the shipment.create_from_order event. Other events serve a variety of other use cases not relevant for basic order fulfillment. For more information about the data in these webhooks, you can review our webhook event types and payload examples.
Alternatively, you can always set up a scheduled job to GET /orders that have not yet been closed in the Source system.
Example: The syncing entity or fulfillment record in the Source will usually need to be updated with the following information at a minimum:
"carrier": "USPS",
"service_name": "Priority Mail",
"total_price": 7.17, // the shipping cost to write back to [ERP/Source]
"tracking_number": "9405510200864427693834",
“shid”: 368765 // the related Shiphawk Shipment ID
When fetching shipment data, you can use GET /orders/:id to accomplish this. Shipment details are provided in the “shipments” node in the order response object.