Pack and Quote API
The RESTful API calculates packing requirement and/or shipping rates. For the API to work properly, create a warehouse profile to obtain API key and warehouse ID, and add boxes and delivery services. To familiarize with the API features, you may use the online calculator in your warehouse profile for testing.
To avoid per minute quota, requests should be spread out whenever possible.
The common hash types referenced in the API are:
Address Hash
firstName
string, optional
Recipient first name.
streetAddress
list, optional
A list of street address lines.
Province or state abbreviation.
ISO 3166-1 two-letter country code.
Residential or commercial address.
Item Hash
qty
integer, optional
default 1
Item quantity.
Shelf ID as defined in warehouse layout where item is stored.
unitPrice
float, optional
default 0.00
Item unit price.
weight
float, optional
default 0.0001
The weight of each unit of item.
weightUnit
string, optional
default lb
The weight unit of item is "kg", "g", "oz" or "lb".
dimensions
list, optional
default length 0.0001
default width 0.0001
default height 0.0001
A list of dimension hashes. Each dimension hash has attributes:
length float | Item length. |
width float | Item width. |
height float | Item height. |
Maximum 2 dimension hashes allowed.
dimensionUnit
string, optional
default in
The dimension unit of item is "m", "cm", "mm", "ft" or "in".
rotatable
boolean, optional
default true
Item can be rotated in any direction for packing.
packable
boolean, optional
default true
Item is not shipped separately.
strappable
boolean, optional
default true
Package containing the product can be bundled with other packages.
voidFiller
boolean, optional
default false
Item is allowed to fill the void space of another item.
voidDimensions
list, optional
A list of void dimension hashes. Each hash has attributes:
length float | Void space length. |
width float | Void space width. |
height float | Void space height. |
Maximum 3 dimension hashes allowed.
prepackageMinQty
integer, optional
default 1
Minimum quantity required to trigger prepackaging.
prepackages
list, optional
A list of prepackaging hashes. Each hash has attributes:
length float | Prepackage length. |
width float | Prepackage width. |
height float | Prepackage height. |
weight float | Prepackage tare weight. |
capacity integer | Prepackage item capacity. |
Maximum 2 prepackaging hashes allowed.
A hash of product stacking rules. Each hash has attributes:
lengthIncrement float | Length increment per stacked item. |
widthIncrement float | Width increment per stacked item. |
heightIncrement float | Height increment per stacked item. |
maxQty integer | Maximum items per stack. |
A hash of shippable packaging (e.g. manufacturer's original box) with attributes:
length float | Packaging length. |
width float | Packaging width. |
height float | Packaging height. |
weight float | Gross weight of packaging and item. |
irregular boolean | Packaging is irregular shape (e.g. pails, drums or tires). |
preferContainers
list, optional
List of tags of containers preferred for packing.
excludeContainers
list, optional
List of tags of containers to avoid for packing.
excludeServices
list, optional
List of tags of services to avoid.
group
integer, optional
default 0
Pack items separately by group 0, 1 or 2.
Package Hash
Box name or null if item is ship-separately or manufacturer original packaging is used.
Package weight unit is "kg", "g", "oz" or "lb".
Package or pallet height.
Package dimension unit is "m", "cm", "mm", "ft" or "in".
Total value of package content.
ID of bundle to strap package to.
A list of tags, if defined, for box.
Packed Item Hash
voidIndex
integer, optional
The index of the embedding item's void space.
Indicate this item is prepacked with attributes:
id integer | System assigned prepackaging identifier. |
length float | Length of prepackaging. |
width float | Width of prepackaging. |
height float | Height of prepackaging. |
dimensionUnit string | Prepackaging dimension unit is "m", "cm", "mm", "ft" or "in". |
capacity integer | Capacity of prepackaging. |
Service Hash
A hash with attributes:
success boolean | Indicate if delivery service is applicable. |
Total value of merchandise in shipment.
3-letter currency code e.g. USD.
Total gross weight of shipment in kilograms.
Handling fee plus negotiated or standard list shipping rates.
Standard list rates for FedEx Packages and UPS Packages.
freeShipping
boolean, optional
True if shipment qualifies for free shipping, otherwise, omitted.
A hash for estimated delivery date and time with attributes:
date string | MM-DD-YYYY |
time string, optional | HH:MM |
Status Hash
List of messages of type string.
Calculate packing requirements and shipping rates for items. To skip rates, set showRates input parameter to false.
URI
http(s)://api.solvingmaze.com/calculate/key/API_KEY/warehouse/WAREHOUSE_ID
Input Parameters
showRates
boolean, optional
default true
Return shipping rates along with packing requirements.
enableCatalog
boolean, optional
default false
Load default item attributes from product catalog with same SKU.
validateDestination
string, optional
Match destination to a valid U.S. street address and return the match in response using:
ups | UPS Street Level Address Validation API. |
usps | USPS Address API. |
Shipping rates, if requested, are based on input destination not matched address.
destination
hash, optional
Date of shipment hash with attributes:
date string | MM-DD-YYYY |
time string | HH:MM |
voidFill
integer, optional
default 1
Void filling method for items marked as void fillers:
0 | No void filling. |
1 | Pack all void fillers into void spaces or none. |
2 | Pack as many void fillers into void spaces as possible. |
A list of tags of delivery services to use.
Output Parameters
Request status and messages.
Valid street addresss matching input destination. Absent if no match is found.
Input Example
{
"destination": {
"post": "90210",
"region": "CA",
"city": "Beverly Hills",
"country": "US",
"residential": true
},
"items": [
{
"sku": "101",
"name": "Toy",
"qty": 2,
"value": 40,
"weight": 0.7,
"weightUnit": "lb",
"dimensions": [
{
"length": 6,
"width": 2,
"height": 2
}
]
"dimensionUnit": "in",
}
]
}
Output Example
{
"status": {
"success": true,
"messages": [
"One or more shipping services available."
]
},
"services": [
{
"carrier": "USPS",
"service": "Priority Mail Flat Rate",
"rate": 11.35,
"currency": "USD",
"status": {
"success": true
},
"delivery": {
"date": "05-20-2013"
},
"packing": [
{
"container": "USPS Flat Rate Medium Box",
"tags": ["box"],
"weight": 3.2,
"length": 11,
"width": 8.5,
"height": 5.5,
"weightUnit": "lb",
"dimensionUnit": "in",
"value": 40,
"items": [
{
"sku": 1,
"name": "Fish Toy",
"qty": 2
}
]
}
]
}
]
}
The example code calculates shipping rates for an item with multiple quantities. It assumes the warehouse is already configured with shipper info, courier and packaging boxes.
<?php
// new item
$items = array();
$item = array();
$item['sku'] = '105';
$item['qty'] = 2;
$item['name'] = 'Trousers';
$item['weight'] = 0.8;
$item['unitPrice'] = 51.60;
$item['weightUnit'] = 'lb';
$item['dimensionUnit'] = 'in';
$dimensions = array();
$dimensions[] = array('length'=>13, 'width'=>12, 'height'=>2);
$item['dimensions'] = $dimensions;
$items[] = $item;
// destination
$dest = array('country'=>'US', 'region'=>'CA', 'post'=>'90210', 'city'=>'Beverly Hills', 'residential'=>true);
// submit request
$ch = curl_init("http://api.solvingmaze.com/calculate/key/$apiKey/warehouse/$warehouseId");
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_POST, true);
$params = array(
"destination" => $dest,
"items" => $items,
);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
// print response
echo $response;
?>
The example code calculates shipping rates for an item with multiple quantities. It assumes the warehouse is already configured with shipper info, courier and packaging boxes.
require 'net/http'
require 'json'
# new item
items = []
items << {
'sku' => '105',
'qty' => 2,
'name' => 'Trousers',
'weight' => 0.8,
'unitPrice' => 51.60,
'weightUnit' => 'lb',
'dimensionUnit' => 'in',
'dimensions' => [{'length' => 8, 'width' => 6, 'height' => 1}]
}
# destination
dest = {'post' => '90210', 'region' => 'CA', 'country' => 'US', 'city'=>'Beverly Hills', 'residential' => true}
# submit request
uri = URI('http://api.solvingmaze.com/calculate/key/$apiKey/warehouse/$warehouseId')
req = Net::HTTP::Post.new(uri.path, initheader = {'Content-Type' =>'application/json'})
params = {
'items' => items,
'destination' => dest
}
req.body = params.to_json
res = Net::HTTP.start(uri.hostname, uri.port) do |http|
http.request(req)
end
# print response
puts res.body
Using JQuery, the example code calculates shipping rates for an item with multiple quantities. It assumes the warehouse is already configured with shipper info, courier and packaging boxes. Please note, care should be taken to avoid exposing your warehouse ID and API key on a public facing website.
var raw = JSON.stringify(
{
"destination": {
"post": "90210",
"region": "CA",
"city": "Beverly Hills",
"country": "US",
"residential": true
},
"items": [
{
"sku": "105",
"name": "Trousers",
"qty": 2,
"weight": 0.8,
"weightUnit": "lb",
"dimensions": [
{
"length": 13,
"width": 12,
"height": 2
}
],
"dimensionUnit": "in"
}
]
}
);
$.ajax({
type: 'POST',
url: 'http://api.solvingmaze.com/calculate/key/$apiKey/warehouse/$warehouseId',
data: raw,
contentType: "application/json",
dataType: 'json',
success: function(data) { console.log(data); }
});