Quickstart

This document is for technical architects and developers that need to integrate with ShipperHQ’s Rates 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 Rates API Reference documentation or can be obtained via our API playground.

Our Rates API is implemented in GraphQL. See the SDK Quickstart for more information.

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

In order to use the ShipperHQ Rates API you'll need a ShipperHQ account configured with at least one Website, one Origin, and one Carrier. Once you have an account, you'll need to retrieve authentication credentials as described below that will allow you to access the Rates API.

Authentication

The ShipperHQ Rates API uses a JWT authentication token generated using credentials specific to each ShipperHQ Account.

Generating a new JWT token is a three step process:

1. Get your ShipperHQ API Key
2. Get your Authentication Code
3. Generate a JWT access token (valid for 30 days)

Only step 3 will need to be repeated every 30 days unless connecting to a different Website in ShipperHQ or re-generating your Authentication Code.

Keep Credentials Private

Your API Key, Authentication Code, and JWT Access Token should be kept secure and not exposed on any client facing code or committed to public code repositories.

Access Scope

Before we dig into the specifics, it is important to define the access scope for the API Key, the Authentication Code and the JWT Access Token. Each of these elements are specific to a single ShipperHQ Website.

You can think of a Website as a sale channel. For instance an online store in the US (production), an online store in Canada (production), a development store, or a CRM sales channel (offline sales). Because ShipperHQ supports multiple Websites, each Website can have its own Shipping rules. Each Website will, as a consequence, generate different type of rates for the same virtual cart and customer choices.

To reflect this level of functionality, authorization and access to the Rates API is specific to a Website: you need a different set of credentials for each ShipperHQ Website.

More information about Websites in ShipperHQ

Retrieving an API Key

API Keys are accessible via the ShipperHQ dashboard. To get the API key:

1. Log into ShipperHQ and go to the Websites section of the dashboard.
2. Select the Website you want to get the key from
3. Select the API key and copy it to your application

Retrieving an Authentication Code

The method for retrieving your Authentication Code varies depending on your eCommerce platform and whether or not this is a new or existing ShipperHQ Account.

New Manually Connected Accounts

Platforms: Magento (Adobe Commerce), WooCommerce, Zoey, Salesforce B2C Commerce Cloud

On these platforms, you can generate a new Authentication Code within the ShipperHQ dashboard.

1. Visit the Websites section of the dashboard
2. Click on the relevant Website
3. Click on "Generate new Authentication Code"
4. Copy the code: It will not be shown again for this Website.

Changing Live Authentication Codes

Generating a new Authentication Code invalidates the previous Authentication Codes for that Website. This should not be done while in production unless absolutely necessary. We recommend creating a new Website for new integrations to avoid impacting existing integrations. Contact Dev Support to double-check and avoid any service disruption for existing Websites.

New Single Sign On Accounts

Platforms: BigCommerce, Shopify

For these platforms, the Authentication Code is automatically generated and exchanged between the eCommerce platform and ShipperHQ. It is not available within the ShipperHQ dashboard but can be provided by our developer support team.

Contact Dev Support and make sure to specify the URL of the Website for which you would like to get the Authentication Code.

Existing Accounts

Platforms: All

Please contact Dev Support and make sure to specify the URL of the Website for which you would like to get the Authentication Code.

---

Generating your JWT Authentication Token

Once you have your ShipperHQ API Key and Authentication Code, you can generate the JWT token used to access the ShipperHQ Rates API.

The ShipperHQ API Playground can be used to create an Authentication Token for testing. You will need to use this same query in your integration to create secret tokens when required.

1. Navigate to the ShipperHQ API Playground
2. Click Add New in the top left corner
3. Set the URL to https://rms.shipperhq.com
4. Click the Reload Docs button
5. Send a createSecretToken mutation with your API Key and Authentication Code

The response contains the token you use to make requests to the ShipperHQ Rates API. This token expires every 30 days.

Example Secret Token Request

Create a secret token

mutation CreateSecretToken {
   createSecretToken(
      api_key: "your_api_key",
      auth_code: "your_auth_code"
      )
      {
        token
      }
}

JWT Token Expiration

