Overview
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.
For ShipperHQ customers interested in building their own integration with ShipperHQ, a sandbox/playground for testing GraphQL is available at graphiql.shipperhq.com
On This Page
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
- “shipperhq_shipping_group” : This is used to place the shipping group on an item which can be used to match on carrier rules.
- “shipperhq_warehouse” : This is used if you are using multi-origin functionality, in order to specify which origin an item comes from.
- “shipperhq_dim_group” : This is used if you have created any dimensional rules for your items to be packed a specific way.
- “ship_length”, “ship_width”, and “ship_height” : These are used if you are placing dimensions on items. Must include all three if using.
- “ship_separately” : This allows for the item to be packed separately into it’s own box when used for rating.
- “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