Skip to main content


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.



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.



ProtocolMethodBody EncodingEndpoint URL


The following headers are required for every Insights API call.

X-ShipperHQ-Access-TokenThe Access Token retrieved from the ShipperHQ dashboard
X-ShipperHQ-ScopeThe 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.


The ShipperHQ Insights API includes the following operation.

viewOrderReturns detailed shipment information for a given order.



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 {

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 {
# ...
items {
# ...

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 {
# ...

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 OptionsData TypeDescription
liftgate_requiredBooleanThis specifies liftgate is required at the destination.
notify_requiredBooleanThis requests an appointment delivery or notice of delivery.
inside_deliveryBooleanThis requests delivery inside the destination.
limited_deliveryBooleanThis specifies limited access at the destination address.
destination_typeEnumSpecifies 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.


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.


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 ElementElementDescription
ordershipmentsEach 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.
shipmentgroupedItemsEach shipment may contain one or more items. Note: these may be packed into one or more packages (see below).
rateBreakdownpackagesOne or more packages may be used in rating a method.
packageitemsEach package may contain one or more items.

Specific Elements and Properties

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

Parent ElementProperties
carrierCodeUnique identifier for the carrier selected by the customer at checkout. Useful for automated processing of orders.
carrierTitleUser-friendly name of the carrier selected by the customer at checkout.
methodCodeUnique identifier for the method selected by the customer at checkout. Useful for automated processing of orders.
methodTitleThe user-friendly name of the method selected by the customer at checkout.
totalChargesThe total amount charged for shipping to the customer.
transactionIdA unique identifier for the shipping quote requested that provided the shipping option selected. Useful for troubleshooting when contacting ShipperHQ support.
nameIn 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.
carrierCodeUnique identifier for the carrier selected by the customer at checkout. Useful for automated processing of orders.
carrierTitleUser-friendly name of the carrier selected by the customer at checkout.
carrierTypeIdentifies 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".
methodCodeUnique identifier for the method selected by the customer at checkout. Useful for automated processing of orders.
methodTitleThe user-friendly name of the method selected by the customer at checkout.
totalChargesThe total amount charged for shipping to the customer.
currencyCurrency of the shipping charge.
negotiatedRateBoolean indicator for if the rates returned were negotiated (account) rates with the carrier. Only applies to certain live-rate carriers.
dispatchDateIf Date & Time applies to this shipment, indicates the estimated date on which the shipment will be dispatched. Useful for order processing.
deliveryDateIf Date & Time applies to this shipment, indicates the estimated date on which the shipment will be delivered.
handlingFeeReflects any Handling Fees defined on the carrier in ShipperHQ.
shippingPriceThe cost of shipping generated by the custom-rate carrier or returned by the live-rate carrier.
totalChargesResulting total of shipping charged after all fees have been applied.
costBase shipping rate before any rules or fees were applied.
customDutiesIf using Landed Cost Engine or a carrier which supports returning duties and taxes, indicates the duties and taxes.
Package dimensions.
packageNameIf using Dimensional Packing, the name of the Box used.
packingWeightTotal weight of the package including items.
weightWeight of the items contained in the package.
skuItem SKU.
qtyPackedQuantity of the item packed in this package.
weightPackedWeight of the item packed in this package.
selectedOptionIndiciates accessorial options selected at checkout (e.g. liftgate, inside delivery, etc.)
pickupNameUnique name of the pickup location as configured in ShipperHQ.
publicIdPublic ID of the location (for pickup at location services e.g. UPS Access Point, FedEx Hold at Location, PUDO).
addressThe 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.


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

  1. ShipperHQ's native integration installed and enabled on Magento 2, BigCommerce, or Shopify
  2. 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

  1. Navigate to the ShipperHQ API Playground
  2. Open a new API playground tab ("+ Add new" button in top navbar)
  3. Enter the API Endpoint URL ( into the URL bar
  4. Click the Docs button
  5. Click the Reload Docs (refresh) icon
  6. 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:

  1. Click the Headers (asterisk) icon in the left-hand navbar
  2. 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.


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.


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


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.