ShipperHQ Insights API Reference

ShipperHQ Insights API Reference Documentation

Contact

ShipperHQ Dev Support

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

API Endpoints
Production Server:
https://ovs.shipperhq.com/

Queries

viewOrder

Retrieve shipment information for an order
Returns [Order]

Name Description
orderNumber - String!

Example

Query
query viewOrder($orderNumber: String!) {
  viewOrder(orderNumber: $orderNumber) {
    orderNumber
    apiKey
    orderNumberText
    isActive
    orderDetail {
      ...OrderDetailFragment
    }
    shipments {
      ...ShipmentFragment
    }
    recipient {
      ...AddressFragment
    }
    createdAt
  }
}
Variables
{"orderNumber": "xyz789"}
Response 
{
  "data": {
    "viewOrder": [
      {
        "orderNumber": "abc123",
        "apiKey": "xyz789",
        "orderNumberText": "abc123",
        "isActive": true,
        "orderDetail": OrderDetail,
        "shipments": [Shipment],
        "recipient": Address,
        "createdAt": DateTime
      }
    ]
  }
}

Types

Address

Shipping address information for the order

Field Name Description
country - String Country code of shipping address, in ISO alpha-2 format
region - String Region, state or locality of shipping address
city - String City or town of shipping address
street - String Street address
street2 - String Second line of street address
zipcode - String Zipcode or post code of shipping address
firstName - String Recipient's first name
lastName - String Recipient's last name
email - String Contact email of recipient
company - String Company name of shipping address
telephone - String Contact telephone number of recipient
Example
{
  "country": "xyz789",
  "region": "xyz789",
  "city": "abc123",
  "street": "xyz789",
  "street2": "xyz789",
  "zipcode": "xyz789",
  "firstName": "xyz789",
  "lastName": "abc123",
  "email": "xyz789",
  "company": "abc123",
  "telephone": "abc123"
}
Types

AdvancedFees

Fees and charges included in shipping method

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

Boolean

The Boolean scalar type represents true or false.

Example
false
Types

CalendarDate

Delivery date and time slot selected by the customer, only applicable with calendar based shipping rates

Field Name Description
deliveryDateRanges - [DeliveryDateRange!]! Internal use only
timeSlots - [TimeSlot!]! Selected time slot for pickup or delivery
availableDeliveryDates - [String!] Selected delivery date or pickup date
Example
{
  "deliveryDateRanges": [DeliveryDateRange],
  "timeSlots": [TimeSlot],
  "availableDeliveryDates": ["xyz789"]
}
Types

Carrier

Carrier and shipping method information for the shipment

Field Name Description
carrierDetail - CarrierDetail! Carrier and shipping method information for the shipment
methods - [Method!]! Shipping method and shipping rate information
sortOrder - Int Internal use only
dateFormat - String Merchants preferred date format, in ISO 8601 Date and time format
calendarDate - CalendarDate Delivery date and time slot selected by the customer, only applicable with calendar based shipping rates
packages - [Package!]! List of packages in this shipment, calculated based on carrier settings and items in the request
pickupDetail - PickupDetail Selected pickup location details, for In Store Pickup carriers only
Example
{
  "carrierDetail": CarrierDetail,
  "methods": [Method],
  "sortOrder": 987,
  "dateFormat": "abc123",
  "calendarDate": CalendarDate,
  "packages": [Package],
  "pickupDetail": PickupDetail
}
Types

CarrierDetail

Carrier specific information e.g. code and name

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! Type of carrier e.g. UPS, FedEx, custom
deliveryDateMessage - String Internal use only
Example
{
  "carrierCode": "abc123",
  "carrierTitle": "xyz789",
  "carrierType": "xyz789",
  "deliveryDateMessage": "xyz789"
}
Types

DateTime

Example
object
Types

DeliveryDateRange

Internal use only

Field Name Description
fromDate - String!
toDate - String!
Example
{"fromDate": "abc123", "toDate": "abc123"}
Types

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example
987.65
Types

GroupedItem

Details of items in shipment

Field Name Description
itemId - String! Unique item ID
sku - String Item's SKU
qty - Int Item qty
name - String Item's name
hs_code - String HS Code - used in customs and duties calculations
origin_country - String Item's country of origin or manufacture
declared_value - Float Item's declared value
Example
{
  "itemId": "xyz789",
  "sku": "abc123",
  "qty": 987,
  "name": "xyz789",
  "hs_code": "abc123",
  "origin_country": "xyz789",
  "declared_value": 123.45
}
Types

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example
object
Types

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
987
Types

Item

Details of item in package

