ShipHawk

The ShipHawk Developer Hub

Welcome to the ShipHawk developer hub. You'll find comprehensive guides and documentation to help you start working with ShipHawk as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

Address Object

 

Address objects represent an origin or destination of a shipment and are required in order to get rates and book shipments. They can also be saved to the address book so that frequently used addresses can be stored for search or retrieval at a later time.

Required Attributes when getting Rates

When rating, zip is the only required attribute.

Required Attributes when creating Addresses and Shipments

Either name or company is required along with street1, city, state, zip and country when creating an address or booking a shipment.

Attribute
Type
Description

id

string

name

string

Usually Required Not required when company is present or when rating.
The name of the contact person at this address.

company

string

Usually Required Not required when name is present or when rating.

street1

string

Usually Required Not required when rating.

street2

string

Apt or suite #, mailstop, etc.

city

string

Usually Required Not required when rating.
City or town.

state

string

Usually Required Not required when rating.
2-digit state or province required for US and Canadian addresses.

zip

string

required
Zip or postal code.

country

string

A 2-digit ISO country code. Default: US

phone_number

string

Usually Required Not required when rating.

email

string

is_residential

boolean

Default: false

code

string

A unique reference for this address. This field is indexed so that you can search for addresses by this code using the List all Addresses endpoint. The code may have numbers, letters, underscores, and dashes.

Example Address

{
  "id" : "adr_mjPzyRpD",
  "name": "Leonard Cooper",
  "company": "Rockets Inc.",
  "street1": "2311N Los Robles Ave.",
  "street2": "4th Floor",
  "city": "Pasadena",
  "state": "CA",
  "zip": "91108",
  "country": "US",
  "phone_number": "6265551358",
  "email": "leonard@smashingprotons.com",
  "is_residential":true,
  "validated": false,
  "code": "MYUNIQUECODE"
}

Example Address (zip code only for rating)

{
  "zip": "91108"
}
Suggest Edits

Create an Address

Creates a new address object.

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/addresses/
curl -X POST https://sandbox.shiphawk.com/api/v4/addresses \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '{
    		"name": "Hans Gruber",
    		"street1": "328 State Street",
    		"city": "Santa Barbara",
    		"state": "CA",
    		"zip": "93101",
    		"is_residential": true
			}' 
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "adr_bEmW36ve",
  "name": "Hans Gruber",
  "company": null,
  "street1": "328 State Street",
  "street2": null,
  "city": "Santa Barbara",
  "state": "CA",
  "zip": "93101",
  "country": "US",
  "phone_number": null,
  "email": null,
  "is_residential": true,
  "validated": false,
  "code": null
}

Body Params

name
string

Required unless company is present.

company
string

Required unless name is present.

street1
string
required

Required.

street2
string
city
string
required

Required.

state
string
required

Required.

zip
string
required

Required.

country
string

A 2-digit ISO country code.

is_residential
boolean

Default: false

phone_number
string
email
string
code
string

Unique code to easily lookup this address when searching

 
Suggest Edits

Retrieve an Address

Retrieve the details of an existing address using the address id.

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/addresses/id
curl https://sandbox.shiphawk.com/api/v4/addresses/adr_bEmW36ve \
	-H 'X-Api-Key: YOUR_API_KEY'
	
	
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "adr_bEmW36ve",
  "name": "Hans Gruber",
  "company": null,
  "street1": "328 State Street",
  "street2": null,
  "city": "Santa Barbara",
  "state": "CA",
  "zip": "93101",
  "country": "US",
  "phone_number": null,
  "email": null,
  "is_residential": true,
  "validated": false,
  "code": null
}

Path Params

id
string
required
 
Suggest Edits

Retrieve an Address by code

Retrieve an existing address using the address code.

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/addresses/code/code
curl https://sandbox.shiphawk.com/api/v4/addresses/code/MYUNIQUECODE \
	-H 'X-Api-Key: YOUR_API_KEY'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "adr_bEmW36ve",
  "name": "Hans Gruber",
  "company": null,
  "street1": "328 State Street",
  "street2": null,
  "city": "Santa Barbara",
  "state": "CA",
  "zip": "93101",
  "country": "US",
  "phone_number": null,
  "email": null,
  "is_residential": true,
  "validated": false,
  "code": "MYUNIQUECODE"
}

Path Params

code
string
required
 
Suggest Edits

Update an Address

Updates an existing address. Any parameters not provided will retain their original values.

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/addresses/id
curl -X POST https://sandbox.shiphawk.com/api/v4/addresses/adr_bEmW36ve \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '{
        "phone_number": "8053352432"
      }' 
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "adr_bEmW36ve",
  "name": "Hans Gruber",
  "company": null,
  "street1": "328 State Street",
  "street2": null,
  "city": "Santa Barbara",
  "state": "CA",
  "zip": "93101",
  "country": "US",
  "phone_number": "8053352432",
  "email": null,
  "is_residential": true,
  "validated": false,
  "code": null
}

Path Params

id
string
required

id of the address to be updated

Body Params

name
string

Name of the person associated with address

company
string

Name of company

street1
string

Street address 1

street2
string

Apt or suite #, mailstop, etc.

city
string

City or town

state
string

State or provice

zip
string

Zip or postal code

country
string

A 2-digit ISO country code

is_residential
boolean

Whether the address is a residential or not

phone_number
string

Phone number

email
string

Email

validated
string
code
string
 
Suggest Edits

Delete an Address

Permanently deletes an existing address using the address id. This action cannot be undone.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/addresses/id
curl -X DELETE https://sandbox.shiphawk.com/api/v4/addresses \
  -H 'Content-Type: application/json'
  -H 'X-Api-Key: YOUR_API_KEY'
  -d {"id":["adr_bEmW36ve"]}
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

Can be a string for a single address id or an array of strings for multiple address ids

 
Suggest Edits

List all Addresses

Returns a list of all addresses you have created.

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/addresses
curl https://sandbox.shiphawk.com/api/v4/addresses/ \
  -H 'X-Api-Key: YOUR_API_KEY'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
   {
    "id": "adr_RSTYe0Xq",
    "name": "Theodore Lee",
    "company": "ShipHawk",
    "street1": "328 State Street",
    "street2": "#12",
    "city": "Santa Barbara",
    "state": "CA",
    "zip": "93101",
    "country": "US",
    "phone_number": "8053442495",
    "email": "theodore@shiphawk.com",
    "is_residential": false,
    "validated": false,
    "code": "abc"
  },
  {
    "id": "adr_bEmW36ve",
    "name": "Hans Gruber",
    "company": "ShipHawk",
    "street1": "328 State Street",
    "street2": "#12",
    "city": "Santa Barbara",
    "state": "CA",
    "zip": "93101",
    "country": "US",
    "phone_number": "8053442495",
    "email": "hansgruber@shiphawk.com",
    "is_residential": false,
    "validated": false,
    "code": "123"
  }
]
 
Suggest Edits

Validate an Address

Updates the specified address based on USPS address validation.

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/addresses/validate
curl -X POST -H "X-Api-Key: [Your-API-Key]" 
-d '{
"addresses": 
 [
   { 
     "street1": "1420 GARDINER LN", 
     "city": "Louisville", 
     "state": "KY", 
     "zip": "40231"
   }, 
   { 
     "street1": "26 Castilian Dr", 
     "city": "Goleta", 
     "state": "CA", 
     "zip": "93117" 
    }
  ]
}' "https://sandbox.shiphawk.com/api/v4/addresses/validate"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
"valid": false,
"non_deliverable_addresses": [
 {
   "street1": "1 Infinite",
   "city": "Cupertins",
   "state": "WA",
   "zipcode": "95014",
   "suggestions": [
     {
       "street1": "1 Infinite Loop",
       "city": "Cupertino",
       "state": "CA",
       "zipcode": "95014"
     }
   ]
 }
]
}

Body Params

street1
string
required
street2
string
city
string
required
state
string
required
zip
string
required
country
string
 

Address Validation

Address validation is a paid service (from $0.05 per validation) and is only enabled for select accounts. To enable this service, please reach out to support@shiphawk.com

Suggest Edits

Document Object

A document is the paperwork required by a particular carrier in order to ship a set of goods. For parcel carriers, a shipping label is needed. For LTL carriers, a bill of lading is needed. For international shipments, a commercial invoice and Internal Transaction Number (ITN) may be needed.

 
Attribute
Type
Description

id

string

type

string

The document types are:
bol signed_bol pod address_label waybill carrier_doc image other

url

string

A URL link to a pdf version of the document

file

string

For type label, the file will be in .zpl format. For type bill_of_lading, the file will be in .pdf format. For type commercial_invoice, the file will be in .pdf format.

created_at

date time

Example Document

{
    "id": "doc_jd83k8fy2",
    "type": "label",
    "url": "",
    "file": "^XA^CF,0,0,0^PR12...^FS\n^PQ1\n^XZ\n",
    "created_at": "2015-11-08T20:57:32Z"
}
Suggest Edits

Create a Document

Upload a document to the shipment

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/shipment_id/documents
curl -X POST 'https://sandbox.shiphawk.com/api/v4/shipments/shp_x4xevmdN/documents' \
	-H 'X-Api-Key: [Your API Key]' \
  -d @YOUR_FILE_NAME \
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "id": "doc_kgMJXRTv",
    "type": "BOL",
    "url": "http://0.0.0.0:3000/uploads/ci_P97NCNHHTA.pdf",
    "file": "^XA^CF,0,0,0^PR12...^FS\n^PQ1\n^XZ\n",
    "created_at": "2016-01-17T02:34:05.360Z"
  }
]

Body Params

file
file

A shipment document

document_type
string

bol or signed_bol or pod or address_label or waybill or carrier_doc or image or other

 
Suggest Edits

Retrieve a Document

Retrieves a document on a shipment

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/documents/id
curl -X GET "https://sandbox.shiphawk.com/api/v4/documents/doc_jd83k8fy2?api_key=[[app:key]]"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "doc_jd83k8fy2",
  "type": "bol",
  "url": "",
  "file": "",
  "created_at": "2015-11-08T20:57:32Z"
}

Path Params

id
int32
required

The id for the document you are looking for.

 
Suggest Edits

Update Document Type of Document on the Shipment

Changes the document type for a shipment document

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/id/documents/id
curl -X POST 'https://sandbox.shiphawk.com/api/v4/shipments/sh_PJTRcatk/documents/doc_tngz4S6J' \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR_API_KEY' \
   -d '{ "tracking_number": "abc", "document_type": "pod" }'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "doc_tngz4S6J",
  "type": "pod",
  "url": "",
  "file": "",
  "created_at": "2015-11-08T20:57:32Z"
}

Body Params

document_type
string
required

The new document type.

 
Suggest Edits

Delete a Document

Delete a document from shipment by id

 

Authentication

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/shipments/id/documents/id
curl -X DELETE 'https://sandbox.shiphawk.com/api/v4/shipments/sh_PJTRcatk/documents/doc_tngz4S6J' \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR_API_KEY'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     204 No Content
{
	"status": "204"
}
 
Suggest Edits

Retrieve a List of a Shipment's documents

Retrieve an existing shipment by shipment id

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/id/documents
curl -X GET 'https://sandbox.shiphawk.com/api/v4/shipments/ship_jdh973f92n/documents' \
	-H 'X-Api-Key: YOUR_API_KEY' \
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
 {
  "id": "doc_jd83k8fy2",
  "type": "label",
  "url": "",
  "file": "",
  "created_at": "2015-11-08T20:57:32Z"
 } 
]
 
Suggest Edits

Handling Unit Object

A handling unit is a physical unit consisting of packaging materials (load carriers/packing material) and the goods contained on/in it. Examples include: pallet carton crate.

Handling units are primarily used for rating freight shipments, although the /rates endpoint will also return parcel rates if the can_ship_parcel flag is true.

 

The handling unit is always the outermost level tendered to the carrier.

For example, when boxes are shrink-wrapped on a pallet, the handling unit is the pallet. When boxes are tendered loose, i.e. not unitized, the handling unit is the carton.

Paraphrased from: GS1 Bill of Lading Guidelines

Attribute
Type
Description

type

String

required
Use value handling_unit

quantity

integer

The number of handling units with these attributes.

Default: 1

handling_unit_type

string

required

Handling unit types:
pallet carton box crate bag

length

number (inches)

required

Limited to one decimal place.

width

number (inches)

required

Limited to one decimal place.

height

number (inches)

required

Limited to one decimal place.

weight

number (pounds)

required
Limited to one decimal place.

value

integer

required

The total value of the contents in US Dollars, rounded to the nearest whole dollar.

freight_class

string

NMFC freight class codes:
50 55 60 65 70 77.5 85 92.5 100 110 125 150 175 200 250 300 400 500

nmfc

string

The National Motor Freight Classification code.

Default value will be calculated based on density (This can affect rating accuracy).

description

string

A description of the handling unit's contents. Typically this should be the name of the NMFC commodity, but can also be a more generic description. This attribute will be printed on the Bill of Lading (BOL).

package_type

string

required for pallets

Describes the type of packages contained in or on the handling unit.

The package types are:
carton box crate bag

package_quantity

integer

required for pallets

The number of packages contained in or on the handling unit. No mix or matching allowed.

product_sku

string

Only use this field if you have integrated with our Product Service

optimize_packing

boolean

If true, we will attempt to palletize prior to rating.

Default: false

Example Handling Unit

{
 "type": "handling_unit",
 "quantity": 1,
 "handling_unit_type":"pallet",
 "length":40,
 "width":48,
 "height":48,
 "weight":500,
 "value": 1250,
 "freight_class":"77.5",
 "nmfc":"70500.03",
 "description":"Flooring NOI, in Boxes",
 "package_type":"box",
 "package_quantity":20
}
 
 
Suggest Edits

Insurance Object

 

The insurance object is used to define whether insurance should be included at the time of shipment booking. By default, insurance is not included when a shipment is booked.

When requested, the following rates will be applied:

Small Parcel Insurance charges: 1% or $3 of stated value, whichever is higher
LTL insurance charges: 1% or $30 of stated value, whichever is higher

Attribute
Type
Description

insurance

Object

{"active" : true} will include insurance.

Suggest Edits

Create a Label

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/id/labels
curl -XPOST 'https://sandbox.shiphawk.com/api/v4/shipments/shp_x4xevmdN/labels' \
	-H 'Content-Type: application/json'\
	-H 'X-Api-Key: YOUR_API_KEY'\
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "url": "https://assets.shiphawk.com/uploads/package_labels_combined_abe6b2df3f10a6ff167d.pdf",
}

Body Params

label_format
string

This specifies which format the label will be generated as. Valid values are 'ZPL' or 'PDF'

 
Suggest Edits

Return a Shipment's Label URLs

Return a shipment's packages label hrefs.

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/id/labels
curl -XGET 'https://sandbox.shiphawk.com/api/v4/shipments/shp_x4xevmdN/labels' \
	-H 'Content-Type: application/json'\
	-H 'X-Api-Key: YOUR_API_KEY'\
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "url": "https://assets.shiphawk.com/uploads/package_labels_combined_abe6b2df3f10a6ff167d.pdf",
}

Query Params

label_format
string
 
