Overview
For ShipperHQ customers interested in building their own integration with ShipperHQ, a sandbox/playground for testing GraphQL is available at graphiql.shipperhq.com.
Access to the ShipperHQ GraphQL API is available to customers on a ShipperHQ Enterprise Plan only. For more information or to upgrade to the Enterprise Plan, please contact us.
On This Page
Viewing Docs
Once you’ve entered an endpoint URL (SHQ’s url – https://api.shipperhq.com/v2/graphql – is entered by default) press the RELOAD button then click the DOCS button to show the available GraphQL queries
Authentication
1. Obtain your credentials
To use the ShipperHQ API you must generate an authentication token. To do so, you will need your ShipperHQ API Key and Authentication Code.
- Login to your ShipperHQ account
- Navigate to Websites
- Select the website you configured for this store
- Scroll to “Connecting ShipperHQ to Your eCommerce Platform”
- Copy your API Key
- If your site is not yet live, Generate New Authentication Code and copy
- Do NOT reset this authentication code if you are live. If you do, you will break your rating in checkout. If you do reset, you will need to ensure you update your Magento extension to use the new code.
2. Obtain Authentication Token
- Navigate to the ShipperHQ GraphQL playground
- Click Add New in the top left corner
- Set the URL to https://rms.shipperhq.com (make sure you get right url), and click the Reload Docs button
- Send a createSecretToken mutation with your API Key and Authentication Code
mutation CreateSecretToken {
createSecretToken(api_key: "your_api_key", auth_code: "your_auth_code") {
token
}
}
The response will contain the token that you use to make requests to the ShipperHQ API. This token currently expires every 30 days.
Preparing a query
For Rate queries, set the URL to https://api.shipperhq.com/v2/graphql. (You may need to switch back to this endpoint after receiving your token from rms.shipperhq.com.)
Before writing a query the following Headers need to be entered. Click the headers button on the left which has a star shaped icon.
- X-ShipperHQ-Secret-Token – This is the token generated in Step 2 above
- X-ShipperHQ-Scope – This is the SCOPE from your SHQ account
- X-ShipperHQ-Session – This identifies a cart/order, use any value
After the headers are entered you can type the QUERY you want to test then click the SEND REQUEST button. The results will display in the pane on the right.
Variables need to be added by clicking the Variables button (icon of stacked boxes) on the left toolbar. The variables are entered in JSON format.
Example Queries
#
# Fetches a basic quote
#
# If there are multiple shipments/warehouses they will be simplified
# into a single "merged" carrier. This makes this call suitable for use in
# platforms that expect a single shipping method per order
#
query RetrieveShippingQuote($ratingInfo: RatingInfoInput!) {
retrieveShippingQuote(ratingInfo: $ratingInfo){
transactionId
carriers {
carrierCode
carrierTitle
carrierType
error {
errorCode
internalErrorMessage
externalErrorMessage
priority
}
shippingRates {
code
title
totalCharges
}
}
errors {
errorCode
internalErrorMessage
externalErrorMessage
priority
}
}
}
#
# Fetches a detailed quote with calendar details included
#
# This query fetches a more detailed copy of the shipping rates
# it will show the full rate breakdown. Not all fields are included in this
# example, use the docs to see all available fields.
#
# This example uses calendar functionality. You will need to have that enabled on your account in order to see results with date information
query RetrieveFullShippingQuote($ratingInfo: RatingInfoInput!) {
retrieveFullShippingQuote(ratingInfo: $ratingInfo) {
transactionId
validationStatus
shipments {
shipmentDetail {
name
shipmentId
}
carriers {
carrierDetail {
carrierCode
carrierTitle
carrierType
}
methods {
methodDetails {
methodCode
methodTitle
totalCharges
}
}
calendarDate {
availableDeliveryDates
}
dateFormat
error {
errorCode
internalErrorMessage
externalErrorMessage
priority
}
}
groupedItems {
itemId
}
}
errors {
errorCode
internalErrorMessage
externalErrorMessage
priority
}
}
}
#
# Typical request you might use if using LTL carriers - notice the availableOptions
#
#
# This example uses calendar functionality. You will need to have that enabled on your account in order to see results with date information
query RetrieveFullShippingQuote($ratingInfo: RatingInfoInput!) {
retrieveFullShippingQuote(ratingInfo: $ratingInfo) {
transactionId
validationStatus
shipments {
shipmentDetail {
name
shipmentId
}
carriers {
carrierDetail {
carrierCode
carrierTitle
carrierType
}
methods {
methodDetails {
methodCode
methodTitle
totalCharges
}
}
availableOptions {
destinationType
insideDelivery
liftGateRequired
limitedDelivery
notifyRequired
}
error {
errorCode
internalErrorMessage
externalErrorMessage
priority
}
}
}
errors {
errorCode
internalErrorMessage
externalErrorMessage
priority
}
}
}
# # Fetches shipping rates and breakdown of rates for multiple shipments/warehouses # # This query will fetch the merged shipping rate as well as a detailed
# breakdown of the shipping rates and packing information query RetrieveFullShippingQuote($ratingInfo: RatingInfoInput!) { retrieveFullShippingQuote(ratingInfo: $ratingInfo) { transactionId validationStatus shipments { shipmentDetail { name shipmentId } carriers { carrierDetail { carrierCode carrierTitle carrierType } methods { methodDetails { methodCode methodTitle totalCharges } rateBreakdownList { methodCode carrierDetail { carrierCode carrierTitle } methodDetails { totalCharges methodTitle methodCode } packages { items { qtyPacked sku weightPacked } packageDetail { packageName width height length weight declaredValue } } } } packages { items { qtyPacked sku weightPacked } packageDetail { packageName width height length weight declaredValue } } availableOptions { destinationType insideDelivery liftGateRequired limitedDelivery notifyRequired } error { errorCode internalErrorMessage externalErrorMessage priority } } } errors { errorCode internalErrorMessage externalErrorMessage priority } } }
Example Variables
#
# These must be included in the variables section of your GraphQL client. This example is # a basic ratingInfo object showing item attributes
#
{
"ratingInfo": {
"cart": {
"items": [{
"itemId": "57",
"sku": "25-MB01",
"storePrice": 34,
"weight": 1,
"qty": 1,
"type": "SIMPLE",
"basePrice": 34,
"taxInclBasePrice": null,
"taxInclStorePrice": 34,
"discountPercent": null,
"discountedBasePrice": null,
"discountedStorePrice": null,
"discountedTaxInclBasePrice": null,
"discountedTaxInclStorePrice": null,
"attributes": [{
"name": "shipperhq_warehouse",
"value": "CA Origin,NY Origin"
}],
"items": null
}],
"declaredValue": 34
},
"destination": {
"country": "US",
"region": "TX",
"city": "Austin",
"street": "5701 S MoPac Expy",
"street2": "#1821",
"zipcode": "78749"
},
"customer": {
"customerGroup": "NOT LOGGED IN"
},
"cartType": "STD",
"requestedOptions": null,
"siteDetails": {
"appVersion": "1.0.0",
"ecommerceCart": "Magento 2 Community",
"ecommerceVersion": "2.3.1",
"websiteUrl": "http://www.example.com",
"ipAddress": "12.34.567"
}
}
}
Item Attributes
Item attributes in the request allow you to include item specific values e.g.a shipping group or an origin. They are required if you are using any type of features such as carrier rules, dimensional shipping, multi-origin, etc. The most common attributes are listed below.
Note: All values are case sensitive
Multiple Values
If an attribute has multiple values, they must be separated by a delimiter. The default delimiter is a comma.
Using Hash (“#”) As Delimiter
If your data is already separated by hashes, you can use hashes with ShipperHQs GraphQL API. You will need to set appVersion to “2.0.0” in siteDetails
Available Attributes
- “shipperhq_shipping_group” : the shipping group on an item which can be used to match on carrier rules. Use delimited values if you have more than one shipping group.
- “shipperhq_warehouse” : if you are using multi-origin functionality, in order to specify which origin(s) an item comes from. Use delimited values if you have more than one origin.
- “shipperhq_dim_group” : if you have created any dimensional rules for your items to be packed a specific way.
- “ship_length”, “ship_width”, and “ship_height” : dimensions of your items. Must include all three if using.
- “ship_separately” : the item to be packed separately into it’s own box when used for rating.
"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 in the requestedOptions field in the request allow you to include services for the entire shipment e.g Liftgate or Residential delivery. They are useful if you are using Freight carriers or small package carriers that offer specific delivery methods for residential delivery . The most common attributes are listed below.
Note: All values are case sensitive
Requested Option fields:
- For freight shipments:
- “liftgate_required”: specifies that a liftgate is required at the destination (Boolean)
- “notify_required” : request an appointment delivery or notice of delivery (Boolean)
- “inside_delivery” : request delivery inside the destination (Boolean)
- “limited_delivery”: limited access at the destination address (Boolean)
- For freight and small package shipments:
-
“destination_type”: specify if destination is a “Residential” or “Business” address
-
requestedOptions: {
options: [
{
code: "liftgate_required",
value: "true"
},
{
code: "destination_type",
value: "residential"
}]}
Example Responses
Please use the ShipperHQ GraphQL sandbox