Shipping Insights SDK

Overview 

This guide is intended for technical architects and developers that need to integrate with ShipperHQ for the purpose of providing detailed shipping information for customer orders.

Use the information outlined in this document to view how custom fields and attributes are queried and modified.

Note, this does not document the standard types and fields the API provides. This information is found in the GraphQL schema and obtained via our GraphQL playground. Please refer to the Introduction to GraphQL article from Graphql.org for more information about GraphQL. 

Shipping Insights Use Cases

  • Time-Sensitive Delivery: During the holidays or special occasions, most customers’ online orders are time-sensitive. The dispatch date provided to meet the delivery date shown for the method the customer chose at checkout enables merchants to meet high customer expectations for on-time delivery.
  • Cost-Effective Packing: When Dimensional Packing and Shipping Insights are enabled, merchants can easily access packing details used to calculate the shipping rate shown to the customer at checkout. This allows merchants to actually pack each product in the right box in the most efficient manner. Please see our How to Set Up Dimensional Packing guide for more information.
  • Multi-Origin Fulfillment: ShipperHQ’s multi-origin shipping logic automatically pulls in the rates for the most efficient fulfillment center for merchants using multiple shipping origins. With Shipping Insights, these merchants can now see exactly which items should be packed and shipped from each origin to streamline their fulfillment processes.
  • Pickup Orders: Self-pickup options for online orders, like In-Store and Curbside Pickup, are becoming increasingly popular with customers. Shipping Insights automatically displays the pickup location for each relevant order for merchants offering these convenient pickup options.

Getting Started

Shipping Insights is an essential feature for any merchant looking to bridge the gap between their checkout experience and fulfillment while fine-tuning their eCommerce shipping strategy. With Shipping Insights enabled, ShipperHQ stores detailed and relevant shipping information for each order placed as a detailed window in the eCommerce platform and is available as an API for custom integrations. 

Shipping Insights Workflow

ShipperHQ is able to store the shipping rate information (quotes) when we respond to a shipping rate request. If enabled on a user’s account, ShipperHQ stores the quote information that includes, but is not limited to:

  • Carrier information: Carrier code, name, and type
  • Shipping rate information: Method codes and names, rates, delivery dates, and dispatch dates
  • Packing details: SKUs and quantity in boxes
  • Shipping origin information
  • Options that a customer selected at checkout

After an order is placed, the quote information is converted into an order and persisted in ShipperHQ’s database. We retain the detailed information from the quote that relates to the order and the shipping method chosen by the customer. In addition to basic order details, we have detailed packing information, carrier and shipping method details, and selections by the customer on the checkout (method and dates chosen, etc.).

How it works: Before

How it works: After

How it works: Using the Order Details

Accessing the shipping order information using ShipperHQ’s custom integrations is achieved by querying in one of the following two ways depending on your needs:

  • Processing Data via GraphQL query – You can retrieve shipping information for a given order using the ‘viewOrder’ query, submitting the platform’s order ID, and then requesting the information you require as part of the query in GraphQL. This is most suited to scenarios where you need to integrate with other systems to process that information, e.g., obtain dispatch date and box sizes to pack goods into.
  • Viewing Data via Drop-in React component – This renders the shipping information pertaining to the order in a user-friendly way. This method is most suited to scenarios where you want to display the data against the order for the merchant to read.

Accessing Shipping Insights

Prerequisites

You need to have a ShipperHQ account with the Shipping Insights Advanced Feature enabled.

Generating Access Tokens

Use the following process to obtain your access tokens to authenticate requests. The Shipping Insights API uses access tokens to limit permissions and is intended for use when viewing order information only.

Note, please protect your access tokens as they give read access to sensitive information. As such, it is NOT recommended to commit them to publicly accessible areas like GitHub or in client-side code.

Add the access token to the header of your request to authenticate your request with the Shipping Insights API.

Use the following process to generate and/or view access tokens for your website on ShipperHQ.

  1. Log into your ShipperHQ account. 
  2. Click Websites from the Basic Setup list.
  3. Click the desired website if you have more than one.
  4. Click the Integrations tab.
  5. View the generated access token under Shipping Insights
  6. Click the Copy button to copy the token.
  7. Click the Generate New Access Token button for a new token.

Retrieving Shipping Insights Information

Authentication

  1. Click the headers button on the left, which has a star-shaped icon, and enter the following headers:
  • X-ShipperHQ-Access-Token – This is the token generated above
  • X-ShipperHQ-Scope – This is the scope of your ShipperHQ account under which your token was generated. Possible values:
    • LIVE
    • TEST
    • INTEGRATION
    • DEVELOPMENT
    Note: For non-Magento ShipperHQ accounts, always use LIVE.

Request Definitions

You can retrieve the Shipping Insights information by querying the Shipping Insights GraphQL API or by using the Shipping Insights Component Integration.
Use your own tool or navigate to ShipperHQ’s playground to view any GraphQL queries. Follow the procedure outlined below to use GraphQL.

  1. Navigate to the ShipperHQ GraphQL playground
  2. In a new GraphQL playground window, enter https://ovs.shipperhq.com into the URL
  3. Click the Docs button
  4. Click the Reload Docs icon
  5. Click the Query link to view a list of available fields

Shipping Insights Examples