Suggest Edits

Notes Object

A note is a body of text that can be associated with Shipment. These notes can contain descriptions for how to handle the shipment or other miscellaneous instructions. A note may also have a tag for easy searching.

 

Notes

Attribute
Type
Description

body

string

Contents of the note

tag

string

Tag for the note

Suggest Edits

Create a New Note

Create a customer note for a shipment.

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/id/notes
curl -X POST 'https://sandbox.shiphawk.com/api/v4/shipments/sh_PJTRcatk/notes' \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR_API_KEY' \
   -d '{ "body": "YOUR_NOTE", "tag": "YOUR_TAG" }'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
	"body": "my note",
  "tag": "my tag"
}

Body Params

body
string
required

Body of the note

tag
string

Tag for the note

 
Suggest Edits

Retrieve Note for a Shipment

Retrieve a single shipment note with the shipment_id.

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/shipment_id/notes/note_id
curl -XGET 'https://sandbox.shiphawk.com/api/v4/shipments/shp_x4xevmdN/notes/not_9NNpS29B' \
	-H 'Content-Type: application/json'\
	-H 'X-Api-Key: YOUR_API_KEY'\
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "body": "my note",
  "tag": "my tag"
}
 
Suggest Edits

Update a Note

Edit an existing note.

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/shipment_id/notes/note_id
curl -X POST 'https://sandbox.shiphawk.com/api/v4/shipments/sh_PJTRcatk/notes/not_tngz4S6J' \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR_API_KEY' \
   -d '{ "body": "Note body", "tag": "Note tag" }'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
	"body": "my note",
  "tag": "my tag"
}

Body Params

body
string

Body of the note

tag
string

Tag for the note

 
Suggest Edits

Retrieve a List of Notes for the Shipment

Retrieve the customer notes for a shipment.

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/shipment_id/notes
curl -XGET 'https://sandbox.shiphawk.com/api/v4/shipments/shp_x4xevmdN/notes' \
	-H 'Content-Type: application/json'\
	-H 'X-Api-Key: YOUR_API_KEY'\
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "id": "note_sNceKj2n",
    "body": "My note",
    "tag": "My tag",
    "created_at": "2016-01-17T04:45:23Z"
  }
]
 
Suggest Edits

Delete a Note

Delete a single note from a shipment.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/shipments/shipment_id/notes/note_id
curl -X DELETE 'https://sandbox.shiphawk.com/api/v4/shipments/shp_3hz66jkB/notes/not_0Wjh9Mra' \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR_API_KEY'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     204 No Content
{
	"status": "204"
}
 
Suggest Edits

Order Object

An order represents a Customer's purchase of one or more products from a Retailer. An order is typically created at checkout and contains all pertinent details to fulfill the Customer's purchase.

 
Attribute
Type
Description

id

string

order_number

string

required

source_system

string

Optional

Source system (e.g. "Shopify" / "Magento")

source_system_id

string

Optional

source

string

Optional

Source represents where the order came from. It can be as simple as "API" or "Manual" or "John Smith" as a way to tag how this order was triggered.

source_system_processed_at

DateTime

Optional

origin_address

hash

Optional
Address

destination_address

hash

Optional
Address

order_line_items

array

total_price

float

Optional

shipping_price

float

Optional

tax_price

float

Optional

items_price

float

Optional

status

string

required
[new],
[partially_shipped] ,
[shipped] ,
[delivered] ,
[cancelled]

requested_shipping_details

string

Optional

requested_rate_id

string

Optional

proposed_shipments

array

The shipments recommended by ShipHawk or dictated by Shipping Policies for the given order.

Proposed shipments are only created if there is enough information to get rates (origin/dest. zips and at least one valid item_type)

Suggest Edits

Order Line Item Object

An order line item represents the item or product that is intended for purchase by a Customer. Customers may have one or many order line items for each order.

 
Attribute
Type
Description

id

string

source_system_id

string

The source_system unique identifier

Optional

name

string

The friendly name of the order line item.

Usually Required Not required when SKU Object is present.

sku

string

Usually Required Not required when name is present.

SKU Object

quantity

number

The number of this specific order line item contained in the order.

Empty assumes a value of "1"

value

number

The dollar value of the item

Empty assumes a value of "$0.00"

Optional

length

number

Optional

width

number

Optional

height

number

Optional

weight

number

Optional

item_type

string

Can be one of the following values:

parcel handling_unit unpacked

Optional

unpacked_item_type_id

integer

handling_unit_type

string

This field is only necessary if the item_type is handling_unit.

Can be any of the values outline in Handling Unit Object

origin_address

hash

If specified, this overrides all other origin addresses associated with the order.

Optional
Address

hs_code

string

Order Example

{
  "id" : "ordi_hnnthm8S",
  "source_system_id" : "1234",
  "name" : "Dakine Leash",
  "sku" : "sku_leash7",
  "quantity" : "1",
  "price" : "10.0",
  "length" : "10.0",
  "width" : "10.0",
  "height" : "10.0",
  "weight" : "0.0",
  "item_type" : "parcel",
  "unpacked_item_type_id" : 123,
  "handling_unit_type" : null,
  "hs_code" : null,
  "origin_address": null
}
Suggest Edits

Create an Order

Create a new order.

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders
curl -X POST https://sandbox.shiphawk.com/api/v4/orders \
  -H 'Host: sandbox.shiphawk.com' \
  -H 'X-Api-Key: [Your-Api-Key]' \
  -d '
{
    "order_number": "ORD10100111",
    "source_system": "ShipHawk eComm",
    "source_system_id": "SH123",
    "source": "Proprietary",
    "source_system_processed_at": "2016-03-01",
    "origin_address": {
      "name": "Mike Richardson",
      "company": "ShipHawk",
      "street1": "1234 Main St.",
      "city": "Virginia Beach",
      "state": "VA",
      "zip": "23454",
	   	"phone_number":"805-335-2432",
      "email":"mikel@shiphawk.com"
    },
    "destination_address": {
      "name": "George Chapman",
      "company": "Hawk Apps",
      "street1": "1234 Main St.",
      "city": "Ventura",
      "state": "California",
      "zip": "93001",
      "phone_number":"805-770-1642",
      "email":"george@shiphawk.com"
    },
    "order_line_items": [{
      "source_system_id": "SH123",
      "name": "",
      "sku": "1234",
      "quantity": 1,
      "value": 251.00,
      "length": 11.0,
      "width": 11.0,
      "height": 11.0,
      "weight": 15.0,
      "item_type": "parcel"
    }],
    "total_price": 1000,
    "shipping_price": 800,
    "tax_price": 50,
    "items_price": 150,
    "status": "",
    "requested_shipping_details": "FedEx Ground (3-5 Day Service)",  
    "requested_rate_id": "01004c4c-da3c-48ff-b2e7-2f44389077e8"
    }'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
	"id": "ord_a9Q11tYQ",
  "order_number": "ORD10100111",
	"source_system": "ShipHawk eComm",
	"source_system_id": "SH123",
	"source": "Proprietary",
	"source_system_processed_at": "2016-03-01",
	"origin_address": {
		"name": "Mike Richardson",
		"company": "ShipHawk",
		"street1": "1234 Main St.",
		"city": "Virginia Beach",
		"state": "VA",
		"zip": "23454",
		"phone_number":"805-335-2432",
		"email":"mikel@shiphawk.com"
	},
	"destination_address": {
		"name": "George Chapman",
		"company": "Hawk Apps",
		"street1": "1234 Main St.",
		"city": "Ventura",
		"state": "California",
		"zip": "93001",
		"phone_number":"805-770-1642",
		"email":"george@shiphawk.com"
	},
	"order_line_items": [{
		"source_system_id": "SH123",
		"name": "",
		"sku": "1234",
		"quantity": 1,
		"value": 251.00,
		"length": 11.0,
		"width": 11.0,
		"height": 11.0,
		"weight": 15.0,
		"item_type": "parcel"
	}],
	"total_price": 1000,
	"shipping_price": 800,
	"tax_price": 50,
	"items_price": 150,
	"status": "",
	"requested_shipping_details": "FedEx Ground (3-5 Day Service)",
	"requested_rate_id": "01004c4c-da3c-48ff-b2e7-2f44389077e8"
}

Body Params

order_number
string

An order number

source_system
string

Source system (e.g. "Shopify" / "Magento")

source_system_id
string

Source system ID

source_system_processed_at
date

Time order was processed from source system

source
string

Source represents where the order came from. It can be as simple as "API" or "Manual" or "John Smith" as a way to tag how this order was triggered.

origin_address
object

Origin address

 
destination_address
object

Destination address

 
order_line_items
array

List of order line items

total_price
double

Total price

shipping_price
double

Shipping price (static shipping price set by you if not calculated by ShipHawk)

tax_price
double

Tax price

items_price
double

Items price

status
string

Status of order

requested_shipping_details
string

Requested shipping details

requested_rate_id
string

The rate ID to use for this order

 
Suggest Edits

Update an Order

Update an existing Order

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/id
curl -X POST https://sandbox.shiphawk.com/api/v4/orders \
  -H 'Host: sandbox.shiphawk.com' \
  -H 'X-Api-Key: [Your-Api-Key]' \
  -d '{
   		  "id": "ord_a9Q11tYQ",
        "order_number": "ORD10001",
    		"source_system": "ShipHawk eComm",
    		"source_system_id": "SH123",
    		"source": "Magento",
    		"source_system_processed_at": "2016-03-01",
        "origin_address": {
            "name": "Mike Richardson",
            "company": "ShipHawk",
            "street1": "1234 Main St.",
            "city": "Virginia Beach",
            "state": "VA",
            "zip": "23454"
        },
        "destination_address": {
            "name": "George Chapman",
            "company": "Hawk Apps",
            "street1": "1234 Main St.",
            "city": "Ventura",
            "state": "CA",
            "zip": "93001"
        },
        "order_line_items": [{
            "source_system_id": "SH123",
            "name": "Bread Box",
            "sku": "BB123-1",
            "quantity": 1,
            "price": 10.00,
            "length": 10.0,
            "width": 10.0,
            "height": 10.0,
            "weight": 10.0,
            "item_type": "parcel"
        	}, {
            "source_system_id": "SH123",
            "name": "High Quality Knife",
            "sku": "HGK1231",
            "quantity": 1,
            "price": 10.00,
            "length": 10.0,
            "width": 10.0,
            "height": 10.0,
            "weight": 10.0,
            "item_type": "handling_unit",
            "unpacked_item_type_id": 456,
            "handling_unit_type": "box"
        	}],
        "total_price": 1000,
        "shipping_price": 800,
        "tax_price": 50,
        "items_price": 150,
        "status": "new",
        "requested_shipping_details": "FedEx Ground (3-5 Day Service)"
    }'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
   		  "id": "ord_a9Q11tYQ",
        "order_number": "ORD10001",
    		"source_system": "ShipHawk eComm",
    		"source_system_id": "SH123",
    		"source": "Magento",
    		"source_system_processed_at": "2016-03-01",
        "origin_address": {
            "name": "Mike Richardson",
            "company": "ShipHawk",
            "street1": "1234 Main St.",
            "city": "Virginia Beach",
            "state": "VA",
            "zip": "23454"
        },
        "destination_address": {
            "name": "George Chapman",
            "company": "Hawk Apps",
            "street1": "1234 Main St.",
            "city": "Ventura",
            "state": "CA",
            "zip": "93001"
        },
        "order_line_items": [{
            "source_system_id": "SH123",
            "name": "Bread Box",
            "sku": "BB123-1",
            "quantity": 1,
            "price": 10.00,
            "length": 10.0,
            "width": 10.0,
            "height": 10.0,
            "weight": 10.0,
            "item_type": "parcel"
        	}, {
            "source_system_id": "SH123",
            "name": "High Quality Knife",
            "sku": "HGK1231",
            "quantity": 1,
            "price": 10.00,
            "length": 10.0,
            "width": 10.0,
            "height": 10.0,
            "weight": 10.0,
            "item_type": "handling_unit",
            "unpacked_item_type_id": 456,
            "handling_unit_type": "box"
        	}],
        "total_price": 1000,
        "shipping_price": 800,
        "tax_price": 50,
        "items_price": 150,
        "status": "new",
        "requested_shipping_details": "FedEx Ground (3-5 Day Service)"
    }

Path Params

id
string
required

Body Params

order_number
string

Order number

source_system
string

Source system (e.g. "Shopify" / "Magento")

source_system_id
string

Source system ID

source_system_processed_at
string

Time order was processed from source system

source
string

Source represents where the order came from. It can be as simple as "API" or "Manual" or "John Smith" as a way to tag how this order was triggered.

origin_address
object

Origin address

 
destination_address
object

Destination Address

 
order_line_items
array

Order line items

total_price
double

Total price

shipping_price
double

Shipping price

tax_price
double

Tax price

items_price
double

Items price

status
string

Status

requested_shipping_details
string

Requested shipping details (e.g. "FedEx Ground")

 
Suggest Edits

Cancel an Order

Update an existing Order

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/id
curl -X POST https://sandbox.shiphawk.com/api/v4/orders \
  -H 'Host: sandbox.shiphawk.com' \
  -H 'X-Api-Key: [Your-Api-Key]' \
  -d '{
   		  "id": "ord_a9Q11tYQ",
        "status": "cancelled"
    }'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
   		  "id": "ord_a9Q11tYQ",
        "order_number": "ORD10001",
    		"source_system": "ShipHawk eComm",
    		"source_system_id": "SH123",
    		"source": "Magento",
    		"source_system_processed_at": "2016-03-01",
        "origin_address": {
            "name": "Mike Richardson",
            "company": "ShipHawk",
            "street1": "1234 Main St.",
            "city": "Virginia Beach",
            "state": "VA",
            "zip": "23454"
        },
        "destination_address": {
            "name": "George Chapman",
            "company": "Hawk Apps",
            "street1": "1234 Main St.",
            "city": "Ventura",
            "state": "CA",
            "zip": "93001"
        },
        "order_line_items": [{
            "source_system_id": "SH123",
            "name": "Bread Box",
            "sku": "BB123-1",
            "quantity": 1,
            "price": 10.00,
            "length": 10.0,
            "width": 10.0,
            "height": 10.0,
            "weight": 10.0,
            "item_type": "parcel"
        	}, {
            "source_system_id": "SH123",
            "name": "High Quality Knife",
            "sku": "HGK1231",
            "quantity": 1,
            "price": 10.00,
            "length": 10.0,
            "width": 10.0,
            "height": 10.0,
            "weight": 10.0,
            "item_type": "handling_unit",
            "unpacked_item_type_id": 456,
            "handling_unit_type": "box"
        	}],
        "total_price": 1000,
        "shipping_price": 800,
        "tax_price": 50,
        "items_price": 150,
        "status": "cancelled",
        "requested_shipping_details": "FedEx Ground (3-5 Day Service)"
    }

Path Params

id
string
required

Body Params

status
string

Status

 
Suggest Edits

