Quickstart

This document is for technical architects and developers that need to integrate with ShipperHQ’s Insights API to build their own integration to retrieve shipment details from ShipperHQ.

Note, this does not document the standard types and fields the API provides. This information is included in the Insights API Reference documentation or can be obtained via our API playground.

As with all our APIs, our Insights API is implemented with GraphQL. If you're unfamiliar with GraphQL, see our SDK Quickstart.

API Access Available on ShipperHQ Enterprise

Access to the ShipperHQ APIs requires a ShipperHQ Enterprise plan. You can check your current plan in your ShipperHQ Dashboard. If you're not currently on an Enterprise plan, please contact us to review upgrade options.

Note: This requirement does not apply to ShipperHQ Partners. Contact our Partnerships team for more info.

Requirements

ShipperHQ account with the Shipping Insights Advanced Feature enabled
An eCommerce platform or custom integration supporting the PlaceOrder mutation of the Labels API, either:
- ShipperHQ’s native Magento 2, BigCommerce, or Shopify app installed on the eCommerce platform
- A custom integration implementing both our Rates API and the PlaceOrder mutation of our Labels API

Authentication

The Insights API is accessed using a unique Access Token generated in a ShipperHQ account. Each access token is unique per Website for multi-site ShipperHQ accounts.

Since Access Tokens are unique for each ShipperHQ account and Website, Partners or Third Party integrations should include a mechanism for merchants to input their Shipping Insights Access Token in the integration. Each ShipperHQ merchant will generate an access token on their ShipperHQ account in order to access the Insights API for their orders.

Generating an Access Token

To generate an access token in ShipperHQ:

Log into a ShipperHQ account
Ensure the Shipping Insights Advanced Feature is enabled (under Advanced Features on the left-hand navbar)
Click "Websites" in the left-hand navbar and click the edit icon to edit the website which you wish to connect to
Go to the "Integrations" tab on the Website
Under Shipping Insights, select Generate New Access Token

This will provide you with an Access Token which can be used for Insights API requests.

Changing Live Access Tokens

Generating a new Access Token invalidates any previously generated Access Tokens for that Website. For this reason, this should not be done while in production unless absolutely necessary. Access Tokens should be kept secure and not exposed on any client facing code or committed to public code repositories.

Definitions

Endpoint

Protocol	Method	Body Encoding	Endpoint URL
`HTTPS`	`POST`	`application/JSON`	`https://ovs.shipperhq.com`

Headers

The following headers are required for every Insights API call.

Header	Description
`X-ShipperHQ-Access-Token`	The Access Token retrieved from the ShipperHQ dashboard
`X-ShipperHQ-Scope`	The configuration Scope for this ShipperHQ Website (accepts `LIVE`, `TEST`, `DEVELOPMENT`, or `INTEGRATION`). If unsure or if the ShipperHQ account does not support multiple scopes, use `LIVE`.

Operations

The ShipperHQ Insights API includes the following operation.

Query	Description
`viewOrder`	Returns detailed shipment information for a given order.

Details

`orderNumber`

The orderNumber argument of the viewOrder call is used to look up a unique order with the Insights API. If you are using the native ShipperHQ apps/plugins/extensions for supported eCommerce platforms (complete list here), the orderNumber will be the Order Number set by your eCommerce platform. If you are instead using the PlaceOrder mutation of the Labels API, orderNumber will be the value you set as the Order Number in your PlaceOrder call.

Useful fields by feature

Date & Time

The Date & Time Advanced Feature allows merchants to give their customers accurate delivery dates, times in transit, or even a date picker on supported eCommerce platforms. In order to determine the correct delivery date to display, ShipperHQ also generates a Dispatch Date (the date on which the package is expected to be picked up by the carrier) based on the merchant's ShipperHQ configuration. For merchants who use Date & Time, it's useful to have the Insights API return the Dispatch and Delivery dates.

Fields for Date & Time

You can retrieve the dispatch date as well as the delivery promise via the timeInTransitOptions object:

query Order {
  viewOrder(orderNumber: "...") {
    # ...
    shipments {
      carriers {
        methods {
          timeInTransitOptions{
            deliveryDate
            dispatchDate
          }
        }
      }
    }
  }
}

Dimensional Packing