Field Name Description
id - ID Deprecated: do not use
sku - String! Item's SKU
qtyPacked - Float! Quantity of items in package
weightPacked - Float! Weight of items in package
Example
{
  "id": ID,
  "sku": "abc123",
  "qtyPacked": 987.65,
  "weightPacked": 987.65
}
Types

LabelType

Enum Value Description

PRIMARY

CUSTOMS

FORM

AGREEMENT

RETURN
Types

Method

Shipping methods and rate information

Field Name Description
id - ID Deprecated: do not use
methodDetails - MethodDetail! Shipping method information like code, title, total charges
timeInTransitOptions - TimeInTransitOptions Dispatch and delivery date of the shipping method
rateBreakdownList - [RateBreakdown!]! Breakdown of shipping rates used to make up this shipping method, for example with merged rates
advancedFees - AdvancedFees Fees and charges included in shipping method
packages - [Package!]! Packages or boxes included in shipping rate
selectedOptions - [SelectedOption!]! Delivery options included in shipping rate, e.g. liftgate, residential delivery
Example
{
  "id": ID,
  "methodDetails": MethodDetail,
  "timeInTransitOptions": TimeInTransitOptions,
  "rateBreakdownList": [RateBreakdown],
  "advancedFees": AdvancedFees,
  "packages": [Package],
  "selectedOptions": [SelectedOption]
}
Types

MethodDetail

Shipping method information like code, title, total charges

Field Name Description
methodCode - String! Unique code of shipping method - intended for internal use
methodTitle - String! Title of shipping rate - intended for display to end users
totalCharges - Float! Shipping rate including all fees and charges
currency - String Currency code of shipping rate
negotiatedRate - Boolean Indicator whether shipping method is a negotiated rate with carrier
deliveryMessage - String Delivery date information included in method title - included so developers can conditionally format this part of method title
quoteId - String Quote ID for this shipment estimate
Example
{
  "methodCode": "xyz789",
  "methodTitle": "xyz789",
  "totalCharges": 987.65,
  "currency": "abc123",
  "negotiatedRate": true,
  "deliveryMessage": "abc123",
  "quoteId": "xyz789"
}
Types

Order

Information stored for a single order

Field Name Description
orderNumber - String! Unique number or id for this order
apiKey - String! Internal use only
orderNumberText - String Public facing order number, only populated if different to orderNumber
isActive - Boolean! Internal use only
orderDetail - OrderDetail! Summary of shipping information for the entire order
shipments - [Shipment!]! Shipping and packing information for each shipment in the order
recipient - Address Shipping address information for the order
createdAt - DateTime! When this order was created
Example
{
  "orderNumber": "xyz789",
  "apiKey": "abc123",
  "orderNumberText": "xyz789",
  "isActive": false,
  "orderDetail": OrderDetail,
  "shipments": [Shipment],
  "recipient": Address,
  "createdAt": DateTime
}
Types

OrderDetail

Summary of shipping information for the entire order

Field Name Description
carrierCode - String! Unique code for carrier - intended for internal use
carrierTitle - String! Title of carrier - intended for display to end users
methodCode - String! Unique code of shipping method - intended for internal use
methodTitle - String! Title of shipping method - intended for display to end users
totalCharges - Float! Shipping charges including all fees
transactionId - String! ShipperHQ's transction ID
currency - String Currency the account is set to
Example
{
  "carrierCode": "abc123",
  "carrierTitle": "abc123",
  "methodCode": "xyz789",
  "methodTitle": "xyz789",
  "totalCharges": 123.45,
  "transactionId": "abc123",
  "currency": "xyz789"
}
Types

Package

Package or box included in shipping rate

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

PackageDetail

Package information like box name, packed dimensions and value

Field Name Description
declaredValue - Float Declared value of package
height - Float! Height of package
length - Float! Length of package
packageName - String! Box or package name
packingWeight - Float Weight of package including packaging
surchargePrice - Float! Surcharge from package
weight - Float! Weight of package
width - Float! Width of package
freightClass - String Freight class of package
Example
{
  "declaredValue": 123.45,
  "height": 123.45,
  "length": 123.45,
  "packageName": "xyz789",
  "packingWeight": 987.65,
  "surchargePrice": 987.65,
  "weight": 987.65,
  "width": 987.65,
  "freightClass": "abc123"
}
Types

PickupDetail

Selected pickup location information and display preferences

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

PickupLocationDetail

Details of selected pickup location like address, hours, location