Retrieve an Order

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/orders/id
curl -X GET -H "X-Api-Key: [Your-Api-Key]" "https://sandbox.shiphawk.com/api/v4/orders/ord_VvnbP1hJ"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "ord_a9Q11tYQ",
  "order_number": "9999",
  "source_system": "",
  "source_system_id": "",
  "source": "",
  "shipments": [],
  "source_system_processed_at": null,
  "origin_address": {
    "id": "oadr_ZhXjxGqG",
    "name": "Parcel Origin",
    "company": "Parcel Origin Company",
    "street1": "123 Small Parcel Circle",
    "street2": "Apt 5",
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "country": "US",
    "phone_number": "5555551212",
    "email": "parcel_origin@test.com"
  },
  "destination_address": {
    "id": "oadr_Ds2cTF6v",
    "name": "Parcel Destination",
    "company": "Parcel Destination Company",
    "street1": "555 Small Parcel Delivered",
    "street2": "Suite 8",
    "city": "Santa Barbara",
    "state": "CA",
    "zip": "93015",
    "country": "US",
    "phone_number": "8055557777",
    "email": "parcel_destination@email.com"
  },
  "total_price": 1000,
  "shipping_price": 800,
  "tax_price": 50,
  "items_price": 150,
  "order_line_items": [
    {
      "id": "ordi_sBzZ4RKn",
      "source_system_id": "",
      "name": "test name",
      "sku": "test sku",
      "quantity": 1,
      "price": 10,
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 0,
      "item_type": "parcel",
      "unpacked_item_type_id": 123,
      "handling_unit_type": "handling unit type",
      "hs_code": "hs code"
    },
    {
      "id": "ordi_tnGNHPE1",
      "source_system_id": "",
      "name": "test name",
      "sku": "test sku",
      "quantity": 1,
      "price": 10,
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 10,
      "item_type": "parcel",
      "unpacked_item_type_id": 456,
      "handling_unit_type": "handling unit type",
      "hs_code": "hs code"
    }
  ],
  "requested_shipping_details": "",
  "status": "new",
  "proposed_shipments": [],
  "cancelled_at": null,
  "created_at": "2016-05-13T20:02:54Z",
  "updated_at": "2016-05-13T20:02:54Z"
}

Path Params

id
string
required

An order id

 
Suggest Edits

List all Orders

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/orders/
curl -X GET -H "X-Api-Key: [Your-Api-Key]" 
"https://sandbox.shiphawk.com/api/v4/orders/"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "ord_a9Q11tYQ",
  "order_number": "9999",
  "source_system": "",
  "source_system_id": "",
  "source": "",
  "shipments": [],
  "source_system_processed_at": null,
  "origin_address": {
    "id": "oadr_ZhXjxGqG",
    "name": "Parcel Origin",
    "company": "Parcel Origin Company",
    "street1": "123 Small Parcel Circle",
    "street2": "Apt 5",
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "country": "US",
    "phone_number": "5555551212",
    "email": "parcel_origin@test.com"
  },
  "destination_address": {
    "id": "oadr_Ds2cTF6v",
    "name": "Parcel Destination",
    "company": "Parcel Destination Company",
    "street1": "555 Small Parcel Delivered",
    "street2": "Suite 8",
    "city": "Santa Barbara",
    "state": "CA",
    "zip": "93015",
    "country": "US",
    "phone_number": "8055557777",
    "email": "parcel_destination@email.com"
  },
  "total_price": 1000,
  "shipping_price": 800,
  "tax_price": 50,
  "items_price": 150,
  "order_line_items": [
    {
      "id": "ordi_sBzZ4RKn",
      "source_system_id": "",
      "name": "test name",
      "sku": "test sku",
      "quantity": 1,
      "price": 10,
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 0,
      "item_type": "parcel",
      "unpacked_item_type_id": 123,
      "handling_unit_type": "handling unit type",
      "hs_code": "hs code"
    },
    {
      "id": "ordi_tnGNHPE1",
      "source_system_id": "",
      "name": "test name",
      "sku": "test sku",
      "quantity": 1,
      "price": 10,
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 10,
      "item_type": "parcel",
      "unpacked_item_type_id": 456,
      "handling_unit_type": "handling unit type",
      "hs_code": "hs code"
    }
  ],
  "requested_shipping_details": "",
  "status": "new",
  "proposed_shipments": [],
  "cancelled_at": null,
  "created_at": "2016-05-13T20:02:54Z",
  "updated_at": "2016-05-13T20:02:54Z"
},
{
  "id": "ord_a9Q11tPW",
  "order_number": "10000",
  "source_system": "",
  "source_system_id": "",
  "source": "",
  "shipments": [],
  "source_system_processed_at": null,
  "origin_address": {
    "id": "oadr_ZhXjxGqG",
    "name": "Parcel Origin",
    "company": "Parcel Origin Company",
    "street1": "123 Small Parcel Circle",
    "street2": "Apt 5",
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "country": "US",
    "phone_number": "5555551212",
    "email": "parcel_origin@test.com"
  },
  "destination_address": {
    "id": "oadr_Ds2cTF6v",
    "name": "Parcel Destination",
    "company": "Parcel Destination Company",
    "street1": "555 Small Parcel Delivered",
    "street2": "Suite 8",
    "city": "Santa Barbara",
    "state": "CA",
    "zip": "93015",
    "country": "US",
    "phone_number": "8055557777",
    "email": "parcel_destination@email.com"
  },
  "total_price": 1000,
  "shipping_price": 800,
  "tax_price": 50,
  "items_price": 150,
  "order_line_items": [
    {
      "id": "ordi_sBzZ4RKn",
      "source_system_id": "",
      "name": "test name",
      "sku": "test sku",
      "quantity": 1,
      "price": 10,
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 0,
      "item_type": "parcel",
      "unpacked_item_type_id": 123,
      "handling_unit_type": "handling unit type",
      "hs_code": "hs code"
    },
    {
      "id": "ordi_tnGNHPE1",
      "source_system_id": "",
      "name": "test name",
      "sku": "test sku",
      "quantity": 1,
      "price": 10,
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 10,
      "item_type": "parcel",
      "unpacked_item_type_id": 456,
      "handling_unit_type": "handling unit type",
      "hs_code": "hs code"
    }
  ],
  "requested_shipping_details": "",
  "status": "new",
  "proposed_shipments": [],
  "cancelled_at": null,
  "created_at": "2016-05-13T20:02:54Z",
  "updated_at": "2016-05-13T20:02:54Z"
}
 
Suggest Edits

Parcel Object

A parcel represents a box or other packed item that can be shipped via USPS, FedEx, UPS, or other regional couriers. It must be under 150 lbs in weight and 165 inches in length plus girth.

 

Parcel weights are in ounces (oz.)

Unlike handling units or unpacked items, parcel shipment weights are in ounces instead of lbs. This allows for more accurate rating for very small items such as letters and envelopes.

Attribute
Type
Description

length

number (inches)

required

Limited to one decimal place.

width

number (inches)

required

Limited to one decimal place.

height

number (inches)

required

Limited to one decimal place.

weight

number (ounces)

required

value

integer (US dollars)

required

product_sku

string

type

string

Default: parcel

Example Parcel

{
 "type": "parcel", 
 "length": 6,
 "width":  4,
 "height": 5,
 "weight": 480.0,
 "value":  65,
}
Suggest Edits

SKU Object

A SKU is used by retailers to identify distinct items or products for sale. A SKU is represented by a unique code consisting of letters and numbers. The SKU Object contains top-level product information that correspond to your unique product identifiers within your eCommerce Platform (Shopify, Magento, etc.) or ERP. SKUs can contain many shippable items which are represented by the Item Object.

 
Attribute
Type
Description

sku

string

Required

Product SKU

name

string

Product name

description

string

Product description

image_url

string

Hyperlink to the product image

packing_code

string

Proprietary packing code for a product (not required).

price

float

Unit price of product

valid_for_rating

boolean

true when all items on the SKU are valid for rating

default: false

items

array of objects

Array of Item Objects

addresses

array of objects

Array of Address Objects

units_per_sku

integer

If you have a sku that represents a quantity and you sell the sku by increments of that quantity.

Example:
Sku ABC is 25lb of X.
You sell 50lb of X
and want to send us quantity 50 instead of quantity 2

In this example 25 would be the 'units_per_sku'

aggregate_weight

boolean

Use for fast LTL rating
default: false

Suggest Edits

SKU Item Object

A SKU can have multiple SKU Items. Each item represents a shippable unit for that particular SKU. For example, SKU "452BBDB" is a Server that ships in two (2) boxes. Each box can be shipped as a parcel; therefore, the SKU would have two (2) SKU Items.

 
Attribute
Type
Description

length

float

Item length in inches

width

float

Item width in inches

height

float

Item height in inches

weight

float

required for rating
Item weight in pounds

quantity

integer

required for rating
How many

item_type

string

required for rating
Must be "parcel", "handling_unit", or "unpacked"

unpacked_item_type_id

string

Required when item_type is "unpacked"

handling_unit_type

string

Must be "pallet", "carton", "box", "crate", or "bag"

package_type

string

If item_type is "handling_unit" and handling_unit_type is "pallet", package_type must be "carton", "crate", "box", or "bag"

package_quantity

integer

Required if item_type is "handling_unit" and handling_unit_type is "pallet"

requires_crating

boolean

true if the item requires crating

freight_class

string

If item_type is "handling_unit" then freight class must be one of 50, 55, 60, 65, 70, 77.5,85,92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, or 500.

nmfc

string

The National Motor Freight Classification code (If provided, ensures more accurate rating).

can_ship_parcel

boolean

Rating will also return parcel rates if the can_ship_parcel flag is true and the item_type is a "handling_unit"

optimize_packing

boolean

If true, we will attempt to palletize prior to rating.

Default: false

harmonized_code

string

When there is only one known harmonized_code

country_of_manufacture

string

Optional
Should be a 2 character ISO country code

Suggest Edits

Create a SKU

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/skus/

curl -X POST https://sandbox.shiphawk.com/api/v4/skus \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR-API-KEY' \
   -d '{ 
   "sku": "my_product_sku", 
   "name": "High Quality Product",
   "description": "A very nice product", 
   "image_url": "http://onthewingphotography.com/wings/wp-content/uploads/2014/09/red-tailed-hawk-close-up-mia-mcpherson-2192.jpg",
   "packing_code": "some packing code", 
   "price": 19.99,
   "items": [
   		{ "quantity": 1,
				"length": 1.2, 
       	"width": 2.3, 
       	"height": 4.1, 
       	"weight": 4, 
       	"item_type": "parcel" 
      },
      {
        "quantity": 1,
	      "length": 5.3, 
  	    "width": 1.5, 
    	  "height": 4.2, 
      	"weight": 6, 
      	"item_type": "parcel"
      }  
   ],
   "address_ids": ["adr_123456", "adr_654321"]
   }'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
  "sku": "my_product_sku",
  "name": "High Quality Product",
  "description": "A very nice product",
  "image_url": "http://onthewingphotography.com/wings/wp-content/uploads/2014/09/red-tailed-hawk-close-up-mia-mcpherson-2192.jpg",
  "packing_code": "some packing code",
  "price": 19.99,
  "valid_for_rating": true,
  "items": [
    {
      "length": 1.2,
      "width": 2.3,
      "height": 4.1,
      "weight": 4,
      "unpacked_item_type_id": null,
      "item_type": "parcel",
      "handling_unit_type": null,
      "package_type": null,
      "package_quantity": null,
      "requires_crating": false,
      "quantity": 1,
      "freight_class": null,
      "nmfc": null,
      "can_ship_parcel": false,
      "optimize_packing": false,
      "harmonized_code": null
    },
    {
      "length": 5.3,
      "width": 1.5,
      "height": 4.2,
      "weight": 6,
      "unpacked_item_type_id": null,
      "item_type": "parcel",
      "handling_unit_type": null,
      "package_type": null,
      "package_quantity": null,
      "requires_crating": false,
      "quantity": 1,
      "freight_class": null,
      "nmfc": null,
      "can_ship_parcel": false,
      "optimize_packing": false,
      "harmonized_code": null
    }
  ],
  "addresses": [
    {
      "id": "adr_123456",
      "street1": "23 Sunset Street",
      "street2": null,
      "city": "Houston",
      "state": "TX",
      "zip": "77005",
      "country": "US",
      "is_warehouse": false,
      "code": "test_sku-123"
    },
    {
      "id": "adr_654321",
      "street1": "34 Fish Avenue",
      "street2": null,
      "city": "Helena",
      "state": "AR",
      "zip": "72342",
      "country": "US",
      "is_warehouse": false,
      "code": "test_sku-789"
    }
  ]
}

Body Params

sku
string
required

SKU of the product

name
string

Commonly used name for product

description
string

Additional information about the product

image_url
string

Static URL to an image of the product

packing_code
string

Proprietary packing code assigned to a product

price
double

The unit price of the product as a decimal

address_ids
array of strings

An array of ids that already exist on Addresses

items
array

An array of new Items with parameters

units_per_sku
int32
aggregate_weight
boolean

Set to True if using units_per_sku or to enable fastest LTL rates

 
Suggest Edits

Update a SKU

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/skus/sku

curl -X POST https://sandbox.shiphawk.com/api/v4/skus/my_product_sku \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR-API-KEY' \
   -d '{ 
   "sku": "my_product_sku", 
   "name": "High Quality Product",
   "description": "A very nice product", 
   "image_url": "http://onthewingphotography.com/wings/wp-content/uploads/2014/09/red-tailed-hawk-close-up-mia-mcpherson-2192.jpg",
   "packing_code": "some packing code", 
   "price": 19.99,
   "items": [
   		{ "quantity": 1,
				"length": 1.2, 
       	"width": 2.3, 
       	"height": 4.1, 
       	"weight": 4, 
       	"item_type": "parcel" 
      },
      {
        "quantity": 1,
	      "length": 5.3, 
  	    "width": 1.5, 
    	  "height": 4.2, 
      	"weight": 6, 
      	"item_type": "parcel"
      }  
   ],
   "address_codes": ["adr_H823HB32", "adr_H1HCF5aC"]
   }'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
  "sku": "my_product_sku",
  "name": "High Quality Product",
  "description": "A very nice product",
  "image_url": "http://onthewingphotography.com/wings/wp-content/uploads/2014/09/red-tailed-hawk-close-up-mia-mcpherson-2192.jpg",
  "packing_code": "some packing code",
  "price": 19.99,
  "valid_for_rating": true,
  "items": [
    {
      "length": 1.2,
      "width": 2.3,
      "height": 4.1,
      "weight": 4,
      "unpacked_item_type_id": null,
      "item_type": "parcel",
      "handling_unit_type": null,
      "package_type": null,
      "package_quantity": null,
      "requires_crating": false,
      "quantity": 1,
      "freight_class": null,
      "nmfc": null,
      "can_ship_parcel": false,
      "optimize_packing": false,
      "harmonized_code": null
    },
    {
      "length": 5.3,
      "width": 1.5,
      "height": 4.2,
      "weight": 6,
      "unpacked_item_type_id": null,
      "item_type": "parcel",
      "handling_unit_type": null,
      "package_type": null,
      "package_quantity": null,
      "requires_crating": false,
      "quantity": 1,
      "freight_class": null,
      "nmfc": null,
      "can_ship_parcel": false,
      "optimize_packing": false,
      "harmonized_code": null
    }
  ],
  "addresses": [
    {
      "id": "adr_H823HB32",
      "street1": "23 Sunset Street",
      "street2": null,
      "city": "Houston",
      "state": "TX",
      "zip": "77005",
      "country": "US",
      "is_warehouse": false,
      "code": "test_sku-123"
    },
    {
      "id": "adr_H1HCF5aC",
      "street1": "34 Fish Avenue",
      "street2": null,
      "city": "Helena",
      "state": "AR",
      "zip": "72342",
      "country": "US",
      "is_warehouse": false,
      "code": "test_sku-789"
    }
  ]
}

