Overview

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

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

Terminology

Understanding Orders in ShipHawk

Orders in ShipHawk represent any kind of order (sales orders, purchase orders, transfer orders, and so on) that contains items/SKUs that are ready to be shipped.   

In some ERPs, the concept of what’s been purchased is separate 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 items that are ready to be fulfilled.  Similarly, Acumatica has Sales Orders (what’s been purchased), and then Shipments (what’s ready to be fulfilled).

In almost all cases, you will want to 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 items that are ready (and in inventory) to be shipped. 

Integration Steps

The following is a high-level summary of integration steps.

Step 1. Map out your integration plan

As you think about building your integration, you will need to consider the following:

• Installing/uninstalling the App that connects ShipHawk and the ERP/Source

• Managing settings like authentication and syncing entities

• Managing Order and Line Item field mappings

• Creating Orders in ShipHawk

• Updating the ERP/Source with shipment details from their ShipHawk

• Log all interactions with ShipHawk APIs

Step 2: Obtain your 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.

Step 3. 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, like: 

• 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.

Step 4. Send syncing entity as Orders 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.  

If the POST to Orders is successfully created in ShipHawk, the connector should:

• Record that the shipment has been sent to ShipHawk with a date/time stamp

• Record the successfully created order_id from ShipHawk in [ERP/Source]

If the POST to Orders is NOT successful, the connector should:

• Log failures including error messages provide by ShipHawk

• Provide a method for the Merchant to manually retrigger a sync

When POSTing Orders to ShipHawk, remember, the payload MUST include the Warehouse Codes for each Location the order or shipment is shipping from so that the correct warehouse fulfills it in ShipHawk. We expect the customer will add the Warehouse Code from ShipHawk to location in [ERP/Source] so that the Warehouse Code can be sent to ShipHawk with the Order or Order Line Item Warehouse Code reference.  This is critical to ensure that the order is fulfilled from the right Warehouse location, and remember to pass warehouse code at both Order and Order Line Item level: 

Order level looks like: "warehouse": {"code": "CA_Warehouse"}

Order line item looks like : "warehouse_code": “CA_Warehouse”

Standard Order fields usually include: order number,  warehouse code, destination address (the recipient), billing_address (the person billed for the order, almost always the same as recipient, unless it is a gift order), total price, items, shipping price, source system id 

Full list: https://docs.shiphawk.com/#order-object  

Standard Order Line Items  usually include: name, SKU, quantity, value, warehouse location, dimensions, weight, harmonization code, country of manufacture/origin, source system id

Full list: https://docs.shiphawk.com/#order-orderlineitem-object

Step 5. Update Source 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.    

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.