ShipperHQ Labels API Reference Documentation

Labels API Reference

ShipperHQ Dev Support
Contact us

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

API Endpoints
Production Server:
https://postapi.shipperhq.com/v3/graphql/label

Queries

cancelLabel

Returns a CancelLabelOutput

Name Description
cancelLabelInfo - CancelLabelInfoInput Cancellation of shipment

Example

Query
query cancelLabel($cancelLabelInfo: CancelLabelInfoInput) {
  cancelLabel(cancelLabelInfo: $cancelLabelInfo) {
    responseSummary {
      ...ResponseSummaryFragment
    }
    transactionId
    errors {
      ...ErrorFragment
    }
  }
}
Variables
{"cancelLabelInfo": CancelLabelInfoInput}
Response 
{
  "data": {
    "cancelLabel": {
      "responseSummary": ResponseSummary,
      "transactionId": "abc123",
      "errors": [Error]
    }
  }
}

createLabel

Returns a LabelOutput

Name Description
labelInfo - LabelInfoInput Label Information

Example

Query
query createLabel($labelInfo: LabelInfoInput) {
  createLabel(labelInfo: $labelInfo) {
    transactionId
    errors {
      ...ErrorFragment
    }
    labels {
      ...LabelFragment
    }
  }
}
Variables
{"labelInfo": LabelInfoInput}
Response 
{
  "data": {
    "createLabel": {
      "transactionId": "xyz789",
      "errors": [Error],
      "labels": [Label]
    }
  }
}

createManifest

Returns a ManifestOutput

Name Description
manifestInfo - ManifestInfoInput Manifest Information

Example

Query
query createManifest($manifestInfo: ManifestInfoInput) {
  createManifest(manifestInfo: $manifestInfo) {
    manifests {
      ...ManifestFragment
    }
    responseSummary {
      ...ResponseSummaryFragment
    }
    errors {
      ...ErrorFragment
    }
  }
}
Variables
{"manifestInfo": ManifestInfoInput}
Response 
{
  "data": {
    "createManifest": {
      "manifests": [Manifest],
      "responseSummary": ResponseSummary,
      "errors": [Error]
    }
  }
}

placeOrder

Returns a PlaceOrderOutput

Name Description
placeOrderInfo - PlaceOrderInfoInput Order Info To Place

Example

Query
query placeOrder($placeOrderInfo: PlaceOrderInfoInput) {
  placeOrder(placeOrderInfo: $placeOrderInfo) {
    responseSummary {
      ...ResponseSummaryFragment
    }
    errors {
      ...ErrorFragment
    }
    transactionId
  }
}
Variables
{"placeOrderInfo": PlaceOrderInfoInput}
Response 
{
  "data": {
    "placeOrder": {
      "responseSummary": ResponseSummary,
      "errors": [Error],
      "transactionId": "abc123"
    }
  }
}

Types

AddressInput

Address of an originating or receiving location

Input Field Description
telNo - String

Telephone number of a contact at this location, if applicable. eg '(+44) 00000 000000'
country - String

ISO 2 character country code for this location. eg 'US', 'MX', 'UK'
zipcode - String

5 digit zipcode (US) or post code if applicable. eg '78748', 'SS8 9DE'
destinationType - String

Deprecated. Use selectedOptions instead.
city - String

City name. eg 'Columbus', 'Ontario', 'Perth'
selectedOptions - SelectedOptionsInput

Optional properties or shipping accessorials that apply to this location. List of Name/Value pairs.
accessorials - SelectedOptionsInput

Deprecated. Use selectedOptions instead
street2 - String

Second line of street address if applicable. eg 'Building 5 Suite 210'
givenName - String

Given name of a contact at this location, if applicable. eg 'Karen'
street - String

First line of the street address. eg '123 Main Street'
region - String

2 or 3 character region code if applicable. eg 'AK', 'BC', 'NSW'
email - String

Email address of a contact at this location, if applicable. eg ' hello@example.com'
companyName - String

Business name of this location, if applicable. eg 'Zowta, LLC'
familyName - String

