Building a Pack Request

This Page will help you create a basic request to the Paccurate API

Welcome to Paccurate, the smartest cartonization solution. In order to cartonize your items into boxes (or any type of container), you will be making requests to our REST API.

A request to the Paccurate API requires two core pieces: Items and Boxes with dimensional and weight data.

  • Items are the units that will be cartonized into the provided boxes. To be packed properly, they must have data for length, width, and height. Weight is utilized and strongly recommended whenever available.
  • Boxes are the cartons that the units could be placed in. In parcel shipments, they are most often corrugated, envelopes, or mailers. For freight/LTL shipments the Boxes can refer to pallets, trailers, or containers. Boxes require length, width, and height dimensions as well as a maximum weight

📘

It is important to note that the item and box data must be sent as part of every Paccurate request. This information is usually sourced from your WMS or ERP of choice. Determining where these pieces of data become available is up to you or your technology resources. What follows is an overview of what your systems need in order to make a successful cartonization request to Paccurate.

Items

Sending Items to the API requires each type of item to be represented with a quantity (sent as an integer) and dimensions (an object with the attributes of x, y, and z, all of which are numbers). These items are wrapped in an array called itemSets to be passed as part of the request. An example of a set of items looks like this:

{
  "itemSets": [
    {
      "refId": 0,
      "color": "green",
      "name": "Dispenser",
      "weight": 4,
      "dimensions": {
        "x": 9.5,
        "y": 3.25,
        "z": 4.5
      },
      "quantity": 1
    },
    {
      "refId": 1,
      "color": "blue",
      "name": "Tape",
      "weight": 0.3,
      "dimensions": {
        "x": 4.75,
        "y": 4.75,
        "z": 1
      },
      "quantity": 20
    },
    {
      "refId": 2,
      "color": "red",
      "name": "Stand",
      "weight": 17,
      "dimensions": {
        "x": 28,
        "y": 4.38,
        "z": 23.38
      },
      "quantity": 3,
    }
	]
}

Additional attributes on each item are name, refId, and sequence — these 3 values can be used by Paccurate to target the item in rules. Users can also assign a color attribute to an item, which is used in the output images to identify each instance of the item in its assigned box.

Boxes

Now that we have some items that need packing, it’s time to put them into some boxes. A typical request to Paccurate includes an array called boxTypes , which follows a similar pattern to itemSets — a list of boxes (or any type of container) along with their corresponding dimensions and a weightMax. An example set of boxes looks like this:

{
	"boxTypes": [
    {
      "weightMax": 65,
      "name": "Small",
      "dimensions": {
        "x": 12,
        "y": 6,
        "z": 6.75
      }
    },
    {
      "weightMax": 80,
      "name": "Medium",
      "dimensions": {
        "x": 14.5,
        "y": 6.75,
        "z": 12.75
      }
    },
    {
      "weightMax": 70,
      "name": "Wide Low",
      "dimensions": {
        "x": 12,
        "y": 12,
        "z": 4.25
      }
    }
  ]
}

Boxes also support refId and name which can be used to for targeting in rules. Some commonly used additional attributes are:

  • price is an integer that represents the cost of the box. If provided, it is used alongside volume utilization to determine which boxes to select for packing.
  • weightTare ****is a number that represents the actual weight of the box — if provided, this will be included into the total weight of the packed box.
  • itemsPerBoxMax is an integer that represents maximum quantity of items that can be contained in one instance of the box.
  • reservedSpace is a number that represents the amount of space that needs to be kept available (most often for packing material). For example, adding "reservedSpace":.2 to a box means it can only be packed to 80% of its volume — we are reserving .2 (or 20%) of the space.

There are a handful of more advanced options over in the schema that provide more granular control of the boxes.

Sending the request

Now that we’ve covered what required of boxes and items, let’s construct the API request. Using the data above, the request body should look like this:

{
  "itemSets": [
    {
      "refId": 0,
      "color": "green",
      "name": "Dispenser",
      "weight": 4,
      "dimensions": {
        "x": 9.5,
        "y": 3.25,
        "z": 4.5
      },
      "quantity": 1
    },
    {
      "refId": 1,
      "color": "blue",
      "name": "Tape",
      "weight": 0.3,
      "dimensions": {
        "x": 4.75,
        "y": 4.75,
        "z": 1
      },
      "quantity": 20
    },
    {
      "refId": 2,
      "color": "red",
      "name": "Stand",
      "weight": 17,
      "dimensions": {
        "x": 28,
        "y": 4.38,
        "z": 23.38
      },
      "quantity": 3
    }
  ],
  "boxTypes": [
    {
      "weightMax": 65,
      "name": "Small",
      "dimensions": {
        "x": 12,
        "y": 6,
        "z": 6.75
      }
    },
    {
      "weightMax": 80,
      "name": "Medium",
      "dimensions": {
        "x": 14.5,
        "y": 6.75,
        "z": 12.75
      }
    },
    {
      "weightMax": 70,
      "name": "Wide Low",
      "dimensions": {
        "x": 12,
        "y": 12,
        "z": 4.25
      }
    }
  ]
}

Paccurate is a restful API and can be accessed using any HTTP client that can make a POST request with a JSON body — whether that’s a cURL via CLI, the Postman GUI, or the fetch API from a web client.

The URL to post to is https://api.paccurate.io

If you have an API key, be sure to set it in the headers as demonstrated below:

Authorization: apikey xyz-123-generated-key

As a curl request, it will look like:

curl -H "Authorization: apikey xyz-123-generated-key" https://api.paccurate.io/ -d '{
  "itemSets": [
    {
      "refId": 0,
      "color": "green",
      "name": "Dispenser",
      "weight": 4,
      "dimensions": {
        "x": 9.5,
        "y": 3.25,
        "z": 4.5
      },
      "quantity": 1
    },
    {
      "refId": 1,
      "color": "blue",
      "name": "Tape",
      "weight": 0.3,
      "dimensions": {
        "x": 4.75,
        "y": 4.75,
        "z": 1
      },
      "quantity": 20
    },
    {
      "refId": 2,
      "color": "red",
      "name": "Stand",
      "weight": 17,
      "dimensions": {
        "x": 28,
        "y": 4.38,
        "z": 23.38
      },
      "quantity": 3
    }
  ],
  "boxTypes": [
    {
      "weightMax": 65,
      "name": "Small",
      "dimensions": {
        "x": 12,
        "y": 6,
        "z": 6.75
      }
    },
    {
      "weightMax": 80,
      "name": "Medium",
      "dimensions": {
        "x": 14.5,
        "y": 6.75,
        "z": 12.75
      }
    },
    {
      "weightMax": 70,
      "name": "Wide Low",
      "dimensions": {
        "x": 12,
        "y": 12,
        "z": 4.25
      }
    }
  ]
}'

To see this example request in action, click here. You can see the details of the raw request, and also make modifications to the configuration in the ‘Configure’ tab that will update the request itself and allow you to re-run it.

Wrapping up

While Items and Boxes are required for Paccurate to pack, the API’s power lies in Rules and Options. Rulesallow users to apply business logic (lock orientation, pack as-is, exclude) to items and cartons. Options offer additional configurability such as box lookahead, placement axis order, and packing goals such as most items or lowest cost.

Thanks for reading

Updated 11 months ago

What’s Next