ShipHawk’s NetSuite bundle - which is a Hybrid SuiteApp - provides Web Services integration between NetSuite and ShipHawk. Our SuiteApp communicates with NetSuite to perform the following tasks:

• Imports item data from NetSuite, which ShipHawk treats as Product SKUs.

• Imports item fulfillment records from NetSuite, which ShipHawk treats as Orders

• Creates or updates Item Fulfillment records in NetSuite when Orders are fulfilled in ShipHawk. Your organization can access this shipment data to accrue shipping costs, adjust customer billing, make financial decisions and generate ASNs (Advanced Ship Notices) directly or using a 3rd-party solution.

It is recommended that you choose to sync your item fulfillments in NetSuite as Orders in ShipHawk by default. This ensures  you will only fulfill the items that are in inventory and ready to be shipped. Though it is not recommended, your organization can also opt to sync sales orders in NetSuite as Orders in ShipHawk. Contact your ShipHawk Account Manager to determine the best setup method for fulfilling your orders through ShipHawk.

This communication between NetSuite and ShipHawk allows your organization to access ShipHawk services. The installation procedures in this manual are specific to NetSuiteVersion 2022.2.

This guide covers the following topics:

Syncing Item Fulfillments to ShipHawk

ShipHawk uses item fulfillments in NetSuite to create Orders in ShipHawk. This is the preferred method of syncing data to ShipHawk because both Orders in ShipHawk and item fulfillments in NetSuite only contain items that are ready to be fulfilled.

Below is an explanation of how Item Fulfillments in NetSuite and Orders in ShipHawk interact:

When a user creates an item fulfillment in NetSuite:

• An order is automatically created in ShipHawk with a corresponding proposed shipment.

• The item fulfillment number is used as the order number in ShipHawk (ex: IF138296)

When a user updates an item fulfillment in NetSuite:

• The corresponding order in ShipHawk will also be updated. This applies to updates such as line item changes and changes to the destination address.

When a user deletes an item fulfillment in NetSuite:

• The order is deleted in ShipHawk.

When an order is fulfilled in ShipHawk:

• The item fulfillment record is updated in NetSuite.

When a user deletes an order in ShipHawk:

• The order or item fulfillment will not be automatically deleted in NetSuite

• The order can be re-synced by updating the item fulfillment in NetSuite.

The following charts illustrate the fulfillment workflow from NetSuite to ShipHawk when item fulfillments sync to ShipHawk compared to when sales orders do. 

Sync Item Fulfillments as Orders (Recommended)

Open

Sync Sales Orders as Orders (Not Recommended without Permission)

Open

Regardless of which syncing entity your organization opts to use, the installation procedures outlined in this document remain the same.

Installation Overview

This chapter provides a broad overview of the steps necessary to install ShipHawk’s bundle in your NetSuite instance. The ShipHawk SuiteApp Installation Guide defines terms and illustrates a roadmap of the installation process. 

Installation Checklist

To use ShipHawk’s functionality in your instance of NetSuite, you must complete the installation and setup tasks in the following order:

Enable token-based authentication setup. Install the ShipHawk SuiteApp in your NetSuite instance.

Customize your script deployment settings.

Set up your proxy user.

Generate  access tokens.

Configure ShipHawk’s SuiteApp settings for NetSuite.

Add your ShipHawk API key to NetSuite.

Add your ShipHawk warehouse IDs to NetSuite.

Add your NetSuite account ID to ShipHawk.

Configure your NetSuite account in ShipHawk.

The preceding steps describe a broad overview of the installation process.

SuiteApp Definitions

Installation Procedures

This section provides detailed procedures for the installation of the ShipHawk bundle in your instance of NetSuite. The installation gives ShipHawk access to your NetSuite account and allows ShipHawk to create and/or update fulfillment information in your NetSuite. The following procedures guide you through the process of configuring your ShipHawk bundle installation. These procedures are intended for your organization’s system administrator.

Enabling token-based authentication

NetSuite and ShipHawk communicate bilaterally. NetSuite sends item fulfillment data and information to ShipHawk via our API. ShipHawk uses webservices in order to write information back to NetSuite. To set up these web services, we use token-based authentication, which you will set up in the following steps.

To create access tokens

1. From your NetSuite top menu, click Setup > Company > Enable Features.
   
   

   The Enable Features screen is displayed.
   
   