Path Params

sku
string
required

SKU of the product

Body Params

name
string

Commonly used name for product

description
string

Additional information about the product

image_url
string

Static URL to an image of the product

packing_code
string

Proprietary packing code assigned to a product

price
double

The unit price of the product as a decimal

items
array

An array of new Items with parameters

address_ids
array of strings

An array of ids for Addresses that already exist

 
Suggest Edits

Retrieve a SKU

Get details on a particular product SKU.

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/skus/sku
curl -X GET -G https://sandbox.shiphawk.com/api/v4/skus/my_product_sku \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR-API-KEY-HERE' 
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "sku": "my_product_sku",
  "name": "High Quality Product",
  "description": "A very nice product",
  "image_url": "http://onthewingphotography.com/wings/wp-content/uploads/2014/09/red-tailed-hawk-close-up-mia-mcpherson-2192.jpg",
  "packing_code": "some packing code",
  "price": 19.99,
  "valid_for_rating": true,
  "items": [
    {
      "length": 1.2,
      "width": 2.3,
      "height": 4.1,
      "weight": 4,
      "unpacked_item_type_id": null,
      "item_type": "parcel",
      "handling_unit_type": null,
      "package_type": null,
      "package_quantity": null,
      "requires_crating": false,
      "quantity": 1,
      "freight_class": null,
      "nmfc": null,
      "can_ship_parcel": false,
      "optimize_packing": false,
      "harmonized_code": null
    },
    {
      "length": 5.3,
      "width": 1.5,
      "height": 4.2,
      "weight": 6,
      "unpacked_item_type_id": null,
      "item_type": "parcel",
      "handling_unit_type": null,
      "package_type": null,
      "package_quantity": null,
      "requires_crating": false,
      "quantity": 1,
      "freight_class": null,
      "nmfc": null,
      "can_ship_parcel": false,
      "optimize_packing": false,
      "harmonized_code": null
    }
  ],
  "addresses": [
    {
      "id": "adr_H823HB32",
      "street1": "23 Sunset Street",
      "street2": null,
      "city": "Houston",
      "state": "TX",
      "zip": "77005",
      "country": "US",
      "is_warehouse": false,
      "code": "test_sku-123"
    },
    {
      "id": "adr_H1HCF5aC",
      "street1": "34 Fish Avenue",
      "street2": null,
      "city": "Helena",
      "state": "AR",
      "zip": "72342",
      "country": "US",
      "is_warehouse": false,
      "code": "test_sku-789"
    }
  ]
}

Path Params

sku
string
required

Provide the SKU of the product to retrieve

 
Suggest Edits

List all SKUs

List all Skus associated with an account.

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/skus/
curl -X GET https://sandbox.shiphawk.com/api/v4/skus \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR-API-KEY-HERE'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "sku": "101",
    "name": "Patio dining set - Boxed",
    "description": "6 piece outdoor table, chairs, and umbrella",
    "image_url": "https://s3-us-west-1.amazonaws.com/shiphawk-external/patio1.jpeg",
    "packing_code": null,
    "price": 0,
    "valid_for_rating": true,
    "items": [
      {
        "length": 20,
        "width": 20,
        "height": 10,
        "weight": 5,
        "unpacked_item_type_id": null,
        "item_type": "handling_unit",
        "handling_unit_type": "box",
        "package_type": null,
        "package_quantity": null,
        "requires_crating": null,
        "quantity": 1,
        "freight_class": "70",
        "nmfc": null,
        "can_ship_parcel": false,
        "optimize_packing": false,
        "harmonized_code": null
      },
      {
        "length": 30,
        "width": 30,
        "height": 40,
        "weight": 4,
        "unpacked_item_type_id": null,
        "item_type": "handling_unit",
        "handling_unit_type": "box",
        "package_type": null,
        "package_quantity": null,
        "requires_crating": null,
        "quantity": 4,
        "freight_class": "85",
        "nmfc": null,
        "can_ship_parcel": false,
        "optimize_packing": false,
        "harmonized_code": null
      },
      {
        "length": 50,
        "width": 50,
        "height": 10,
        "weight": 12,
        "unpacked_item_type_id": null,
        "item_type": "handling_unit",
        "handling_unit_type": "box",
        "package_type": null,
        "package_quantity": null,
        "requires_crating": null,
        "quantity": 1,
        "freight_class": "92.5",
        "nmfc": null,
        "can_ship_parcel": false,
        "optimize_packing": false,
        "harmonized_code": null
      }
    ],
    "addresses": [
      {
      "id": "adr_H823HB32",
      "street1": "23 Sunset Street",
      "street2": null,
      "city": "Houston",
      "state": "TX",
      "zip": "77005",
      "country": "US",
      "is_warehouse": false,
      "code": "test_sku-123"
    },
    {
      "id": "adr_H1HCF5aC",
      "street1": "34 Fish Avenue",
      "street2": null,
      "city": "Helena",
      "state": "AR",
      "zip": "72342",
      "country": "US",
      "is_warehouse": false,
      "code": "test_sku-789"
    }
    ]
  },
  {
    "sku": "102",
    "name": "Patio dining set - Palletized",
    "description": "6 piece outdoor table, chairs, and umbrella",
    "image_url": "https://s3-us-west-1.amazonaws.com/shiphawk-external/patio2.jpeg",
    "packing_code": null,
    "price": 0,
    "valid_for_rating": false,
    "items": [
      {
        "length": 30,
        "width": 30,
        "height": 40,
        "weight": 4,
        "unpacked_item_type_id": null,
        "item_type": "handling_unit",
        "handling_unit_type": "pallet",
        "package_type": "carton",
        "package_quantity": 4,
        "requires_crating": null,
        "quantity": 1,
        "freight_class": "100",
        "nmfc": null,
        "can_ship_parcel": false,
        "optimize_packing": false,
        "harmonized_code": null
      },
      {
        "length": 50,
        "width": 50,
        "height": 10,
        "weight": 12,
        "unpacked_item_type_id": null,
        "item_type": "handling_unit",
        "handling_unit_type": "pallet",
        "package_type": "carton",
        "package_quantity": 1,
        "requires_crating": null,
        "quantity": 4,
        "freight_class": null,
        "nmfc": null,
        "can_ship_parcel": false,
        "optimize_packing": false,
        "harmonized_code": null
      }
    ],
    "addresses": [
      {
      "id": "adr_H1HCF5aC",
      "street1": "34 Fish Avenue",
      "street2": null,
      "city": "Helena",
      "state": "AR",
      "zip": "72342",
      "country": "US",
      "is_warehouse": false,
      "code": "test_sku-789"
    }
    ]
  }
]
 
Suggest Edits

Delete SKUs

Delete a particular product or set of products from your account.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/skus/sku
curl -X DELETE https://sandbox.shiphawk.com/api/v4/skus \
   -H 'Content-Type: application/json' \
   -H 'X-Api-Key: YOUR-API-KEY-HERE' \
   -d '{"sku": ["my_product_sku"]}'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

sku
array of strings
required

Can be a string for a single SKU or an array of strings for mulitple SKUs

 
Suggest Edits

Proposed Shipment Object

A proposed shipment is information describing a shipment that hasn't been created yet. You can use either a Rate or a Proposed Shipment in order to create a new shipment.

 
Attribute
Type
Description

id

string

carrier

string

carrier_code

string

service_level

string

estimated_delivery_date

date

Estimated date of delivery in YYYY-MM-dd format

service_days

number

Estimated number of days required to complete the delivery service.

standardized_service_name

string

Specifies which standardized service is being used for the proposed shipment:

Ground Guaranteed Freight International Economy International Priority Local Delivery Next Day Restricted Ground Room of Choice Same-Day Freight Standard Courier Standard Freight Standard Vehicle Three-Day Threshold Two-Day White Glove

carrier_type

string

Will be one of the following values:
Small Parcel LTL Home Delivery Blanket Wrap Truckload Courier Intermodal Auto Local Delivery Final Mile

is_customer_tariff

boolean

Indicates whether this shipment will be booked using your tariff or ShipHawk's tariff

order_id

string

Public ID of related Order.

total_price

decimal

Sum of all of the prices in the price_details attribute

final_mile

object

price_details

object

A breakdown of the price.

shipping packing insurance accessorials duties taxes

origin_address

object

destination_address

object

origin_accessorials

array of objects

Array of accessorials that can be applied to a shipment:
{
id: string
side: string
price: number
name: string
default: boolean
type: string
}

destination_accessorials

array of objects

Array of accessorials that can be applied to a shipment:
{
id: string
side: string
price: number
name: string
default: boolean
type: string
}

packages

array

Array of hashes representing the packages that were used for rating:
{
length: number
width: number
height: number
weight: number
volume: number
freight_class: string
packing_type: string
package_type: string
materials: array
labors: array
package_items: [{},...]
}

Each element in the package_items array will be a hash representing the items specified in the Rate Request:
{
product_sku: string
product_sku_packing_code: string
item_name: string
description: string
length: number
width: number
height: number
weight: number
volume: number
value: number
unpacked_item_type_id: string
require_crating: boolean
freight_class: string
nmfc: string
hs_code: string
country_of_origin: string
xid: string
order_line_item_id: string
}

ship_date

string

YYYY-MM-DD

policies_applied

array

Array of hashes representing the rating rules applied for rating:
{
id: string
name: string
}

Quote Detail Example

{
 "id": "pshp_qvXjD02V",
 "carrier": "UPS",
 "carrier_code": "ups",
 "service_level": "UPS Ground",
 "estimated_delivery_date": "2016-01-24",
 "service_days": "",
 "carrier_type": "Small Parcel",
 "is_customer_tariff": true,
 "order_id": "ord_ybfcDDx9",
 "total_price": 12.91,
 "final_mile": {
  "price": 0,
  "final_mile_service_name": null,
  "final_mile_service_days": null,
  "using_final_mile_carrier": false,
  "final_mile_carrier": null
 },
"price_details": {
  "shipping": 12.91,
  "packing": 0,
  "insurance": 0,
  "accessorials": 0,
  "duties": 0,
  "taxes": 0
 },
"origin_address": {
  "name": "Mike Richardson",
  "company": "ShipHawk",
  "street1": "1234 Main St.",
  "city": "Virginia Beach",
  "state": "VA",
  "zip": "23454",
  "phone_number":"805-335-2432",
  "email":"mikel@shiphawk.com"
 },
"destination_address": {
  "name": "George Chapman",
  "company": "Hawk Apps",
  "street1": "1234 Main St.",
  "city": "Ventura",
  "state": "California",
  "zip": "93001",
  "phone_number":"805-770-1642",
  "email":"george@shiphawk.com"
 },
"origin_accessorials": [],
"destination_accessorials": [],
"packages": [{
  "length": 8,
  "width": 8,
  "height": 7,
  "weight": 4.1,
  "freight_class": "70",
  "package_items": [{
    "length": 8,
    "width": 8,
    "height": 7,
    "weight": 4.1,
    "value": 65,
    "freight_class": "70",
    "nmfc": null,
    "unpacked_item_type_id": null,
    "product_sku": null,
    "description": "",
    "require_crating": null
   }]
 }], 
 "ship_date": "2016-04-07",
 "policies_applied": [{
 	"id": "rule_BB6ddfyJ",
  "name": "FedEx Rating Rule,
 }]  
}
Suggest Edits

Rate Request Object

Rate Requests are used to get rates for any type of shipment or carrier, including parcel, freight, home delivery, and blanket wrap.

 
Attribute
Type
Description

origin_address

object

required
Address

destination_address

object

required
Address

items

array

required
Parcels,
Handling Units ,
Unpacked Items , and/or product_sku

carrier_filter

array

Strings that specify carriers that will return rates for this request.

carrier_type_filter

array

Strings that specify carrier types that will return rates for this request. Will be one of the following values:

Small Parcel LTL Home Delivery Blanket Wrap Truckload Courier Intermodal Auto Local Delivery Final Mile

rate_filter

string

Specifies how rates should be returned. Will be one of the following filters or blank:
best consumer top_10

standardized_service_filter

string

Specifies which services to return in the rate detail object. Use on of the following filters or leave blank:
Ground Three-Day Two-Day Next Day Restricted Ground International Economy International Priority

Standard Freight Guaranteed Freight
Same-Day Freight

Local Delivery Threshold Room of Choice White Glove

Standard Courier Standard Vehicle

origin_accessorials

object

{
inside_pickup: boolean
liftgate_pickup: boolean
}

Default: all false

destination_accessorials

object

{
inside_delivery: boolean
liftgate_delivery: boolean
notify_prior_delivery: boolean
schedule_appointment_delivery: boolean
}

Default: all false

rates

array

ship_date

string

The date of the shipment in ISO-8601 format (YYYY-MM-DD). Must be today's date or a future date.

Default: tomorrow

display_rate_detail

boolean

When set to true the Rate Details on each Rate will be displayed. Otherwise it will be blank.

Default: false

usps_parcel_select

boolean

When set to true the USPS Parcel Select Ground service rates will be included in the rate request.

Default: false

usps_library_mail

boolean

When set to true the USPS Library Mail service rates will be included in the rate request.

Default: false

usps_media_mail

boolean

When set to true the USPS Media Mail service rates will be included in the rate request.

Default: false

apply_rules

boolean

When set to true the system will apply the Rating Rules that are active on your account.

Default: false

Example Rate Request

{
	"origin_address": {
		"zip": "23454"
	},
	"destination_address": {
		"zip": "93001"
	},
	"items": [{
		"length": 6,
		"width": 4,
		"height": 5,
		"weight": 64.0,
		"value": 65
	}],
	"carrier_filter": ["usps", "fedex"],
	"rate_filter": "",
	"origin_accessorials": {},
	"destination_accessorials": {},
	"ship_date": "2016-01-31",
 	"apply_rules": false
}
Suggest Edits

Rate Object

A rate represents a specific combination of price, carrier, and service level. You get back an array of rates when you send in a rate request. Depending on the items in the rate request, ShipHawk will return rates from hundreds of carriers, compare multiple carrier types (Parcel/LTL/Home Delivery/Blanket Wrap), combine line haul and first/final mile pickup and delivery, and even add required packing.

 

Rates may contain multiple Shipping Details

Sometimes a rate will contain multiple Shipping Details. For example, if you request rates for multiple parcels and book a rate with FedEx or USPS, separate shipments will be created for each parcel (each with its own tracking number).

Another example is if you request rates for a very small unpacked item (like a ring) and a large item (like a sofa). The small unpacked item will most likely be serviced by a parcel carrier and the large item by a LTL/Blanket Wrap carrier.

