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

Order Resources

 
Suggest Edits

Order Request Object

 

Used when creating or updating Orders. Parameters are optional unless noted.

Parameter
Type
Description, Defaults

order_number

string

required

source_system

string

Source system ("NetSuite", "Shopify", "Magento", etc.)

source_system_id

string

source_system_domain

string

origin_address

hash

Address object.

destination_address

hash

Address object.

order_line_items

array

List of Order Line Item Request objects.

total_price

float

tax_price

float

items_price

float

status

string

requested_shipping_details

string

requested_rate_id

string or array[string]

self_packed

boolean

Default: true

include_return_labels

Default: false

reference_numbers

array

List of Reference Number Request objects

proposed_shipments

array

List of Proposed Shipment Request objects

tags

array[string]

warehouse_id

string

warehouse_code

string

notes

array

List of Note Request objects

integration_id

integer

instant_proposed_shipment_generation

boolean

Default: false

billing_details

hash

Shipment Billing Details Request object

duties_taxes_billing_details

hash

Shipment Billing Details Request object

Suggest Edits

Order Reference Numbers Request 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

Order Line Item Request Object

 

Parameters are optional unless noted.

Parameter
Type
Description, Defaults

source_sytem_id

string

name

string

sku

string

quantity

integer

Default: 1

value

float

price

float

length

float

Length dimension.

width

float

Width dimension.

height

float

Height dimension.

weight

float

Line item weight.

item_type

string

unpacked_item_type_id

string

handling_unit_type

string

One of:
pallet carton box crate bag drum

hs_code

string

country_of_origin

string

freight_class

string

nmfc

string

package_type

string

package_quantity

integer

volume_cubic_ft

float

warehouse_id

string

warehouse_code

string

line_number

integer

description

string

origin_address

hash

reference_numbers

array

List of Order Line Reference Number Request objects.

hazmat_data

hash

List of Hazmat Data Request objects.

Suggest Edits

Order Line Reference Numbers Request 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'

Parameter
Type
Description, Defaults

id

string

code

string

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

external_code

string

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.

Suggest Edits

Hazmat Data Request Object

 
Parameter
Type
Description, Defaults

un_or_na_number

string

proper_shipping_name

string

technical_name

string

hazard_class_or_division

string

packing_group

string

emergency_response_phone_number

string

emergency_contact_name

string

emergency_contact_phone_number

string

regulation_level

string

container

string

quantity

integer

amount

decimal

amount_unit

string

One of:
kg lbs oz l

Suggest Edits

Order Response Object

 

Returned from Order creation, updating, retrieval, etc.

Attributes
Type
Description

id

string

ShipHawk Order identifier.

order_number

string

combined_order_numbers

array[string]

List of Order Line Item origin order numbers.

source_system

string

Source system ("NetSuite", "Shopify", "Magento", etc.)

source_system_id

string

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.

source_system_processed_at

DateTime

origin_address

hash

Address object.

destination_address

hash

Address object.

reference_numbers

array

List of Order Reference Number Response objects

total_price

float

shipping_price

float

tax_price

float

items_price

float

order_line_items

array

List of Order Line Item Response objects

requested_shipping_details

string

requested_rate_id

string

status

string

include_return_label

boolean

cancelled_at

DateTime

created_at

DateTime

udpated_at

DateTime

error_message

array[string]

batch_id

string

Order batch identifier

batch_name

string

Order batch name

requested_billing_details

hash

Shipment Billing Details Response object

tags

array[string]

warehouse

hash

Warehouse object

packing_slip_template

hash

Packing Slip Template object

single_sku

string

One of:
(None)
(Multiple Items)
a single SKU (if the order has a single Order Line Item with a SKU)

single_sku_name

string

One of:
(None)
(Multiple Items)
a single SKU (if the order has a single Order Line Item with a SKU)

hold_until

DateTime

integration_id

integer

shipments

array

List of Shipment objects

proposed_shipments

array

List of Proposed Shipment objects

notes

array

List of Note objects

*documents

array

List of Document objects

shipped_order_line_items

array

List of Order Line Item objects

not_shipped_order_line_items

array

List of Order Line Item objects

Suggest Edits

Order Line Item Response Object

 
Attributes
Type
Description

id

string

source_system_id

string

origin_order_source_system_id

string

In the case of combined shipments, this line item's original order source system

origin_order_number

string

In the case of combined shipments, this line item's original order number

name

string

description

string

sku

string

upc

string

quantity

decimal

value

decimal

length

decimal

width

decimal

height

decimal

weight

decimal

freight_class

string

package_quantity

integer

package_type

string

item_type

string

unpacked_item_type_id

string

handling_unit_type

string

hs_code

string

country_of_origin

string

lot_number

string

serial_number

string

line_number

integer

warehouse_id

string

warehouse_code

*string

origin_address

hash

{
  id: string
  name: string
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
  phone_number: string
  email: string
  is_residential: boolean
  is_warehouse: boolean
  address_type: string
  code: string
}

error_message

string

reference_numbers

array[object]

Array of Order Response objects

Suggest Edits

Hazmat Data Response Object

 
Attribute
Type
Description

un_or_na_number

string

proper_shipping_name

string

hazard_class_or_division

string

packing_group

string

emergency_response_phone_number

string

emergency_contact_name

string

emergency_contact_phone_number

string

regulation_level

string

container

string

quantity

integer

amount_unit

string

One of:
kg lbs oz l

Suggest Edits

Order Reference Numbers Response Object

 
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

Suggest Edits

Create an Order

Create a new order.

 

Header Auth

 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"
    }],
    "reference_numbers": [{
      "code":  "reference_id",
      "name":  "Shipper's Order #",
      "value": "787878"
      }, 
      {
      "code": "purchase_id",
      "name":  "Purchase Order #",
      "value": "191919"
      }],
    "total_price": 1000,
    "shipping_price": 800,
    "tax_price": 50,
    "items_price": 150,
    "status": "new",
    "requested_shipping_details": "FedEx Ground",  
    "requested_rate_id": "01004c4c-da3c-48ff-b2e7-2f44389077e8"
    }'
A binary file was returned

You couldn't be authenticated

{
	"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"
}
 
Suggest Edits

Update an Order

Update an existing Order

 

Header Auth

 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)"
    }'
A binary file was returned

You couldn't be authenticated

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

Retrieve an Order

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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/"
A binary file was returned

You couldn't be authenticated

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

Cancel an Order

Update an existing Order

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/id
curl -X POST https://sandbox.shiphawk.com/api/v4/orders/ord_a9Q11tYQ \
  -H 'Host: sandbox.shiphawk.com' \
  -H 'X-Api-Key: [Your-Api-Key]' \
  -d '{
        "status": "cancelled"
      }'
A binary file was returned

You couldn't be authenticated

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

Combine One or More Orders

Use the Combine Orders endpoint to take one or more orders and combine their details together so that you can process them as a single order. For example, the same customer may make two separate orders today. As a shipper, you may want to combine orders that go to the same address to reduce the number of shipments your customer receives.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/combine
curl -X POST https://sandbox.shiphawk.com/api/v4/orders/combine \
  -H 'Host: sandbox.shiphawk.com' \
  -H 'X-Api-Key: [Your-Api-Key]' \
  -d '{
	  	'master_order_id':'ord_x3M3T85J',
  		'ids':['ord_x3M3T85J','ord_Zeey0xf9']
    }
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

master_order_id
string
required

A ShipHawk assigned order ID

ids
string
required

