ShipHero - NetSuite QuickStart Template Implementation

  • Updated

OVERVIEW

The ShipHero - NetSuite Template revolves around syncing items and orders from NetSuite to ShipHero and updating the shipments to NetSuite, once processed in ShipHero.

 

Installing the Template from Marketplace

  • Login to Celigo Integrator, head to the Marketplace and search for ShipHero - NetSuite and Install. Once the template is installed, the template tile will be available in the Home tab. Click on the template or continue setup to configure the connection.

Customizing Settings & Connections

 1 -  Configuring NetSuite Connection

Click on Configure.

  • Select the authentication type as Automatic.
  • The Account ID can be retrieved in NetSuite under Setup → Company → Company Information → Account ID.
  • Copy and paste the Account ID into the Account ID field in the connection setup.

  • Click Save and Authorize.
  • A popup will appear prompting you to log in to NetSuite. Using the Administrator role for the account is recommended to minimize permission issues.
  • Once it is logged in, the NetSuite connection is set up.

 

Once the NetSuite connection is configured, the next step is configuring the ShipHero Connection.

 

2 - Configuring ShipHero Connection

API Documentation: https://developer.shiphero.com/graphql-primer/

To authorize a ShipHero connection, a username and password of the ShipHero account is needed. The token and refresh token can be created using Postman.

The following details are required to create a token:

 



Request type - HTTP - POST request

URL - https://public-api.shiphero.com/auth/token

Request Body - email or username and password of the ShipHero account

 

Once the request is sent, the response body will contain the access token and refresh token that can be used to configure a ShipHero connection in Integrator.

 

Click on Configure.

  • The Set up connection page will open.

 

  • The Auth Type should be set to "Token." Enter the token and refresh token generated in Postman into their respective fields, with the token in the Token field and the refresh token in the Refresh Token field.

The Access Token and refresh token details should be specified as shown below.

 

Once the Configure refresh token checkbox is enabled, the refresh token part will be seen followed by token auth details.

  • Configure the refresh token details as shown below.

Testing the ShipHero Connection

To validate the token authentication, make a POST call to ShipHero. You can use any query from the ShipHero API documentation for this purpose. Fetch the query and use it in the block provided to verify the authentication details.

For example, the query used is to fetch products in the system.

query {products {request_id complexity data(first: 10) { edges { node { id legacy_id account_id name sku barcode country_of_manufacture warehouse_products { warehouse_id on_hand  } } } } } }

  • Click on Test Connection in the bottom right and once a successful call is made to test the connection, the details are validated, and the message will be shown on the top as shown below.

Click Save and Close.

Integration Data Flows

Data Flow -  01 - Export Items from NetSuite to ShipHero [Add/Update]

 

Synopsis:

The flow exports inventory items from NetSuite to ShipHero and updates item details such as description, dimensions, and other information.

 

Steps Involved:

1 - NetSuite Saved search

Create an Item type saved search in NetSuite and add the criteria as shown below, any additional criteria can be used based on user-specific requirements. Public checkbox should be enabled.

It is advisable to create two custom fields under the Item record to use it as a writeback for the item in NetSuite once created in ShipHero.

Custom Fields to be created - ‘ShipHero Item ID’ - Text field, ‘Exported to ShipHero’ - Checkbox

The NetSuite results tab should mainly contain the mandatory fields required to create an Item in ShipHero per the API documentation. Any additional fields are user-specific and can be mapped based on the fields available in the ShipHero schema.

 

Mandatory fields are as follows:

  • SKU
  • Display Name
  • Quantity on Hand

Additional fields that can be used to store information are dimensions(length, height, width, and weight), Manufacturer country, Image, etc.

Fields such as customer_account_id and warehouse_id are mandatory and should be retrieved by doing an Account query in Postman or a ShipHero POC should be providing it.

Once the values are retrieved, go to the ShipHero - NetSuite template’s Settings, paste the values accordingly, and click Save. These values are constant and will be mapped to the flows accordingly.




Once the saved search is created, open the Export section of the flow and select the saved search. If the saved search is not showing up in the list, use the refresh button to refresh the list.

Click Save and close.


2 - Import Block Mappings

a) Mappings used to create a Product in ShipHero.

 

Note: ‘customer_account_id’ and ‘warehouse_id’ are client-specific fields.

 

b) - To update a product, SKU and customer_account_id are mandatory. Some field examples that can be updated are shown below.

 

3 - Writeback block Mappings

Once a product is created in ShipHero, a product ID will be generated as a response along with a few other details related to the product by ShipHero. It is advisable to store this product ID value under the corresponding item in NetSuite as a reference, hence the custom fields.



Assumptions:

  1. Voiding, canceling, or deleting the record is out of scope.
  2. Item Deletes are not supported or recommended in NetSuite; in-activation is suggested instead.
  3. Serialized and lot-numbered items are out of scope.
  4. Items shouldn’t be INACTIVE in NetSuite to get exported to ShipHero.

 