2. Click the SuiteCloud tab to access these options. New options populate below.
   
   

    

3. Under the Manage Authentication section, enable the Token-Based Authentication setting.

   
   ShipHawk now can interact with NetSuite’s security using token-based authentication.

Installing the ShipHawk bundle

You must first install the SuiteApp in your NetSuite account.  This section describes how to locate and install the bundle in your account.

To install the bundle

1. Log into your NetSuite account. 

2. From the NetSuite menu at the top of the screen, select ​Customization > SuiteBundler > Search & Install Bundles.
   
   

   The Search & Install Bundles screen is displayed.
   
   

3. Click the Advanced link under the Search button. Additional fields populate below the link.
   
   

4. Select the Production Account option from the Location drop-down field.
   
   

   The Account ID field populates to the right of the Location field.

5. Enter the account number TSTDRV2246640 and click the Search button.
   
   

    

   The ShipHawk bundle is displayed  in the grid below.
   
   

6. Click on the ShipHawk link in the grid. The ShipHawk Bundle Details screen populates.
   
   

7. Click the Install button to begin the installation process for ShipHawk’s SuiteApp. A series of pop up windows and prompts will populate.

8. Confirm all prompts.

Congratulations, you have installed the ShipHawk SuiteApp!

Contact your ShipHawk Implementation Representative if you have any questions.

Configuring the Script Deployment settings

In order to prevent potential communication conflicts between ShipHawk and NetSuite, the following script settings must be adjusted. Scripts determine how ShipHawk and NetSuite interact with each other and what information is exchanged.

To edit script deployments

1. From the top menu of your NetSuite dashboard, click Customization > Scripting > Script Deployments.
   
   

   The Script Deployments screen is populated.
   
   

    

2. Locate and select the ShipHawk Sales Order ClientScript option from the Script dropdown field under the Filters section. ClientScripts are displayed under the Show Undeployed grid.
   
   

    

3. Locate the customdeploy_shiphawk_so_cs script. The record type for this script is Sales Order. Click Edit in the row corresponding to this script.
   
   You will be redirected to the Script Deployment screen.
   
   

4. Verify three settings under the Audience tab:
   
   

   1. The Select All checkbox for the Roles field is unchecked.

   2. All subsidiaries in the Subsidiaries field must be selected. This grants them rights to use ShipHawk functionality.

   3. The Select All checkbox for the Employees field is checked.
      
      

5. Click Save when you finish.

You now are finished configuring script settings for the installation.

Setting Up A Proxy User

A user must be associated with the interactions between ShipHawk and NetSuite.  You can choose an existing user or a user dedicated solely to the ShipHawk SuiteApp. Only one is required to establish the connection.

To manage users and their roles

1. From your NetSuite dashboard, click Setup > User/Roles > Manage Users.
   
   

   The Manage Users screen is displayed.
   
   

    

2. Select any user whose role is currently Administrator. The Employee screen populates.
   
   

    

3. Navigate to the Access tab and click Edit.
   
   

    

4. From the Roles dropdown field, select ShipHawk Shipping Web Services and click Add.

   1. ShipHawk Shipping Web Services should be displayed as a new role under the Roles table of the Access tab.

5. Click the Save button to finish.

Creating Access Tokens

Access tokens allow ShipHawk to interact with your NetSuite account programmatically. In this step, you will create the access tokens used to grant ShipHawk access.

To create an access token

1. From the NetSuite dashboard, select Setup > Users/Roles > Access Tokens > New.
   You will be redirected to the Access Token screen.
   
   

2. Complete the screen by entering the following information:

   1. In the Application Name field, choose ShipHawk Integration.

   2. In the User field, choose the proxy user you set up in the previous procedure.

   3. In the Role field, select ShipHawk Shipping Web Services. 

   4. After  you complete each field, the Token Name field automatically populates with a new token name. Click Save, but DO NOT EXIT THE SCREEN. A confirmation screen will populate.

3. Copy both the Token ID and the Token Secret in the Token Name field to a protected document or
location outside of NetSuite. You will need to access this document later.

Configuring ShipHawk Settings in NetSuite

ShipHawk Settings control various aspects of the SuiteApp integration, including communication between ShipHawk and NetSuite, data synchronization, field mapping and more. This step focuses on connectivity for rating and order synchronization. Contact your ShipHawk Implementation Representative to discuss optional settings and configuration.

To add your ShipHawk API key to NetSuite

