ShipperHQ Rates API Reference Documentation

Rates API Reference

ShipperHQ Dev Support
Contact us

Terms of Service: https://shipperhq.com/useragreement

API Endpoints
Production Server:
https://api.shipperhq.com/v2/graphql

Queries

retrieveFullShippingQuote

Retrieve detailed shipping rate information for each shipment, including shipping options available for each shipment and carrier
Returns a FullShippingQuote

Name Description
ratingInfo - RatingInfoInput Information on items in cart and destination, used to calculate shipping rates

Example

Query
query retrieveFullShippingQuote($ratingInfo: RatingInfoInput) {
  retrieveFullShippingQuote(ratingInfo: $ratingInfo) {
    errors {
      ...ErrorFragment
    }
    shipments {
      ...ShipmentFragment
    }
    transactionId
    units {
      ...UnitsFragment
    }
    validationStatus
  }
}
Variables
{"ratingInfo": RatingInfoInput}
Response
{
  "data": {
    "retrieveFullShippingQuote": {
      "errors": [Error],
      "shipments": [Shipment],
      "transactionId": "abc123",
      "units": Units,
      "validationStatus": "xyz789"
    }
  }
}

retrieveShippingQuote

Retrieve basic shipping rates including carrier and method titles and total shipping charges.
Returns a BasicShippingQuote

Name Description
ratingInfo - RatingInfoInput Information on items in cart and destination, used to calculate shipping rates

Example

Query
query retrieveShippingQuote($ratingInfo: RatingInfoInput) {
  retrieveShippingQuote(ratingInfo: $ratingInfo) {
    carriers {
      ...RatingCarrierFragment
    }
    errors {
      ...ErrorFragment
    }
    transactionId
  }
}
Variables
{"ratingInfo": RatingInfoInput}
Response
{
  "data": {
    "retrieveShippingQuote": {
      "carriers": [RatingCarrier],
      "errors": [Error],
      "transactionId": "xyz789"
    }
  }
}

Types

AdvancedFee

Fees and charges included in shipping method

Field Name Description
changeRulesApplied - [String] List of shipping rules that surcharged or discounted the shipping rate
cost - BigDecimal Base shipping rate before any rules or fees were applied
customDuties - BigDecimal Duties and taxes on shipping rate
flatRulesApplied - [String] List of shipping rules that set the shipping rate
handlingFee - BigDecimal Handling fees applied to the shipping rate
shippingPrice - BigDecimal Shipping rate without any handling fees or taxes applied
totalCharges - BigDecimal Total price of shipping rate including any fees
Example
{
  "changeRulesApplied": ["xyz789"],
  "cost": BigDecimal,
  "customDuties": BigDecimal,
  "flatRulesApplied": ["xyz789"],
  "handlingFee": BigDecimal,
  "shippingPrice": BigDecimal,
  "totalCharges": BigDecimal
}

AttributeInput

An attribute entry

Input Field Description
name - String

ShipperHQ Attribute Name

value - String

Value of ShipperHQ Attribute Name

Example
{"name": "xyz789", "value": "xyz789"}

AvailableOption

Selectable options available for this carrier e.g liftgate, residential delivery

Field Name Description
destinationType - String Moved to generic Options field
insideDelivery - Boolean! Moved to generic Options field
liftGateRequired - Boolean! Moved to generic Options field
limitedDelivery - Boolean! Moved to generic Options field
notifyRequired - Boolean! Moved to generic Options field
options - [Option] List of options available for this carrier
Example
{
  "destinationType": "abc123",
  "insideDelivery": true,
  "liftGateRequired": false,
  "limitedDelivery": true,
  "notifyRequired": false,
  "options": [Option]
}

AvailableOptionType

Enum Value Description

BOOLEAN

SELECT

TEXT

BasicShippingQuote

Basic shipping rate information including carrier and method titles and total shipping charges

Field Name Description
carriers - [RatingCarrier!] Carrier and shipping rate detail
errors - [Error!] Errors returned from request
transactionId - String! ShipperHQ's transction ID
Example
{
  "carriers": [RatingCarrier],
  "errors": [Error],
  "transactionId": "abc123"
}