Family name of a contact at this location, if applicable. eg 'Baker'
Example
{
  "telNo": "xyz789",
  "country": "abc123",
  "zipcode": "abc123",
  "destinationType": "xyz789",
  "city": "abc123",
  "selectedOptions": SelectedOptionsInput,
  "accessorials": SelectedOptionsInput,
  "street2": "abc123",
  "givenName": "xyz789",
  "street": "abc123",
  "region": "xyz789",
  "email": "abc123",
  "companyName": "abc123",
  "familyName": "xyz789"
}
Types

BigDecimal

Built-in java.math.BigDecimal

Example
object
Types

Boolean

Built-in Boolean

Example
false
Types

CancelLabelInfoInput

Input details required for label cancellation

Input Field Description
trackingId - String

Used to identify a specific package within a shipment (optional)
shipmentId - String

Used to identify the entire shipment (Must be present to close shipment)
siteDetails - SiteDetailsInput

Details about the site/platform originating this request
carrier - CarrierInput

Details about shipping carrier
Example
{
  "trackingId": "xyz789",
  "shipmentId": "xyz789",
  "siteDetails": SiteDetailsInput,
  "carrier": CarrierInput
}
Types

CancelLabelOutput

Response status of cancellation of shipment

Field Name Description
responseSummary - ResponseSummary Contains the status indicator of cancellation 1 = success
transactionId - String Generated by ShipperHQ for identifying request
errors - [Error]
Example
{
  "responseSummary": ResponseSummary,
  "transactionId": "abc123",
  "errors": [Error]
}
Types

CarrierInput

Describes the desired carrier for this shipment

Input Field Description
carrierType - String

The carrier type code for the selected carrier. Can be retrieved from the shipping rate response. Case sensitive. eg 'fedEx'
carrierCode - String

The carrier code for the selected carrier. Can be retrieved from the shipping rate response or from your ShipperHQ account. Case sensitive. eg 'shqups1'
Example
{"carrierType": "xyz789", "carrierCode": "xyz789"}
Types

CustomsDetailInput

The details of the package in the shipment, used for intl shipments

Input Field Description
hsCode - String

Deprecated: Not Currently in use
itemDescription - String

Description of items, if empty a general description is sent
weight - BigDecimal

Weight of package
qty - BigDecimal

The packaged quantity
sku - String

SKU of item in package
countryOfOrigin - String

Uppercase ISO 2 country code for origin of shipment
descriptionForExport - String

Brief description of reason for package export. Nothing will result in unknown reason
Example
{
  "hsCode": "abc123",
  "itemDescription": "xyz789",
  "weight": BigDecimal,
  "qty": BigDecimal,
  "sku": "abc123",
  "countryOfOrigin": "abc123",
  "descriptionForExport": "xyz789"
}
Types

Date

Built-in scalar representing an instant in time

Example
2021-10-13T04:36:14.135Z
Types

Error

Error information

Field Name Description
internalErrorMessage - String Error message intended for internal application use
errorCode - Int! ShipperHQ Error Code
priority - Int Relative error priority
externalErrorMessage - String Error message intended for display to end user
Example
{
  "internalErrorMessage": "xyz789",
  "errorCode": 123,
  "priority": 123,
  "externalErrorMessage": "abc123"
}
Types

Event

Field Name Description
date - String
country - String
postalCode - String
description - String
timeZone - String
location - String
id - Int
time - String
Example
{
  "date": "abc123",
  "country": "abc123",
  "postalCode": "xyz789",
  "description": "xyz789",
  "timeZone": "xyz789",
  "location": "abc123",
  "id": 123,
  "time": "abc123"
}
Types

Float

Built-in Float

Example
987.65
Types

Int

Built-in Int

Example
987
Types

Label

Label Details

Field Name Description
labelImage - String Image of the label specified in type PDF/PNG/etc... base64 encoded string
copies - Int Number of copies needed to print for the label
shipmentId - String Used to identify shipment. Can also be used for cancelling services
postageCost - PostageCost The cost of having mail delivered. Not always retreieved from service
labelType - LabelType Used to specify what kind of label. PRIMARY, CUSTOMS, FORM, etc...
labelUrl - String Used for providing url to see label and see online
trackingId - String Used for tracking status of shipment
Example
{
  "labelImage": "xyz789",
  "copies": 987,
  "shipmentId": "xyz789",
  "postageCost": PostageCost,
  "labelType": LabelType,
  "labelUrl": "abc123",
  "trackingId": "abc123"
}
Types

