Skip to main content

Quickstart

The goal of the ShipperHQ SDK is to give you the information you need to use the ShipperHQ APIs. Each API has its own overview, usage guide, quickstart guide, FAQ, and API reference. On these, you'll find detailed information related to each specific API. Below you'll find general information that applies to the ShipperHQ Developer Platform as a whole.

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.

High-level Workflow​

High Level ShipperHQ processes and API

While developers can use each API independently, the goal of the ShipperHQ SDK is to make it easy to integrate with the full ShipperHQ workflow following this sequence:

  1. Rates API
  2. PlaceOrder Mutation (not required for most major integrations)
  3. Insights API
  4. Labels API (in beta)

ShipperHQ Test Accounts​

In order to use ShipperHQ, you'll need to have a ShipperHQ account. Some functionality may also require that your account is on a certain ShipperHQ plan. You can create a ShipperHQ account at ShipperHQ.com which will start with a 15-day free trial.

Developer Support​

To support your integration with ShipperHQ, please use our Dev Support contact form. Our dev support team aims to help you integrate with ShipperHQ as fast as possible with minimal hiccups. Keep in mind that we are ShipperHQ experts, not necessarily experts into your own area of expertise: please share context with us including what you want to achieve and why.

GraphQL​

Our APIs are implemented in GraphQL, an API query language. Compared to other API approaches like SOAP or standard REST, GraphQL makes it easier to request exactly the information you need from our API. This avoids the clutter and extra weight of unnecessary fields in requests and responses.

If you're unfamiliar with GraphQL, Please refer to the Introduction to GraphQL article from GraphQL.org for more information.

GraphQL Benefits​

  • Flexibility: GraphQL gives users the ability to access the details used to obtain the shipping rate and query what is most important to you and your business. As such, you can query 5 pieces of information or every possible field as you see fit.
  • Customization: GraphQL gives users the ability to build their own integration into ShipperHQ to rate shipments, retrieve shipment details, produce labels, and more.

API Playground​

The ShipperHQ API Playground gives you an easy way to test different ShipperHQ APIs without having to write any code. You'll need the Endpoint URL for the API you're looking to experiment with as well as the authorization credentials for that API.

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 (found in the Quickstart doc for each API) 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 Quickstart doc for each API. 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.

Authentication​

ShipperHQ's APIs use two types of authentication:

Integration Requirements​

Each ShipperHQ API is highly flexible and can support a variety of use cases. Due to our implementation of GraphQL, each API call can request only relevant elements be returned. However, for each API, there are certain elements which are important when a ShipperHQ account is using certain functionality. Because of this, if you intend to make your integration of ShipperHQ's APIs 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.

See specific requirements by API:

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