1. From the NetSuite dashboard, select ShipHawk > Setup > ShipHawk Settings.
   You will be redirected to the ShipHawk Settings List screen.
   
   

    

2. Click Edit to access ShipHawk settings.
   
   

3. Complete the ShipHawk Settings screen.

   1. In the SHIPHAWK HOST NAME field:

      1. Enter the ShipHawk endpoint to set up your Production environment.
         For example, if the ShipHawk endpoint is:
         https://abcdef.tms.myshiphawk.com
         Enter:
         abcdef.tms.myshiphawk.com
         
         NOTE: If you are interested in a sandbox environment or user-acceptance testing environment, please contact your ShipHawk account manager for more information.
         
         

   2. In the API Key field, enter the ShipHawk API key found in the ShipHawk platform. To locate the ShipHawk API key, complete the following steps:
      
      

      1. Login to your ShipHawk account in a separate browser window or tab.  If you are not sure which account to use, contact your ShipHawk Implementation Representative.
         
         

      2. On the right side of ShipHawk’s top menu bar, click on the Settings icon and select the Settings link. The Settings screen appears.
         
         

      3. From the left-side menu, click on the Developer API link. The API Keys screen appears.
         
         

          

      4. Click the Create New API Key button located at the top of the screen. The Create API Key pop-up window appears.
         
         

          

      5. Enter a Name for your API Key. Then, click Create API Key.
         
         

         
         A success message will display at the top of the pop-up window to confirm your API Key has been generated.
         
         

      6. Click Copy to copy your API Key.
         
         

         
         Important: Your API Key will only be displayed one time. Ensure you have saved and copied your key correctly before exiting the Create API Key window.
         
         

      7. After you have successfully copied the API Key to your clipboard, click Done.

      8. Navigate back to NetSuite and the ShipHawk Settings screen.

      9. Paste the ShipHawk API key into the API Key field in NetSuite.
         
         

   3. Click on the Shipping Methods tab.
      
      

   4. In the Default Shipping Method dropdown field, select your organization’s usual shipping method. If unknown, just select one from the dropdown list. Your ShipHawk Implementation Representative will assist you with this later.

   5. Click Save when you are finished.

Configuring the SuiteApp in ShipHawk

Now that NetSuite has been configured to communicate with ShipHawk, we must set up your ShipHawk account to access and update information on the NetSuite side. ShipHawk uses access tokens and account information in previous steps to set up the connection successfully. 

To set up NetSuite settings in ShipHawk

1. From your ShipHawk application window, click on the Settings icon > Integrations.
   
   

   
   You will be redirected to the  Integrations screen.
   
   

    

2. From the Integrations screen, click on the NetSuite tile. The Manage your Accounts screen populates.
   
   

    

3. To complete integration between your ShipHawk NetSuite, you must enter your NetSuite account ID in the Account ID field in the ShipHawk platform. You can locate your account ID in NetSuite.

   1. The letters in your Account ID must be entered in all uppercase, otherwise your account will not connect.

To get your Account ID from NetSuite

1. Open your NetSuite account in another tab or browser window.

2. From the NetSuite dashboard, select Setup > Company > Company Information.
   
   

3. You will be redirected to the Company Information screen.
   
   

    

   1. Copy the value found in the Account ID field to your system clipboard.
      
      

       

4. Navigate back to your ShipHawk account and complete the Manage Your Accounts screen as follows:

   1. Paste the account ID number you copied from NetSuite into the Account ID field.

   2. In the Account Name field, enter your organization’s name. We suggest the following format:

      1. COMPANYNAME_NETSUITEENVIRONMENT

   3. Enter your Token ID (previously saved in the Message Center of BaseCamp) in the User Token ID field. See the Creating access tokens section for more information.

   4. Enter your Token Secret (previously saved in the Message Center of BaseCamp) in the User Token Secret field.

   5. Leave the Is a sandbox account option unchecked unless you have a premium sandbox account in NetSuite.

5. Click Connect.

Installation of the ShipHawk SuiteApp now is complete. Continue to the next section to learn how to test
the secure connection between ShipHawk and NetSuite.

Managing NetSuite Concurrent Connections and ShipHawk Performance

As a NetSuite administrator, you can manage and monitor the number of concurrent connections your NetSuite implementation can use for integrating with other applications, including ShipHawk. 