The Dimensional Packing will determine the best package or packages to use for each shipment based on the merchant's ShipperHQ configuration. When Dimensional Packing is used, the Insights API can return the packages, details about each package, and item assignments for each.

This information will be returned as one or more packages objects each containing packageDetail and items objects. The packageName field of the packageDetail object will be the name defined in ShipperHQ for that package. The items object may contain one or more items and indicate the sku of each as well as the quantity of that SKU packed in this package.

Fields for Dimensional Packing

You can retrieve the package information via the packageDetail object including the item(s) in each package:

query Order {
  viewOrder(orderNumber: "...") {
    # ...
    shipments {
      carriers {
        packages {
          packageDetail {
            height
            length
            width
            weight
            packageName
            # ...
          }
        }
        items {
          sku
          qtyPacked
          # ...
        }
      }
    }
  }
}

note

Other related fields are available and can be found in the Insights API Reference documentation.

Multi-Origin Shipping

With the Multi-Origin Shipping Advanced Feature enabled, merchants are able to configure multiple ship-from locations (Origins) in their ShipperHQ account. They can then assign specific products to specific Origins or use their ShipperHQ configuration to configure ShipperHQ to select Origins automatically.

When an order contains shipments from multiple Origins, the Insights API will return multiple shipments objects. Each shipment has its own unique ID and contains the details about that shipment and the carriers used for that shipment. No special Insights API request is required to return multiple shipments but there are some fields which are useful in this scenario.

Fields for Multi-Origin

The unique name of the origin as configured in ShipperHQ is returned as the value of the name field of shipmentDetail.

query Order {
  viewOrder(orderNumber: "...") {
    # ...
    shipments {
      shipmentDetail {
        name
        # ...
      }
    }
  }
}

note

Other related fields are available and can be found in the Insights API Reference documentation.

Requested Options

Requested Options indicate specific services or properties for the entire shipment such as "Liftgate Required" or "Residential Delivery". These are most commonly used for LTL Freight carriers or small package carriers that offer specific delivery methods for residential delivery.

These attributes and their values are returned in a set of name/value pairs in the selectedOption field on a Insights API response. The most common attributes are listed below.

Requested Options	Data Type	Description
`liftgate_required`	Boolean	This specifies liftgate is required at the destination.
`notify_required`	Boolean	This requests an appointment delivery or notice of delivery.
`inside_delivery`	Boolean	This requests delivery inside the destination.
`limited_delivery`	Boolean	This specifies limited access at the destination address.
`destination_type`	Enum	Specifies if a destination is a residential (`residential`) or business (`commercial`) address.

Integration Requirements

Our Insights API can return a variety of useful information (see the Insights API Reference for full details) and you can request as little or as much as needed. However, there are certain elements that are important when a ShipperHQ account is using certain functionality. Because of this, if you intend to make your integration of ShipperHQ's Insights API available to multiple clients we require support for certain elements. Meeting these requirements means your integration will support all of the most commonly used ShipperHQ features and functionality.

The following sections describe the fields that can be returned by the Insights API which integrations should support retrieving and processing.

info

While we have endeavored to provide a complete list of requirements for a baseline integration of ShipperHQ, individual use cases may differ. Therefore, we always recommend contacting Dev Support prior to building a new integration.

note

We don't require single-purpose, custom integrations to meet these requirements. However, we do strongly recommend that all integrations of the ShipperHQ Insights API do so in order to support the breadth of ShipperHQ's capabilities and to future-proof the integration against shipping needs that may change in the future.

General Requirements

The integration should:

Provide clients with a UI for entering their ShipperHQ Account-specific API credentials and use those credentials in all API calls to ShipperHQ

Request Requirements

Each request to viewOrder requires that the orderNumber argument is included. See the orderNumber section of this guide for more information.

Response Handling

Since each ShipperHQ account may be configured with different features and functionality, it's important to support a fairly broad set of response elements in any integration. These are discussed below. See the Insights API Reference for all available options.

Handling Multiples

Certain elements may contain multiple child elements. The integration should be able to handle multiples of these elements appropriately:

