ShipperHQ Insights API Reference Documentation

ShipperHQ Insights API Reference

Contact

ShipperHQ Dev Support
Contact us

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) {
    createdAt
    orderNumber
    apiKey
    orderNumberText
    isActive
    orderDetail {
      ...OrderDetailFragment
    }
    shipments {
      ...ShipmentFragment
    }
    recipient {
      ...AddressFragment
    }
  }
}
Variables
{"orderNumber": "xyz789"}
Response
{
  "data": {
    "viewOrder": [
      {
        "createdAt": "abc123",
        "orderNumber": "xyz789",
        "apiKey": "xyz789",
        "orderNumberText": "xyz789",
        "isActive": true,
        "orderDetail": OrderDetail,
        "shipments": [Shipment],
        "recipient": Address
      }
    ]
  }
}

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": "abc123",
  "city": "xyz789",
  "street": "xyz789",
  "street2": "xyz789",
  "zipcode": "abc123",
  "firstName": "xyz789",
  "lastName": "abc123",
  "email": "abc123",
  "company": "abc123",
  "telephone": "xyz789"
}

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": 123.45,
  "cost": 987.65,
  "customDuties": 123.45,
  "flatRulesApplied": ["xyz789"],
  "changeRulesApplied": ["xyz789"]
}

Boolean

The Boolean scalar type represents true or false.

Example
false

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
availableDeliveryDates - [String!] Selected delivery date or pickup date
timeSlots - [TimeSlot!]! Selected time slot for pickup or delivery
Example
{
  "deliveryDateRanges": [DeliveryDateRange],
  "availableDeliveryDates": ["xyz789"],
  "timeSlots": [TimeSlot]
}

Carrier

Carrier and shipping method information for the shipment

Field Name Description
carrierDetail - CarrierDetail! Carrier specific information e.g. code and name
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
}

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": "abc123",
  "carrierType": "xyz789",
  "deliveryDateMessage": "xyz789"
}

DeliveryDateRange

Internal use only

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

Float

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

Example
123.45

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": "abc123",
  "sku": "xyz789",
  "qty": 987,
  "name": "xyz789",
  "hs_code": "abc123",
  "origin_country": "xyz789",
  "declared_value": 987.65
}

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

Int

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

Example
123

Item

Details of item in package

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

LabelType

Enum Value Description

PRIMARY

CUSTOMS

FORM

AGREEMENT

RETURN

Method

Shipping methods and rate information

Field Name Description
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
{
  "methodDetails": MethodDetail,
  "timeInTransitOptions": TimeInTransitOptions,
  "rateBreakdownList": [RateBreakdown],
  "advancedFees": AdvancedFees,
  "packages": [Package],
  "selectedOptions": [SelectedOption]
}

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
Example
{
  "methodCode": "xyz789",
  "methodTitle": "xyz789",
  "totalCharges": 123.45,
  "currency": "xyz789",
  "negotiatedRate": false,
  "deliveryMessage": "abc123"
}

Order

Information stored for a single order

Field Name Description
createdAt - String
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
Example
{
  "createdAt": "abc123",
  "orderNumber": "abc123",
  "apiKey": "abc123",
  "orderNumberText": "abc123",
  "isActive": false,
  "orderDetail": OrderDetail,
  "shipments": [Shipment],
  "recipient": Address
}

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
Example
{
  "carrierCode": "xyz789",
  "carrierTitle": "xyz789",
  "methodCode": "xyz789",
  "methodTitle": "xyz789",
  "totalCharges": 123.45,
  "transactionId": "abc123"
}

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

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!
weight - Float! Weight of package
width - Float! Width of package
Example
{
  "declaredValue": 987.65,
  "height": 123.45,
  "length": 123.45,
  "packageName": "xyz789",
  "packingWeight": 987.65,
  "surchargePrice": 123.45,
  "weight": 987.65,
  "width": 987.65
}

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": true,
  "showMap": "xyz789",
  "showAddress": "xyz789"
}

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": "abc123",
  "pickupName": "xyz789",
  "latitude": 123.45,
  "longitude": 123.45,
  "street1": "xyz789",
  "street2": "xyz789",
  "city": "xyz789",
  "state": "xyz789",
  "country": "abc123",
  "zipcode": "xyz789",
  "phone": "abc123",
  "distance": 987.65,
  "currentTime": "xyz789",
  "pickupDate": "xyz789",
  "dispatchDate": "abc123",
  "locationMap": "xyz789",
  "calendarDate": CalendarDate,
  "standardHours": "abc123",
  "publicId": "xyz789",
  "nonStandardHours": "abc123",
  "email": "abc123",
  "contactName": "xyz789",
  "imageUrl": "abc123",
  "walkingDirections": "abc123",
  "websiteUrl": "xyz789",
  "pickupFullName": "abc123",
  "emailOption": "abc123"
}

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
packages - [Package!]! Packages or boxes included in shipping rate
Example
{
  "shipmentDetail": ShipmentDetail,
  "carrierDetail": CarrierDetail,
  "methodCode": "abc123",
  "methodDetails": MethodDetail,
  "timeInTransitOptions": TimeInTransitOptions,
  "advancedFees": AdvancedFees,
  "packages": [Package]
}

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": "xyz789", "value": "abc123"}

Shipment

Shipping and packing information for this shipment

Field Name Description
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
{
  "shipmentDetail": ShipmentDetail,
  "carriers": [Carrier],
  "groupedItems": [GroupedItem]
}

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
Example
{"shipmentId": "abc123", "name": "abc123", "description": "abc123"}

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.

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

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": "xyz789"}