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

Viewing Docs

Once you’ve entered an endpoint URL (SHQ’s url is entered by default) press the RELOAD button then click the DOCS button to show the available GraphQL queries

Preparing a query

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-Access-Token – This is the API Key for a valid website in your SHQ account
• 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
    }
  }
}

Example Variables

# 
# These must be included in the variables section of your GraphQL client
#

{
  "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"
    }
  }
}

Example Attributes

These are the most common attributes that can be used to utilized to add even more functionality to your cart and checkout. They are required if you are using any type of features such as carrier rules, dimensional shipping, multi-origin, etc…

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” : This is used to place the shipping group on an item which can be used to match on carrier rules.
2. “shipperhq_warehouse” : This is used if you are using multi-origin functionality, in order to specify which origin an item comes from.
3. “shipperhq_dim_group” : This is used if you have created any dimensional rules for your items to be packed a specific way.
4. “ship_length”, “ship_width”, and “ship_height” : These are used if you are placing dimensions on items. Must include all three if using.
5. “ship_separately” : This allows for the item to be packed separately into it’s own box when used for rating.
6. “shipperhq_hs_code” : This is used if you are utilizing the landed cost engine, and must be added to each item in order to grab duties and taxes properly.

      "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"
      } ],

Example Responses

Please use the ShipperHQ GraphQL sandbox