GraphQL Sandbox Usage

Overview

For ShipperHQ customers interested in building their own integration with ShipperHQ, a sandbox/playground for testing GraphQL is available at graphiql.shipperhq.com.

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

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.

  1. Login to your ShipperHQ account 
  2. Navigate to Websites 
  3. Select the website you configured for this store 
  4. Scroll to “Connecting ShipperHQ to Your eCommerce Platform” 
  5. Copy your API Key
  6. If your site is not yet live, Generate New Authentication Code and copy
  7. 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

  1. Navigate to the ShipperHQ GraphQL playground
  2. Click Add New in the top left corner 
  3. Set the URL to https://rms.shipperhq.com (make sure you get right url), and click the Reload Docs button 
  4. 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

  1. “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. 
  2. “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. 
  3. “shipperhq_dim_group” : if you have created any dimensional rules for your items to be packed a specific way. 
  4. “ship_length”, “ship_width”, and “ship_height” :  dimensions of your items. Must include all three if using.
  5. “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

Was this doc helpful?