The JWT tokens used by ShipperHQ have a 30 day expiration timestamp encoded inside: no need to remember the expiration date. We recommend using your favorite JWT parsing library to extract the expiration date, so you will know the exact second the token expires. New tokens can be requested up to an hour before the current token expires.

Definitions

Endpoint

Protocol	Method	Body Encoding	Endpoint URL
HTTPS	POST	application/JSON	https://api.shipperhq.com/v2/graphql

Headers

Any query or request must include the following headers:

Header Name	Header description
X-ShipperHQ-Secret-Token	This is the JWT Secret token you have generated for your ShipperHQ account.
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.
X-ShipperHQ-Session	This is a unique identifier for a cart/order. Use any unique alphanumeric string.

Operations

The ShipperHQ Rates API includes the following operations.

Query	Description
retrieveShippingQuote	Retrieve basic shipping rates including carrier and method titles and total shipping charges.
retrieveFullShippingQuote	Retrieve detailed shipping rate information for each shipment, including origin or warehouse information, carrier and method information, freight options available, available dates, in-store pickup information, and more.

Details

API Rate Limits

• Request Limits: Rates API queries are subject to the request limits of your ShipperHQ account. Please view your request limits on ShipperHQ’s pricing page.
• Monitoring Request limits: You can view your usage within the Analytics tab of your ShipperHQ dashboard.

Ship-To Address

The address to which the order will be shipped is defined in the destinationInput type. While destinationInput should always be included, the specific fields required depend on several factors. A limited set of fields (e.g. region, zipcode, country) can be used in cases where a low-accuracy shipping estimate is required (e.g. on shopping cart or product pages).

Option Name	Data Type	Description
selectedOptions	Name/Value	Optional. Name/value pair used to set specific attributes of the destination. See below for available options.
street	String	Optional but recommended for accuracy particularly in a checkout scenario. Can be excluded when requesting an informational estimate (e.g. cart or product pages).
street2	String	Optional but recommended for accuracy particularly in a checkout scenario if provided by the end user.
city	String	Optional for most scenarios. Required for certain carriers including DHL Express and most LTL Freight carriers (e.g. YRC Freight, FedEx Freight).
region	String	Optional but recommended for certain countries (e.g. US, Canada, Australia, etc.). Required by certain carriers to return live rates. Expected values vary by country but most are standard 2-character region codes.
zipcode	String	Optional but recommended for many countries (e.g. US, Canada, Australia, UK, etc.). Required by most carriers to return live rates for these countries.
country	String	Required for nearly all scenarios. Expected value is an ISO alpha-2 country code.

Selected Options

Possible values of the selectedOptions field are:

Option Name	Data Type	Description
destination_type	Enum	The type of address given. Values can be residential or commercial. Address type may be set explicitly here or can be determined automatically by ShipperHQ's Address Validation functionality.

destination Example

"destination": {
    "street": "4801 Southwest Pkwy",
    "street2": "Bldg 2, Ste 240",
    "city": "Austin",
    "region": "TX",
    "zipcode": "78738",
    "country": "US",
    "selectedOptions": [ {
        "name" : "destination_type",
        "value" : "commercial"
      } ]
}

Item Attributes

Item attributes in the request allow you to include item-specific values like a shipping group or an origin. They may be required if you are using any type of features such as Shipping Groups, Dimensional Packing, Multi-Origin, etc.

These attributes and their values are sent in a set of name/value pairs in the attributes field of an item on a Rates API request. The most common attributes are listed below.

Values are case sensitive

All item attribute values are case sensitive and must match the corresponding item configured in the ShipperHQ dashboard including any spaces.

For example, if the name of an Origin in ShipperHQ is "New York", none of "NEW YORK", "new york", or "NewYork" would match.

