Quickstart

This document is for technical architects and developers that need to integrate with ShipperHQ’s Labels API to build their own integration to generate and print shipping labels.

Note, this does not document the standard types and fields the API provides. This information is included in the Labels API Reference documentation, which is available to early access partners. Please contact us if interested..

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

Early Access Program

The ShipperHQ Labels API is currently in closed Beta. ShipperHQ is looking for early access partners interested in participating in this program. Please contact us if interested.

Pricing

Usage of the Labels API will not be free and its use is not covered by a base ShipperHQ subscription. A cost per label will be incurred when creating labels via this API. Exact pricing will be announced in future. Contact us 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

• ShipperHQ account with the Generate Shipping Labels 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
• An account with at least one of the carriers supported by the ShipperHQ Labels API connected to your ShipperHQ account and configured to allow label generation

Authentication

The ShipperHQ Labels 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 Labels 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 Labels 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 Labels 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://postapi.shipperhq.com/v3/graphql/label

Headers

Header	Description
X-ShipperHQ-Secret-Token	The JWT Secret token you have generated for your ShipperHQ account.

Operations

The ShipperHQ Labels API includes the following operations.

Query	Description
placeOrder	Used to indicate to ShipperHQ that a certain quote should be stored and associated with a given OrderNumer. See the PlaceOrder Mutation Guide for usage details.
createLabel	Creates and returns a shipping label. See Creating Labels for usage details.
createManifest	Used to create a manifest required by certain carriers. See Creating Manifests for usage details.
cancelLabel	Cancels a given label that has been generated by ShipperHQ. See Cancelling Labels for usage details.

Details

Requested Services

The requestedServices field of LabelPieceInput is used to define specific add-on services to be used on a given package. Currently, SIGNATURE_OPTION is the only supported Requested Service. The values used vary by carrier as outlined below.

Name

Values

SIGNATURE_OPTION

FedEx Desc. FedEx Value UPS Desc. UPS Value Service Default SERVICE_DEFAULT No Signature Required NO_SIGNATURE_REQUIRED None null Indirect Signature Required INDIRECT Delivery Confirmation 1 Direct Signature Required DIRECT Signature Required 2 Adult Signature Required ADULT Adult Signature Required 3 Note: Default signature required options can be set on the carrier in the ShipperHQ dashboard. Use SIGNATURE_OPTION in requestedServices to override these defaults.

Label Formats and Stock

ShipperHQ can return a variety of label formats, sizes, and types. Additionally, we support formats intended for laser printers to be printed on standard paper as well as thermal label stock. These options are set on the Carrier in ShipperHQ. The specific options available vary by carrier but the options chosen will change the resulting label image returned by the Labels API.

Carriers and Methods

The Labels API current supports UPS, FedEx, and USPS. The carrierId and methodCode fields identify the specific carrier and method, respectively, you're generated a label for. These fields are defined below.

Parent Element	Element(s)	Notes
CarrierInput	carrierType	The carrier type code for the selected carrier (e.g. ups or fedEx).
CarrierInput	carrierCode	Unique identifier for a specific instance of a Carrier in ShipperHQ. On the "Advanced" tab for each carrier you'll find its code. Note that it is possible to have multiple instances of the same carrier configured on a ShipperHQ account therefore it's important to ensure you're using the correct carrierCode.
ShipmentDetailInput	shippingMethodCode	Code for the specific service (shipping method) to be used.

Choosing a carrier and method

While you can use any valid carrierType, carrierCode, and shippingMethodCode when requesting a label, not all services are available for all shipments. Therefore, it's generally best practice to use the values returned by the Insights API.

Carrier Accounts

No account/billing information is included in Labels API requests. This is because ShipperHQ uses the account/billing information configured on the Carrier in ShipperHQ. The Carrier to use is indicated with the carrierCode field of CarrierInput in the request.

Carrier Services

UPS

The Labels API currently supports the following types of UPS services:

• UPS Ground and Air Domestic & International Small Package
• UPS Access Point
• UPS Ground with Freight Pricing

note

ShipperHQ does not currently support producing labels for UPS SurePost.

FedEx

The Labels API currently supports the following types of FedEx services:

• FedEx Ground & Home Delivery Small Package
• FedEx Express Domestic & International Small Package
• FedEx Hold at Location

note

ShipperHQ does not currently support producing labels for FedEx Ground Economy or FedEx Freight.

USPS

The Labels API currently supports all standard USPS domestic and international services.

International

Requirements for international shipments are generally more strict than domestic shipments. Therefore, certain fields are required that are not required for domestic shipments.

