Documentation

Paccurate is a cartonization and shipping cost-reduction API. These docs are here to help you get started.
See some example "recipes" Get started with an API Key

Overview

Welcome!

Initially built for a production parcel-shipping environment, paccurate is much more than bin-packing math. When provided sufficient information, it will account for the quirks of carrier rate tables, the complexities of dim weight fees, time required to pack, and many other non-intutive costs. Paccurate is practical cartonization for the real world.

Technical Summary

The vision of paccurate has always been one of focus and flexibility. From our use of the terms "box" and "item," it could sound as if items are always things from your inventory, and boxes are always made of cardboard.

However, paccurate doesn't view these as limiting words. A "box" can just as easily be a pallet or a shipping container, and an "item" can just as easily be a master carton or a loaded pallet, ready to be put in a truck.

It's in these ways that paccurate doesn't force your hand. With this perspective, it's apparent that shipping something "this-side-up" applies just as much to packing eggs in a crate as it does to packing pallets on a truck. Rather than try to anticipate every use case out there, we try to expose enough functionality in the API for you to deal with new scenarios as you encounter them.

Introduction

We can get started packing some simple scenarios to show how the "items" and "boxes" are defined and how they can be extended.

One item, one box

Items are defined in classes called itemSets. These are most frequently SKU-based in the real world, and refer to like items where you define the dimensions and properties of a single member item and add a quantity. At a minimum, the following should be set:

refId

A unique, nonnegative integer identifier for this itemSet. These are used only for consistency and later on for defining rules on how you want your items packed.

dimensions

x, y, and z floating point numbers representing the magnitude of the height, width, and length dimensions of itemSet. The units are unspecified; Paccurate will assume all units used are consistent throughout the request and will not perform conversions.

weight

The unit weight of a single member of the itemSet. Can be zero.

quantity

The number of members of the itemSet to be packed.

Click the pack button to see the response

Two items, one box

To add more of the same item, increase the quantity in the itemSet.

Click the pack button to see the response

Four items, two boxes

Further increasing the quantity will cause two box objects to be created in order to pack all itemSets.

Click the pack button to see the response

Box type choice

To consider two or more different boxTypes for packing itemSets, add another boxType to the list.

At a minimum, a boxType must include:

dimensions

x, y, and z floating point numbers describing the packable volume of the boxType, same as with an itemSet.

weightMax

The maximum net weight allowable to be packed in a single box of this boxType.

name, weightTare, price (of packaging materials), and a rateTable are among additional options that can be specified on a boxType.

Click the pack button to see the response

Two item types

To pack multiple different itemSets together, simply add another itemSet to the list. By default, the items will be color-coded in the visualization to help differentiation.

Click the pack button to see the response

Volume as cost

If specified, the itemSet.weight is always considered as a critical requirement of packing. If omitted, Paccurate will pack based on volume only.

Furthermore, in the absence of any rateTable or packaging materials price information for a given boxType, the cost returned in the response will reflect the total volume of the packed box. Note in the response that the totalCost field is equal to the volumeMax attribute of the single packed box.

In other words, without additional information, Paccurate will attempt to minimize to total volume of all cartons or containers in the shipment. If given pricing information, it is total cost of the carton or container that is minimized, and the estimated cost is given in the box.cost and totalCost fields of the response.

It is also inadvisable though not impossible to mix itemSets with and without weight dimensional data.

Click the pack button to see the response

Leftovers

Any itemSets that cannot be packed in any of the specified boxTypes will be passed back without a packing solution in the leftovers list. This most frequently happens if the item is too large for any box or if there are rules specified such that packing the item is impossible.

Click the pack button to see the response

Recipes

CSR quoting and Shipping estimation in shopping cart

Paccurate can be used to give more accurate rates at checkout, reducing overestimation (which often leads to shopping cart abandonment), and underestimation (which can lead to lower margins than expected).

Click the pack button to see the response

Optimizing rate shopping

A cost-optimal packing configuration may not be the same for two different carriers. This is because rate tables have distinct quirks and don't scale the same way in lbs per zone. The ideal approach is to submit a seperate request for each carrier you wish to rate shop. The results will take carrier pricing characteristics into account automatically.

Click the pack button to see the response

Click the pack button to see the response

Pallet Shipping

Pallets are handled differently than other containers. Beyond built-in best practices, rules like allowableOverhang can be passed in the request to comply with customer-specific specifications, and cohortPacking and cohortMax can be used to ensure itemSets are mostly packed together and not strewn about the container.

Click "Load Pallet" to see the response

Container Shipping