LabelInfoInput

Input details required for label generation

Field Name Description
sender - SenderInput Details about fulfillment center
recipient - RecipientInput Details about shipment recipient
siteDetails - SiteDetailsInput Details about the site/platform originating this request
shipments - [ShipmentInput] Details about packages in the shipment
carrier - CarrierInput Details about shipping carrier
Example
{
  "sender": SenderInput,
  "recipient": RecipientInput,
  "siteDetails": SiteDetailsInput,
  "shipments": [ShipmentInput],
  "carrier": CarrierInput
}
Types

LabelOutput

Output details from the label provider

Field Name Description
transactionId - String Generated by ShipperHQ for identifying request
errors - [Error]
labels - [Label] Label info returned from the carrier service
Example
{
  "transactionId": "xyz789",
  "errors": [Error],
  "labels": [Label]
}
Types

LabelPieceInput

The details of the package in the shipment

Field Name Description
declaredValue - BigDecimal Declared value of package
insuredValue - BigDecimal Insured value of package
freightClass - String Freight class of the package. Currently only for use on UPS Ground w/ Freight
requestedServices - [ServiceInput] Request service of package, meant to override dashboard configuration, name/value pair
id - Int Deprecated: Not currently used
length - BigDecimal Length of package
width - BigDecimal Width of package
height - BigDecimal Height of package
customsDetails - CustomsDetailInput Additional information used for international shipments
referenceId - String Used to provide a specific id to reference package on shipment
containerType - String Deprecated: Not currently in use
weight - BigDecimal Weight of package
Example
{
  "declaredValue": BigDecimal,
  "insuredValue": BigDecimal,
  "freightClass": "xyz789",
  "requestedServices": [ServiceInput],
  "id": 987,
  "length": BigDecimal,
  "width": BigDecimal,
  "height": BigDecimal,
  "customsDetails": CustomsDetailInput,
  "referenceId": "xyz789",
  "containerType": "abc123",
  "weight": BigDecimal
}
Types

LabelType

Enum Value Description

PRIMARY

CUSTOMS

FORM

AGREEMENT

RETURN
Types

Manifest

Field Name Description
manifestImage - String
manifestId - String
manifestUrl - String
Example
{"manifestImage": "xyz789", "manifestId": "xyz789", "manifestUrl": "abc123"}
Types

ManifestInfoInput

Field Name Description
siteDetails - SiteDetailsInput Details about the site/platform originating this request
pieces - [ManifestPieceInput]
sender - ManifestSenderInput
carrier - CarrierInput
Example
{
  "siteDetails": SiteDetailsInput,
  "pieces": [ManifestPieceInput],
  "sender": ManifestSenderInput,
  "carrier": CarrierInput
}
Types

ManifestOutput

Field Name Description
manifests - [Manifest]
responseSummary - ResponseSummary
errors - [Error]
Example
{
  "manifests": [Manifest],
  "responseSummary": ResponseSummary,
  "errors": [Error]
}
Types

ManifestPieceInput

Input Field Description
carrierCode - String
carrierType - String
shippingMethodCode - String
labelId - String
referenceId - String
Example
{
  "carrierCode": "abc123",
  "carrierType": "xyz789",
  "shippingMethodCode": "abc123",
  "labelId": "xyz789",
  "referenceId": "abc123"
}
Types

ManifestSenderInput

Input Field Description
originName - String
Example
{"originName": "xyz789"}
Types

NameValuePairInput

A Name/Value pair

Input Field Description
value - String

Data value stored at this name. eg 'RESIDENTIAL'
name - String

Name identifying this data point. eg 'destination_type'
Example
{"value": "xyz789", "name": "xyz789"}
Types

PlaceOrderInfoInput

Input Field Description
orderNumber - String
recipient - AddressInput
methodCode - String
siteDetails - SiteDetailsInput