Attribute
Type
Description

id

string

The unique ID assigned to this rate by ShipHawk

carrier

string

The name of the carrier

carrier_code

string

The code in ShipHawk that represents this carrier

service_name

string

The name of the carrier service for this rate.

service_level

string

Legacy name of the carrier service for this rate.

price

decimal

Total price of all the applicable costs associated with shipping (transport, pickup, packing, delivery, etc.)

est_delivery_date

date_time

Estimated delivery date. This is based on the ship_date passed in through the rate_request (YYYY-MM-DD).

origin_network_location_id

string

The unique ID representing the origin network location assigned to this rate. Only applicable for enterprise accounts. Default response will be null.

destination_network_location_id

string

The unique ID representing the destination network location assigned to this rate. Only applicable for enterprise accounts. Default response will be null.

Example Rate

{
   "id": "rate_bwjvNhtf3NVya2D6VYJCSNcA",
   "carrier": "FedEx",
   "carrier_code": "fedex",
   "service_name": "FedEx Ground",
   "service_level": "FedEx Ground",
   "price": 10.19,
   "est_delivery_date": "2017-01-06",
   "origin_network_location_id": null,
   "destination_network_location_id": null
}
Suggest Edits

Rate Item Object

 
Attribute
Type
Description

type

string

required for rating
Must be "parcel", "handling_unit", or "unpacked"

product_sku

string

Product SKU that represents this item.

*unpacked_item_type_id*

string

Required when type is "unpacked"

handling_unit_type

string

Must be "pallet", "carton", "box", "crate", or "bag"

quantity

integer

required for rating
How many

length

float

Item length in inches

width

float

Item width in inches

height

float

Item height in inches

weight

float

required for rating
Item weight in pounds

item_type of "parcel" requires weight in ounces.

item_type of "handling_unit" or "unpacked" require weight in imperial pounds.

volume_cubic_ft

float

Item cubic volume in (cubic feet)

value

float

Item value (for insurance or declared value purposes) in USD

freight_class

string

If type is "handling_unit" then freight class must be one of 50, 55, 60, 65, 70, 77.5,85,92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, or 500.

package_type

string

If item_type is "handling_unit" and handling_unit_type is "pallet", package_type must be "carton", "crate", "box", or "bag"

package_quantity

integer

Required if item_type is "handling_unit" and handling_unit_type is "pallet"

requires_crating

boolean

true if the item requires crating

description

string

The description to be displayed on the Bill of Lading associated with this shipment. Applicable only for non-parcel shipments

nmfc

string

The National Motor Freight Classification code (If provided, ensures more accurate rating).

can_ship_parcel

boolean

Rating will also return parcel rates if the can_ship_parcel flag is true and the item_type is a "handling_unit"

Only available for enterprise accounts.

optimize_packing

boolean

If true, we will attempt to palletize prior to rating.

Default: false

Only available for enterprise accounts.

harmonized_code

string

When there is only one known harmonized_code

country_of_origin

string

Optional
Should be a 2 character ISO country code

Suggest Edits

Rate Detail Object

A rate detail describes the price breakdown that makes up the price of the Rate.

 
Attribute
Type
Description

pickup_price

number

delivery_price

number

proposed_shipments

array

applied_rules

array

Displays the appropriate Rating Rules
that were applied to this rate.

Example Rate Detail

"rates": [{
		"id": "rate_DEt97dpm90FmEEyaVaY2DtCY",
		"carrier": "Pilot",
		"carrier_code": "pilot",
		"service_name": "Basic",
		"service_level": "Basic",
		"price": 115.54,
		"est_delivery_date": "2017-01-06",
		"origin_network_location_id": null,
		"destination_network_location_id": null,
		"rate_detail": {
			"pickup_price": 0.0,
			"delivery_price": 0.0,
			"proposed_shipments": [{
				"id": null,
				"carrier": "Pilot",
				"carrier_code": "pilot",
				"service_name": "Basic",
				"estimated_delivery_date": "2017-01-06T00:00:00Z",
				"service_days": 5,
				"standardized_service_name": "Threshold",
				"carrier_type": "Home Delivery",
				"is_customer_tariff": false,
				"insurance_type": "third_party",
				"order_id": null,
				"total_price": 115.54,
				"final_mile": {
					"price": 0.0,
					"final_mile_service_name": null,
					"final_mile_service_days": null,
					"using_final_mile_carrier": false,
					"final_mile_carrier": null
				},
				"price_details": {
					"shipping": 115.54,
					"packing": 0.0,
					"insurance": 30.0,
					"accessorials": 0.0,
					"duties": 0.0,
					"taxes": 0.0
				},
				"origin_address": {
					"name": null,
					"company": null,
					"street1": null,
					"street2": null,
					"city": null,
					"state": null,
					"zip": "93105",
					"country": "US",
					"phone_number": null,
					"email": null,
					"is_residential": false,
					"address_type": "commercial"
				},
				"destination_address": {
					"name": null,
					"company": null,
					"street1": null,
					"street2": null,
					"city": null,
					"state": null,
					"zip": "60601",
					"country": "US",
					"phone_number": null,
					"email": null,
					"is_residential": true,
					"address_type": "residential"
				},
				"origin_instructions": null,
				"destination_instructions": null,
				"packages": [{
					"length": 10.0,
					"width": 10.0,
					"height": 10.0,
					"weight": 1.0,
					"volume": 0.58,
					"freight_class": "400",
					"packing_type": "palletized",
					"package_type": "carton",
					"package_quantity": 2,
					"materials": [],
					"labors": [],
					"package_items": [{
						"product_sku": "asdf",
						"product_sku_packing_code": null,
						"item_name": "Handling Unit",
						"description": "wetrwer",
						"length": 10.0,
						"width": 10.0,
						"height": 10.0,
						"weight": 1.0,
						"volume": 0.58,
						"value": 1.0,
						"unpacked_item_type_id": 33695,
						"require_crating": null,
						"freight_class": "400",
						"nmfc": "21323123",
						"hs_code": null,
						"country_of_origin": "US",
						"xid": null,
						"order_line_item_id": null
					}],
					"quantity": 1
				}],
				"ship_date": "2016-12-29",
				"policies_applied": [],
				"fees": {
					"insurance": {
						"active": false
					}
				},
				"include_return_label": null
			}]
		},
		"applied_rules": []
	}
Suggest Edits

Create a New Rate Request

A rate request can be created in the following ways:

  1. Using only a origin and destination zip (within the Address object ) and items, you can create a rate request and receive rates to use to create a shipment.

  2. Using only a origin and destination zip_code (within the Address object ) and items, and origin_accessorials and/or destination_accessorials, you can create a rate request and receive rates with only carriers that support these accessorials.

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/rates/
curl -H "Content-Type: application/json" -X POST -d'{
  "items":[
    {
    	"item_type": "parcel",
      "length": "10",
      "width" : "10",
      "height": "11",
      "weight": "10",
      "value": 100.00
    }
  ],
  "origin_address":{ "zip": "93101"},
  "destination_address":{ "zip": "60060"}
}' 'https://sandbox.shiphawk.com/api/v4/rates?api_key=YOUR_API_KEY'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "rates": [
        {
            "id": "fa0855e8-e87f-484e-a83a-7d4b704389db",
            "carrier": "FedEx",
            "service_level": "Ground",
            "price": 20.23,
            "est_delivery_date": "2016-01-24"
        },
        {
            "id": "8e69660b-ea25-48b7-b6a1-f5ba17cf04b4",
            "carrier": "FedEx",
            "service_level": "Next Day Priority",
            "price": 120.45,
            "est_delivery_date": "2016-01-20"
        },
        {
            "id": "4b2fb47c-e200-4dcb-b100-a8f8426a7fdb",
            "carrier": "FedEx",
            "service_level": "Next Day Standard",
            "price": 111.1,
            "est_delivery_date": "2016-01-20"
        },
        {
            "id": "22ffabf4-0e8a-48d4-bf38-ea4d04073085",
            "carrier": "FedEx",
            "service_level": "2 Day",
            "price": 65.61,
            "est_delivery_date": "2016-01-21"
        },
        {
            "id": "ab252fca-51d9-4b25-b584-a84fd24444ef",
            "carrier": "FedEx",
            "service_level": "Next Day Early",
            "price": 152.96,
            "est_delivery_date": "2016-01-20"
        },
        {
            "id": "c7922813-5dad-4873-a858-68b8daf90a67",
            "carrier": "FedEx",
            "service_level": "3 Day",
            "price": 47.06,
            "est_delivery_date": "2016-01-22"
        }
    ]
}

Body Params

items
array
required

Array of Parcels, Handling Units , and/or Unpacked Items

origin_address
object
required

Address

 
destination_address
object
required

Address

 
origin_accessorials
object
 
destination_accessorials
object
 
standardized_service_filter
string

Used to limit your rate response results to carrier services of a specific service level.

carrier_filter
string

Used to limit your rate response to specific carriers. See carrier endpoints to retrieve a list of carriers for your account.

apply_rules
string
display_rate_detail
boolean

Shows complete details of rate response. Suggested that you set this value to TRUE during testing and/or debugging

ship_date
date

Use this to specify the date you plan on shipping this item. Providing this value will ensure a more accurate estimated delivery date.

 
Suggest Edits

Rating Rules Object

A rating rule allows you to control the "rate" that your Customers see. Use these rules to configure how shipping costs are computed and displayed to the Customer. Rules consist of two components:

  • criteria - the condition used to decide when the rule will be triggered
  • action(s) - decides how a rate will be computed

Example actions include:

  • transparent costs (customers see the actual ship cost)
  • a fixed markup (customers see the actual shipping cost plus a fixed $ markup)
  • a percent markup (customers see the actual shipping cost plus a percent $ markup)
  • a fixed markdown (customers see the actual shipping cost minus a fixed $ markdown)
  • a percent markdown (customers see the actual shipping cost minus a percent $ markdown)
  • a flat rate (customers see a flat rate regardless of actual shipping cost)
  • free rate (a free shipping option is provided)

Virtually every order attribute can be used in the criteria, which gives considerable flexibility for how rating rules can be configured.

 
Attribute
Type
Description

id

string

name

string

Provide a friendly descriptive name for the rating rule.

active

boolean

Indicates whether a rule is currently able to be applied to rate requests.

criteria

array

actions

array

Specifies the action that is to be applied to a particular rate prior to being returned.

Action Object

created_at

date_time

Date rating rule was created

updated_at

date_time

Date rating rule was last modified

Suggest Edits

Create a Rating Rule

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/rating_rules/
curl -X POST 
-H "X-Api-Key: [YOUR-API-KEY]"
-d '{
  "name": "Free Shipping for Orders over $100",
  "criteria": [{
    "field": "order_value",
    "operator": "GREATER_THAN",
    "value": "99.99"
  }],
  "actions": [{    
    "name": "create_table_rate",
    "value": {"shipping_price": 0, "service_name": "Ground", "carrier_name": "Free Shipping"}
  }]
}' "https://sandbox.shiphawk.com/api/v4/rating_rules"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "rule_54PvMvT2",
  "name": "Free Shipping for Orders over $100",
  "active": true,
  "subtype": "pre_rating",
  "criteria": [
    {
      "field": "order_value",
      "operator": "GREATER_THAN",
      "value": 99.99,
      "group": "default"
    }
  ],
  "actions": [
    {
      "name": "create_table_rate",
      "value": {
        "shipping_price": 0,
        "service_name": "Ground",
        "carrier_name": "Free Shipping"
      }
    }
  ],
  "created_at": "2016-06-14T03:18:29Z",
  "updated_at": "2016-06-14T03:18:29Z"
}

Body Params

name
array
required
criteria
array
required
actions
array
required
active
boolean
 
Suggest Edits

Update a Rating Rule

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/rating_rules/id
curl -X POST 
	-H "X-Api-Key: [YOUR-API-KEY]" 
	-d '{
  "name": "R0000001",
  "criteria": [{
    "field": "order_value",
    "operator": "GREATER_THAN",
    "value": "200"
  }],
  "actions": [{    
    "name": "create_table_rate",
    "value": {"shipping_price": 0, "service_name": "Ground", "carrier_name": "Free Shipping"}
  }]
}' "https://sandbox.shiphawk.com/api/v4/rating_rules/rule_P2JB3Bc5"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "rule_P2JB3Bc5",
  "name": "R0000001",
  "active": true,
  "subtype": "pre_rating",
  "criteria": [
    {
      "field": "order_value",
      "operator": "GREATER_THAN",
      "value": 200,
      "group": "default"
    }
  ],
  "actions": [
    {
      "name": "create_table_rate",
      "value": {
        "shipping_price": 0,
        "service_name": "Ground",
        "carrier_name": "Free Shipping"
      }
    }
  ],
  "created_at": "2016-06-14T03:18:29Z",
  "updated_at": "2016-06-14T03:18:29Z"
}

Body Params

name
array
required
criteria
array
required
actions
array
required
active
boolean
 
Suggest Edits

Retrieve a Rating Rule

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/rating_rules/id
curl -X GET 
	-H "X-Api-Key: [YOUR-API-KEY]"
"https://sandbox.shiphawk.com/api/v4/rating_rules/rule_P2JB3Bc5"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "rule_P2JB3Bc5",
  "name": "R0000001",
  "active": true,
  "subtype": "pre_rating",
  "criteria": [
    {
      "field": "order_value",
      "operator": "GREATER_THAN",
      "value": 100,
      "group": "default"
    }
  ],
  "actions": [
    {
      "name": "create_table_rate",
      "value": {
        "shipping_price": 0,
        "service_name": "Ground",
        "carrier_name": "Free Shipping"
      }
    }
  ],
  "created_at": "2016-06-14T03:23:59Z",
  "updated_at": "2016-06-14T03:23:59Z"
}

Path Params

id
string
required
 
Suggest Edits

List all Rating Rules

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/rating_rules/
curl -X GET 
	-H "X-Api-Key: [YOUR-API-KEY]"
"https://sandbox.shiphawk.com/api/v4/rating_rules"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": "rule_P2JB3Bc5",
    "name": "R0000001",
    "active": true,
    "subtype": "pre_rating",
    "criteria": [
      {
        "field": "order_value",
        "operator": "GREATER_THAN",
        "value": 100,
        "group": "default"
      }
    ],
    "actions": [
      {
        "name": "create_table_rate",
        "value": {
          "shipping_price": 0,
          "service_name": "Ground",
          "carrier_name": "Free Shipping"
        }
      }
    ],
    "created_at": "2016-06-14T03:23:59Z",
    "updated_at": "2016-06-14T03:23:59Z"
  },
  {
    "id": "rule_tAJ4Z6Bg",
    "name": "R0000002",
    "active": false,
    "subtype": "pre_rating",
    "criteria": [
      {
        "field": "order_value",
        "operator": "GREATER_THAN",
        "value": 200,
        "group": "default"
      }
    ],
    "actions": [
      {
        "name": "create_table_rate",
        "value": {
          "shipping_price": 0,
          "service_name": "Ground",
          "carrier_name": "Free Shipping"
        }
      }
    ],
    "created_at": "2016-06-14T03:29:37Z",
    "updated_at": "2016-06-14T03:29:37Z"
  }
]
 
