Building an Order Fulfillment Integration with ShipHawk

This guide will walk you through the common use cases for building an order fulfillment integration with ShipHawk, including best practices and common missteps.  The concepts within this guide can be applied to building order fulfillment integrations between ShipHawk and eCommerce shopping carts, order management software, warehouse management software or enterprise resource planning software. 

The guide assumes that integration is for connectivity purposes only and that Merchants use the ShipHawk user interface in the warehouse to find, finalize and fulfill orders.  

This guide covers the following topics:

Before You Start

Read through the object resources in ShipHawk’s API Docs. You'll need to know a few of these details to understand some of the cases and examples below and how to optimize your application. Read the following sections to familiarize yourself with core concepts:  

• Order resources

• Shipment resources

• Webhooks

Terminology

Avoid These Mistakes

Incorrect syncing entity

The concept of “Orders” in ShipHawk can be a bit confusing.  Orders in ShipHawk represent any kind of order (sales orders, purchase orders, transfer orders, etc.) that contains items/SKUs that are ready to be shipped.   

In many ERPs/Source systems, they separate the concepts of what’s been purchased from what is ready to be fulfilled.  For instance, NetSuite has the concepts of Sales Orders and fulfillment entities called Item Fulfillments.  The Sales Order contains all of the items purchased and the Item Fulfillment contains only the items that are ready to be fulfilled.  So which object from NetSuite should you use when creating Orders in ShipHawk?  

In almost all cases, you will want to use the Item Fulfillment to create the Order in ShipHawk because this ensures you only fulfill the items that are ready (and in inventory) to be shipped.  

The only time you would want to use the Sales Order to sync is if you do not need to worry if the inventory is available or not.  This is really only applicable to eCommerce shippers who usually (a) do not have a warehouse management system in place; and (b) do not need to worry about backorders because they only ship complete.

Missing Order Line Item Detail

When sending an Order to ShipHawk, you will always want to specify as much Order Line Item detail as possible.  While ShipHawk can store SKU information, we recommend passing the most current information along with the order_line_items when POSTing Orders.  

ShipHawk will prefer the API parameters over stored default  so that any changes that have been made will be honored at the time of Order POST.

Sending the wrong Item_Type

Item Type has a powerful impact on how ShipHawk processes your order line items.  In general, this should be left blank or sent with the value ‘unpacked’.  Any other value like ‘parcel’ or ‘handling_unit’ will cause unexpected behavior.  Unless you’ve discussed this with a ShipHawk solution engineer or support team member, do not use ‘parcel’ or ‘handling_unit’.

Missing Order-level and Line-level References

Initial passes at the integration often miss the power and value of Order-level and Line-level references.  ShipHawk does not have normalized fields for every possible order- or line-level detail.  Many Merchants have valuable information at the order- or line- level that they want to use when (a) applying shipping rules in ShipHawk; or (b) including these values on ShipHawk generated shipping documents like packing slips or parcel label references.  

While ShipHawk allows ‘unlimited’ order- and line- level references, we recommend only mapping what is necessary to trigger rules and create documents while fulfilling your orders.  

"reference_numbers": [{

      "code": "other_id",  

      "name": "Cust1",

      "value": "123456"

 }]

Misusing Origin Address and not specifying Warehouse Locations

Origin Address is a legacy node that we intend to deprecate for Orders.  For now, we recommend populating the Origin Address with the exact same address as the Warehouse Location you are fulfilling the order from when POSTing Orders.  Please note that it will be deprecated. 

ShipHawk uses Warehouse Codes to specify the warehouse the order is shipping from.  Warehouses are manually set up in ShipHawk and given a Code by the Merchant. Usually this is the same code or ID as the Warehouse or Location in their source system to simplify code development; however, it can be short sighted if you intend to have more than one source system connected to ShipHawk because codes may be different across systems.  This is a developer preference and can be solved many ways, but we recommend the simple approach to use the same code/ID as the main source system in your initial build.  

Warehouse Code may be specified both at the Order-Level and Line-Level.  This is done because of the various syncing entity approaches available.  Regardless of approach, we recommend that you send the warehouse code at BOTH the order and order line item level.   

Mishandling writeback information when updating Source system

Some Source systems have concepts for “Box size”, “Packing Material” “Shipping Method” or “Ship Via” that, if not supplied when updating the Order source system, causes the writeback to fail.  Make sure you map out the required fields between ShipHawk and your Source system such that information is not missed that will prevent a writeback from being successful.  

Unclear about known limitations

A few known limitations to be aware of: 

• No public API available to force a specific Carrier, Service, or Accessorial.  If you need to specify this information, you will need to pass a value through ‘requested_ship_method’ or order-level or line-level references and use these as criteria for Shipping Policies in ShipHawk.  With that information, we will know how you would like the order to be processed.  

• No public API available to pass License Plate or Tote # data to ShipHawk

• No public API available to handle or search for non-surviving combined orders  

• If you need SSCC information for ASNs, you will need to use GET /orders or GET /shipments to access the package level information required.  Webhooks do not currently provide the information required when you need to write back SSCC information to your Source.

Step 1. Map out your integration plan

As you think about building your integration, you will need to solve 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/*

Open

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 allow for a syncing entity decision.  The syncing entity gives the Merchant a choice to sync whatever corresponding object should be used as an Order in ShipHawk.  In this example, the Source system has two possible syncing entities: “Order” or “Shipment”. These are the names of the sales order and fulfillment object in this particular source system.

Open

If you do not want to build out both syncing options, we recommend using the fulfillment entity for your initial build. 

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.  Here is an example of some basic field mapping in a ShipHawk-Acumatica integration.

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: Settings > 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. 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.

Frequently Asked Questions

What if I need SSCC information for ASNs? 

If you need to capture SSCC information for Advanced Ship Notices (ASNs) to support wholesale trade relationships you will need to write more information back to the Source system.

With SSCC shipping, you need the SSCC ID for each Package in the Shipment and will need to make sure you have the Line Item details for each Package.  The SSCC identifier is called: "sscc_serial_references": ["000000843246110054"] for each Package and the “package_items” contains a list of the line items contained in each package.  See Packages object and Handling Unit Packages object for more information.

What are Proposed Shipments?

Proposed Shipments are an intermediate object between Orders and Shipments that contain the details about how certain items from an Order should be shipped.  ShipHawk generates these asynchronously as Orders are created in ShipHawk. They are mutable objects that the warehouse team interacts with during fulfillment.  Unlike Proposed Shipments, Shipments and their Package details are not editable once created.  Shipments can only be progressed through delivery statuses or cancelled.