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
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
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
}
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]
}
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
}
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]
}
CustomerInput
Customer group
Input Field | Description |
---|---|
customerGroup -
String
|
The Customer Group this user is in |
Example
{"customerGroup": "xyz789"}
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"
}
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"
}
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"
}
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
}
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
}
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"
}