Skip to main content

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.

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.

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.


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

ProtocolMethodBody EncodingEndpoint URL
HTTPSPOSTapplication/JSONhttps://api.shipperhq.com/v2/graphql

Headers

Any query or request must include the following headers:

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

Operations

The ShipperHQ Rates API includes the following operations.

QueryDescription
retrieveShippingQuoteRetrieve basic shipping rates including carrier and method titles and total shipping charges.
retrieveFullShippingQuoteRetrieve 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 NameData TypeDescription
selectedOptionsName/ValueOptional. Name/value pair used to set specific attributes of the destination. See below for available options.
streetStringOptional but recommended for accuracy particularly in a checkout scenario. Can be excluded when requesting an informational estimate (e.g. cart or product pages).
street2StringOptional but recommended for accuracy particularly in a checkout scenario if provided by the end user.
cityStringOptional for most scenarios. Required for certain carriers including DHL Express and most LTL Freight carriers (e.g. YRC Freight, FedEx Freight).
regionStringOptional 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.
zipcodeStringOptional but recommended for many countries (e.g. US, Canada, Australia, UK, etc.). Required by most carriers to return live rates for these countries.
countryStringRequired for nearly all scenarios. Expected value is an ISO alpha-2 country code.

Selected Options

Possible values of the selectedOptions field are:

Option NameData TypeDescription
destination_typeEnumThe 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 NameData TypeDescription
shipperhq_shipping_groupStringAssigns an item to one or more Shipping Groups.
shipperhq_warehouseStringUsed with ShipperHQ's Multi-Origin functionality to specify the Origin or Origins which can fulfill the item.
shipperhq_dim_groupStringAssigns 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
FloatUsed with Dimensional Packing to specify the product's dimensions for packing. If used, all 3 fields are required.
freight_classFloatSets the freight class of the item. Freight classes can also be set on Shipping Groups if this attribute is not used.
shipperhq_hs_codeStringUsed 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_locationStringUsed 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_separatelyBooleanUsed with Dimensional Packing to identify items which are packed separately to other items.
shipperhq_master_boxesStringUsed with Dimensional Packing to assign products to Master Packing Boxes.
shipperhq_availability_dateDateUsed with ShipperHQ's Date & Time functionality to tell ShipperHQ the date on which this product will be available (e.g. backorder, preorder).
shipperhq_declared_valueFloatSets the declared value of the item for use in insurance or duties & tax calculation.
must_ship_freightBooleanTells ShipperHQ this item must ship via a freight carrier.
shipperhq_poss_boxesStringUsed 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 (, ). A hash sign (#) is also accepted but requires that the appVersion in the siteDetails of your request is set to 2.0.0.

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

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:

ElementNotes
cartTypeThe 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
ecommerceCartThe name of the integrated platform (e.g. "Magento" or "XYZ CRM"). Contact Dev Support if unsure.
appVersionThe 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)
ecommerceVersionThe 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)
cartInputThe 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
typeGenerally 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.
itemsIf 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.
attributesThe 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.
customerInputIf 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 ElementRequired
methodDetailmethodTitle and totalCharges
carrierDetailcarrierTitle
timeInTransitOptiondeliveryDate (if included in response)
shipmentsAppropriately handle multiple shipment elements
unitsAppropriately 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 ElementRequired
carrierDetailcarrierCode for the carrier of the method selected by the customer
methodDetailmethodCode 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.