Containers are just a further extension of the same packing logic, with specific rules and properties. As the scale grows, units such as feet, meters, or in this example decimeters, may become more convenient than inches, but otherwise the principles are the same. allowableOverhang and cohortPacking are also useful, as are weightTare and placementStyle to give more control on the balance and organization of the resulting solution.

Click "Load Container" to see the response

Avoiding dim rating

FedEx and UPS (and USPS in some zones) will charge dimensional weight fees for low density packages. They determine whether a carton is "low density" by multiplying its length, width, and height, and then dividing the result by a special number called a dim factor. This is a carton's dimensional weight. The cost of a package is based on the higher of either its dimensional weight or actual weight. Unaided by technology, it can be difficult to consistently avoid dim rate fees for several reasons:

1. Dim rate fees don't show up at time of shipping- they are added to a shippers monthly bill. This can make the "cheapest" solution deceptive during fulfillment.
2. Because every carton has a minimum cost, there are times when taking a dim rating fee is cheaper than packing in multiple, more dense, packages.
3. Dim rating only applies in certain circumstances and zones. There are subtle differences in dim rating between FedEx and UPS.

Click the pack button to see the response

Click the pack button to see the response

From item to box to pallet

Some shippers may ship larger orders via LTL. In these cases, it may be advantageous to predict the cost of shipping a pallet when only the line items are known. In two requests, a shipper can "cartonize" SKUs to cartons to pallets.

Click the pack button to see the response

Click the pack button to see the response

Bin-location Awareness

By including bin number and distance limit params, the pack response can act as a pick-and-pack guide. Your boxes or totes will still be optmized, but paccurate will also make sure that items physically close together are in the same box. Likewise, items in far away zones will not be packed together. This opens some interesting possibilities such as "fluid" pick zones, wherein a picker's zone may overlap with another one as needed, which reduces the liklihood that 2 pickers will go to adjacent aisles for the same order. The savings can be considerable in instances where 2 box shipments become 1 box shipments.

Click "Pack" to see the response

Item Rules

A lot of items are special and require specific considerations when packing. Hazardous materials, fragile, rolled items, nested items, the list goes on.

Exclusionary rules

In the classic puzzle of shipping a fox, a chicken, and a sack of grain, how do we pack all three so our precious cargo isn't consumed? The fox can't go with the chicken, and the chicken can't go with the grain. To express this in Paccurate, we need exclude rules.

Define two rules objects, one for the fox itemRefId == 0 excluding it from the chicken itemRefId == 1 and the chicken from the grain itemRefId == 2

Note that exclusion rules are symmetric, and that if the chicken is explicitly excluded from the grain, then the grain is implicitly excluded from the chicken, and it does not matter which is the itemRefId and which is in the targetItemRefIds

  "rules": [{
      "itemRefId": 0,
      "targetItemRefIds": [1],
      "operation": "exclude"
    },
    {
      "itemRefId": 1,
      "targetItemRefIds": [2],
      "operation": "exclude"
  }]

Click the pack button to see the response

Item orientation

Frequently, you'll want to pack items in a specific manner–whether it's a fragile, ancient figurine that must be placed on its base, or you've had the idea of shipping an opened jug of orange juice, you will want to ensure that up stays up. lock-orientation is a rule that retricts items from being rotated around some or any axis.

  "rules": [{                                    
      "itemRefId": 0,                              
      "operation": "lock-orientation"              
    },                                             
    {                                              
      "itemRefId": 1,                              
      "operation": "lock-orientation",             
      "options": {                                 
        "freeAxes": [0]                            
      }                                            
    },                                             
    {                                              
      "itemRefId": 2,                              
      "operation": "lock-orientation",             
      "options": {                                 
        "freeAxes": [0,1]                          
      }                                            
  }]

Click the pack button to see the response

Getting Started

Playing in the sandbox

As you may have noticed, the API is open and accessible, returning real results. Obviously, rate limiting will occur without valid API credentials, but you can run a limited number of unique requests about as reasonably often as any developer would want. If you're contact form averse, this is the easiest way to get your feet wet.

Get legit with an API key

Figuring out how to pack the same 25 items over and over again isn't going to help much in the long run. To try the API for free, sign up for a trial key.

Using your API key

When composing your HTTP request, add an Authorization header with the string apikey followed by your key, e.g.:

Authorization: apikey xyz-123-generated-key

or

curl -H "Authorization: apikey xyz-123-generated-key" https://api.paccurate.io/ -d '{
      "itemSets": [{
      "refId": 0,
      "dimensions": {"x": 5.5, "y": 6, "z": 6},
      "quantity": 3
  }],
  "boxTypeSets": ["fedex"]
}'