Suggest Edits

Delete a Rating Rule

 

Authentication

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/rating_rules/id
curl -X DELETE -H "X-Api-Key: [YOUR-API-KEY]" 
"https://sandbox.shiphawk.com/api/v4/rating_rules/rule_8gRxC8wR"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required
 
Suggest Edits

Criteria Object

Rating rule criteria allow you to apply rule actions based on certain rate request params. Criteria is used to specific which data and under what conditions the rating rule is to be applied.

Specifies the criteria that must be satisfied for this rule to be applied:

  {
    "field": "",
    "operator": "",
    "value": 0.00,
    "group": "default"
  }

where:

field is the order attribute to be tested
operator is how the test be done
value is the data used in the test

 
Attribute
Type
Description

field

string

The order field attribute used in the comparison.

Examples:
sku, length, width, height, weight, value, zipcode

operator

string

EQUAL NOT_EQUAL BETWEEN GREATER_THAN LESS_THAN GREATER_THAN_OR_EQUAL LESS_THAN_OR_EQUAL``equal IN NOT_IN STARTS_WITH ENDS_WITH GLOBAL

value

many

Value takes its Type based on the operator

group

string

Groups allow you to combine criteria using compound logic.

By default:

  • all criteria belong to a default group.
  • all criteria within a group must be matched
  • any groups must match

Example:
((crieria1 AND criteria2) OR (criteria3 AND criteria4))

where criteria1 and criteria2 belong to the same named group and criteria3 and criteria4 belong to a different named group.

Suggest Edits

Action Object

Rating rule actions dictate how you want certain criteria to effect your rate response.

 
Attribute
Type
Description

name

string

The name of the specific action you are inflicting on the criteria specified. Takes values:

Rating Rules can take the following actions:

create_table_rate markup_percentage markdown_percentage markup_flat_amount markdown_flat_amount cheapest_rates_filter best_rate_filter consumer_rates_filter fastest_rates_filter carrier_filter carrier_type_filter standardized_service_filter best_rate_filter

Shipping Policies can only use the following actions:

carrier_filter carrier_type_filter standardized_service_filter best_rate_filter

value

many

The following table describes all values that actions can take along with simple examples.

Name
Value
Example

create_table_rate

hash

[{
"name": "create_table_rate",
"value": {
"carrier_name": "Free",
"service_name": "Ground",
"shipping_price": 0
}]

markup_percentage

number

[{
"name": "markup_percentage",
"value": 10
}]

markdown_percentage

number

[{
"name": "markdown_percentage",
"value": 10
}]

markup_flat_amount

number

[{
"name": "markup_flat_amount",
"value": 10
}]

markup_flat_amount

number

[{
"name": "markdown_flat_amount",
"value": 10
}]

cheapest_rates_filter

number

Value indicates the maximum number of rates to return.

[{
"name": "cheapest_rates_filter",
"value": 5
}]

best_rate_filter

Leave empty

[{
"name": "best_rate_filter",
"value": ""
}]

consumer_rates_filter

Leave empty

[{
"name": "consumer_rates_filter",
"value": ""
}]

fastest_rates_filter

number

[{
"name": "fastest_rates_filter",
"value": 3
}]

carrier_filter

string

[{
"name": "carrier_filter",
"value": "fedex"
}]

carrier_type_filter

string

[{
"name": "carrier_type_filter",
"value": ["Home Delivery"]
}]

Using one or more of the following values:

Small Parcel LTL Home Delivery Blanket Wrap Truckload Courier Intermodal Auto Local Delivery Final Mile

standardized_service_filter

string

[{
"name": "standardized_service_filter",
"value": "Next Day"
}]

Using one of the following values:

Ground Guaranteed Freight International Economy International Priority Local Delivery Next Day Restricted Ground Room of Choice Same-Day Freight Standard Courier Standard Freight Standard Vehicle Three-Day Threshold Two-Day White Glove

Suggest Edits

Shipment Object

 

Third Party Insurance

If you are booking shipments on your own tariff and elect to use third party insurance. You will receive a separate bill from ShipHawk for the cost of this insurance

Rate ID Expiration

Rate requests expire two (2) hours after creation. In the event that your rate request expires, you will not be able to create a shipment from that rate ID. You will need to request a new rate prior to making the POST to shipments.

Attribute
Type
Description

id

string

required

shid

integer

Shiphawk ID

origin_address

object

destination_address

object

carrier

string

service_level

string

total_price

number

Total price of all applicable costs associated with shipping (pickup, packing, delivery etc)

status

string

ordered confirmed scheduled_for_pickup agent_prep ready_for_carrier_pickup delivered in_transit exception cancelled

tracking_number

string

documents

array

final_mile

object

{
carrier: string,
service_level: string,
transit_time: string
}

packages

array

fees

object

{
shipping: number
packing: { active: boolean}
pickup: { active: boolean}
insurance: { active: boolean}
accessorials: number
duty: number
taxes: number
}

Set packing, insurance, or pickup active: true if you would like to include it when booking your shipment.

Active Default: false

dispatch

string

assignee_id

string

origin_network_location_id

string

Only applicable on the Enterprise plan

destination_network_location_id

string

Only applicable on the Enterprise plan

reference_numbers

array

origin_instructions

string

destination_instructions

string

shiphawk_managed

boolean

{
    "id": "shp_rxgm7dZ8",
    "shid": 12345,
    "status": "ordered",
    "origin_address": {
        "id": "badr_zpMW9XYs",
        "name": "Parcel Origin",
        "company": "Parcel Origin Company",
        "street1": "123 Small Parcel Circle",
        "street2": "Apt 5",
        "city": "Chicago",
        "state": "CA",
        "zip": "93101",
        "country": "US",
        "phone_number": "5555551212",
        "email": "parcel_origin@test.com",
        "is_residential": false,
        "address_type": "commercial",
        "validated": null,
        "code": null
    },
    "destination_address": {
        "id": "badr_zcPfK8aG",
        "name": "Parcel Destination",
        "company": "Parcel Destination Company",
        "street1": "555 Small Parcel Delivered",
        "street2": "Suite 8",
        "city": "Santa Barbara",
        "state": "IL",
        "zip": "60060",
        "country": "US",
        "phone_number": "8055557777",
        "email": "parcel_destination@email.com",
        "is_residential": false,
        "address_type": "commercial",
        "validated": null,
        "code": null
    },
    "carrier": "FedEx",
    "service_level": "Ground",
    "total_price": 17.53,
    "tracking_number": null,
    "documents": null,
    "price_details": {
        "shipping": 17.53,
        "packing": 0,
        "insurance": 0,
        "pickup": 0,
        "delivery": 0,
        "accessorials": 0,
        "duty": null,
        "taxes": null
    },
    "dispatch": null,
    "final_mile": null,
    "packages": [
        {
            "id": null,
            "length": 10,
            "height": 11,
            "width": 10,
            "weight": 0.625,
            "freight_class": "500"
        }
    ],
    "assignee_id": null,
    "origin_network_location_id": null,
    "destination_network_location_id": null,
    "reference_numbers": [
        {
            "id": "shpr_HMRjWs5b",
            "code": "invoice_id",
            "value": "H32HKHU3",
            "name": null
        },
        {
            "id": "shpr_KfSJz5xp",
            "code": "other_id",
            "value": "TRX-23412LKJ",
            "name": "Transaction Number"
        }
    ],
    "origin_instructions": "Look for Patty Mayonaise she has the goods",
    "destination_instructions": "The secret knock is the Funky Town Beat",
    "shiphawk_managed": true
Suggest Edits

Reference Numbers Object

 

Code Mapping for Reference Numbers

code x12_code

invoice_id 'SO',
customer_id 'CO',
reference_id 'CR',
purchase_id 'PO',
bol_id 'BM',
other_id 'ZZ'

Attribute
Type
Description

id

string

code

string

Refer to the code mapping above to determine which code to use

value

string

An invoice number, purchase number, etc

name

string

If our codes don't support your needs. Use other_id and then you can name your own reference number.

Reference Number Example

{
	"id": "shpr_12345",
  "code": "SO",
  "value": "99999",
  "name": "Sales Order Number"
},
{
	"id": "shpr_78910",
  "code": "CR",
  "value": "xx-99999",
  "name": "Customer Reference Number"
}
Suggest Edits

Create a New Shipment

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/
curl -H "Content-Type: application/json" -X POST -d'{
    	"rate_id": "a8e5c4b8-d789-457c-b0b0-b8a983923c41",
        "assignee_id": null,
        "origin_instructions": "Look for Patty Mayonaise she has the goods",
        "destination_instructions": "The secret knock is the Funky Town Beat",
        "reference_numbers": [{"code": "invoice_id", "value": "first_value"},
                            {"code": "other_id", "value": "second_value", "name": "if code ZZ"}],
        "origin_address": {
            "name": "Parcel Origin",
            "company": "Parcel Origin Company",
            "phone_number": "5555551212",
            "email": "parcel_origin@test.com",
            "street1": "123 Small Parcel Circle",
            "street2": "Apt 5",
            "city": "Chicago",
            "state": "IL",
            "zip": "60060",
            "country": "US"
        },
        "destination_address": {
            "name": "Parcel Destination",
            "company": "Parcel Destination Company",
            "phone_number": "8055557777",
            "email": "parcel_destination@email.com",
            "street1": "555 Small Parcel Delivered",
            "street2": "Suite 8",
            "city": "Santa Barbara",
            "state": "CA",
            "zip": "93105",
            "country": "US"
        },
        "fees" : {
            "insurance" : {
               "active" : true
            }
        }
    }' 'https://sandbox.shiphawk.com/api/v4/shipments?api_key=YOUR_API_KEY'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

rate_id
string
required
origin_address
object
required

You may pass in either an address id from a previously created address or you can pass in the required address parameters

 
destination_address
object
required

You may pass in either an address id from a previously created address or you can pass in the required address parameters

 
origin_network_location_id
string
destination_network_location_id
string
origin_instructions
string
destination_instructions
string
accessorials
array of strings
reference_numbers
array
fees
object

When requested, insurance for small parcel will be charged at 1% of stated value or $3, whichever is greater. Insurance for LTL shipments will be charged at $30 or 1%, whichever is greater.

 
request return label
boolean

A return label is returned when a shipment is created

 

A shipment may be created in 3 different ways:

Using the required fields

This will manually create a shipment.

NOTE Only create a shipment in this way if you know the packed dimensions of your items, carrier, and service_level and don't care about the price.

Using a rate_id

This will create a shipment for each proposed_shipment in the rate. If there is only one item being shipped there will only be one proposed_shipment in the rate. This is the use case where you have chosen a rate and would like to create a shipment from that rate.

Using a proposed_shipment_id

This will create a shipment from an existing proposed shipment. Only pass in proposed_shipment_id, do not pass in any other attributes.

When to create a shipment

Shipments should only be created once it is fairly certain that the goods will be transported. For parcel shipments, a label will be generated immediately on shipment creation and charges may be incurred. For freight and blanket wrap shipments, carriers may be notified and dispatched on shipment creation.

If the goods are not yet ready to be processed, create a Quote instead.

Suggest Edits

Create a New External Shipment

External shipments are shipments you have booked outside of ShipHawk but would like to add to your dashboard for tracking purposes.

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/external_shipments
    {
        "assignee_id": null,
        "origin_instructions": "Look for Patty Mayonaise she has the goods",
        "destination_instructions": "The secret knock is the Funky Town Beat",
        "reference_numbers": [{"code": "invoice_id", "value": "first_value"},
                            {"code": "other_id", "value": "second_value", "name": "if code ZZ"}],
        "origin_address": {
            "name": "Parcel Origin",
            "company": "Parcel Origin Company",
            "phone_number": "5555551212",
            "email": "parcel_origin@test.com",
            "street1": "123 Small Parcel Circle",
            "street2": "Apt 5",
            "city": "Chicago",
            "state": "IL",
            "zip": "60060",
            "country": "US"
        },
        "destination_address": {
            "name": "Parcel Destination",
            "company": "Parcel Destination Company",
            "phone_number": "8055557777",
            "email": "parcel_destination@email.com",
            "street1": "555 Small Parcel Delivered",
            "street2": "Suite 8",
            "city": "Santa Barbara",
            "state": "CA",
            "zip": "93105",
            "country": "US"
        }
    }
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "id": "shp_j2AM5v2K",
    "status": "ordered",
    "origin_address": {
        "id": "badr_GhC9xnHN",
        "name": "Parcel Origin",
        "company": "Parcel Origin Company",
        "street1": "123 Small Parcel Circle",
        "street2": "Apt 5",
        "city": "Chicago",
        "state": "IL",
        "zip": "93101",
        "country": "US",
        "phone_number": "5555551212",
        "email": "parcel_origin@test.com",
        "is_residential": false,
        "address_type": "commercial",
        "validated": null,
        "code": null
    },
    "destination_address": {
        "id": "badr_Azc9KtGc",
        "name": "Parcel Destination",
        "company": "Parcel Destination Company",
        "street1": "555 Small Parcel Delivered",
        "street2": "Suite 8",
        "city": "Santa Barbara",
        "state": "CA",
        "zip": "60060",
        "country": "US",
        "phone_number": "8055557777",
        "email": "parcel_destination@email.com",
        "is_residential": false,
        "address_type": "commercial",
        "validated": null,
        "code": null
    },
    "carrier": "FedEx",
    "service_level": "Ground",
    "total_price": 17.53,
    "tracking_number": null,
    "documents": null,
    "price_details": {
        "shipping": 17.53,
        "packing": 0,
        "insurance": 0,
        "pickup": 0,
        "delivery": 0,
        "accessorials": 0,
        "duty": null,
        "taxes": null
    },
    "dispatch": null,
    "final_mile": null,
    "packages": [
        {
            "id": "pkg_HdREBS6Y",
            "tracking_number": null,
            "tracking_url": null,
            "freight_class": "500",
            "packing_type": null,
            "package_items": [
                {
                    "id": "pkgi_yV1JnyZM",
                    "product_sku": null,
                    "product_sku_packing_code": null,
                    "item_name": "Small Parcel",
                    "dimensions": {
                        "length": 10,
                        "width": 10,
                        "height": 11,
                        "weight": 0.625,
                        "volume": 0.636574074074074,
                        "density": 0.98
                    },
                    "freight_class": "500",
                    "nmfc": null,
                    "hs_code": null,
                    "country_of_origin": null,
                    "xid": null,
                    "value": 300,
                    "description": null
                }
            ],
            "materials": null,
            "labors": null,
            "length": 10,
            "width": 10,
            "height": 11,
            "weight": 0.625,
            "volume": null
        }
    ],
    "assignee_id": null,
    "origin_network_location_id": null,
    "destination_network_location_id": null,
    "reference_numbers": [
        {
            "id": "shpr_0b2TEY0J",
            "code": "invoice_id",
            "value": "first_value",
            "name": null
        },
        {
            "id": "shpr_qcmxWAMm",
            "code": "other_id",
            "value": "second_value",
            "name": "if code ZZ"
        }
    ],
    "origin_instructions": "Look for Patty Mayonaise she has the goods",
    "destination_instructions": "The secret knock is the Funky Town Beat",
    "shiphawk_managed": true
}