Details about the site/platform originating this request
carrierCode - String
transId - String
totalCharges - Float
Example
{
  "orderNumber": "abc123",
  "recipient": AddressInput,
  "methodCode": "xyz789",
  "siteDetails": SiteDetailsInput,
  "carrierCode": "abc123",
  "transId": "abc123",
  "totalCharges": 123.45
}
Types

PlaceOrderOutput

Field Name Description
responseSummary - ResponseSummary
errors - [Error]
transactionId - String
Example
{
  "responseSummary": ResponseSummary,
  "errors": [Error],
  "transactionId": "abc123"
}
Types

PostageCost

Field Name Description
insurance - BigDecimal
total - BigDecimal
tax - BigDecimal
shipping - BigDecimal
duties - BigDecimal
Example
{
  "insurance": BigDecimal,
  "total": BigDecimal,
  "tax": BigDecimal,
  "shipping": BigDecimal,
  "duties": BigDecimal
}
Types

RecipientInput

Describes the recipient details shipment is going to

Input Field Description
selectedOptions - SelectedOptionsInput

Optional properties or shipping accessorials that apply to this location. List of Name/Value pairs.
street2 - String

Second line of street address if applicable. eg 'Building 5 Suite 210'
zipcode - String

5 digit zipcode (US) or post code if applicable. eg '78748', 'SS8 9DE'
locationId - String

Unique ID assigned to the location. Required FedEx HAL and UPS Access Point shipments
pickupState - String

For Use With UPS AccessPoint: The state of center to pick up from, eg 'TX'
pickupZipcode - String

For Use With UPS AccessPoint: The zipcode of center to pick up from
pickupStreet1 - String

For Use With UPS AccessPoint: The main street of center to pick up from
region - String

2 or 3 character region code if applicable. eg 'AK', 'BC', 'NSW'
street - String

First line of the street address. eg '123 Main Street'
destinationType - String

Deprecated. Use selectedOptions instead.
pickupName - String

For Use With UPS AccessPoint: The name of center to pick up from
city - String

City name. eg 'Columbus', 'Ontario', 'Perth'
pickupCity - String

For Use With UPS AccessPoint: The city of center to pick up from
locationType - String

Currently only required for FedEx HAL shipments, describes the type of center to be picked up from
email - String

Email address of a contact at this location, if applicable. eg ' hello@example.com'
givenName - String

Given name of a contact at this location, if applicable. eg 'Karen'
pickupStreet2 - String

For Use With UPS AccessPoint (optional): Additional address details of center to pick up from, eg 'Suite 500'
accessorials - SelectedOptionsInput

Deprecated. Use selectedOptions instead
pickupCountry - String

For Use With UPS AccessPoint: The country of center to pick up from, eg 'US'
familyName - String

Family name of a contact at this location, if applicable. eg 'Baker'
companyName - String

Business name of this location, if applicable. eg 'Zowta, LLC'
country - String

ISO 2 character country code for this location. eg 'US', 'MX', 'UK'
telNo - String

Telephone number of a contact at this location, if applicable. eg '(+44) 00000 000000'
Example
{
  "selectedOptions": SelectedOptionsInput,
  "street2": "xyz789",
  "zipcode": "xyz789",
  "locationId": "abc123",
  "pickupState": "abc123",
  "pickupZipcode": "xyz789",
  "pickupStreet1": "xyz789",
  "region": "xyz789",
  "street": "xyz789",
  "destinationType": "xyz789",
  "pickupName": "xyz789",
  "city": "abc123",
  "pickupCity": "xyz789",
  "locationType": "abc123",
  "email": "xyz789",
  "givenName": "xyz789",
  "pickupStreet2": "xyz789",
  "accessorials": SelectedOptionsInput,
  "pickupCountry": "abc123",
  "familyName": "abc123",
  "companyName": "abc123",
  "country": "abc123",
  "telNo": "xyz789"
}
Types

ResponseSummary

Field Name Description
date - Date
version - String
transactionId - String
status - Int!
Example
{
  "date": "2021-10-13T04:36:14.135Z",
  "version": "xyz789",
  "transactionId": "abc123",
  "status": 123
}
Types

SelectedOptionsInput

List of optional properties that are active. Name/Value pairs.