Field Name Description
pickupId - String ShipperHQ's ID for pickup location
pickupName - String Name of pickup location - intended for display to end user
latitude - Float Location latitude - to display map of location
longitude - Float Location longitude - to display map of location
street1 - String Street line one of location's address
street2 - String Street line two of location's address
city - String City of location's address
state - String Region or state of location's address
country - String Country of location's address, in ISO alpha-2 format
zipcode - String Zipcode or post code of location's address
phone - String Contact phone number of pickup location
distance - Float Distance of pickup location to user's delivery address
currentTime - String Current time at pickup location
pickupDate - String Earliest available pickup date including lead time
dispatchDate - String Earliest available dispatch date including lead time
locationMap - String Deprecated: No longer supported
calendarDate - CalendarDate Delivery date and time slot selected by the customer, only applicable with calendar based shipping rates
standardHours - String Standard opening hours for this pickup location
publicId - String Location's public ID, often used for post order processing
nonStandardHours - String Opening hours outside of standard hours
email - String Email address for pickup location
contactName - String Contact person at pickup location
imageUrl - String URL of image showing location map or storefront - not always supported
walkingDirections - String Walking directions from user's location to store - not always supported
websiteUrl - String Location's website
pickupFullName - String Name and address of pickup location in a single field
emailOption - String Internal use only
Example
{
  "pickupId": "xyz789",
  "pickupName": "xyz789",
  "latitude": 987.65,
  "longitude": 987.65,
  "street1": "xyz789",
  "street2": "abc123",
  "city": "abc123",
  "state": "abc123",
  "country": "abc123",
  "zipcode": "abc123",
  "phone": "xyz789",
  "distance": 123.45,
  "currentTime": "abc123",
  "pickupDate": "abc123",
  "dispatchDate": "xyz789",
  "locationMap": "xyz789",
  "calendarDate": CalendarDate,
  "standardHours": "abc123",
  "publicId": "xyz789",
  "nonStandardHours": "xyz789",
  "email": "xyz789",
  "contactName": "xyz789",
  "imageUrl": "abc123",
  "walkingDirections": "xyz789",
  "websiteUrl": "abc123",
  "pickupFullName": "xyz789",
  "emailOption": "xyz789"
}
Types

RateBreakdown

Breakdown of individual shipping rates used to make up a shipping method, for example with merged rates or rate shopping

Field Name Description
shipmentDetail - ShipmentDetail! Details of shipment
carrierDetail - CarrierDetail! Carrier specific information e.g. code and name
methodCode - String! Unique code of shipping method - intended for internal use
methodDetails - MethodDetail! Shipping method information like code, title, total charges
timeInTransitOptions - TimeInTransitOptions Dispatch and delivery date information
advancedFees - AdvancedFees Fees and charges included in shipping method
isWinningRate - Boolean Is this the winning rate
packages - [Package!]! Packages or boxes included in shipping rate
Example
{
  "shipmentDetail": ShipmentDetail,
  "carrierDetail": CarrierDetail,
  "methodCode": "abc123",
  "methodDetails": MethodDetail,
  "timeInTransitOptions": TimeInTransitOptions,
  "advancedFees": AdvancedFees,
  "isWinningRate": false,
  "packages": [Package]
}
Types

SelectedOption

Delivery options included in shipping rate, e.g. liftgate, residential delivery

Field Name Description
name - String Name of option
value - String Value selected
Example
{"name": "abc123", "value": "abc123"}
Types

Shipment

Shipping and packing information for this shipment

Field Name Description
id - ID Deprecated: do not use
shipmentDetail - ShipmentDetail! Unique ID and display name of shipment
carriers - [Carrier!]! Carrier and shipping method information for the shipment
groupedItems - [GroupedItem!]! Details of items in shipment
Example
{
  "id": ID,
  "shipmentDetail": ShipmentDetail,
  "carriers": [Carrier],
  "groupedItems": [GroupedItem]
}
Types

ShipmentDetail

Unique ID and display name of shipment

Field Name Description
shipmentId - String! Unique id of shipment
name - String! Display name of shipment
description - String Further description of shipment - intended for display to end user e.g. tooltip
originAddress - Address Address of origin
Example
{
  "shipmentId": "xyz789",
  "name": "xyz789",
  "description": "xyz789",
  "originAddress": Address
}
Types

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Types

TimeInTransitOptions

Dispatch and delivery date information

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

TimeSlot

Time slot information for pickup or delivery

Field Name Description
timeStart - String! Start time of selected time slot
timeEnd - String! End time of selected time slot
interval - String! Length of time slot, in minutes
Example
{"timeStart": "abc123", "timeEnd": "abc123", "interval": "abc123"}
Documentation by Anvil SpectaQL