Parent Element	Element	Description
`order`	`shipments`	Each order may contain one or more shipments. For example, when using Multi-Origin Shipping, a single order may contain items being fulfilled from different distribution facilities. Or, if certain items in the order must ship via an LTL freight carrier but others must ship via an express service, the ShipperHQ account may be configured to split these into separate shipments from the same Origin. Each shipment will have its own set of details include the carrier, method, and rates used for that shipment.
`shipment`	`groupedItems`	Each shipment may contain one or more items. Note: these may be packed into one or more `packages` (see below).
`rateBreakdown`	`packages`	One or more packages may be used in rating a method.
`package`	`items`	Each package may contain one or more items.

Specific Elements and Properties

The integration should appropriately handle at minimum the following elements and properties:

Parent Element Properties

orderDetail

`carrierCode`	Unique identifier for the carrier selected by the customer at checkout. Useful for automated processing of orders.
`carrierTitle`	User-friendly name of the carrier selected by the customer at checkout.
`methodCode`	Unique identifier for the method selected by the customer at checkout. Useful for automated processing of orders.
`methodTitle`	The user-friendly name of the method selected by the customer at checkout.
`totalCharges`	The total amount charged for shipping to the customer.
`transactionId`	A unique identifier for the shipping quote requested that provided the shipping option selected. Useful for troubleshooting when contacting ShipperHQ support.

shipmentDetail

name In multi-shipment scenarios, this is the identifier for the specific shipment. Most frequently used in Multi-Origin orders. For multi-origin shipments, name will be the unique name of the Origin configured in ShipperHQ.

carrierDetail

`carrierCode`	Unique identifier for the carrier selected by the customer at checkout. Useful for automated processing of orders.
`carrierTitle`	User-friendly name of the carrier selected by the customer at checkout.
`carrierType`	Identifies the live-rate or custom-rate carrier used. Since ShipperHQ can be configured to use custom names and codes for carriers, this provides identification for the "behind-the-scenes" carrier. E.g. "ups" or "auspost".

methodDetail

`methodCode`	Unique identifier for the method selected by the customer at checkout. Useful for automated processing of orders.
`methodTitle`	The user-friendly name of the method selected by the customer at checkout.
`totalCharges`	The total amount charged for shipping to the customer.
`currency`	Currency of the shipping charge.
`negotiatedRate`	Boolean indicator for if the rates returned were negotiated (account) rates with the carrier. Only applies to certain live-rate carriers.

timeInTransitOptions

`dispatchDate`	If Date & Time applies to this shipment, indicates the estimated date on which the shipment will be dispatched. Useful for order processing.
`deliveryDate`	If Date & Time applies to this shipment, indicates the estimated date on which the shipment will be delivered.

advancedFees

`handlingFee`	Reflects any Handling Fees defined on the carrier in ShipperHQ.
`shippingPrice`	The cost of shipping generated by the custom-rate carrier or returned by the live-rate carrier.
`totalCharges`	Resulting total of shipping charged after all fees have been applied.
`cost`	Base shipping rate before any rules or fees were applied.
`customDuties`	If using Landed Cost Engine or a carrier which supports returning duties and taxes, indicates the duties and taxes.

packageDetail

`height` `length` `width`	Package dimensions.
`packageName`	If using Dimensional Packing, the name of the Box used.
`packingWeight`	Total weight of the package including items.
`weight`	Weight of the items contained in the package.

item

`sku`	Item SKU.
`qtyPacked`	Quantity of the item packed in this package.
`weightPacked`	Weight of the item packed in this package.

selectedOption Indiciates accessorial options selected at checkout (e.g. liftgate, inside delivery, etc.)

pickupLocationDetail

`pickupName`	Unique name of the pickup location as configured in ShipperHQ.
`publicId`	Public ID of the location (for pickup at location services e.g. UPS Access Point, FedEx Hold at Location, PUDO).

address

The following address elements must be supported:

company
street
street2
city
region
zipcode
country

Error Handling

The ShipperHQ Insights API may return errors in in several cases:

If ShipperHQ encounters a general error processing a request (e.g. credentials issues, malformed request, etc.) an error message will be returned indicating the type of error encountered. In this case, your integration should appropriately display a user-friendly message. The values of the errorCode and internalErrorMessage are not intended to be displayed to end-users but are useful to log for troubleshooting.
If no shipment information can be found for the given OrderNumber

See the Errors section of this doc for further details and for possible error codes and messages see the Insights API FAQ.

Additional Guidance