Body Params

origin_address
object
 
destination_address
object
 
carrier
string
service_level
string
total_price
double
tracking_number
string
reference_numbers
array
accessorials
array
origin_instructions
string
destination_instructions
string
origin_network_location_id
string
destination_network_location_id
string
assignee_id
string
 
Suggest Edits

Update an Existing Shipment

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/id
{
	"status": "delivered",
	"tracking_number": "Track my ship",
	"origin_instructions": "Instructions for the man with the pickup truck",
	"destination_instructions": "Instructions for the man with the bigger pickup truck",
  "itn_confirmation_number": 1343,
  "origin_address": {
 		"company": "Example, Inc",
		"street1": "465 Hillview Ave",
		"street2": null,
		"phone_number": "1234567890",
		"email": "order@example.org" 
  },
  "destination_address": {
 		"company": "Example, Inc",
		"street1": "465 Hillview Ave",
		"street2": null,
		"phone_number": "1234567890",
		"email": "order@example.org" 
  }
}
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "id": "shp_Rz3apJJD",
    "status": "delivered",
    "origin_address": {
        "id": "badr_Mevdnh8f",
        "name": "Parcel Origin",
        "company": "Parcel Origin Company",
        "street1": "123 Small Parcel Circle",
        "street2": "Apt 5",
        "city": "Chicago",
        "state": "IL",
        "zip": "93101",
        "country": "US",
        "phone_number": "5555551212",
        "email": "parcel_origin@test.com",
        "is_residential": false,
        "address_type": "commercial",
        "validated": null,
        "code": null
    },
    "destination_address": {
        "id": "badr_C54BAzed",
        "name": "Parcel Destination",
        "company": "Parcel Destination Company",
        "street1": "555 Small Parcel Delivered",
        "street2": "Suite 8",
        "city": "Santa Barbara",
        "state": "CA",
        "zip": "60060",
        "country": "US",
        "phone_number": "8055557777",
        "email": "parcel_destination@email.com",
        "is_residential": false,
        "address_type": "commercial",
        "validated": null,
        "code": null
    },
    "carrier": "FedEx",
    "service_level": "Ground",
    "total_price": 17.53,
    "tracking_number": "Track my ship",
    "documents": null,
    "price_details": {
        "shipping": 17.53,
        "packing": 0,
        "insurance": 0,
        "pickup": 0,
        "delivery": 0,
        "accessorials": 0,
        "duty": null,
        "taxes": null
    },
    "dispatch": null,
    "final_mile": null,
    "packages": [
        {
            "id": "pkg_3Afyctr1",
            "tracking_number": null,
            "tracking_url": null,
            "freight_class": "500",
            "packing_type": null,
            "package_items": [
                {
                    "id": "pkgi_Rr45d32c",
                    "product_sku": null,
                    "product_sku_packing_code": null,
                    "item_name": "Small Parcel",
                    "dimensions": {
                        "length": 10,
                        "width": 10,
                        "height": 11,
                        "weight": 0.625,
                        "volume": 0.636574074074074,
                        "density": 0.98
                    },
                    "freight_class": "500",
                    "nmfc": null,
                    "hs_code": null,
                    "country_of_origin": null,
                    "xid": null,
                    "value": 300,
                    "description": null
                }
            ],
            "materials": null,
            "labors": null,
            "length": 10,
            "width": 10,
            "height": 11,
            "weight": 0.625,
            "volume": null
        }
    ],
    "assignee_id": null,
    "origin_network_location_id": null,
    "destination_network_location_id": null,
    "reference_numbers": [
        {
            "id": "shpr_P63Yf0Qx",
            "code": "invoice_id",
            "value": "first_value",
            "name": null
        },
        {
            "id": "shpr_FBYPhpNh",
            "code": "other_id",
            "value": "second_value",
            "name": "if code ZZ"
        }
    ],
    "origin_instructions": "Instructions for the man with the Pickup Truck",
    "destination_instructions": "Instructions for the man with the dump truck",
    "shiphawk_managed": true
}

Path Params

id
string
required

Body Params

status
string
tracking_number
string
origin_instructions
string
destination_instructions
string
packages
array
origin_network_location_id
string
destination_network_location_id
string
itn_confirmation_number
string

International confirmation number for this shipment

reference_numbers
array

Will update existing reference numbers if "id" field is provided and create them if it is not (or given ID does not exist). Reference numbers whose IDs are not present will be deleted unless the array is empty

origin_address
object
 
destination_address
object
 
 

Update an existing shipment

Suggest Edits

Retrieve a Shipment

Retrieve an existing shipment by shipment id.

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/id
curl -X GET "https://sandbox.shiphawk.com/api/v4/shipments/ship_jdh973f92n?api_key=[[app:key]]"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
	"id": "ship_jdh973f92n",
  "origin_address": {
 		"id" : 70463,
 		"name": "Leonard Alexander",
 		"company": null,
 		"street1": "8711N Los Robles Ave.",
 		"street2": "4th Floor",
 		"city": "Pasadena",
 		"state": "CA",
 		"zip": "91108",
 		"country": "US",
 		"phone_number": "6265551358",
 		"email": "leonard+test@smashingprotons.com",
 		"is_residential":true,
 		"address_type": null,
 		"validated": false,
 		"code": null
	},
  "destination_address": {
 		"id" : "adr_13jlj3k5",
 		"name": "Tom Current",
 		"company": null,
 		"street1": "1000 Puesta Del Sol",
 		"street2": null,
 		"city": "Carpinteria",
 		"state": "CA",
 		"zip": "93013",
 		"country": "US",
 		"phone_number": "8055551358",
 		"email": "tom@gmail.com",
 		"is_residential":true,
 		"address_type": null,
 		"validated": false,
 		"code": null
	},
  "carrier": "USPS",
  "service_level": "Priority Mail",
  "total_price": 23.89,
  "tracking_number": "9405510200829690928151",
  "documents": [{
 		"id": "doc_jd83k8fy2",
 		"type": "label",
 		"tracking_number": "9405510200829690928151",
 		"url": "",
 		"file": "",
    "package_id": "pkg_Jj4kdj9h",
 		"itn_confirmation": null,
 		"created_at": "2015-11-08T20:57:32Z"
	}],
  "price_details":[{
		"type": "shipping",
  	"name": "usps priority mail",
  	"price": 23.89,
  	"quantity": null,
  	"unit_price": null,
  	"unit_of_measure": null
	},
	{
		"type": "packing",
  	"name": "labor",
  	"price": 38.50,
  	"quantity": 23.20,
  	"unit_price": 1.16,
  	"unit_of_measure": :"minute"
	}],
  "dispatch": {},
  "pickup": {},
  "delivery": {},
  "final_mile": {},
  "packages": [{
    "id": "pkg_Jj4kdj9h",
  	"length": 6,
		"width": 4,
		"height": 5,
		"weight": 64.0,
		"value": 65
    
  }]
}

Path Params

id
int32
required

required

 
Suggest Edits

Cancel a Shipment

This request will set the shipment's status to cancelled, void all labels, and cancel any scheduled pickups.

NOTE Charges may be incurred depending on the state of the shipment when it is cancelled.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/shipments/id
No code samples available
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
int32
required

required

 

Example Response

{
	...
  
	"details" : {
    ...
    "status" : "cancelled",
    ...
	}

	...
}
Suggest Edits

Retrieve the URL of a Commercial Invoice PDF file

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/id/commercial_invoice
curl -X GET "https://sandbox.shiphawk.com/api/v4/shipments/ship_jdh973f92n/commercial_invoice?regen_pdf=true"
	-H 'X-Api-Key: {YOUR API KEY}'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "url": "http://0.0.0.0:3000/uploads/CI_1028503.pdf",
  "with": {
    "block_options": [],
    "nested_attributes": [],
    "exposures": {
      "url": {
        "documentation": {
          "type": "string"
        }
      }
    }
  }
}

Path Params

id
string
required

Query Params

regen_pdf
boolean

Indicates whether the API should regenerate the invoice PDF (regen_pdf=true) or use the previously generated PDF (regen_pdf=false, default). Should be set to true if any of the information on the invoice may have changed.

 

Returns the URL to download the commercial invoice for a shipment. If is is possible that some information has changed since the creation of the shipment, set regen_pdf=true in the request, and the PDF will be re-generated with the latest data. To download the PDF directly, access "/shipments/:id/commercial_invoice .pdf" with the same parameters.

Suggest Edits

Retrieve the URL of a BOL PDF File

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/id/bol
curl -X GET https://sandbox.shiphawk.com/api/v4/shipments/ship_jdh973a52n/bol?regen_pdf=true&carrier_code=mxd
	-H 'X-Api-Key: {YOUR API KEY}'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "url": "https://sandbox.shiphawk.com/uploads/BOL_4028749.pdf",
  "with": {
    "block_options": [],
    "nested_attributes": [],
    "exposures": {
      "url": {
        "documentation": {
          "type": "string"
        }
      }
    }
  }
}

Path Params

id
string
required

Query Params

regen_pdf
boolean

Indicates whether the API should regenerate the BOL PDF (regen_pdf=true) or use the previously generated PDF (regen_pdf=false, default). Should be set to true if any of the information on the BOL may have changed.

carrier_code
string

Code specifying the carrier handling this BOL. Only required if regen_pdf is set to true or the BOL has not been generated yet.

 

Returns the URL to download the BOL for a shipment. If is is possible that some information has changed since the creation of the shipment, set regen_pdf=true in the request, and the PDF will be re-generated with the latest data. To download the PDF directly, access "/shipments/:id/bol.pdf" with the same parameters.

$.get('http://yoursite.com/test/' + id, function(data) {
    console.log(data);
});
Suggest Edits

Retrieve the URL of an Address Label PDF File

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/id/address_labels
curl -X GET https://sandbox.shiphawk.com/api/v4/shipments/ship_jdh973a52n/address_labels?regen_pdf=true&carrier_code=mxd
	-H 'X-Api-Key: {YOUR API KEY}'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "url": "https://sandbox.shiphawk.com/uploads/Address_Labels_4028749.pdf",
  "with": {
    "block_options": [],
    "nested_attributes": [],
    "exposures": {
      "url": {
        "documentation": {
          "type": "string"
        }
      }
    }
  }
}

Path Params

id
string
required

Query Params

regen_pdf
string

Indicates whether the API should regenerate the address label PDF (regen_pdf=true) or use the previously generated PDF (regen_pdf=false, default). Should be set to true if any of the information on the address label may have changed.

carrier_code
string

Code specifying the carrier handling this BOL. Only required if regen_pdf is set to true or the address label has not been generated yet.

 

Returns the URL to download the address label for a shipment. If is is possible that some information has changed since the creation of the shipment, set regen_pdf=true in the request, and the PDF will be re-generated with the latest data. To download the PDF directly, access "/shipments/:id/address_labels.pdf" with the same parameters

$.get('http://yoursite.com/test/' + id, function(data) {
    console.log(data);
});
Suggest Edits

Track Shipment

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/id/tracking
No code samples available
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "id": "shp_j2AM5v2K",
    "status": "ordered",
    "status_updates": [],
    "tracking_number": null,
    "actual_delivery_date": null,
    "actual_pickup_time": "2016-02-08T00:00:00.000Z"
}

Path Params

id
string
required
 
Suggest Edits

Track Shipment Subscription

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/id/tracking
No code samples available
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

Body Params

callback_url
string
required
 
Suggest Edits

List all Shipments

Retrieve all shipments for your account

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/
curl -X GET -H "X-Api-Key: [Your-Api-Key]" 
"https://sandbox.shiphawk.com/api/v4/shipments?per_page=999"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
	"id": "ship_jdh973f92n",
  "origin_address": {
 		"id" : 70463,
 		"name": "Leonard Alexander",
 		"company": null,
 		"street1": "8711N Los Robles Ave.",
 		"street2": "4th Floor",
 		"city": "Pasadena",
 		"state": "CA",
 		"zip": "91108",
 		"country": "US",
 		"phone_number": "6265551358",
 		"email": "leonard+test@smashingprotons.com",
 		"is_residential":true,
 		"address_type": null,
 		"validated": false,
 		"code": null
	},
  "destination_address": {
 		"id" : "adr_13jlj3k5",
 		"name": "Tom Current",
 		"company": null,
 		"street1": "1000 Puesta Del Sol",
 		"street2": null,
 		"city": "Carpinteria",
 		"state": "CA",
 		"zip": "93013",
 		"country": "US",
 		"phone_number": "8055551358",
 		"email": "tom@gmail.com",
 		"is_residential":true,
 		"address_type": null,
 		"validated": false,
 		"code": null
	},
  "carrier": "USPS",
  "service_level": "Priority Mail",
  "total_price": 23.89,
  "tracking_number": "9405510200829690928151",
  "documents": [{
 		"id": "doc_jd83k8fy2",
 		"type": "label",
 		"tracking_number": "9405510200829690928151",
 		"url": "",
 		"file": "",
    "package_id": "pkg_Jj4kdj9h",
 		"itn_confirmation": null,
 		"created_at": "2015-11-08T20:57:32Z"
	}],
  "price_details":[{
		"type": "shipping",
  	"name": "usps priority mail",
  	"price": 23.89,
  	"quantity": null,
  	"unit_price": null,
  	"unit_of_measure": null
	},
	{
		"type": "packing",
  	"name": "labor",
  	"price": 38.50,
  	"quantity": 23.20,
  	"unit_price": 1.16,
  	"unit_of_measure": :"minute"
	}],
  "dispatch": {},
  "pickup": {},
  "delivery": {},
  "final_mile": {},
  "packages": [{
    "id": "pkg_Jj4kdj9h",
  	"length": 6,
		"width": 4,
		"height": 5,
		"weight": 64.0,
		"value": 65
    
  }]
}
 
Suggest Edits

Shipping Policies Object

Shipping Policies allow you to dictate how shipments are configured for your order. Without a shipping policy in place, ShipHawk will automatically create a Proposed Shipment that uses the cheapest possible carrier and service available for your account. But that's not good enough, so we created Shipping Policies.

Shipping Policies put you in control to choose what you're optimizing for whether it's cost, speed, specific service levels or a preferred carrier. For example, you could use a shipping policy to ensure that you always use FedEx Ground services for items that exceed $250 in value. That way, your higher ticket items always ship with your preferred carrier.

Using criteria and actions, you can create very simple or very complex shipping policies at a Global, Order and Product detail level.

 
Attribute
Type
Description

id

string

name

string

Provide a friendly descriptive name for the shipping policy.

active

boolean

Indicates if the shipping policy is enabled for the account.

criteria

array

Used to indicate the conditions under which the shipping policy will be applied.

actions

array

Used to identify how the Account holder wants proposed shipments to be created given that criteria TRUE in an order.

created_at

date_time

Date the shipping policy was created.

updated_at

date_time

Date the shipping policy was last modified.

Suggest Edits