BasicShippingRate

Basic shipping rates including carrier and method titles and total shipping charges

Field Name Description
code - String! Unique code of shipping rate - intended for internal use
currency - String Currency code of shipping rate
title - String! Title of shipping rate - intended for display to end users
totalCharges - BigDecimal! Shipping rate including all fees and charges
Example
{
  "code": "xyz789",
  "currency": "xyz789",
  "title": "xyz789",
  "totalCharges": BigDecimal
}

BigDecimal

Built-in java.math.BigDecimal

Example
object

Boolean

Built-in Boolean

Example
true

CalendarDate

Dates and timeslots available for selection with this carrier

Field Name Description
availableDeliveryDates - [String!] Available delivery dates, returned as list of dates
deliveryDateRanges - [DeliveryDateRange!]! Available delivery dates, returned as date ranges
timeSlots - [TimeSlot!]! Time slots available for selection
Example
{
  "availableDeliveryDates": ["xyz789"],
  "deliveryDateRanges": [DeliveryDateRange],
  "timeSlots": [TimeSlot]
}

Carrier

Carrier and rate information, to display as options to customer

Field Name Description
availableOptions - AvailableOption Selectable options available for this carrier e.g liftgate, residential delivery
calendarDate - CalendarDate Dates and timeslots available for selection with this carrier
carrierDetail - CarrierDetail! Carrier specific information e.g. code and name
dateFormat - String Merchants preferred date format, in ISO 8601 Date and time format
error - Error Error information returned by carrier
methods - [Method!]! Shipping methods and rate information
packages - [Package!]! List of packages calculated based on carrier settings and items in the request
pickupDetail - PickupDetail Pickup location details, for In Store Pickup carriers only
preventRulesApplied - [String] List of rules applied that prevented carrier returning rates
sortOrder - Int Order this carrier should be displayed in list of carriers, lowest to highest
Example
{
  "availableOptions": AvailableOption,
  "calendarDate": CalendarDate,
  "carrierDetail": CarrierDetail,
  "dateFormat": "abc123",
  "error": Error,
  "methods": [Method],
  "packages": [Package],
  "pickupDetail": PickupDetail,
  "preventRulesApplied": ["xyz789"],
  "sortOrder": 123
}

CarrierDetail

Carrier specific information e.g. code and name

Field Name Description
carrierCode - String! Unique code for this carrier - intended for internal use
carrierEstimatedDeliveryDate - String Delivery date message to display estimated delivery dates
carrierTitle - String! Title of carrier - intended for display to end users
carrierType - String! Carrier type e.g. UPS, FedEx, custom
customDescription - String Description of carrier - intended for display to end users e.g. tooltip
displayTab - String Display carrier as delivery or pickup type carrier
Example
{
  "carrierCode": "abc123",
  "carrierEstimatedDeliveryDate": "abc123",
  "carrierTitle": "abc123",
  "carrierType": "abc123",
  "customDescription": "xyz789",
  "displayTab": "xyz789"
}

CartInput

Cart details

Field Name Description
declaredValue - BigDecimal Total value of the cart
freeShipping - Boolean Does the cart receive free shipping?
items - [ItemInput] List of items in the cart
Example
{
  "declaredValue": BigDecimal,
  "freeShipping": true,
  "items": [ItemInput]
}

CartType

Enum Value Description

ACCOUNT

CART

INTERNAL

MAC

MAC_PICKUP

PDP

STD

CustomerInput

Customer group

Input Field Description
customerGroup - String

The Customer Group this user is in

Example
{"customerGroup": "xyz789"}

DeliveryDateRange

Range of available delivery dates

Field Name Description
fromDate - String Start date of range
toDate - String End date of range
Example
{"fromDate": "xyz789", "toDate": "abc123"}

DestinationInput

Destination address details

Input Field Description
selectedOptions - SelectedOptionsInput

Additional address information selected in checkout

city - String

Destination city