While the Insights API Reference contains all available fields, not all possible attributes are described in the current version of this guide. Some less-common attributes are not yet described. Contact Dev Support if you need assistance with any specific scenario or for additional guidance on best practices for your specific use case.

Testing

To test the Insights API you will need to already have either:

ShipperHQ's native integration installed and enabled on Magento 2, BigCommerce, or Shopify
A custom integration of the ShipperHQ Rates API and the PlaceOrder mutation of the Labels API.

Enable & Retrieve Access Token

Within the ShipperHQ account you wish to use, enable the Shipping Insights Advanced Feature from the Advanced Features section of the dashboard. Then, retrieve the Shipping Insights Access Token from the Website on that account.

Place an Order

Place an order on your eCommerce or custom platform. Note the Order Number since this will be used to retrieve Shipping Insights information.

Test with the API Playground

The ShipperHQ API Playground gives you an easy way to test the ShipperHQ Insights API without having to write any code.

Loading and Viewing Docs

Navigate to the ShipperHQ API Playground
Open a new API playground tab ("+ Add new" button in top navbar)
Enter the API Endpoint URL (https://ovs.shipperhq.com) into the URL bar
Click the Docs button
Click the Reload Docs (refresh) icon
Click the Query, Mutation, or Subscription link to view a list of available actions and the arguments and fields you can include in your request

Updating Headers

Authentication information for ShipperHQ's APIs is sent in HTTP headers. Required Headers can be found in the Request Headers section of this doc. In the API Playground, these can be set in the Headers window:

Click the Headers (asterisk) icon in the left-hand navbar
Enter the required Header keys and Header values for the API you're using (e.g. "X-ShipperHQ-Secret-Token")

Creating a Query

In the left-hand column of the API Playground you can enter your desired query body. As you browse the Docs in the API Playground, you can use the "ADD QUERY" buttons to add a basic version of a given query to the body. You can also add specific elements of a query using the "ADD FRAGMENT" buttons shown next to each field. Alternately, copy and paste an example from one of our API Guides and update its variables to match the appropriate values for your use case.

When you click "Send Request" the response will be shown in the panel between the body and Docs. You'll also see HTTP status and status codes. To see previous queries and results, click the History (counter-clockwise clock) icon in the left-hand navbar.

note

The GraphQL tool used in our API Playground does not always display errors in your headers/queries. If docs fail to load, please clear all fields/headers, try again, and use Inspect Element/Console to see errors.

Examples

Since the Insights API is implemented in GraphQL, you can retrieve as much information as you want or as little as you need. You'll find examples of both simple and more advanced Insights API requests and their associated responses as well as a Postman collection with pre-configured examples on the Examples doc.

See Examples

Errors

Most errors are returned as an errors object. These will include a message property which will indicate the specific error.

No order found

When an order can not be found that matches the orderNumber provided an empty viewOrder object will be returned.

Authentication issues

If the Access Token provided is invalid or the ShipperHQ account it belongs to is disabled, the error message Access Denied will be returned.

API Access Available on ShipperHQ Enterprise

Requirements​

Authentication​

Generating an Access Token​

Changing Live Access Tokens

Definitions​

Endpoint​

Headers​

Operations​

Details​

orderNumber​

Useful fields by feature​

Date & Time​

Dimensional Packing​

note

Multi-Origin Shipping​

note

Requested Options​

Integration Requirements​

info

note

General Requirements​

Request Requirements​

Response Handling​

Handling Multiples​

Specific Elements and Properties​

Error Handling​

Additional Guidance​

Testing​

Enable & Retrieve Access Token​

Place an Order​

Test with the API Playground​

Loading and Viewing Docs​

Updating Headers​

Creating a Query​

note

Examples​

Errors​

No order found​

Authentication issues​

Requirements

Authentication

Generating an Access Token

Definitions

Endpoint

Headers

Operations

Details

`orderNumber`

Useful fields by feature

Date & Time

Dimensional Packing

Multi-Origin Shipping

Requested Options

Integration Requirements

General Requirements

Request Requirements

Response Handling

Handling Multiples

Specific Elements and Properties

Error Handling

Additional Guidance

Testing

Enable & Retrieve Access Token

Place an Order

Test with the API Playground

Loading and Viewing Docs

Updating Headers

Creating a Query

Examples

Errors

No order found

Authentication issues