NetSuite limits the number of concurrent API connections that you are allowed based on your service tier. For more information, see NetSuite’s Concurrency Governance Cheat Sheet.

The number of concurrent connections (operations) available for an integration is an important consideration for overall performance. For ShipHawk, the more concurrent connections available, the faster ShipHawk can write back shipment information to NetSuite and update Item Fulfillment records. 

In NetSuite, the number of concurrent connections is shown in the Account Concurrency Limit field, and also on the Concurrency Monitor and Integration Governance screens. You can now configure the number of concurrent connections ShipHawk will use with your NetSuite implementation in the Concurrency Rate Limit field. The Concurrency Rate Limit setting in ShipHawk must be less than or equal to the Account Concurrency Limit field in NetSuite.

Monitoring Concurrency Performance

You can view concurrency performance in NetSuite with the Concurrency Monitor, and review concurrency usage for integrations on the Integration Governance screen. For example, you might have a NetSuite Basic service tier that allows for five concurrent connections, or you might have a higher service tier that allows for more connections. As a NetSuite administrator, you need to identify the service tier that best meets your overall business and performance requirements.

Account Concurrency Limit in NetSuite

In NetSuite, the Account Concurrency Limit setting defines the number of concurrent operations that can be performed for each integration. For example, if your Account Concurrency Limit is set to three and you book five shipments in ShipHawk, NetSuite will only create the first three Item Fulfillment records simultaneously. The two remaining records will not be created until the first three records were successfully created.

To check the current value of the Account Concurrency Limit in NetSuite:

1. Select Setup > Integration > Integration Governance.
   
   

    

2. Note the Account Concurrency Limit field value. This value should be greater than or equal to the Concurrency Rate Limit value you can set in ShipHawk.

Rate Limiting in ShipHawk

On the ShipHawk web portal, you can specify the number of connections that ShipHawk uses to connect to NetSuite in the Concurrency Rate Limit field:

1. Select Settings (gear icon) > Integrations.

2. Click the NetSuite tile for NetSuite Manage Your Accounts.

3. Select Advanced tab and go to the Rate Limiting section:
   
   

    

4. In Concurrency Rate Limit, enter a value that is less than or equal to the Account Concurrency Limit in NetSuite.

Adding ShipHawk Warehouses to NetSuite Locations

Both NetSuite and ShipHawk have the concept of Locations / Warehouses. Because of this, we need to create a relationship between Locations in NetSuite and Warehouses in ShipHawk.

To map ShipHawk Warehouses to NetSuite Locations

1. From your NetSuite dashboard, select Setup > Company > Locations.
   
   

   Click directly on the Locations link. Do not click on either New or Search.
   
   The Location screen is populated with a list of your existing stores and warehouses.
   
   

   
   If your organization has “child” locations under the main location record as in the graphic above, link only the “parent” locations to ShipHawk. Having a single ShipHawk warehouse point to multiple NetSuite locations creates errors.
   
   In the case that your organization absolutely must ship from a “child” location, create new warehouses in ShipHawk and link each one to the corresponding “child” location record in NetSuite.
   
   

2. Each Location in your NetSuite account must be linked to an equivalent Warehouse in ShipHawk using the warehouse ID number. Click the Edit link in the row corresponding to the first warehouse location you want to edit. The Location screen will populate with details related to that location.
   
   

    

3. To link your ShipHawk warehouse to this NetSuite location, you must enter the unique warehouse code for this warehouse in the ShipHawk Warehouse Code field. You can find the warehouse code in the ShipHawk platform.

4. Open ShipHawk  in a separate browser window or tab.

5. Click on the Settings icon > Warehouses.
   
   

    

   You will be redirected to the Warehouses screen.
   
   

    

6. Select the first warehouse you want to add to NetSuite and click on the name of the warehouse.
   
   

7. From the Warehouse Details screen, highlight the code in the Warehouse Code field and copy to the system clipboard.
   
   

8. Navigate back to your NetSuite account and the Location screen.

9. Paste the copied warehouse code into the ShipHawk Warehouse Code field and click Save. The Locations screen reappears.
   
   

10. Repeat this procedure for each warehouse in your account.

Confirm Connection

This section provides instructions for testing and verifying  the connection between NetSuite and ShipHawk after installation and integration.

Testing the connection

Before using ShipHawk with NetSuite, you must confirm that NetSuite and ShipHawk can securely communicate with one another. An easy way to test the connection is by synchronizing the product field mappings.

