How to Use Shipping Insights API

Overview

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 available as an API for custom integrations. 

For a full list of the Shipping Insights details and usage scenarios, please view the Shipping Insights document.

For ShipStation users, you can now view Shipping Insights inside your ShipStation account when processing your orders using ShipperHQ’s API functionality. Please use the How to Connect ShipperHQ to ShipStation guide to enable the Shipping Insights feature.

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

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.).

The shipping order information is queried in two different ways depending on your need:

  1. 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 process that information, e.g., obtain dispatch date and box sizes to pack goods into.
  2. 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.

Authorization Tokens

Before you begin, 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 to use with 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.

To authenticate your request with the Shipping Insights API, you should add the access token to the header of your request. See the Creating Shipping Insights Query section below for more information.

Generate Access Token 

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

  1. Log into ShipperHQ.
  2. Click Websites from the Basic Setup list.
  3. Click the desired website.
  4. Click the Integrations tab.
  5. View the generated access token into the field provided.
  6. Click the Generate New Access Token button for a new token.

How to Retrieve Shipping Insights Information

Use one of the following methods to retrieve Shipping Insights information.

Method 1: Querying Shipping Insights GraphQL API

Viewing Schema

The best way to query our data for testing and view the schema is via the GraphQL playground. First, load the playground up (see the example below) with no data/queries to ensure you can reach the docs and see the schema.

Connect to the following URL:

To run any GraphQL queries you can use your own tool or navigate to our playground:

  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 Reload Docs button.
  4. Click the Docs button to show the available GraphQL queries.

This GraphQL tool does not always display an error in your headers/queries. If you do not see docs loading, then please clear all fields/headers, try again, and use Inspect Element/Console to see errors – they are there! We are working to find a better playground utility tool.

Creating a Shipping Insights Query

Pre-Requisites

This assumes that Shipping Insights or Enhanced Checkout is enabled for the merchant and supported by the platform. If unsure, please contact ShipperHQ. We assume you are using the GraphQL Playground to perform the query.

Steps to creating a Shipping Insights Query

This process consists of the following steps:

  • Open new Playground Tab
  • Update the Headers to allow you to authenticate and locate your store
  • Prepare the body of the query
Open new Playground Tab
  1. Click Add New in the top left corner.
  2. Set the URL to https://ovs.shipperhq.com (make sure you use the correct URL).
  3. Click the Reload Docs button.
Update Headers
  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 used to make requests to the Shipping Insights API.
  • X-ShipperHQ-Scope – This is the scope from your ShipperHQ account. It should be one of the following:
    • LIVE
    • TEST
    • INTEGRATION
    • DEVELOPMENT
Please ONLY use the LIVE value if you are not a Magento user.
Send the Query

Using the schema, you can create a query, but you require a valid order number. It is advised you do a very simple query first. Enter this in the query section:

query ViewOrder {
  viewOrder(orderNumber: "000000001") {
    orderNumber
    createdAt
    orderDetail {
       carrierTitle
       methodTitle
    }
  }
}

You should see something like this:

{
  "data": {
    "viewOrder": [
      {
        "orderNumber": "000000001",
        "createdAt": "2020-09-17T13:26:18.839Z",
        "orderDetail": {
          "carrierTitle": "Shipping",
          "methodTitle": "Multiple Warehouses"
        }
      }
    ]
  }
}
Example Basic Query
#
# Fetch a basic
#
# 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 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
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Method 2: Shipping Insights Component Integration

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>

The module is wrapped in a DIV, which has an ov-modal CSS class applied. Note, any custom CSS rules can be applied to that class.

Was this doc helpful?