ShipHawk assigned order IDs you want to combine into the master order ID

 
Suggest Edits

Split Orders

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/id/split
{
	"order_number": "100123-1",
	"total_price": 0,
	"shipping_price": 0,
	"tax_price": 0,
	"items_price": 0,
	"order_line_items": [{
		"id": "ordi_vNxGyyTg",
		"quantity": "1"
	}]
}
A binary file was returned

You couldn't be authenticated

{
	"id": "ord_E16Pa27p",
	"order_number": "100123-1",
	"source_system": null,
	"source_system_id": null,
	"source": null,
	"source_system_processed_at": "2017-10-31T17:57:31+00:00",
	"origin_address": {
		"name": "Max Horrell",
		"company": "ShipHawk",
		"street1": "925 De La Vina St.",
		"street2": "",
		"city": "Santa Barbara",
		"state": "CA",
		"zip": "93101",
		"country": "US",
		"phone_number": "(573) 486-1438",
		"email": "max@shiphawk.com",
		"is_residential": false
	},
	"destination_address": {
		"name": "Aaron Freeman",
		"company": "",
		"street1": "123 Test St.",
		"street2": "",
		"city": "Campbell",
		"state": "CA",
		"zip": "95008",
		"country": "US",
		"phone_number": "",
		"email": null,
		"is_residential": false,
		"is_po_box": false
	},
	"reference_numbers": [{
		"id": "shpr_ep76TNgq",
		"code": "other_id",
		"value": "receiving@shiphawk.com",
		"name": "ContactEmail"
	}, {
		"id": "shpr_rgHkxfjx",
		"code": "other_id",
		"value": "95008",
		"name": "BillingZipcode"
	}],
	"total_price": 0.0,
	"shipping_price": 0.0,
	"tax_price": 0.0,
	"items_price": 0.0,
	"order_line_items": [{
		"id": "ordi_mQze4Efc",
		"source_system_id": null,
		"name": "2 - ProfessionalsFlyer-Mortgage 2017",
		"description": null,
		"sku": "6375987",
		"upc": null,
		"quantity": 1,
		"value": 0.32,
		"length": 0.0,
		"width": 0.0,
		"height": 0.0,
		"weight": 0.0,
		"freight_class": null,
		"package_quantity": null,
		"package_type": null,
		"item_type": "parcel",
		"unpacked_item_type_id": null,
		"handling_unit_type": null,
		"hs_code": null,
		"lot_number": null,
		"serial_number": null,
		"line_number": null,
		"origin_address": null,
		"error_message": null
	}],
	"requested_shipping_details": "UPS Ground",
	"requested_rate_id": null,
	"status": "new",
	"include_return_label": false,
	"cancelled_at": null,
	"created_at": "2017-12-06T00:20:08+00:00",
	"updated_at": "2017-12-06T00:20:08+00:00",
	"error_message": [],
	"batch_id": null,
	"batch_name": null,
	"requested_billing_details": null,
	"tags": [],
	"warehouse": null,
	"single_sku": "6375987",
	"hold_until": null,
	"shipments": [],
	"proposed_shipments": [],
	"notes": [],
	"shipped_order_line_items": [],
	"not_shipped_order_line_items": [{
		"id": "ordi_mQze4Efc",
		"source_system_id": null,
		"name": "2 - ProfessionalsFlyer-Mortgage 2017",
		"description": null,
		"sku": "6375987",
		"upc": null,
		"quantity": 1,
		"value": 0.32,
		"length": 0.0,
		"width": 0.0,
		"height": 0.0,
		"weight": 0.0,
		"freight_class": null,
		"package_quantity": null,
		"package_type": null,
		"item_type": "parcel",
		"unpacked_item_type_id": null,
		"handling_unit_type": null,
		"hs_code": null,
		"lot_number": null,
		"serial_number": null,
		"line_number": null,
		"origin_address": null,
		"error_message": null
	}]
}

Path Params

id
string
required

Body Params

order_number
string
total_price
string
shipping_price
string
tax_price
string
items_price
string
order_line_items
array of strings
 

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

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

Hold One or More Orders

Holding orders allows you to set orders aside from your standard workflow so that you can address them later. It is typically used for orders that contain out of stock or backordered products.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/hold
curl -X POST https://sandbox.shiphawk.com/api/v4/orders/hold \
  -H 'Host: sandbox.shiphawk.com' \
  -H 'X-Api-Key: [Your-Api-Key]' \
  -d '{
    "ids": ["ord_AwD7Zr18", "ord_dEBTr6as"],
    "hold_until": "2017-11-11"
}'
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

ids
string
required

ShipHawk assigned order IDs you want to put on Hold

hold_until
date
required

Enter the date you want these items to be release from their "hold" status

 
Suggest Edits

Remove Hold on Orders

Immediately removes a hold on all specified orders.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/hold/restore
curl -X POST https://sandbox.shiphawk.com/api/v4/orders \
  -H 'Host: sandbox.shiphawk.com' \
  -H 'X-Api-Key: [Your-Api-Key]' \
 -d '{
    "ids": ["ord_AwD7Zr18", "ord_dEBTr6as"]
}'
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

ids
string
required

ShipHawk assigned order IDs you want to remove from the 'hold' status

 
Suggest Edits

Retrieve Proposed Shipments on an Order

Proposed shipments indicate the recommended way to ship out the items for an order. This service answers the question "how should I ship X?" for your warehouse team. These proposed shipments use your company's business rules so that items are always configured the way they "should be" shipped. That said, your team can always change these later if they find out the business rule was wrong or that there was a better way to ship the item(s).

 

Header Auth

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/orders/:id/proposed_shipments
curl --request GET \
  --url https://sandbox.shiphawk.com/api/v4/orders/:id/proposed_shipments
var request = require("request");