Attribute Name	Data Type	Description
shipperhq_shipping_group	String	Assigns an item to one or more Shipping Groups.
shipperhq_warehouse	String	Used with ShipperHQ's Multi-Origin functionality to specify the Origin or Origins which can fulfill the item.
shipperhq_dim_group	String	Assigns an item to a Packing Rule used in Dimensional Packing. Only required when Dimensional Rules are used to pack specific items differently than general packing rules.
ship_length ship_width ship_height	Float	Used with Dimensional Packing to specify the product's dimensions for packing. If used, all 3 fields are required.
freight_class	Float	Sets the freight class of the item. Freight classes can also be set on Shipping Groups if this attribute is not used.
shipperhq_hs_code	String	Used with ShipperHQ's Landed Cost Engine functionality and shipping providers which return cross-border duties & taxes to set the HS Code of the item.
shipperhq_location	String	Used with ShipperHQ's In-Store Pickup functionality to specific the Location or Locations where the item is available for pickup. Not necessary if all items are available from all locations.
ship_separately	Boolean	Used with Dimensional Packing to identify items which are packed separately to other items.
shipperhq_master_boxes	String	Used with Dimensional Packing to assign products to Master Packing Boxes.
shipperhq_availability_date	Date	Used with ShipperHQ's Date & Time functionality to tell ShipperHQ the date on which this product will be available (e.g. backorder, preorder).
shipperhq_declared_value	Float	Sets the declared value of the item for use in insurance or duties & tax calculation.
must_ship_freight	Boolean	Tells ShipperHQ this item must ship via a freight carrier.
shipperhq_poss_boxes	String	Used with ShipperHQ's Dimensional Packing functionality to set the boxes which this item may pack into. Not necessary if using Dimensional Rules to set item box assigments.

Delimiting multiple values

A delimiter is required between multiple values for item attributes. The default delimiter is a comma (,) followed by an optional space (, ).

Attributes Example

"attributes" : [ {
    "name" : "shipperhq_shipping_group",
    "value" : "FLAT59,FREE"
  }, {
    "name" : "ship_width",
    "value" : "2.0000"
  }, {
    "name" : "ship_length",
    "value" : "2.0000"
  }, {
    "name" : "ship_height",
    "value" : "36.0000"
  }, {
    "name" : "shipperhq_dim_group",
    "value" : "RULE1,RULE2"
  }, {
    "name" : "shipperhq_hs_code",
    "value" : "123456"
  }, {
    "name" : "shipperhq_warehouse",
    "value" : "ORIGIN1,ORIGIN2"
  } ],

Requested Options

Requested Options allow you to 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 sent in a set of name/value pairs in the requestedOptions field on a Rates API request. 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.

Available Options Example

requestedOptions: {
   options: [
   {
       code: "liftgate_required",
       value:  "true"
   },
   {
       code: "destination_type",
       value: "residential"
   }]}   

Product Types

ShipperHQ accepts multiple product types which are handled differently. These are indicated in the type property of item objects. See below for available product types and how they're handled.

The most common product type is SIMPLE. This applies to the majority of individual, shippable products.

