...
| Table of Contents | ||||
|---|---|---|---|---|
|
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:
Terminology
Term | Definition |
Source | The system you are integrating ShipHawk with. |
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. |
Orders | The object in ShipHawk that represents an order. |
Shipments | The object in ShipHawk that represents a shipment. |
Packages | The object in ShipHawk |
Warehouse | The object in ShipHawk that represents the location used to fulfill an Order. |
Merchant | A ShipHawk customer. Usually an eCommerce company. |
Customer | The Merchant’s customer, a buyer, consumer, recipient the items being shipped |
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.
...
Identify the object in your system that represents the items that are available to pick / items that are ready to ship -- usually an object called an Item Fulfillment, Fulfillment or Shipment -- and create Orders in ShipHawk for this object instead of the sales/purchase/transfer order object in your source system.
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.
...
Always pass the most current order_line_item data. In many Source systems, Items/SKUs/Products often have a Weight, but may be missing Length, Width, Height. The more detail you can provide to ShipHawk, the better our algorithms can help make packing and shipping decisions.
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.
...
"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.
...
Send warehouse_code at both the order level and the 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:
...
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.
...
When a syncing entity record is updated in the Source system, the corresponding Order in ShipHawk should also be updated (update an order).
When a syncing entity record is deleted in the Source system, the corresponding Order in ShipHawk should also be deleted (delete an order).
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.
...
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.
...