Parent Element	Element(s)	Notes
LabelPieceInput	declaredValue	Declared value of the package.
CustomsDetailInput	itemDescription	A general description of the item being shipped, used for customs declarations.
CustomsDetailInput	weight	The weight of the individual item, used for customs declarations.
CustomsDetailInput	qty	The quantity of the item included in the package, used for customs declarations.
CustomsDetailInput	sku	The item's SKU, used for customs declarations.
CustomsDetailInput	countryOfOrigin	The item's country of origin, used for customs declarations.
CustomsDetailInput	descriptionForExport	The reason given for the export of the item, used for customs declarations.

Important

Customs declarations are governed by national and international law and contracts between shippers and carriers may also govern customs declarations. Any individual requesting a label via ShipperHQ for an international shipment accepts responsibility for any customs information provided and ensuring that all required declarations are made in the form required.

Pickup Services

When printing labels for pickup services (where the carrier will hold the package for the recipient to pick up from a carrier location), additional recipient details are required. These are in addition to the common recipient address information. Details for supported pickup services are described below.

UPS Access Point

UPS requires that for UPS Access Point shipments, both the customer (recipient) address is provided in the standard fields but also requires the following.

Parent Element	Element(s)	Notes
RecipientInput	locationId	Unique identifier for the UPS Access Point location, can be retrieved from the Insights API.
RecipientInput	pickupName	The name of the UPS Access Point location, can be retrieved from the Insights API.
RecipientInput	pickupStreet1 pickupStreet2 pickupCity pickupState	Full address of the UPS Access Point location, can be retrieved from the Insights API.

FedEx Hold at Location

For FedEx Hold at Location shipments, the recipient address provided should be the address of the FedEx Hold at Location pickup location. FedEx also requires the following.

Parent Element	Element(s)	Notes
RecipientInput	locationId	Unique identifier for the FedEx Hold at Location location, can be retrieved from the Insights API.
RecipientInput	locationType	Identifies if the location is a FedEx OnSite or FedEx Hold at Location location, can be retrieved from the Insights API.

Usage

Creating Labels

Key Label Request Elements

There are several elements which are key to accurately creating labels with ShipperHQ. In addition to these, specific carriers, carrier services, and types of shipments may require additional elements.

Parent Element	Element(s)	Notes
sender	street street2 city region zipcode country	The sender (ship-from) address.
sender	originName	The unique identifier (name) of the Origin configured in ShipperHQ.
recipient	street street2 city region zipcode country	The recipient (ship-to) address.
carrier	carrierType	The carrier type code for the selected carrier (e.g. ups or fedEx).
carrier	carrierCode	Unique identifier for the specific Carrier defined in ShipperHQ to be used for this label, can be retrieved with Insights API.
shipmentDetail	shipmentId	A unique alphanumeric string which will act as an identifier for any subsequent actions (e.g. cancel).
shipmentDetail	shippingMethodCode	Code for the specific service (shipping method) to be used, can be retrieved with Insights API.
shipmentInput	pieces	Contains one or more packages included in this shipment for which you wish to create labels.
pieces	referenceId	The unique identifier for the package, can be retrieved with Insights API.
pieces	length width height weight	Package dimensions and weight are required for most shipments.

Key Label Response Elements

The following at a minimum should be included in the requested response fields.

Parent Element	Element(s)	Notes
LabelOutput	transactionId	Unique identifier for the transaction assigned by ShipperHQ. Should be stored as a way to look up the transaction if needed for troubleshooting.
Label	trackingId	The carrier-assigned tracking number for this package and/or shipment.
Label	shipmentId	Unique identifier for the shipment. Can be used for further actions such as cancellation.
Label	labelImage	Returns the label in a base64 encoded string in the configured format. See Label Formats and Stock.
Label	labelUrl	If the label is not expected to be printed immediately, the returned URL may be used to access the label image digitally.
Label	labelType	The type of label returned. Commonly used for international services where the carrier may require different types of labels be printed for a single package and/or shipment.
Label	copies	Indicates the number of copies of the given label that should be printed. Commonly used for international shipments.
Error	errorCode	ShipperHQ Error Code which identifies a given error. See Error Handling.
Error	priority	Identifies the priority of the error returned. See Error Handling.
Error	internalErrorMessage	Provides details of the error. Not intended to be displayed to the end user but should be logged for troubleshooting. See Error Handling.
Error	externalErrorMessage	Provides user friendly details of the error. Should be displayed to the end user. See Error Handling.

Important

The use of labels generated via ShipperHQ is governed by any agreements and/or contracts in place between the shipper and the carrier. A person requesting a label to be generated via ShipperHQ accepts responsibility for ensuring that any labels produced are used in accordance with applicable agreements.