The DOWNLOADABLE, GIFTCARD, and VIRTUAL types represent products that are not shipped. They may impact the shipping rate returned depending on the configuration of the ShipperHQ account (e.g. if Gift Cards contribute to an order's eligibility for free shipping) so should be included in rate requests. Weights are not required for these items.

Other types represent groups of items purchased together. These are the BUNDLE, GROUPED, and CONFIGURABLE types. For these items, we expect the item to contain additional items in its items property. These are the "Child" items of this "Parent" item. Depending on the configuration of the ShipperHQ account, shipping rates may be calculated based solely on the Parent products or on the Child products.

Integration Requirements

While very few elements are required for a successful API call to the Rates API (see the Rates API Reference), there are certain elements that are required in order to support certain features and functionality of ShipperHQ. Because of this, if you intend to make your integration of ShipperHQ's Rates 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.

Some requirements are dependent on the capabilities of the platform into which ShipperHQ is being integrated. For example, if the platform doesn't support Customer Groups, that field is not required. These exceptions are noted below.

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 Rates 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:

• Use the retrieveFullShippingQuote query in any checkout/transactional workflows (retrieveShippingQuote may be used for informational shipping quotes e.g. shipping estimates presented on a Cart or Product page)
• Provide clients with a UI for entering their ShipperHQ Account-specific API credentials and use those credentials in all API calls to ShipperHQ
• Send a unique value in the X-ShipperHQ-Session request header for each shipping quote request

Request Requirements

In addition to the general integration requirements, there are specific elements that should be included in an integration:

Element	Notes
cartType	The appropriate Cart Type for each rate quote should be set. E.g. CART for shipping estimate in a shopping cart, STD for checkout, etc.
siteDetailsInput	ecommerceCart The name of the integrated platform (e.g. "Magento" or "XYZ CRM"). Contact Dev Support if unsure. appVersion The version of your integration with ShipperHQ (e.g. your first release may be "1.0.0" but updated to "1.0.1" at a later date) ecommerceVersion The version number of the platform on which the integration sits (e.g. for a Magento extension, this would indicate the version of Magento on which the extension is installed)
cartInput	The freeShipping elements indicates that free shipping applies to the entire cart. Should be used if the integrated platform supports order-level free shipping and set to true when the cart is eligible for free shipping.
items	type Generally set to SIMPLE but if the integrated platform supports item bundles, the BUNDLE type should be used and child items included under those products. If the integrated platform supports VIRTUAL or GIFTCARD products, the appropriate type should be used. items If the integrated platform supports item bundles, the BUNDLE type should be used and the child items should be included in the items property. For SIMPLE products this element is not required. attributes The following minimum product attributes should be supported: shipperhq_shipping_group shipperhq_warehouse shipperhq_dim_group ship_length, ship_width, ship_height freight_class shipperhq_hs_code See the Item Attributes section of this doc for details on these attributes and for other attributes that may be supported if useful for your integration.
customerInput	If the integrated platform supports assigning Customer Groups, the group name should be included in the customerGroup element.

Response Requirements

When ShipperHQ returns a response, the following provides the minimum information that should be displayed to the end user:

Parent Element	Required
methodDetail	methodTitle and totalCharges
carrierDetail	carrierTitle
timeInTransitOption	deliveryDate (if included in response)
shipments	Appropriately handle multiple shipment elements
units	Appropriately handle responses according to the units returned by ShipperHQ

Order Completion

When an end user has selected a shipping method and completed the order, the methodTitle, carrierTitle, and (if applicable) deliveryDate chosen by the customer should be stored along with the order. Additionally, the following should be stored within the integrated system along with the order:

Parent Element	Required
carrierDetail	carrierCode for the carrier of the method selected by the customer
methodDetail	methodCode for the method selected by the customer
fullShippingQuote or basicShippingQuote	The transactionId uniquely identifies the response and is useful in troubleshooting, it should be stored. Optionally, the entirety of the rate request and response may be stored.

Error Handling

The ShipperHQ Rates API may return errors in an error object 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 a specific Carrier or service is unavailable, ShipperHQ will return an error within the carrier. This type of error may indicate that ShipperHQ was unable to return options for this carrier due to a problem (e.g. carrier API timeout), that the ShipperHQ configuration was intentionally set to prevent this carrier from returning any options, or configured to intentionally prevent this carrier from returning specific options for this order. These error objects will include an errorCode and internalErrorMessage which should not be displayed to the end user but may also include an externalErrorMessage which may be displayed to the end user. Your integration should support displaying these messages.

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

Additional Guidance

While the Rates 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

Test with the API Playground

The ShipperHQ API Playground gives you an easy way to test the ShipperHQ Rates 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 (https://api.shipperhq.com/v2/graphql) 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.

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

You'll find examples of both simple and more advanced Rates API requests and their associated responses for a number of common scenarios as well as a Postman collection with pre-configured examples on the Examples doc.

See Examples

Errors

When ShipperHQ encounters an error processing your request, an error object will be returned. This will include:

1. An errorCode: A unique identifier for the specific error encountered which can be used to look up additional information during troubleshooting or provided to ShipperHQ when seeking assistance.
2. internalErrorMessage: Describes the specific error encountered, intended to be used in troubleshooting and not displayed to the end user.
3. externalErrorMessage: A message that can be shown to the end user when an error is encountered. Most commonly used when shipping is intentionally prevented in a specific scenario (e.g. "We are unable to ship to your location."). These messages can be configured within the ShipperHQ dashboard.

Error Example

"errors": [
    {
      "errorCode": 403,
      "internalErrorMessage": "No applicable carriers have been found for this origin.",
      "externalErrorMessage": "This shipping method is currently unavailable. If you would like to ship using this shipping method, please contact_us.",
      "priority": 999
    }
  ]

Possible errorCode Values

A detailed list of errorCode values and associated internalMessage values can be found on the Rates API FAQ.