Create a Shipping Policy

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipping_policies/
curl -X POST 
-H "X-Api-Key: [Your-Api-Key]"
-d '{
      "name": "Use FedEx Next Day for orders over 250",
      "criteria": [{
        "field": "order_value",
        "operator": "GREATER_THAN",
        "value": "250"
      }],
      "actions": [{
        "name": "filter_carrier",
        "value": "fedex"
      },
      {
        "name": "filter_service_level",
        "value": "Next Day"
      }]
    }' "https://sandbox.shiphawk.com/api/v4/shipping_policies"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "spol_HQMa09Kp",
  "name": "Use FedEx Next Day for orders over 250",
  "active": true,
  "criteria": [
    {
      "field": "order_value",
      "operator": "GREATER_THAN",
      "value": 250,
      "group": "default"
    }
  ],
  "actions": [
    {
      "name": "filter_carrier",
      "value": "fedex"
    },
    {
      "name": "filter_service_level",
      "value": "Next Day"
    }
  ],
  "created_at": "2016-06-21T22:41:33Z",
  "updated_at": "2016-06-21T22:41:33Z"
}

Body Params

name
array
required
criteria
array
required
actions
array
required
active
boolean
 
Suggest Edits

Update a Shipping Policy

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipping_policies/id
curl -X POST 
-H "X-Api-Key: [Your-Api-Key]"
-d '{
			"name": "Use FedEx Next Day for orders over 250",
      "active": false,
      "criteria": [{
        "field": "order_value",
        "operator": "GREATER_THAN",
        "value": "250"
      }],
      "actions": [{
        "name": "filter_carrier",
        "value": "fedex"
      },
      {
        "name": "filter_service_level",
        "value": "Next Day"
      }]
    }' "https://sandbox.shiphawk.com/api/v4/shipping_policies/spol_HQMa09Kp"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "spol_HQMa09Kp",
  "name": "Use FedEx Next Day for orders over 250",
  "active": false,
  "criteria": [
    {
      "field": "order_value",
      "operator": "GREATER_THAN",
      "value": 250,
      "group": "default"
    }
  ],
  "actions": [
    {
      "name": "filter_carrier",
      "value": "fedex"
    },
    {
      "name": "filter_service_level",
      "value": "Next Day"
    }
  ],
  "created_at": "2016-06-21T22:41:33Z",
  "updated_at": "2016-06-21T22:41:33Z"
}

Body Params

name
array
required
criteria
array
required
actions
array
required
active
boolean
 
Suggest Edits

Retrieve a Shipping Policy

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipping_policies/id
curl -X GET 
	-H "X-Api-Key: [YOUR-API-KEY]"
"https://sandbox.shiphawk.com/api/v4/shipping_policies/spol_HQMa09Kp"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "spol_HQMa09Kp",
  "name": "Use FedEx Next Day for orders over 250",
  "active": false,
  "criteria": [
    {
      "field": "order_value",
      "operator": "GREATER_THAN",
      "value": 250,
      "group": "default"
    }
  ],
  "actions": [
    {
      "name": "filter_carrier",
      "value": "fedex"
    },
    {
      "name": "filter_service_level",
      "value": "Next Day"
    }
  ],
  "created_at": "2016-06-21T22:41:33Z",
  "updated_at": "2016-06-21T22:41:33Z"
}

Path Params

id
string
required
 
Suggest Edits

List all Shipping Policies

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipping_policies/
curl -X GET 
	-H "X-Api-Key: [YOUR-API-KEY]"
"https://sandbox.shiphawk.com/api/v4/shipping_policies"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "spol_HQMa09Kp",
  "name": "Use FedEx Next Day for orders over 250",
  "active": false,
  "criteria": [
    {
      "field": "order_value",
      "operator": "GREATER_THAN",
      "value": 250,
      "group": "default"
    }
  ],
  "actions": [
    {
      "name": "filter_carrier",
      "value": "fedex"
    },
    {
      "name": "filter_service_level",
      "value": "Next Day"
    }
  ],
  "created_at": "2016-06-21T22:41:33Z",
  "updated_at": "2016-06-21T22:41:33Z"
}
 
Suggest Edits

Delete a Shipping Policy

 

Authentication

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/shipping_policies/id
curl -X DELETE -H "X-Api-Key: [YOUR-API-KEY]" 
"https://sandbox.shiphawk.com/api/v4/shipping_policies/spol_HQMa09Kp"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required
 
Suggest Edits

Tracking Object

 
Attribute
Type
Description

status

string

required
Possible values:
ordered
confirmed
scheduled_for_pickup
agent_prep
ready_for_carrier_pickup
in_transit
delivered
exception
cancelled

status_updates

array

required
StatusUpdate

tracking_number

string

required
This shipment's tracking number

actual_delivery_date

string

Example format:
"2015-06-05T07:00:00.000Z"

actual_pickup_time

string

Example format:
"2015-06-05T08:00:00.000Z"

Suggest Edits

Status Update Object

 

Status Update

Attribute
Type
Description

time

string

required
Time at which the update was received
Example format:
"2015-06-09 18:04:31 UTC"

name

string

required
Carrier-provided update name if this status update was sent by a carrier. For example: "Out for Delivery" or "Arrived at Post Office"
Always set to "ShipHawk Update" if generated by ShipHawk in response to status change.

location

string

Location provided by a carrier. Null if name="ShipHawk Update"

message

string

required
Description of the status update event.

Suggest Edits

Retrieve Tracking Information for a Shipment

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/id/tracking
curl -X GET "https://sandbox.shiphawk.com/api/v4/shipments/ship_jdh990f92n/tracking"
	-H 'X-Api-Key: {MY_API_KEY}'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "ship_jdh990f92n",
  "status": "delivered",
  "status_updates": [
    {
      "time": "2015-06-09 18:04:31 UTC",
      "name": "ShipHawk Update",
      "location": null,
      "message": "Picked up 6/5/15 (Con-way PRO 247266541.  ETA to Auburn, WA dock for Span Alaska transit 6/10/15."
    },
    {
      "time": "2015-06-09 23:45:01 UTC",
      "name": "ShipHawk Update",
      "location": null,
      "message": "Con-way delivered to Span Alaska warehouse in Auburn, WA.  Scheduled to depart Auburn on Thursday 6/11"
    },
    {
      "time": "2015-06-11 22:57:25 UTC",
      "name": "ShipHawk Update",
      "location": null,
      "message": "ETA to Span Alaska- Anchorage 6/15.  Once unloaded and brought to warehouse, will call JR Movers for pick-up scheduling."
    },
    {
      "time": "2015-06-16 22:25:42 UTC",
      "name": "ShipHawk Update",
      "location": null,
      "message": "Shipment has arrived at the Span-Alaska dock in Anchorage Alaska"
    },
    {
      "time": "2015-06-19 15:35:31 UTC",
      "name": "ShipHawk Update",
      "location": null,
      "message": "LVM for Annalissa Ogena 6/17 to schedule delivery.  Re-attempt call 6/18.  E-mail to customer 6/19 for delivery appointment request."
    },
    {
      "time": "2015-06-23 20:07:14 UTC",
      "name": "ShipHawk Update",
      "location": null,
      "message": "Needs to be after 6pm or weekend delivery.  Working with carrier for possible Saturday (6/27) morning delivery.  Will confirm shortly.."
    },
    {
      "time": "2015-06-25 00:22:52 UTC",
      "name": "ShipHawk Update",
      "location": null,
      "message": "Scheduled delivery for Saturday 6/27 before 12pm.  Carrier and customer (Husband Dan) confirmed."
    },
    {
      "time": "2015-06-30 00:19:31 UTC",
      "name": "ShipHawk Update",
      "location": null,
      "message": "Delivery re-scheduled for 6/29 @ 6pm"
    },
    {
      "time": "2015-06-30 20:12:25 UTC",
      "name": "ShipHawk Update",
      "location": null,
      "message": "Delivered 6/29."
    }
  ],
  "tracking_number": "247266541",
  "actual_delivery_date": null,
  "actual_pickup_time": "2015-06-05T07:00:00.000Z"
}

Path Params

id
string
required
 

Retrieve tracking events for a shipment. See StatusUpdate object for details.

Suggest Edits

Subscribe to Status Updates for a Shipment

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/id/tracking
curl -X POST https://sandbox.shiphawk.com/api/v4/shipments/shp_3kBcvMnx/tracking
	-H 'X-Api-Key: {YOUR API KEY}' \
  -d '{"callback_url": "https://www.example.org"}'
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
  "id": "wh_xGMsTugN",
  "resource_name": "Shipment",
  "events": [],
  "callback_url": "https://www.example.org",
  "created_at": "2016-01-18T19:42:12Z"
}

Path Params

id
string
required

shipment id

Body Params

callback_url
string
required

Webhook URL to which notifications will be posted

events
array of strings

List of events that will trigger a webhook callback [requires documentation]

 

Registers a callback URL for shipment tracking events occurring for this shipment. Passing in no events will cause callbacks to be registered for all events. The events for which users can register are:

'shipment_address_update'
'shipment_documents_update'
'shipment_notes_update'
'shipment_status_update'
'shipment_timing_update'
'shipment_tracking_update'

To register for only a subset of these, pass the names of the desired events as a string array in the 'events' parameter. New sets of events passed in in this manner will replace previously requested callbacks.

Suggest Edits

Unpacked Item Object

Small unpacked items must be packed prior to shipping. ShipHawk estimates the packing materials required and provides rates based on the estimated weight and dimensions of the resulting package(s).

For larger items (such as furniture or lab equipment), ShipHawk provide rates for Blanket Wrap carriers and compares those rates against the cost to pack and ship with a traditional LTL or Home Delivery carrier.

 

Multiple unpacked items may be packed into one box.

There may be less packages than unpacked items.

Attribute
Type
Description

type

string

required
Use value unpacked

quantity

integer

Default: 1

length

number (inches)

required

width

number (inches)

required

height

number (inches)

required

weight

number (pounds)

required

value

integer

required

unpacked_item_type_id

string

usually required Not required if valid product_sku is present.

This can be acquired by searching for an Unpacked Item Type

freight_class

string

NMFC freight class codes:
50 55 60 65 70 77.5 85 92.5 100 110 125 150 175 200 250 300 400 500

nmfc

string

The National Motor Freight Classification code.

Default value will be calculated based on density (This can affect rating accuracy).

product_sku

string

Only use this if you have integrated with our Product Service

description

string

require_crating

boolean

Default: false

Example Unpacked Item

{
 "type": "unpacked",
 "length": 20,
 "width": 24,
 "height": 20,
 "weight": 50,
 "value": 975,
 "unpacked_item_type_id": "itm_nWvNMd89"
}
Suggest Edits

Unpacked Item Type Object

Unpacked Item Types represent types of items (i.e. Macbook Pro, Antique Chair, etc.) for which ShipHawk provides detailed information for (i.e. average length, minimum padding, whether it can be rolled or stacked, etc.)

 
Attribute
Type
Description

id

string

name

string

category

string

average_dimensions

object

{
length: number,
width: number,
height: number,
weight: number
}

dimensions

object

{
length: number,
width: number,
height: number,
weight: number
}

Suggest Edits

Retrieve an Unpacked Item Type

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/unpacked_item_types/id
curl -XGET https://sandbox.shiphawk.com/api/v4/unpacked_item_types/itm_gbBwNKXq \
	-H 'Content-Type: application/json'\
	-H 'X-Api-Key: YOUR_API_KEY'\
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "itm_gbBwNKXq",
  "name": "Macbook Pro",
  "category_name": "Electronics",
  "average_dimensions": {
    "avg_width": 15,
    "avg_height": 10,
    "avg_length": 1,
    "avg_weight": 2
  },
  "dimensions": {
    "length": 15,
    "width": 10,
    "height": 1,
    "weight": 2
  }
}
 
Suggest Edits

Search for an Unpacked Item Type

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/unpacked_item_types/search
curl -X GET "https://sandbox.shiphawk.com/api/v4/unpacked_item_types/search?name=chair&api_key=[[app:key]]"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "id": "itm_hD5KWp7C",
    "name": "Chair",
    "category_name": "Home and Garden",
    "average_dimensions": {
      "avg_width": 20,
      "avg_height": 30,
      "avg_length": 40,
      "avg_weight": 50
    },
    "dimensions": {
      "length": 84,
      "width": 66,
      "height": 87,
      "weight": 23
    }
  },
  {
    "id": "itm_Vt6cdajG",
    "name": "Desk Chair",
    "category_name": "Home and Garden",
    "average_dimensions": {
      "avg_width": 22,
      "avg_height": 33,
      "avg_length": 44,
      "avg_weight": 12
    },
    "dimensions": {
      "length": 84,
      "width": 44,
      "height": 52,
      "weight": 19
    }
  }
]

Query Params

name
string
required

Simple name to describe your commodity

 
Suggest Edits

Webhooks

To subscribe to the ShipHawk Webhooks, see the below documentation

 

You can easily setup webhooks to capture and respond to tracking events and milestones for your customers.

Attribute
Type
Description

callback_url

String

Required

Your unqiue callback URL where you'll receive the messages from ShipHawk for your shipments

events

String

List of available webhooks

"shipment.status_update",
"shipment.address_update",
"shipment.notes_update",
"shipment.timing_update",
"shipment.tracking_update",
"shipment.documents_update"

Suggest Edits

Get the list of available webhooks

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/webhooks/events
Get available events: 
curl -X GET -H "X-Api-Key: secret" "https://sandbox.shiphawk.com/api/v4/webhooks/events"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{[
  "shipment.status_update",
  "shipment.address_update",
  "shipment.notes_update",
  "shipment.timing_update",
  "shipment.tracking_update",
  "shipment.documents_update"
]}
 
Suggest Edits

Create a webhook

 

Authentication

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/webhooks
curl -X POST -H "X-Api-Key: secret" -H "Content-Type: application/json" -d 
'{"callback_url": "http://requestb.in/1khurll1", 
	"events":["shipment.status_update","shipment.tracking_update"]}' 
  "https://sandbox.shiphawk.com/api/v4/webhooks"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "id": "wh_6vh3AegY",
  "events": [
    "shipment.status_update",
    "shipment.tracking_update"
  ],
  "callback_url": "http://requestb.in/1khurll1",
  "created_at": "2016-12-28T11:59:15Z"
}

Body Params

Callback URL
string
Events
string
 
Suggest Edits

Get list of created webhooks

 

Authentication

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/webhooks
curl -X GET -H "X-API-KEY: YOUR_API_KEY" "https://sandbox.shiphawk.com/api/v4/webhooks"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "id": "wh_BZ1mtcGR",
    "events": [
      "shipment.timing_update",
      "shipment.tracking_update"
    ],
    "callback_url": "http://requestb.in/197klsd1",
    "created_at": "2017-01-03T22:39:10Z"
  },
  {
    "id": "wh_T85FsAXe",
    "events": [
      "shipment.status_update",
      "shipment.address_update"
    ],
    "callback_url": "http://requestb.in/197klsd1",
    "created_at": "2017-01-03T21:34:57Z"
}
 
Suggest Edits

Delete a webook

 

Authentication

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/webhooks/id
curl -X DELETE -H "X-API-KEY: YOUR_API_KEY" "https://sandbox.shiphawk.com/api/v4/webhooks/wh_BZ1mtcGR"
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     204 No Content
{
  "No Content"
}