var options = { method: 'GET',
  url: 'https://sandbox.shiphawk.com/api/v4/orders/:id/proposed_shipments' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://sandbox.shiphawk.com/api/v4/orders/:id/proposed_shipments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://sandbox.shiphawk.com/api/v4/orders/:id/proposed_shipments");

xhr.send(data);
import requests

url = "https://sandbox.shiphawk.com/api/v4/orders/:id/proposed_shipments"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "pshp_db9hy14Q",
        "carrier": "FedEx",
        "carrier_code": "fedex",
        "service_name": "FedEx Ground Home Delivery",
        "estimated_delivery_date": "2017-10-24T00:00:00+00:00",
        "service_days": 1,
        "standardized_service_name": "Ground",
        "carrier_type": "Small Parcel",
        "is_customer_tariff": true,
        "insurance_type": "carrier",
        "order_id": "ord_Ay6thkDd",
        "total_price": 22.26,
        "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": 22.26,
            "packing": 0,
            "insurance": 0,
            "accessorials": 0,
            "duties": 0,
            "taxes": 0
        },
        "origin_address": {
            "name": "Max Contact Person",
            "company": "Shiphawk Warehouse 3",
            "street1": "26 Castillian Dr",
            "street2": "Suite C",
            "city": "Goleta",
            "state": "CA",
            "zip": "93117",
            "country": "US",
            "phone_number": "805-555-5555",
            "email": null,
            "is_residential": false,
            "is_po_box": false,
            "address_type": "commercial"
        },
        "destination_address": {
            "name": "Tish Demsas",
            "company": "",
            "street1": "235 W Quinto St",
            "street2": "Apt 3",
            "city": "Santa Barbara",
            "state": "CA",
            "zip": "93105",
            "country": "US",
            "phone_number": null,
            "email": null,
            "is_residential": true,
            "is_po_box": false,
            "address_type": "residential"
        },
        "origin_accessorials": [],
        "destination_accessorials": [],
        "origin_instructions": null,
        "destination_instructions": null,
        "packages": [
            {
                "length": null,
                "width": null,
                "height": null,
                "weight": 1,
                "volume": null,
                "value": 35,
                "freight_class": null,
                "nmfc": null,
                "packing_type": "box",
                "package_type": null,
                "package_quantity": null,
                "quantity": 2,
                "commodity_description": "",
                "hazmat": false,
                "un_or_na_number": null,
                "proper_shipping_name": null,
                "hazard_class_or_division": null,
                "packing_group": null,
                "emergency_response_phone_number": null,
                "emergency_contact_name": null,
                "emergency_contact_phone_number": null,
                "materials": [],
                "labors": [],
                "package_items": []
            }
        ],
        "shipment_line_items": [
            {
                "order_line_item_id": "ordi_hQ01mrys",
                "quantity": 1,
                "name": "Tie (Color: Black)",
                "description": "Tie (Color: Black)",
                "sku": "TBLK",
                "upc": "",
                "value": 35,
                "weight": 0,
                "hs_code": null,
                "country_of_origin": null,
                "child_sku": null,
                "child_sku_quantity": 0
            },
            {
                "order_line_item_id": "ordi_dYgaNdfB",
                "quantity": 1,
                "name": "T-Shirt (Color: Black, Size: Large)",
                "description": "T-Shirt (Color: Black, Size: Large)",
                "sku": "TLBK",
                "upc": "",
                "value": 35,
                "weight": 1,
                "hs_code": null,
                "country_of_origin": null,
                "child_sku": null,
                "child_sku_quantity": 0
            }
        ],
        "ship_date": "2017-10-25",
        "created_at": "2017-10-23T17:48:08+00:00",
        "policies_applied": [
            {
                "id": "spol_yBnY9nKx",
                "name": "Tester111"
            }
        ],
        "fees": {
            "insurance": {
                "active": true
            }
        },
        "include_return_label": false,
        "shipment_billing": {
            "shortcut_account_number": null,
            "account_number": null,
            "country": "US",
            "zip": null,
            "bill_to": "sender",
            "carrier_code": null,
            "service_code": null,
            "service_name": null
        },
        "duties_taxes_billing": {
            "shortcut_account_number": null,
            "account_number": null,
            "country": "US",
            "zip": null,
            "bill_to": "sender",
            "carrier_code": null,
            "service_code": null,
            "service_name": null
        },
        "reference_numbers": [],
        "warehouse_code": null
    }
]
 
Suggest Edits

Create an Aggregated Document for Orders

Aggregate documents allow you to retrieve many order documents consolidated into a single PDF or ZPL file.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/:id/aggregated_documents
curl -X POST \
  https://sandbox.shiphawk.com/api/v4/orders/aggregated_documents \
  -H 'x-api-key: Your-Api-Key' \
  -d '{
    "ids": ["ord_mxP20efh", "ord_BdsjNWy1"],
    "document_type": "package_label"
}'
A binary file was returned

You couldn't be authenticated

{
  "aggregated_document_id": "adoc_WF2vMyrD",
  "total_orders": 2,
    "total_documents": 2,
    "total_booked_shipments_with_documents": 2,
    "total_booked_shipments_without_documents": 0,
    "total_unbooked_shipments": 0,
    "pdf": "https://somedocumentURL.pdf",
    "zpl": "https://somedocumentURL.zpl"
}

Body Params

ids
string
required

ShipHawk assigned order IDs you want to retrieve an aggregate document for.

document_types
string
required

Indicates the type of document you want in aggregate. Takes values "bol", "address_label", "package_label","package_labels_combined", "return_package_label", "commercial_invoice", "packing_slip"

 
Suggest Edits

Search Orders

Search across all of your orders to find orders that meet certain criteria.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/orders/simple
curl -X GET \
  https://sandbox.shiphawk.com/api/v4/orders/simple?page=1&per_page=1 \
  -H 'x-api-key: Your-Api-Key' \
A binary file was returned

You couldn't be authenticated

[{
	“id”: “ord_x3M3T85J”,
	“order_number”: “100516723",
	“source”: “magento”,
	“total_price”: 237.59,
	“destination_address”: {
		“name”: “Max  Horrell”,
		“company”: “”,
		“street1”: “5675 Roblar Road”,
		“street2”: “”,
		“city”: “Petaluma”,
		“state”: “CA”,
		“zip”: “60601",
		“country”: “US”,
		“phone_number”: “8058054194",
		“email”: “max@shiphawk.com”,
		“is_residential”: false
	},
	“source_system_processed_at”: “2017-10-23T21:17:02+00:00,
	“status”: “new”,
	“created_at”: “2017-10-23T21:15:25+00:00,
	“batch_id”: null,
	“batch_name”: null,
	“tags”: [],
	“warehouse”: null,
	“single_sku”: “TE-WSW94XL, TE-WHJMP69L”,
	“hold_until”: null
}]

Headers

page
string
per_page
string
status
string
created_at
date
updated_at
date
q
string
 
Suggest Edits

Delete an Order

Delete an existing Order

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/orders/id
curl -X DELETE https://sandbox.shiphawk.com/api/v4/orders/ord_a9Q11tYQ \
  -H 'Host: sandbox.shiphawk.com' \
  -H 'X-Api-Key: [Your-Api-Key]' \
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required
 
Suggest Edits

Shipment Resources

 
Suggest Edits

Shipment Request Object

 

Parameters are optional unless noted.

Parameter
Type
Description, Defaults

proposed_shipment_id

string

rate_id

string

origin_address

hash

{
  public_id: string
  name: string
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
  phone_number: string
  email: string
  is_residential: boolean
  is_warehouse: boolean
  address_type: string
}

destination_address

hash

{
  public_id: string
  name: string
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
  phone_number: string
  email: string
  is_residential: boolean
  is_warehouse: boolean
  address_type: string
}

pickup

array[hash]

List of:
{
  start_time: datetime
  end_time: datetime
}

accessorials

array[hash]

List of:
{
  type: string
  value: string
  optional_value: string
}

type is required

reference_numbers

array[hash]

List of:
{
  id: string
  name: string
  value: string
}

origin_instructions

string

destination_instructions

string

assignee_id

string

origin_network_location_id

string

destination_network_location_id

string

order_id

string

order_number

string

carrier

string

service_name

string

carrier_service_code

string

label_format

string

include_return_label

boolean

is_external

boolean

packages

array[hash]

List of (TODO: packages params )

Suggest Edits

Shipment Response Object

 
Attribute
Type
Description

id

string

shid

integer

origin_address

hash

{
  public_id: string
  name: string
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
  phone_number: string
  email: string
  is_residential: boolean
  is_warehouse: boolean
  address_type: string
  code: string
}

destination_address

hash

{
  public_id: string
  name: string
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
  phone_number: string
  email: string
  is_residential: boolean
  is_warehouse: boolean
  address_type: string
  code: string
}

*carrier

string

carrier_code

string

carrier_scac

string

carrier_type_code

string

is_external

boolean

is_customer_tariff

boolean

is_international

boolean

service_name

string

service_level

string

insurance_type

string

total_price

string

tracking_number

string

documents

array[hash]

Array of:
{
  id: string
  customer_uploaded: boolean
  type: string
  extension: string
  code: string
  url: string
  meta_data: hash
  created_at: decimal
}