Manifest Information

If the carrier requires a manifest be produced for shipments during a given period of time, certain data about each shipment should be stored to be sent in a subsequent createManifest request. See Creating Manifests.

Creating Manifests

Certain carriers may require that certain shippers produce manifests for given sets of shipments (e.g. all shipments being picked up on a certain day by the carrier may need to be included on a manifest). The createManifest operation supports creation of these manifests.

Key Manifest Request Elements

A createManifest request will include one or more pieces which should be included in the manifest. For example, all shipments which will be picked up by the carrier on a given day.

Parent Element	Element(s)	Notes
ManifestSenderInput	originName	The unique identifier (name) of the Origin configured in ShipperHQ.
CarrierInput	carrierCode	Unique identifier for the specific Carrier used to produce this label.
CarrierInput	carrierType	The carrier type code for the selected carrier (e.g. ups or fedEx).
ManifestPieceInput	carrierType	The carrier type code for the selected carrier (e.g. ups or fedEx).
ManifestPieceInput	carrierCode	Unique identifier for the specific Carrier used to produce this label.
ManifestPieceInput	shippingMethodCode	Code for the specific service (shipping method) used.
ManifestPieceInput	labelId	Unique identifier for the label.
ManifestPieceInput	referenceId	The carrier-assigned tracking number for this package and/or shipment.

Multiple Carriers and Accounts

If multiple carriers or carrier accounts are being used, a separate createManifest request will be required for each carrier and account where a manifest is necessary.

Key Manifest Response Elements

The following at a minimum should be included in the requested response fields. One or more Manifest items may be returned.

Parent Element	Element(s)	Notes
ResponseSummary	transactionId	Unique identifier for the transaction assigned by ShipperHQ. Should be stored as a way to look up the transaction if needed for troubleshooting.
Manifest	manifestImage	Printable base64 encoded image of the Manifest.
Manifest	manifestUrl	If the manifest is not expected to be printed immediately, the returned URL may be used to access the manifest image digitally.
Manifest	manifestId	Unique identifier for the manifest.
Error	errorCode	ShipperHQ Error Code which identifies a given error. See Error Handling.
Error	priority	Identifies the priority of the error returned. See Error Handling.
Error	internalErrorMessage	Provides details of the error. Not intended to be displayed to the end user but should be logged for troubleshooting. See Error Handling.
Error	externalErrorMessage	Provides user friendly details of the error. Should be displayed to the end user. See Error Handling.

Cancelling Labels

If a label will not be used it may be cancelled. Each carrier has specific limits on the length of time after it is generated that a label may be cancelled (generally at a minimum several days). The cancelLabel operation supports cancelling labels.

Key Cancellation Request Elements

A cancelLabel request will identify a single unique shipment to be cancelled. If multiple labels need to be cancelled, a separate cancelLabel request must be used for each.

Parent Element	Element(s)	Notes
CancelLabelInfoInput	shipmentId	Unique identifier for the shipment.
CarrierInput	carrierType	The carrier type code for the selected carrier (e.g. ups or fedEx).
CarrierInput	carrierCode	Unique identifier for the specific Carrier used to produce this label.

Key Cancellation Response Elements

The following at a minimum should be included in the requested response fields. If no error is returned, the cancellation has been processed successfully.

Parent Element	Element(s)	Notes
CancelLabelOutput	transactionId	Unique identifier for the transaction assigned by ShipperHQ. Should be stored as a way to look up the transaction if needed for troubleshooting.
Error	errorCode	ShipperHQ Error Code which identifies a given error. See Error Handling.
Error	priority	Identifies the priority of the error returned. See Error Handling.
Error	internalErrorMessage	Provides details of the error. Not intended to be displayed to the end user but should be logged for troubleshooting. See Error Handling.
Error	externalErrorMessage	Provides user friendly details of the error. Should be displayed to the end user. See Error Handling.

Integration Requirements

While very few elements are required for a successful API call to the Labels API, 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 Labels 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.

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:

• 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 request

Error Handling

The integration should appropriately handle any error returned by the Labels API. See the Errors section of this doc for further details and for possible error codes and messages see the Labels API FAQ.

Additional Guidance

While the Labels 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 Labels 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://rms.shipperhq.com/) 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

Since the Labels 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 Labels API requests and their associated responses as well as a Postman collection with pre-configured examples on the Examples doc.

See Examples

Errors

The ShipperHQ Labels API may return errors in an error object. 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.

For possible error codes and messages see the Labels API FAQ.