To synchronize product field mappings

1. From your ShipHawk account, select the Settings icon > Integrations > the NetSuite tile. From the Manage Your Account screen, click the Product Field Mappings tab.

2. From the Manage Your Account screen, click the Product Field Mappings tab.
   
   

    

3. Click the Update button to synchronize ShipHawk’s information to NetSuite.

4. If the connection was successful, a green confirmation message appears.
   
   

    

5. If the connection was unsuccessful, no message appears.

Troubleshooting the connection

This section describes the most common mistakes that could cause a failed connection to NetSuite and can be verified immediately. This troubleshooting section is not intended to be comprehensive; if none of these solutions resolve your connection issues, contact your ShipHawk Implementation Representative.

Did you enter the correct account ID?

The Account ID field on the Manage Your Accounts screen is syntax-sensitive. This means that capitalization matters. Verify that your account ID is correct.

Did you paste the correct Token ID and Token Secret?

The Token ID and Token Secret were saved in the Message Center of your ShipHawk Basecamp account. If you have misplaced this information, you must create new access tokens. The procedures for this step are in the Creating Access Tokens section of this SuiteApp Installation Guide.

If all your IDs and tokens are correct, then there is one more easy task that you can perform before contacting your ShipHawk Implementation Representative. You can access an audit trail in NetSuite to verify if ShipHawk was able to make a successful connection to NetSuite at all.

To access the NetSuite audit trail

1. From your NetSuite dashboard top menu, select Setup > Users > View Login Audit Trail.
   
   

   You will be redirected to the Login Audit Trail Search screen.
   
   

    

2. Personalize the search by filtering the following options:

   1. Select ShipHawk Shipping Web Services or the name of your proxy user in the Role field.

   2. Click the Personalize Search button. The Personalize Login Audit Trail Search Form screen is displayed.
      
      

   3. Click on the Results tab to generate a list of fields included in the search:
      
      

       

   4. Review the included fields and verify that the Detail option is included. If Detail is not displayed on the list, click on the dropdown field at the bottom of the Field grid and select Detail.
      
      

       

   5. Click the Add button.

   6. Click Save. You will be redirected to the Login Audit Trail Search screen.
      
      

       

3. Click Submit to run the search.
   
   

    

4. Review the results and locate the entry with a timestamp that corresponds with your attempt to synchronize the product field mappings.

   1. If one exists and the Status is Success, ShipHawk did successfully communicate with NetSuite.

   2. If one exists and the Status is Failure, then the request did reach NetSuite, but NetSuite blocked it from connecting. The likeliest problem is an incorrect account ID.

   3. If one does not exist at all, ShipHawk was unable to make contact with NetSuite.

If this step is  successful, congratulations, you have completed the setup and installation of ShipHawk’s SuiteApp! 

If this step is unsuccessful, do not worry.  Please contact your ShipHawk Implementation Representative for help troubleshooting the connection.

Upgrade Your SuiteApp

ShipHawk regularly releases new versions of our SuiteApp bundle. When this occurs, you must update the ShipHawk SuiteApp to the latest version. This section provides instructions for performing the update and integration.

Updating an existing bundle on NetSuite Production

The following section provides detailed procedures for updating an existing NetSuite bundle in the NetSuite Production environment.

To update an existing bundle

1. From the NetSuite dashboard, select Customization > SuiteBundler > Search & Install Bundles > List.
   
   

   To go directly to the Installed Bundles screen, type “Page: Installed Bundles” into the Search bar at the top of the dashboard.
   
   

    

   The Installed Bundles screen is displayed.
   
   

    

2. Locate the ShipHawk SuiteApp in the grid below.
   
   

   
   Verify that the account is named ShipHawk Integration (TSTDRV2246640).
   
   

3. From the Action icon on the left hand column, click the Update link in the drop-down field.
   
   

   
   The Preview Bundle Update screen is populated with a deprecated version notice.
   
   

4. Click the Update Bundle button.
   A notice will generate.
   
   

    

5. Click the OK button to accept. The bundle installation begins. You can view the installation progress on the Installed Bundles screen.
   
   

    

6. Once the bundle is successfully updated, the ShipHawk bundle will show the new bundle version and will reference a new deployment account called ShipHawk Integration (TSTDRV2246640).
   
   

    

7. You have now successfully updated the bundle to the latest version. Contact your ShipHawk Account Manager if you have any additional questions.