price_details

hash

{
  shipping: decimal
  packing: decimal
  insurance: decimal
  pickup: decimal
  delivery: decimal
  accessorials: decimal
  duty: decimal
  taxes: decimal
}

dispatch_details

hash

{
  id: string
  pickup_date: date
  pickup_start_time: date
  pickup_end_time: date
  dispatch_instructions: string
  sent_at: date
  sent_type: string
  confirmed_at: date
  confirmation_number: string
  bol_number: string
  status: string
  shipment_id: string
  error_message: string
}

final_mile

string

packages

array[object]

TODO List of Shipment Package Response objects

shipment_line_items

array[hash]

List of:
{
  order_line_item_id: string
  quantity: string
  name: string
  description: string
  sku: string
  upc: string
  value: decimal
  weight: decimal
  hs_code: string
  country_of_origin: string
  child_sku: string
  child_sku_quantity: integer
  line_number: integer
}

assignee_id

string

origin_network_location_id

string

destination_network_location_id

string

reference_numbers

array[object]

List of Reference Number Response objects

origin_instruction

string

destination_instructions

string

shiphawk_managed

boolean

is_external

boolean

print_package_labels_enabled

boolean

exceptions

array[hash]

List of:
{
  id: string
  is_resolved: boolean
  resolved_at: date
  created_at: date
}

est_delivery_date

date

service_days

integer

order_id

string

order_number

string

combined_order_numbers

array[string]

label_url

string

label_format

string

label_document_id

string

label_pdf_url

string

label_pdf_document_id

string

label_zpl_url

string

label_zpl_document_id

string

carrier_report_date

string

label_source

string

created_at

date

updated_at

date

created_by

hash

{
  type: string
  name: string
}

actual_pickup_time

date

shipment_billing

hash

{
  shortcut_account_number: string
  account_number: string
  country: string
  zip: string
  bill_to: string
  carrier_code: string
  service_code: string
  service_name: string
}

duties_taxes_billing

hash

{
  shortcut_account_number: string
  account_number: string
  country: string
  zip: string
  bill_to: string
  carrier_code: string
  service_code: string
  service_name: string
}

packing_slip_template

hash

{
  size: string
  advanced_size: string
}

can_attach_bol

boolean

cannot_attach_bol_reason

string

accessorials

array[object]

List of Accessorial Response objects

is_generate_commercial_invoice

string

Suggest Edits

Shipment Billing Details Request Object

 

Parameters are optional unless noted.

Parameter
Type
Description, Defaults

bill_to

string

Required. One of:
sender third_party recipient

carrier_code

string

service_code

string

account_number

string

name

string

company

string

phone_number

string

street1

string

street2

string

city

string

state

string

`zip

string

country

string

Suggest Edits

Shipment Billing Details Response Object

 
Attribute
Type
Description

bill_to

string

Required. One of:
sender third_party recipient

carrier_code

string

service_code

string

account_number

string

name

string

company

string

phone_number

string

street1

string

street2

string

city

string

state

string

`zip

string

country

string

Suggest Edits

Shipment Accessorials Response Object

 
Attribute
Type
Description

accessorial_type

string

cod_amount

string

Present if accessorial is collect on delivery

payment_types

array[string]

remittance_address

{
  public_id, string
  name, string
  company, string
  street1, string
  street2, string
  city, string
  state, string
  zip, string
  country, string
  phone_number, string
  email, string
  is_residential, boolean
  is_warehouse, boolean
  address_type, string
  code, string
}