Data Flow - 02 - Export Picked Item fulfillments from NetSuite to ShipHero as Sales Order

 

Synopsis

The flow exports the Item fulfillment(Status: Picked) from NetSuite and creates a Sales Order in ShipHero. Only lines that are fully committed will be sent to ShipHero. This flow will only process new Item fulfillments.

Steps Involved:

1 - NetSuite Saved search

Create a transaction type saved search in NetSuite and the criteria to be added are shown below.

Note: ShipHero ID is a mandatory custom field to be created for the item fulfillment record.

 

The saved search results should consist of the following fields.

Click Save and Run.



Once the saved search is created, open the Export section of the flow and select the saved search from the list. If the saved search is not showing up in the list, use the refresh button to refresh the list.

Click Save and close.

 

2 - Import Block Mappings

Mappings to create a sales order in ShipHero are as shown below.

Note: 

  • Shipping fields like carrier and method are based on the shipment methods used by the client and by ShipHero in correspondence.
  • customer_account_id and warehouse_id are client-specific fields.

 

Click Save and close.

 

3 - Writeback flow mapping

When an Order is created in ShipHero, an order ID along with the details related to the ShipHero order will be coming as response. This Order ID should be stored in NetSuite as this ID is used as a reference field to fetch the Order details in ShipHero to process the confirmations back into NetSuite when the Shipment is processed.

 

Limitations:

  • Syncing order updates is out of scope
  • Partial Item and Quantity export to ShipHero are out of scope
  • Order Cancellations are out of scope

Data Flow 03 - Import Shipment Confirmations from ShipHero to NetSuite [Batch]

 

Synopsis

The flow syncs tracking and package-related information back to NetSuite after ShipHero processes the fulfillment. It also supports partial item and partial quantity shipments.

 

Steps Involved:

1 - NetSuite Saved search

Create a transaction type saved search in NetSuite and the criteria to be added are shown below.

The Criteria ensures that only the Item fulfillments that are in Picked status that have been exported to ShipHero by Data Flow 2 will show up in the results.

Below are the fields required to be under the results tab for the saved search.

Click Save and Run.

 

Once the saved search is created, open the Export section of the flow and select the saved search. If the saved search is not showing up in the list, use the refresh button to refresh the list.

Click Save and Close.

 

2 - Lookup Block

This block performs a query on the shipment using the ShipHero ID provided by the saved search. If the order has been processed in ShipHero, the lookup retrieves the relevant details and passes the information to the import block.

If the shipment has been processed (fulfilled) in ShipHero, the details will be carried over to the next import, which will update the item fulfillment in NetSuite.

 

3 - Import block mappings

Below are the mandatory mappings that update the item fulfillment in NetSuite. Any additional fields can be added based on the user’s requirements.

 

Data Flow 03.1 - Import Shipment Confirmations from ShipHero to NetSuite [Realtime]

 

Overview

The difference between the Data Flow 03 and 03.1 is, that this flow is real-time and is triggered when there is any shipment update to the imported order in ShipHero.

ShipHero offers a list of webhooks that can be created based on different statuses to meet specific requirements. In this case, a 'Shipment Update' webhook has been created to enable the trigger.

The Webhook trigger must be created to enable the flow whenever a Shipment is updated.

Steps to create a webhook for any trigger

1 - Open DF 03.1 flow and click on the listener.



2 - The Public URL marked below should be copied and only with the help of this, a webhook is created.

 

 3 - Open Postman and use the following query to create a shipment trigger

Query used above:

mutation {

  webhook_create(

    data: {

      name: "Shipment Update"

      url: "PASTE THE PUBLIC URL HERE"

      shop_name: "Humane" } ) 

   { request_id complexity webhook { shared_signature_secret } } }

 

The name field should be the same as per the documentation.(link)



Headers:

Authorization: Bearer {{Access Token}} → The Access token that was used while setting up the ShipHero connection must be used here.

 

When the POST request is sent, the response will contain a shared signature secret which must be saved as this will be used in Celigo listener.

Below are the details and steps to have the trigger in place.

  • Verification type - HMAC
  • Algorithm - SHA-256
  • Encoding - Base64
  • Header - x-shiphero-hmac-sha256
  • In the Key (secret) field, paste the shared signature secret.

Click Save and close.

The Webhook is created and will be triggered whenever a shipment is updated in ShipHero.

Note: There might be cases where the trigger may not trigger and some orders might not be processed. It is advised to reach out to the ShipHero support/POC in case of issues concerning the webhook and the Public URL might be provided in case of troubleshooting.

However, any orders that were exported from NetSuite will be updated once the Order is fulfilled in ShipHero by Data Flow 03 which is a scheduled run and updates the record based on a Netsuite Saved search.