GraphQL API Basic Query
#
# Fetch basic shipping information
# Carriers, methods, delivery dates, and packing details for an order.

query Order {
  viewOrder(orderNumber: "000000010") {
    shipments {
      id
      shipmentDetail {
        shipmentId
        name
      }
      carriers {
        methods {
          methodDetails {
            methodCode
            methodTitle
            totalCharges
            currency
            negotiatedRate
          }
          timeInTransitOptions {
            dispatchDate
            deliveryDate
          }
        }
        packages {
          packageDetail {
            declaredValue
            height
            length
            width
            weight
            packingWeight
            packageName
            surchargePrice
          }
          items {
            sku
            qtyPacked
            weightPacked
          }
        }
      }
    }
  }
}
Example Basic Response
{
  "data": {
    "viewOrder": [
      {
        "shipments": [
          {
            "id": "ckf6ukxcpasdzh0g38tos1xru4",
            "shipmentDetail": {
              "shipmentId": "23889",
              "name": "Texas Origin"
            },
            "carriers": [
              {
                "methods": [
                  {
                    "methodDetails": {
                      "methodCode": "FEDEX_GROUND",
                      "methodTitle": "Ground",
                      "totalCharges": 8.7,
                      "currency": "USD",
                      "negotiatedRate": false
                    },
                    "timeInTransitOptions": {
                      "dispatchDate": "9/17/2020",
                      "deliveryDate": "9/18/2020"
                    }
                  }
                ],
                "packages": [
                  {
                    "packageDetail": {
                      "declaredValue": 0,
                      "height": 5,
                      "length": 5,
                      "width": 5,
                      "weight": 1.5,
                      "packingWeight": null,
                      "packageName": "Small Box",
                      "surchargePrice": 0
                    },
                    "items": [
                      {
                        "sku": "24-MB04",
                        "qtyPacked": 1,
                        "weightPacked": 1.5
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "id": "ckf6ukxcsxnzx0g3851e6ns8v",
            "shipmentDetail": {
              "shipmentId": "44814",
              "name": "California Origin"
            },
            "carriers": [
              {
                "methods": [
                  {
                    "methodDetails": {
                      "methodCode": "STANDARD_OVERNIGHT",
                      "methodTitle": "Standard Overnight",
                      "totalCharges": 55.45,
                      "currency": "USD",
                      "negotiatedRate": false
                    },
                    "timeInTransitOptions": {
                      "dispatchDate": "9/21/2020",
                      "deliveryDate": "9/22/2020"
                    }
                  }
                ],
                "packages": [
                  {
                    "packageDetail": {
                      "declaredValue": 0,
                      "height": 5,
                      "length": 5,
                      "width": 5,
                      "weight": 1,
                      "packingWeight": null,
                      "packageName": "Small Box",
                      "surchargePrice": 0
                    },
                    "items": [
                      {
                        "sku": "24-MB01",
                        "qtyPacked": 1,
                        "weightPacked": 1
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Shipping Insights Component UI

Integrating Shipping Insights Component (Embedded View)

This type of integration allows you to place Shipping Insights anywhere on the page.

The code below loads the Shipping Insights JS bundle and mounts it on the DIV with id="view". You must supply the Order ID from Magento and the OVS Access Token which is required to retrieve order details.

<div id="ovView"><!-- Shipping Insights --></div>
<script>
    function initShippingInsights(orderId, accessToken) {
        var url = "URL for the JS bundle goes here" 
        var head = document.getElementsByTagName("head")[0];
        var script = document.createElement('script');
        script.type = 'text/javascript';
        script.src = url;
        script.async = true;
        script.onload = function() {
          window.shqShippingInsights.SHQRenderShippingInsights(
              document.getElementById('ovView'),
              orderId,
              {
                endpoint: 'https://ovs.shipperhq.com',
                accessToken,
                scope: 'LIVE',
                currency: 'USD'
              }
          );
        }
        head.appendChild(script)
    }
    
    initShippingInsights(
        '0000022', // Magento Order ID
        '**access token**' // OVS Access Token (should be retrieved on the backend side)
    );
</script>

Integrating Shipping Insights Component (Modal View)

This type of integration allows the display of the Shipping Insights modal when the button is clicked.

The code below loads the Shipping Insights JS bundle and attaches it to the DIV with id="ovModalOpenere" /click event. You must supply the Order ID from your eCommerce platform and the OVS Access Token, which is required to retrieve order details.

<button id="ovModalOpener">
  Open Shipping Insights
</button>
<script>
    function initShippingInsights(orderId, accessToken) {
        var url = "https://assets.shipperhq.com/shq-order-view_0.1.69.js" 
        var head = document.getElementsByTagName("head")[0];
        var script = document.createElement('script');
        script.type = 'text/javascript';
        script.src = url;
        script.async = true;
        script.onload = function() {
          window.shqShippingInsights.SHQAttachShippingInsights(
              document.getElementById('ovModalOpener'),
              orderId,
              {
                endpoint: 'https://ovs.shipperhq.com',
                accessToken,
                scope: 'LIVE',
                currency: 'USD'
              }
          );
        }
        head.appendChild(script)
    }
    initShippingInsights(
        '0000022', // Order ID
        '**access token**' // OVS Access Token (should be retrieved on the backend side)
    );
</script>

Resources

Was this doc helpful?