**`add_freight_charges

boolean

price

decimal

Suggest Edits

Create a New Shipment

 

Header Auth

 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",
        "label_format":"PDF"
        "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'
A binary file was returned

You couldn't be authenticated

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

label_format
string

You may pass in either PDF or ZPL

 

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.

 

Header Auth

 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"
        }
    }
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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" 
  }
}
A binary file was returned

You couldn't be authenticated

{
    "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.

 

Header Auth

 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]]"
A binary file was returned

You couldn't be authenticated

{
	"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.

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://sandbox.shiphawk.com/api/v4/shipments/id
curl --request DELETE \
  --url https://sandbox.shiphawk.com/api/v4/shipments/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://sandbox.shiphawk.com/api/v4/shipments/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://sandbox.shiphawk.com/api/v4/shipments/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://sandbox.shiphawk.com/api/v4/shipments/id");

xhr.send(data);
import requests

url = "https://sandbox.shiphawk.com/api/v4/shipments/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
int32
required

required

 

Example Response

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

	...
}
Suggest Edits

Retrieve the URL of the label(s) for a Parcel Shipment

Return a shipment's packages label hrefs.

 

Header Auth

 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'\
A binary file was returned

You couldn't be authenticated

{
  "url": "https://assets.shiphawk.com/uploads/package_labels_combined_abe6b2df3f10a6ff167d.pdf",
}

Query Params

label_format
string
 
Suggest Edits

Retrieve the URL of a BOL PDF File

 

Header Auth

 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}'
A binary file was returned

You couldn't be authenticated

{
  "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 a Commercial Invoice PDF file

 

Header Auth

 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}'
A binary file was returned

You couldn't be authenticated

{
  "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 an Address Label PDF File

 

Header Auth

 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}'
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments/id/tracking
curl --request GET \
  --url https://sandbox.shiphawk.com/api/v4/shipments/id/tracking
var request = require("request");

var options = { method: 'GET',
  url: 'https://sandbox.shiphawk.com/api/v4/shipments/id/tracking' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://sandbox.shiphawk.com/api/v4/shipments/id/tracking")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://sandbox.shiphawk.com/api/v4/shipments/id/tracking");

xhr.send(data);
import requests

url = "https://sandbox.shiphawk.com/api/v4/shipments/id/tracking"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/shipments/id/tracking
curl --request POST \
  --url https://sandbox.shiphawk.com/api/v4/shipments/id/tracking
var request = require("request");

var options = { method: 'POST',
  url: 'https://sandbox.shiphawk.com/api/v4/shipments/id/tracking' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://sandbox.shiphawk.com/api/v4/shipments/id/tracking")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://sandbox.shiphawk.com/api/v4/shipments/id/tracking");

xhr.send(data);
import requests

url = "https://sandbox.shiphawk.com/api/v4/shipments/id/tracking"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/shipments?page=1&per_page=100
curl -X GET -H "X-Api-Key: [Your-Api-Key]" 
"https://sandbox.shiphawk.com/api/v4/shipments?page=1&per_page=100"
A binary file was returned

You couldn't be authenticated

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

page
string
required
per_page
string
required

Maximum of 100 records per page

 
Suggest Edits

Proposed Shipment Resources

 
Suggest Edits

Proposed Shipment Request Object

 

Parameters are optional unless specified.

Parameter
Type
Description, Defaults

rate_id

string

service_name

string

service_code

string

carrier_code

string

insurance_option

string

One of:
add_insurance no_insurance

self_packed

boolean

packages

array

List of Proposed Shipment Package Request objects

pro_number

string

origin_instructions

string

destination_instructions

string

origin_address

hash

Object:
{
  first_name: string
  last_name: string
  name: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
  phone_number: string
  email: string
  company: string
  location_type: string
  code: string
  is_residential: string
}

destination_address

hash

Object:
{
  first_name: string
  last_name: string
  name: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
  phone_number: string
  email: string
  company: string
  location_type: string
  code: string
  is_residential: string
  is_po_box: boolean
}

alternate_return_address

hash

Object:
{
  first_name: string
  last_name: string
  name: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
  phone_number: string
  email: string
  company: string
  location_type: string
  code: string
  is_residential: string
}

reference_numbers

array

List of Reference Number Request objects

fees

hash

Object:
{
  insurance: {
    active: boolean
  }
}

origin_accessorials

array[object]

List of:
{
  type: string
  value: string
  option_value: string
}

destination_accessorials

array[object]

List of:
{
  type: string
  value: string
  option_value: string
}

include_return_label

boolean

shipment_billing

hash

Shipment Billing Details Request object

duties_taxes_billing

hash

Shipment Billing Details Request object

pickup

hash

Object:
{
  start_time: date
  end_time: date
}

warehouse_code

string

Suggest Edits

Proposed Shipment Response 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_name

string

estimated_delivery_date

date

ISO 8601 formatted estimated date of delivery, i.e., YYYY-MM-DD

service_days

integer

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

One of:
truckload blanket_wrap courier small_parcel ltl intermodal auto local_delivery home_delivery final_mile custom_carrier

tariff_insurance_rule

string

One of:
carrier third_party no_insurance

is_customer_tariff

boolean

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

insurance_type

string

One of:
no_insurance carrier third_party shiphawk or declined

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

Object:
{
  price: decimal
  final_mile_service_name: string
  final_mile_service_days: integer
  using_final_mile_carrier: boolean
  final_mile_carrier: string
}

price_details

object

Object:
{
  shipping: decimal
  packing: decimal
  insurance: decimal
  accessorials: decimal
  duties: decimal
  taxes: decimal
}

origin_address

hash

Optional
Address

destination_address

hash

Optional
Address

alternate_return_address

hash

Optional
Address

origin_accessorials

array[object]

Array of Object:
{
  id: string
  side: string
  price: number
  name: string
  default: boolean
  type: string
  accessorial_type: string
  value: decimal
  option_value: decimal
  accessorial_options: {
    title: string
    value: decimal
  }
}

destination_accessorials

array of objects

Array of Object:
{
  id: string
  side: string
  price: number
  name: string
  default: boolean
  type: string
  accessorial_type: string
  value: decimal
  option_value: decimal
  accessorial_options: {
    title: string
    value: decimal
  }
}

origin_instructions

string

destination_instructions

string

packages

array[object]

List of Proposed Shipment Package Response objects

shipment_line_items

array[hash]

Array of hashes representing the shipment line items for this proposed shipment:
{
  order_line_item_id: integer
  quantity: integer
  name: string
  description: string
  sku: string
  upc: string
  value: number
  weight: number
  hs_code: string
  country_of_origin: string
  child_sku: string
  child_sku_quantity: integer
  line_number: intege
}

ship_date

string

ISO 8601 formatted date, i.e. YYYY-MM-DD

created_at

string

ISO 8601 formatted date, i.e. YYYY-MM-DD

policies_applied

array

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

fees

hash

Hash determining whether there are active fees (currently supporting insurance fees):
{
  insurance: {
    active: boolean
  }
}

include_return_label

boolean

shipment_billing

hash

Shipment Billing Details Response object

duties_taxes_billing

hash

Shipment Billing Details Response object

reference_numbers

array[object]

Array of Order Response Reference Number objects

warehouse_code

string

warehouse_id

string

error_message

string

rate_id

string

Suggest Edits

Proposed Shipment Package Response 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

length

decimal

width

decimal

height

decimal

weight

decimal

volume

decimal

value

decimal

freight_class

string

nmfc

string

packing_type

string

package_type

string

package_quantity

integer

quantity

integer

commodity_description

string

hazmat

boolean

carrier_container

string

unpacked_item_type_id

string

unpacked_item_type_name

string

number_of_units

integer

hazmat_data

object

Hazmat Data Response object

materials

array[hash]

List of packing material:
{
  name: string
  unit_cost: decimal
  ext_cost: decimal
  weight: decimal
  quantity: integer
}

labors

array[hash]

List of:
{
  name: string
  unit_cost: decimal
  ext_cost: decimal
  quantity: decimal
  uom: string
}

package_items

array[hash]

List of:
{
  id: string
  product_sku: string
  product_upc: string
  product_sku_packing_code: string
  product_child_sku: integer
  product_child_sku_quantity: integer
  item_name: string
  description: string
  length: decimal
  width: decimal
  height: decimal
  volume: decimal
  value: decimal
  unpacked_item_type_id: string
  require_crating: boolean
  freght_class: string
  nmfc: string
  hs_code: string
  country_of_origin: string
  order_line_item_id: string
  order_line_item_source_system_id: string
}

handling_unit_packages

array[hash]

List of:
{
  weight: decimal
  value: decimal
  package_type: string
  hazmat: boolean
  freight_class: string
  tracking_number: string
  nmfc: string
  number_of_units: integer
  commodity_description: string
  hazmat_data: Hazmat Data Response object
  package_items: See package_items definition above
}

accessorials

array[hash]

List of:
{
  id: string
  side: string
  price: number
  name: string
  default: boolean
  type: string
  accessorial_type: string
  value: decimal
  option_value: decimal
  accessorial_options: {
    title: string
    value: decimal
  }
}

Suggest Edits

Create a New Proposed Shipment

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/:id/proposed_shipments/
curl 'https://qa.shiphawk.com/api/v4/orders/ord_vY4Ecgxw/proposed_shipments' 
  {
    "id": "pshp_cDRnNnB5",
    "carrier": "FedEx",
    "carrier_code": "fedex",
    "service_name": "FedEx Ground",
    "estimated_delivery_date": null,
    "service_days": null,
    "standardized_service_name": null,
    "carrier_type": "Small Parcel",
    "is_customer_tariff": null,
    "insurance_type": null,
    "order_id": "ord_vY4Ecgxw",
    "total_price": null,
    "final_mile": {
      "price": 0.0,
      "final_mile_service_name": null,
      "final_mile_service_days": null,
      "using_final_mile_carrier": null,
      "final_mile_carrier": null
    },
    "price_details": {
      "shipping": 0.0,
      "packing": 0.0,
      "insurance": 0.0,
      "accessorials": 0.0,
      "duties": 0.0,
      "taxes": 0.0
    },
    "origin_address": {
      "name": "",
      "company": "Ergomotion",
      "street1": "13169 Slover Ave",
      "street2": "STE B",
      "city": "Fontana",
      "state": "CA",
      "zip": "92337",
      "country": "US",
      "phone_number": "805-979-9922",
      "email": "NPatel@ergomotion.com",
      "is_residential": false,
      "address_type": "commercial"
    },
    "destination_address": {
      "name": "Donald Rickley",
      "company": "",
      "street1": "525 Stone Ln",
      "street2": "",
      "city": "Chapman",
      "state": "KS",
      "zip": "67431",
      "country": "US",
      "phone_number": "805-770-1642",
      "email": "mikel@shiphawk.com",
      "is_residential": false,
      "address_type": "commercial"
    },
    "origin_accessorials": [],
    "destination_accessorials": [{
      "id": null,
      "price": null,
      "side": null,
      "name": null,
      "default": null,
      "type": "signature_adult_delivery"
    }],
    "origin_instructions": null,
    "destination_instructions": null,
    "packages": [{
      "length": 1.0,
      "width": 2.0,
      "height": 3.0,
      "weight": 4.0,
      "volume": 0.0,
      "freight_class": "85",
      "packing_type": "box",
      "package_type": null,
      "package_quantity": null,
      "materials": [],
      "labors": [],
      "package_items": [{
        "product_sku": "300146",
        "product_sku_packing_code": null,
        "item_name": "Small Parcel",
        "description": null,
        "length": 1.0,
        "width": 2.0,
        "height": 3.0,
        "weight": 4.0,
        "volume": 0.0,
        "value": 123.0,
        "unpacked_item_type_id": 33694,
        "require_crating": null,
        "freight_class": "85",
        "nmfc": null,
        "hs_code": null,
        "country_of_origin": "US",
        "xid": null,
        "order_line_item_id": "ordi_hKRr4Rhb"
      }],
      "quantity": 1
    }],
    "ship_date": "2016-12-29",
    "policies_applied": [],
    "fees": {
      "insurance": {
        "active": false
      }
    },
    "include_return_label": false
  }
A binary file was returned

You couldn't be authenticated

{
	"id": "pshp_cDRnNnB5",
	"carrier": "FedEx",
	"carrier_code": "fedex",
	"service_name": "FedEx Ground",
	"estimated_delivery_date": null,
	"service_days": null,
	"standardized_service_name": null,
	"carrier_type": "Small Parcel",
	"is_customer_tariff": null,
	"insurance_type": null,
	"order_id": "ord_vY4Ecgxw",
	"total_price": null,
	"final_mile": {
		"price": 0.0,
		"final_mile_service_name": null,
		"final_mile_service_days": null,
		"using_final_mile_carrier": null,
		"final_mile_carrier": null
	},
	"price_details": {
		"shipping": 0.0,
		"packing": 0.0,
		"insurance": 0.0,
		"accessorials": 0.0,
		"duties": 0.0,
		"taxes": 0.0
	},
	"origin_address": {
		"name": "",
		"company": "Ergomotion",
		"street1": "13169 Slover Ave",
		"street2": "STE B",
		"city": "Fontana",
		"state": "CA",
		"zip": "92337",
		"country": "US",
		"phone_number": "805-979-9922",
		"email": "NPatel@ergomotion.com",
		"is_residential": false,
		"address_type": "commercial"
	},
	"destination_address": {
		"name": "Donald Rickley",
		"company": "",
		"street1": "525 Stone Ln",
		"street2": "",
		"city": "Chapman",
		"state": "KS",
		"zip": "67431",
		"country": "US",
		"phone_number": "805-770-1642",
		"email": "mikel@shiphawk.com",
		"is_residential": false,
		"address_type": "commercial"
	},
	"origin_accessorials": [],
	"destination_accessorials": [{
		"id": null,
		"price": null,
		"side": null,
		"name": null,
		"default": null,
		"type": "signature_adult_delivery"
	}],
	"origin_instructions": null,
	"destination_instructions": null,
	"packages": [{
		"length": 1.0,
		"width": 2.0,
		"height": 3.0,
		"weight": 4.0,
		"volume": 0.0,
		"freight_class": "85",
		"packing_type": "box",
		"package_type": null,
		"package_quantity": null,
		"materials": [],
		"labors": [],
		"package_items": [{
			"product_sku": "300146",
			"product_sku_packing_code": null,
			"item_name": "Small Parcel",
			"description": null,
			"length": 1.0,
			"width": 2.0,
			"height": 3.0,
			"weight": 4.0,
			"volume": 0.0,
			"value": 123.0,
			"unpacked_item_type_id": 33694,
			"require_crating": null,
			"freight_class": "85",
			"nmfc": null,
			"hs_code": null,
			"country_of_origin": "US",
			"xid": null,
			"order_line_item_id": "ordi_hKRr4Rhb"
		}],
		"quantity": 1
	}],
	"ship_date": "2016-12-29",
	"policies_applied": [],
	"fees": {
		"insurance": {
			"active": false
		}
	},
	"include_return_label": false
}

Body Params

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

Retrieve a Proposed Shipment

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

Update a Proposed Shipment

Create a new proposed shipment.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/orders/:id/proposed_shipments/:proposed_shipment_id
curl -X POST 
	-H "Content-Type: application/json" 
	-H "X-Api-Key: [Your-Api-Key]"  
  -d '{
        "standardized_service_name": "Ground",
        "carrier": "FedEx",
        "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"
        },
        "packages": [{
            "length": 10,
            "width": 10,
            "height": 10,
            "weight": 10,
            "freight_class": ,
            "value": ,
            "tracking_number": ,
            "packing_type": "boxed",
            "package_type": "null",
            "package_items": [{
              "order_line_item_id": "ordi_8NvJPMjE", 
              "product_sku": "sku_phonecase2"
             }]
        }]
        "origin instructions": "",
        "reference_numbers": [
        {
            "id": "shpr_HMRjWs5b",
            "code": "invoice_id",
            "value": "H32HKHU3",
            "name": null
        },
        {
            "id": "shpr_KfSJz5xp",
            "code": "other_id",
            "value": "TRX-23412LKJ",
            "name": "Transaction Number"
        }
    ],
    } ' "https://sandbox.shiphawk.com/api/v4/orders/ord_AyhTpdFz/proposed_shipments/pshp_mmwefvGy"
A binary file was returned

You couldn't be authenticated

{
	"id": "pshp_V1Y6nbTA",
	"carrier": "FedEx",
	"carrier_code": "fedex",
	"service_level": null,
	"estimated_delivery_date": "2016-08-11T00:00:00Z",
	"service_days": 4,
	"standardized_service_name": "Ground",
	"carrier_type": "Small Parcel",
	"is_customer_tariff": true,
	"order_id": "ord_ybfcDDx9",
	"total_price": 11.92,
	"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": 0.0,
		"packing": 0.0,
		"insurance": 0.0,
		"accessorials": 0.0,
		"duties": 0.0,
		"taxes": 0.0
	},
	"origin_address": {
		"name": "Sue Smith Origin",
		"company": null,
		"street1": "101 State Street",
		"street2": null,
		"city": "Santa Barbara",
		"state": "CA",
		"zip": "93101",
		"country": "US",
		"phone_number": null,
		"email": null,
		"is_residential": false,
		"address_type": "commercial"
	},
	"destination_address": {
		"name": "Cheryl Grant",
		"company": null,
		"street1": "6134 North Odell Avenue",
		"street2": null,
		"city": "Chicago",
		"state": "IL",
		"zip": "60631",
		"country": "US",
		"phone_number": null,
		"email": null,
		"is_residential": false,
		"address_type": "commercial"
	},
	"origin_accessorials": [],
	"destination_accessorials": [{
		"id": "216fa58f-eb5f-4709-881c-1b8450df486c",
		"price": 4.25,
		"side": "destination",
		"name": "Direct Signature Required",
		"default": false,
		"type": "signature_direct_delivery"
	}, {
		"id": "66d48a01-09be-45c3-879c-c1f609f33084",
		"price": 4.25,
		"side": "destination",
		"name": "Indirect Signature Required",
		"default": false,
		"type": "signature_indirect_delivery"
	}, {
		"id": "6348d2b7-428c-4329-ac16-3787556b0362",
		"price": 5.25,
		"side": "destination",
		"name": "Adult Signature Required",
		"default": false,
		"type": "signature_adult_delivery"
	}],
	"packages": [{
		"length": 10.0,
		"width": 10.0,
		"height": 10.0,
		"weight": 10.0,
		"volume": 0.58,
		"freight_class": null,
		"packing_type": "boxed",
		"package_type": null,
		"materials": [],
		"labors": [],
		"package_items": [{
			"product_sku": "sku_phonecase2",
			"product_sku_packing_code": null,
			"item_name": "Small Parcel",
			"description": null,
			"length": 10.0,
			"width": 10.0,
			"height": 10.0,
			"weight": 10.0,
			"volume": 0.58,
			"value": 0.0,
			"unpacked_item_type_id": 33694,
			"require_crating": null,
			"freight_class": null,
			"nmfc": null,
			"hs_code": null,
			"country_of_origin": null,
			"xid": null,
			"order_line_item_id": "ordi_8NvJPMjE"
		}]
	}],
	"ship_date": "2016-08-05",
	"policies_applied": []
}

Body Params

carrier
string

The carrier specified for the proposed shipment.

standardized_service_name
string

The standardized name of the service to be provided by the carrier for the proposed shipment.

packages
array

The packages that are to be shipped with the carrier for the proposed shipment. Within each package, you can associate which package items are associated with it.

origin_address
array of strings

The origin address for the proposed shipment.

destination_address
object

The destination address for the proposed shipment.

 
origin_instructions
string
destination_instructions
string
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

 
Suggest Edits

Rate Resources

 
Suggest Edits

Rate Request Object

 

Parameters are optional unless specified.

Attribute
Type
Description

origin_address

hash

required
{
  id: string
  name: string
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  phone_number: string
  email: string
  code: string
  is_residential: boolean
  country: string
}

destination_address

hash

required
{
  id: string
  name: string
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  phone_number: string
  email: string
  code: string
  is_residential: boolean
  country: string
  is_po_box: boolean
}

source_system

string

source_system_domain

string

source_system_order_id

string

display_rate_detail

boolean

apply_rules

boolean

third_party_fulfillment

boolean

display_rate_uuid

boolean

usps_parcel_select

boolean

usps_library_mail

boolean

carrier_filter

array

carrier_type_filter

array

carrier_service_code

string

standardized_service_filter

string

One of:
White Glove Threshold Standard Courier Room of Choice Flatbed Local Delivery Standard Freight Same-Day Freight Guaranteed Freight Next Day Two-Day Three-Day International Economy International Priority Ground Restricted Ground Standard Vehicle Same Day Flat Rate Same Day Freight Blanket Wrap

rate_filter

string

One of:
best consumer top_10

service_days_filter

integer

ship_date

string

origin_accessorials

hash

destination_accessorials

hash

network_location

string

insurance_option

string

One of:
add_insurance no_insurance

order_source

string

rate_source

string

currency_codes

string

One of:
AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BOV BRL BSD BTN BWP BYN BZD CAD CDF CHE CHF CHW CLF CLP CNY COP COU CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS INR IQD IRR ISK JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRO MUR MVR MWK MXN MXV MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD SSP STD SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD USN UYI UYU UZS VEF VND VUV WST XAF XAG XAU XBA XBB XBC XBD XCD XDR XOF XPD XPF XPT XSU XTS XUA XXX YER ZAR ZMW ZWL

warehouse_id

string

warehouse_code

string

*shipment_line_items

array[hash]

List of:
{
  quantity: integer
  source_system_id: string
  sku: string

items

array

required
List of Rate Item Request objects

shipment_billing

hash

{
  bill_to: string, one of sender third_party recipient
  carrier_code: string
  service_code: string
  account_number: string
  name: string
  company: string
  phone_number: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
}

duties_billing_taxes

hash

{
  bill_to: string, one of sender third_party recipient
  carrier_code: string
  service_code: string
  account_number: string
  name: string
  company: string
  phone_number: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string
}

Suggest Edits

Rate Item Request Object

 

Parameters are optional unless specified.

Attribute
Type
Description

item_type

string

One of:
parcel handling_unit unpacked

type

string

One of:
parcel handling_unit unpacked
Default: parcel

accessorials

array

length

decimal

width

decimal

height

decimal

weight

decimal

weight_uom

string

One of:
lbs, oz

volume_cubic_ft

decimal

value

decimal

handling_unit_type

string

quantity

integer

Default: 1

freight_class

string

nmfc

string

description

string

can_ship_parcel

boolean

Default: false

optimize_packing

boolean

Default: false

ship_individually

boolean

package_type

string

package_quantity

integer

hs_code

string

country_of_origin

string

product_sku

string

require_crating

boolean

Default: false

unpacked_item_type_id

string

hazmat

boolean

Default: false

carrier_container

string

number_of_units

integer

Default: 1

available_in

hash

warehouse_code

string

order_line_item_source_system_id

string

origin_address

hash

{
  id: string
  name: string
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  phone_number: string
  email: string
  code: string
  is_residential: boolean
  country: string, Default: 'US'
}

hazmat_data

hash

See Orders Hazmat Data Request Object

handling_unit_packages

array[hash]

List of:
{
  package_type: string
  package_quantity: integer
  weight, type: decimal
  nmfc, type: string
  freight_class: string
  hazmat, type: boolean Default false
  number_of_units: integer
  commodity_description: string
  hazmat_data: see Orders Hazmat Data Request Object
}

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.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/rates/
curl -H "Content-Type: application/json" -X POST -d'{
  "items":[
    {
    	"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'
A binary file was returned

You couldn't be authenticated

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

Batch Object

 

Attribute
Type
Description

id

string

required

name

string

required

items_count

integer

Number of orders in this batch

created_at

date

Suggest Edits

Create a Batch

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/batches/
curl -X POST -H "X-Api-Key: ce3d2fad3bfd3ee98ada62173b350436" -H "Cache-Control: no-cache" -d '{
 "name": "Batch 4"
}' "https://sandbox.shiphawk.com/api/v4/batches"
A binary file was returned

You couldn't be authenticated

{
  "id": "bat_wy5hexwc",
  "name": "Batch 4",
  "items_count": 0,
  "created_at": "2017-03-23T23:24:53Z"
}

Body Params

name
string
 
Suggest Edits

Add Orders to Batch

 

Header Auth

 Authentication is required for this endpoint.
posthttps://sandbox.shiphawk.com/api/v4/batches/id/orders
curl -X POST -H "X-Api-Key: ce3d2fad3bfd3ee98ada62173b350436" -H "Cache-Control: no-cache" -d '{
 "order_ids": ["ord_fMK5w1PD", "ord_GEgaBGz0", "ord_XjGW0HAp", "ord_rh55PDjm"],
 "reassign": true
}' "https://sandbox.shiphawk.com/api/v4/batches/bat_wy5hexwc/orders"
A binary file was returned

You couldn't be authenticated

Path Params

id
int32
required

Required. Batch public id

Body Params

order_ids
array of strings

Array of the order public_ids

reassign
boolean
 
Suggest Edits

Retrieve a Batch

 

Header Auth

 Authentication is required for this endpoint.
gethttps://sandbox.shiphawk.com/api/v4/batches/id/
curl -X GET -H "X-Api-Key: f8ddb12667bac8263fd908931efa2e96" -H "Cache-Control: no-cache" " "https://qa.shiphawk.com/api/v4/batches/bat_dtq8TVzf/"
A binary file was returned

You couldn't be authenticated

{
  "id": "bat_dtq8TVzf",
  "name": "Batch 4",
  "items_count": 4,
  "created_at": "2017-03-23T23:47:59Z"
}

Path Params

id
int32
required

Required. Batch public id

 
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

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

 

Header Auth

 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'\
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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]]"
A binary file was returned

You couldn't be authenticated

[
  {
    "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

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

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

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.

 

Header Auth

 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
			}' 
A binary file was returned

You couldn't be authenticated

{
  "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.

 

Header Auth

 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'
	
	
A binary file was returned

You couldn't be authenticated

{
  "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.

 

Header Auth

 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'
A binary file was returned

You couldn't be authenticated

{
  "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.

 

Header Auth

 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"
      }' 
A binary file was returned

You couldn't be authenticated

{
  "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.

 

Header Auth

 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"]}
A binary file was returned

You couldn't be authenticated

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

Validate an Address

Updates the specified address based on USPS address validation.

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

List all Addresses

Returns a list of all addresses you have created.

 

Header Auth

 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'
A binary file was returned

You couldn't be authenticated

[
   {
    "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

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

 

Header Auth

 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 \
A binary file was returned

You couldn't be authenticated

[
  {
    "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

 

Header Auth

 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]]"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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" }'
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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'
A binary file was returned

You couldn't be authenticated

{
	"status": "204"
}
 
Suggest Edits

Retrieve a List of a Shipment's documents

Retrieve an existing shipment by shipment id

 

Header Auth

 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' \
A binary file was returned

You couldn't be authenticated

[
 {
  "id": "doc_jd83k8fy2",
  "type": "label",
  "url": "",
  "file": "",
  "created_at": "2015-11-08T20:57:32Z"
 } 
]
 
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

 

Header Auth

 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}'
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"}'
A binary file was returned

You couldn't be authenticated

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

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.

 

Header Auth

 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" }'
A binary file was returned

You couldn't be authenticated

{
	"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.

 

Header Auth

 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'\
A binary file was returned

You couldn't be authenticated

{
  "body": "my note",
  "tag": "my tag"
}
 
Suggest Edits

Update a Note

Edit an existing note.

 

Header Auth

 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" }'
A binary file was returned

You couldn't be authenticated

{
	"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.

 

Header Auth

 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'\
A binary file was returned

You couldn't be authenticated

[
  {
    "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.

 

Header Auth

 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'
A binary file was returned

You couldn't be authenticated

{
	"status": "204"
}
 
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

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

child_sku

string

Requires ShipHawk to enable your account for "optimize packaging level".

If a child sku is specified, then ShipHawk will "roll-up" orders of individual units into the parent sku.

child_sku_qty

integer

Required if child_sku specified

Specifies the number of child_sku items that get "rolled up" into this sku. For example, if this is a master pack with 25 consumer units, enter the consumer unit sku as the child_sku, and 25 as the child_sku_qty.

child_sku_qty_min

integer

Specifies the minimum number of child_sku items that get "rolled up" into this sku. For example, if 25 consumer units are in a master pack, but you still want to ship 20 as a master pack (and take 5 out), specify 20 as the child_sku_qty_m

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

 

Header Auth

 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"]
   }'
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"]
   }'
A binary file was returned

You couldn't be authenticated

{
  "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.

 

Header Auth

 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' 
A binary file was returned

You couldn't be authenticated

{
  "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.

 

Header Auth

 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'
A binary file was returned

You couldn't be authenticated

[
  {
    "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.

 

Header Auth

 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"]}'
A binary file was returned

You couldn't be authenticated

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

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

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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required
 
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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

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

 

Header Auth

 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"
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required
 
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"
"shipment.create_from_order"

Suggest Edits

Webhook POST examples

Detailed information on the data is being sent back for each webhook event

 

status_update event

{
	"event": "shipment.status_update",
	"status": "in_transit",
	"updated_at": "2017-04-04T10:50:57.821Z",
	"shipment_id": 1311664,
	"shipment_public_id": "shp_KfVyKJNy",
	"order_number": null
}

address_update

{
	"event": "shipment.address_update",
	"from_address": {
		"name": "SB Pack and Post",
		"company": null,
		"email": null,
		"phone_number": "8058809339",
		"street1": "1627 Chapala St.",
		"street2": null,
		"city": "SANTA BARBARA",
		"state": "CA",
		"zip": "93101",
		"country": "US",
		"is_residential": false,
		"updated_at": "2017-04-04T23:54:41.305Z"
	},
	"to_address": {
		"name": "Max Horrell",
		"company": null,
		"email": null,
		"phone_number": "8053352432",
		"street1": "117 Lilly Pond Lane",
		"street2": null,
		"city": "EAST HAMPTON",
		"state": "NY",
		"zip": "11937",
		"country": "US",
		"is_residential": true,
		"updated_at": "2015-06-17T21:18:44.731Z"
	},
	"updated_at": "2017-04-04T23:54:41.125Z",
	"shipment_id": 1030067,
	"shipment_public_id": "shp_nAVbypfV",
	"order_number": null
}

notes_update

{
	"event": "shipment.notes_update",
	"status_notes": [{
		"message": "Not available until 3 pm",
		"created_at": "2017-04-04T23:57:31.873Z",
		"updated_at": "2017-04-04T23:57:31.873Z"
	}],
	"updated_at": "2017-04-04T23:57:03.764Z",
	"shipment_id": 1030067,
	"shipment_public_id": "shp_nAVbypfV",
	"order_number": null
}

timing_update

{
	"event": "shipment.timing_update",
	"actual_delivery_date": null,
	"actual_pickup_time": "2017-04-04T07:00:00.000Z",
	"updated_at": "2017-04-05T15:37:40.301Z",
	"shipment_id": 1405294,
	"shipment_public_id": "shp_tzzkd1nW",
	"order_number": null
}

tracking_update

{
	"event": "shipment.tracking_update",
	"tracking_number": "786135883423",
	"tracking_url": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=786135883423",
	"updated_at": "2017-04-06T17:33:20.543Z",
	"shipment_id": 1405294,
	"shipment_public_id": "shp_tzzkd1nW",
	"order_number": null
}

shipment_create_from_order

{
	"event": "shipment.create_from_order",
	"id": "shp_ZqqSDjaC",
	"shid": "SH1455422",
	"status": "ordered",
	"origin_address": {
		"id": "badr_MAz3KFQD",
		"name": "maxstore",
		"company": null,
		"street1": "26 Castilian Drive, Suite C",
		"street2": null,
		"city": "Goleta",
		"state": "CA",
		"zip": "93117",
		"country": "US",
		"phone_number": "",
		"email": null,
		"is_residential": false,
		"is_warehouse": false,
		"address_type": "commercial",
		"code": null
	},
	"destination_address": {
		"id": "badr_0kkt3eHc",
		"name": "max horrell",
		"company": "123",
		"street1": "316 w alamar",
		"street2": null,
		"city": "Santa Barbara",
		"state": "CA",
		"zip": "93105",
		"country": "US",
		"phone_number": "",
		"email": null,
		"is_residential": false,
		"is_warehouse": false,
		"address_type": "commercial",
		"code": null
	},
	"carrier": "USPS",
	"carrier_code": "usps",
	"carrier_type_code": "small_parcel",
	"is_external": false,
	"is_customer_tariff": false,
	"service_name": "Priority Mail",
	"insurance_type": "no_insurance",
	"total_price": 7.17,
	"tracking_number": "9405510200864427693834",
	"documents": [{
		"id": "doc_KNePFaSw",
		"customer_uploaded": false,
		"type": "label for a package",
		"code": "package_label",
		"url": "https://shiphawk.com/api/v4/public/documents/files/0936208d0a9aac0fe3743226936131b9.pdf",
		"created_at": "2017-04-05T00:02:33.408Z"
	}, {
		"id": "doc_sFE0kBNv",
		"customer_uploaded": false,