street - String

Destination street address - first line

street2 - String

Destination street address - second line (SUITE/APT #)

zipcode - String

Destination zipcode/postcode

region - String

Destination state or region

country - String

Destination country

Example
{
  "selectedOptions": SelectedOptionsInput,
  "city": "abc123",
  "street": "abc123",
  "street2": "abc123",
  "zipcode": "xyz789",
  "region": "xyz789",
  "country": "xyz789"
}

Error

Field Name Description
errorCode - Int!
externalErrorMessage - String
internalErrorMessage - String
priority - Int
Example
{
  "errorCode": 123,
  "externalErrorMessage": "xyz789",
  "internalErrorMessage": "abc123",
  "priority": 987
}

FullShippingQuote

Detailed shipping rate information including shipping options available for each shipment and carrier

Field Name Description
errors - [Error!] List of errors returned
shipments - [Shipment!]! Shipping and packing information for each shipment
transactionId - String! ShipperHQ's transction ID
units - Units Currency, volume and weight units
validationStatus - String! Address validation status
Example
{
  "errors": [Error],
  "shipments": [Shipment],
  "transactionId": "xyz789",
  "units": Units,
  "validationStatus": "abc123"
}

GroupedItem

Details of item in shipment

Field Name Description
declaredValue - BigDecimal Item's declared value
hsCode - String HS Code - used in customs and duties calculations
itemId - String! Unique item ID
name - String Item's name
originCountry - String Item's country of origin or manufacture
qty - Int Item qty
sku - String Item's SKU
Example
{
  "declaredValue": BigDecimal,
  "hsCode": "xyz789",
  "itemId": "xyz789",
  "name": "xyz789",
  "originCountry": "xyz789",
  "qty": 123,
  "sku": "xyz789"
}

Int

Built-in Int

Example
987

Item

Details of item in package

Field Name Description
qtyPacked - BigDecimal! Quantity of items in package
sku - String! Item's SKU
weightPacked - BigDecimal! Weight of items in package
Example
{
  "qtyPacked": BigDecimal,
  "sku": "abc123",
  "weightPacked": BigDecimal
}

ItemInput

Full details of an item in the cart

Field Name Description
discountedBasePrice - BigDecimal Price of the item after discounts, no tax, store's base currency
baseCurrency - String User's base currency
discountedTaxInclStorePrice - BigDecimal Price of the item after discounts, with tax, user's currency
storeBaseCurrency - String Store base currency
storePrice - BigDecimal Price of the item before discounts, no tax, user's currency
discountedStorePrice - BigDecimal Price of the item after discounts, no tax, user's currency
freeShipping - Boolean Does the item receive free shipping? Boolean true/false
basePrice - BigDecimal Price of the item before discounts, no tax, store's base currency
discountedTaxInclBasePrice - BigDecimal Price of the item after discounts, with tax, store's base currency
discountPercent - BigDecimal Percent discount applied
storeCurrentCurrency - String Store currency
weight - BigDecimal The item's weight
qty - Int Quantity of the item in the cart
fixedPrice - Boolean Fixed price of item if not using shipping rules
itemId - String The item's ID
fixedWeight - Boolean
taxInclBasePrice - BigDecimal Price of the item before discounts, including tax, store's base currency
type - ItemType Type of item
taxInclStorePrice - BigDecimal Price of the item before discounts, including tax, user's currency
items - [ItemInput] Child item details (if any)
sku - String The item's SKU
attributes - [AttributeInput] Item attributes
taxPercentage - BigDecimal Item tax percentage
packageCurrency - String User package currency
Example
{
  "discountedBasePrice": BigDecimal,
  "baseCurrency": "xyz789",
  "discountedTaxInclStorePrice": BigDecimal,
  "storeBaseCurrency": "xyz789",
  "storePrice": BigDecimal,
  "discountedStorePrice": BigDecimal,
  "freeShipping": false,
  "basePrice": BigDecimal,
  "discountedTaxInclBasePrice": BigDecimal,
  "discountPercent": BigDecimal,
  "storeCurrentCurrency": "xyz789",
  "weight": BigDecimal,
  "qty": 987,
  "fixedPrice": false,
  "itemId": "abc123",
  "fixedWeight": true,
  "taxInclBasePrice": BigDecimal,
  "type": ItemType,
  "taxInclStorePrice": BigDecimal,
  "items": [ItemInput],
  "sku": "xyz789",
  "attributes": [AttributeInput],
  "taxPercentage": BigDecimal,
  "packageCurrency": "xyz789"
}

ItemType

Enum Value Description

BUNDLE

CONFIGURABLE

DOWNLOADABLE

GIFTCARD

GROUPED

SIMPLE

VIRTUAL

Method

Shipping methods and rate information

Field Name Description
advancedFees - AdvancedFee Fees and charges included in shipping method
methodDetails - MethodDetail! Shipping method information like code, title, total charges
packages - [Package!]! Packages or boxes included in shipping rate
rateBreakdownList - [RateBreakdown] Breakdown of shipping rates used to make up this shipping method
selectedOptions - [NameValuePair] Selected options included in shipping rate
timeInTransitOptions - TimeInTransitOption Dispatch and delivery date information
Example
{
  "advancedFees": AdvancedFee,
  "methodDetails": MethodDetail,
  "packages": [Package],
  "rateBreakdownList": [RateBreakdown],
  "selectedOptions": [NameValuePair],
  "timeInTransitOptions": TimeInTransitOption
}

MethodDetail

Shipping method and rate information

Field Name Description
currency - String Currency code of shipping rate
deliveryMessage - String Delivery date information included in method title - included so developers can conditionally format this part of method title
methodCode - String! Unique code of shipping method - intended for internal use
methodDescription - String Additional information about shipping method - intended for display to end users e.g. tooltip
methodTitle - String! Title of shipping rate - intended for display to end users
negotiatedRate - Boolean Indicator whether shipping method is a negotiated rate with carrier
totalCharges - BigDecimal! Shipping rate including all fees and charges
Example
{
  "currency": "abc123",
  "deliveryMessage": "xyz789",
  "methodCode": "abc123",
  "methodDescription": "abc123",
  "methodTitle": "abc123",
  "negotiatedRate": false,
  "totalCharges": BigDecimal
}

NameValuePair

A name-value pair

Field Name Description
name - String Name identifying this data point e.g. destination_type
value - String Value of data e.g. RESIDENTIAL
Example
{"name": "abc123", "value": "xyz789"}

NameValuePairInput

Input Field Description
value - String
name - String
Example
{"value": "xyz789", "name": "xyz789"}

Option

Selectable option available for this carrier

Field Name Description
code - String Option's code - use this code when passing selected options in rate request
defaultValue - String Default value for option
displayType - AvailableOptionType Indicates how available option should be displayed
name - String Option's name - use this to display option to end user
requestRates - Boolean Determines whether a change in option value should cause a new rate request, as the choice may impact shipping methods available or their price
Example
{
  "code": "xyz789",
  "defaultValue": "abc123",
  "displayType": AvailableOptionType,
  "name": "abc123",
  "requestRates": true
}

OptionInput

An option entry

Input Field Description
code - String

Option code

value - String

Value of option code

Example
{"code": "xyz789", "value": "xyz789"}

Package

Package or box included in shipping rate

Field Name Description
items - [Item!]! Information on items in package
packageDetail - PackageDetail! Package information like box name, packed dimensions and value
Example
{
  "items": [Item],
  "packageDetail": PackageDetail
}

PackageDetail

Package information like box name, packed dimensions and value

Field Name Description
declaredValue - BigDecimal Declared value of package
height - BigDecimal! Height of package
length - BigDecimal! Length of package
packageName - String! Box or package name
packingWeight - BigDecimal Weight of package including packaging
surchargePrice - BigDecimal!
weight - BigDecimal! Weight of package
width - BigDecimal! Width of package
Example
{
  "declaredValue": BigDecimal,
  "height": BigDecimal,
  "length": BigDecimal,
  "packageName": "abc123",
  "packingWeight": BigDecimal,
  "surchargePrice": BigDecimal,
  "weight": BigDecimal,
  "width": BigDecimal
}

PickupDetail

Pickup location information and display preferences

Field Name Description
googleApiKey - String Google API key of merchant, used to display map of pickup location
pickupCart - Boolean No longer supported
pickupLocationDetails - [PickupLocationDetail!]! Details of pickup location like address, hours, location
showAddress - String Indicates whether you should display pickup location's address
showMap - String Indicates whether you should display map for this pickup location
showOpeningHours - Boolean! Indicates whether you should display opening hours for this pickup location
Example
{
  "googleApiKey": "abc123",
  "pickupCart": false,
  "pickupLocationDetails": [PickupLocationDetail],
  "showAddress": "abc123",
  "showMap": "xyz789",
  "showOpeningHours": true
}

PickupLocationDetail

Pickup location information like address, hours, location

Field Name Description
calendarDate - CalendarDate Dates and timeslots available for selection with this pickup location
city - String City of locations address
contactName - String Contact person at pickup location
country - String Country of locations address
currentTime - String Current time at pickup location
dispatchDate - String Earliest available dispatch date including lead time
distance - BigDecimal Distance of pickup location to user's delivery address
email - String Email address for pickup location
emailOption - String Pickup location's preference to be notified when order placed for pickup from this location
imageUrl - String URL of image showing location map or storefront - not always supported
latitude - BigDecimal Location latitude - to display map of location
locationMap - String No longer supported
longitude - BigDecimal Location longitude - to display map of location
nonStandardHours - String Opening hours outside of standard hours
phone - String Contact phone number of pickup location
pickupDate - String Earliest available pickup date including lead time
pickupFullName - String Name and address of pickup location in a single field
pickupId - String ShipperHQ's ID for pickup location
pickupName - String Name of pickup location - intended for display to end user
publicId - String Location's public ID, often used for post order processing
standardHours - String Standard opening hours for this pickup location
state - String State of locations address
street1 - String Street line one of locations address
street2 - String Street line two of locations address
walkingDirections - String Walking directions from user's location to store - not always supported
websiteUrl - String Location's website
zipcode - String Zipcode or postcode of locations address
Example
{
  "calendarDate": CalendarDate,
  "city": "xyz789",
  "contactName": "abc123",
  "country": "abc123",
  "currentTime": "xyz789",
  "dispatchDate": "abc123",
  "distance": BigDecimal,
  "email": "abc123",
  "emailOption": "xyz789",
  "imageUrl": "abc123",
  "latitude": BigDecimal,
  "locationMap": "abc123",
  "longitude": BigDecimal,
  "nonStandardHours": "abc123",
  "phone": "abc123",
  "pickupDate": "xyz789",
  "pickupFullName": "xyz789",
  "pickupId": "xyz789",
  "pickupName": "abc123",
  "publicId": "xyz789",
  "standardHours": "abc123",
  "state": "xyz789",
  "street1": "xyz789",
  "street2": "abc123",
  "walkingDirections": "abc123",
  "websiteUrl": "xyz789",
  "zipcode": "xyz789"
}

RateBreakdown

Breakdown of shipping rates used to make up a shipping method

Field Name Description
advancedFees - AdvancedFee Fees and charges included in shipping method
carrierDetail - CarrierDetail Carrier specific information e.g. code and name
isWinningRate - Boolean The winning method of the rates being compared via rate shopping rule
methodCode - String! Unique code of shipping method - intended for internal use
methodDetails - MethodDetail! Shipping method information like code, title, total charges
packages - [Package!]! Packages or boxes included in shipping rate
shipmentDetail - ShipmentDetail Details of shipment
timeInTransitOptions - TimeInTransitOption Dispatch and delivery date information
winningRate - Boolean No longer in use, use isWinningRate
Example
{
  "advancedFees": AdvancedFee,
  "carrierDetail": CarrierDetail,
  "isWinningRate": true,
  "methodCode": "xyz789",
  "methodDetails": MethodDetail,
  "packages": [Package],
  "shipmentDetail": ShipmentDetail,
  "timeInTransitOptions": TimeInTransitOption,
  "winningRate": false
}

RatingCarrier

Carrier and shipping rate information

Field Name Description
carrierCode - String! Unique code for this carrier - intended for internal use
carrierTitle - String! Title of carrier - intended for display to end users
carrierType - String! Carrier type e.g. UPS, FedEx, custom
error - Error Error information
shippingRates - [BasicShippingRate!] Basic shipping rates including carrier and method titles and total shipping charges
Example
{
  "carrierCode": "abc123",
  "carrierTitle": "xyz789",
  "carrierType": "xyz789",
  "error": Error,
  "shippingRates": [BasicShippingRate]
}

RatingInfoInput

Details about the order/shipment to be rated

Input Field Description
cartType - CartType

Checkout type

siteDetails - SiteDetailsInput

Information about site/platform

cart - CartInput

Cart details

destination - DestinationInput

Ship to address

requestedOptions - RequestedOptionsInput

Selected checkout options

customer - CustomerInput

Details about the customer/recipient

Example
{
  "cartType": CartType,
  "siteDetails": SiteDetailsInput,
  "cart": CartInput,
  "destination": DestinationInput,
  "requestedOptions": RequestedOptionsInput,
  "customer": CustomerInput
}

RequestedOptionsInput

Selected delivery options

Field Name Description
carrierCode - String Unique carrier ID
options - [OptionInput] Selected checkout options
shipmentId - String Unique shipment ID
selectedPickupId - String User's selected pickup location ID
selectedDate - String User's chosen delivery date
Example
{
  "carrierCode": "xyz789",
  "options": [OptionInput],
  "shipmentId": "xyz789",
  "selectedPickupId": "abc123",
  "selectedDate": "xyz789"
}

SelectedOptionsInput

Field Name Description
options - [NameValuePairInput]
Example
{"options": [NameValuePairInput]}

Shipment

Shipping and packing information for this shipment

Field Name Description
carriers - [Carrier!]! Carrier and rate information for this shipment
groupedItems - [GroupedItem!]! Details of items in shipment
shipmentDetail - ShipmentDetail! Unique ID and display name of shipment
Example
{
  "carriers": [Carrier],
  "groupedItems": [GroupedItem],
  "shipmentDetail": ShipmentDetail
}

ShipmentDetail

Unique ID and display name of shipment

Field Name Description
description - String Further description of shipment - intended for display to end user e.g. tooltip
name - String! Display name of shipment
shipmentId - String! Unique id of shipment - used when requesting rates for just this shipment
Example
{"description": "abc123", "name": "xyz789", "shipmentId": "abc123"}

SiteDetailsInput

Details about the website/platform

Input Field Description
WebsiteUrl - String

Website URL the request is sent from

IpAddress - String

User's IP Address

EcommerceCart - String

Ecommerce Platform Name

AppVersion - String

ShipperHQ Extension Version

EcommerceVersion - String

Ecommerce Platform's version

Example
{
  "WebsiteUrl": "abc123",
  "IpAddress": "xyz789",
  "EcommerceCart": "abc123",
  "AppVersion": "xyz789",
  "EcommerceVersion": "xyz789"
}

String

Built-in String

TimeInTransitOption

Dispatch and delivery date information

Field Name Description
deliveryDate - String Delivery date of shipping method
dispatchDate - String Dispatch date of shipping method
Example
{"deliveryDate": "xyz789", "dispatchDate": "xyz789"}

TimeSlot

Time slot information for pickup or delivery

Field Name Description
interval - String Length of each time slot
timeEnd - String End time of last time slot available
timeStart - String Start time of first time slot available
Example
{"interval": "xyz789", "timeEnd": "abc123", "timeStart": "abc123"}

Units

Field Name Description
currency - String
volume - String
weight - String
Example
{"currency": "abc123", "volume": "xyz789", "weight": "xyz789"}