Field Name Description
options - [NameValuePairInput] List of optional properties that are active. Name/Value pairs.
Example
{"options": [NameValuePairInput]}
Types

SenderInput

Input Field Description
givenName - String

Given name of a contact at this location, if applicable. eg 'Karen'
familyName - String

Family name of a contact at this location, if applicable. eg 'Baker'
country - String

ISO 2 character country code for this location. eg 'US', 'MX', 'UK'
region - String

2 or 3 character region code if applicable. eg 'AK', 'BC', 'NSW'
zipcode - String

5 digit zipcode (US) or post code if applicable. eg '78748', 'SS8 9DE'
companyName - String

Business name of this location, if applicable. eg 'Zowta, LLC'
originName - String
selectedOptions - SelectedOptionsInput

Optional properties or shipping accessorials that apply to this location. List of Name/Value pairs.
city - String

City name. eg 'Columbus', 'Ontario', 'Perth'
destinationType - String

Deprecated. Use selectedOptions instead.
telNo - String

Telephone number of a contact at this location, if applicable. eg '(+44) 00000 000000'
street - String

First line of the street address. eg '123 Main Street'
email - String

Email address of a contact at this location, if applicable. eg ' hello@example.com'
accessorials - SelectedOptionsInput

Deprecated. Use selectedOptions instead
street2 - String

Second line of street address if applicable. eg 'Building 5 Suite 210'
Example
{
  "givenName": "xyz789",
  "familyName": "xyz789",
  "country": "abc123",
  "region": "abc123",
  "zipcode": "xyz789",
  "companyName": "xyz789",
  "originName": "abc123",
  "selectedOptions": SelectedOptionsInput,
  "city": "xyz789",
  "destinationType": "abc123",
  "telNo": "abc123",
  "street": "abc123",
  "email": "abc123",
  "accessorials": SelectedOptionsInput,
  "street2": "xyz789"
}
Types

ServiceInput

Special requested service for package

Input Field Description
name - String

Name of the attribute requested, eg 'SIGNATURE_OPTION'
value - String

Value of the attribute requested, eg '3' for adult signature via UPS, different per carrier
Example
{"name": "xyz789", "value": "abc123"}
Types

ShipmentDetailInput

Describes the details associated with shipment

Input Field Description
taxCharges - BigDecimal

Deprecated: Currently do not use for any shipments
shipmentId - String

Unique ID associated with the shipment. Can be used for later cancelling/tracking services
shippingMethodCode - String

Method code of service used for shipping package. Best to be case sensitive, eg 'FEDEX_GROUND', should not be adapted in any way
shippingMethodName - String

Deprecated: Currently do not use
insuranceCharges - BigDecimal

Deprecated: Currently do not use. Can place declared value on Piece level
shippingCharges - BigDecimal

The cost of shipping the package via the method requested
selectedDate - String

Used for setting a specific shipment day, eg 'MM/dd/yyyy
Example
{
  "taxCharges": BigDecimal,
  "shipmentId": "xyz789",
  "shippingMethodCode": "xyz789",
  "shippingMethodName": "abc123",
  "insuranceCharges": BigDecimal,
  "shippingCharges": BigDecimal,
  "selectedDate": "abc123"
}
Types

ShipmentInput

Describes the details associated with package being shipped and it's contents

Field Name Description
pieces - [LabelPieceInput] The packages of the shipment
shipmentDetail - ShipmentDetailInput Details of service and additional info for shipment
Example
{
  "pieces": [LabelPieceInput],
  "shipmentDetail": ShipmentDetailInput
}
Types

SiteDetailsInput

Details about the website/platform

Input Field Description
ecommerceCart - String

Ecommerce Platform Name
ipAddress - String

User's IP Address
websiteUrl - String

Website URL the request is sent from, should match what is inside SHQ dashboard
appVersion - String

Version number of the client application
ecommerceVersion - String

Ecommerce Platform's version
Example
{
  "ecommerceCart": "xyz789",
  "ipAddress": "abc123",
  "websiteUrl": "abc123",
  "appVersion": "xyz789",
  "ecommerceVersion": "abc123"
}
Types

String

Built-in String

Documentation by Anvil SpectaQL