The modern Distribution Center often contains machines that can build custom boxes in real time based on a customer's specific order. These machines help reduce waste and product damage, as well as reduce the chance of incurring dimensional weight fees. The Paccurate API is able to not only replicate this on-demand logic, but greatly improve upon it by integrating cost-awareness. Paccurate's optimized boxes can then be used to inform the box-on-demand machine what size carton to build for the order. Read more about how Paccurate helps Hunter Douglas control their box-cutting machines in this case study.

Using Paccurate with box-on-demand machines requires the use of boxTypeGenerators in the API. Box type generators incorporate many inputs, all of which we will explore here.

At its core, boxTypeGenerators is an array of BoxTypeGenerator objects that include the same attributes as any provided boxType, along with the configuration options for the dynamic box creation. Each Box Type Generator (BTG) supports 3 top-level inputs:

Here is an example BTG list with two different configured boxTypeGenerator objects:

We'll explore what all of the settings mean in further detail below.

It's easiest to build a Box Type Generator configuration step by step: base properties, operation, and custom properties.

The boxTypeDefaults object contains box properties that each generated box will inherit. At minimum, boxTypeDefaults must have a refId property. The API will reject a request if the defaults are missing the refId. It is recommended to also include a name; this will assist in troubleshooting the pack response and help differentiate between different BTG configurations. Below is an example of a typical boxTypeDefaults configuration for a boxTypeGenerator. Some common box packing properties that may be relevant for on-demand boxes can be found in our guide to Item and Box Limits. For more information around what can be added to boxTypeDefaults, visit the BoxProperties page in our schema.

For On-demand cartonization, you will want to use "operation":"cartesian" which leverages all of the inputs and limits. For more information on "operation":"pack-as-is", please visit our guide on Ship-in-own-container.

The options for BTGs have 9 available attributes, each with their own subset of parameters. These attributes can be broken out into 4 categories: axis values, metric limits, price thresholds, and trimming. At minimum, a BTG requires an axis value for each axis [x, y, z]. The limits and thresholds offer fine-grain controls to accurately represent things like surcharges and operational constraints. The trimming option determines the level of precision when returning a box dimension.

There are two ways for Paccurate to adjust a box dimension in a given axis: range and list. In sum, these comprise 6 of the available options: xRange, xList, yRange, yList, zRange, and zList.

List: The syntax for a list is straightforward -- it is a list of numbers representing available values for the axis. For example: "xList":[2,4,6] tells the generated box it can only have a height of 2, 4, or 6. No other values would be attempted or returned. Below is an example of how a box making machine with a fixed footprint (12x16) would be represented this way in the API (using lists):

In the example, there are 5 available heights provided to the list. The footprint is fixed, as yList and zList values only include one number.

Range: The syntax for a range definition is more complex. An axis range has 5 configurable attributes:

The config below uses ranges to generate each axis length. The height uses min, max and increment, while the length and width use deriveFromItems.

The generated boxes from the above would have one of 4 different heights, since the generator is incrementing from the min 3 to the max of 12 in units of 3. The length and width values are derived from the items that are added to the box. Pass in some items to this configuration, and you get the results below.

When deciding whether to use lists vs ranges, there are performance impacts to consider. Lists provide a fixed number of possible values to generate on each axis, while ranges allow the potential values to change with varying degrees of precision. Providing an increment to a range helps to control the amount of possible lengths that can be generated, thus improving processing time. It's encouraged to experiment with these settings and mix and match ranges and lists to get performant results when time is critical.

In addition to the axis length limits we just covered, BTGs support a list of limits for calculated metrics of the generated box size. These limits add boundaries for the generated box sizes not to exceed or fall below. Each limit object has three values:

In the configuration above, there is a maximum length-plus-girth (longest dimension value + 2x shortest dimension + 2x second shortest dimension), and a maximum volume value of 900 cubic inches.

One of the most powerful aspects of boxTypeGenerators is being able to leverage cost as the dimensions of a generated box change. The priceComponents parameter enables this cost-awareness around the calculated box metrics in addition to volume and weight. Things like additional handling fees and oversize charges can be captured here and used in the final generated box size. Each pricing component is comprised of 4 values:

While the limits option creates box size restrictions on the calculated metrics, pricingComponents uses the threshold values that, when exceeded, incur the additional fee from the corresponding item in the prices attribute.

Given the configuration above, a box with a length-plus-girth value of 45 would cost $2.00, while a value of 60 or more would cost $5.00. Also included is a limit for longest-dimension of 20.

Below is how Paccurate packs the config above:

As you can see, the single item is less expensive at $2.00, while all of the other items exceed the 40 length + girth threshold, and thus cost $5.00 to ship. These costs are in addition to any other pricing information provided to a request, such as a base box cost, rate table, or dim weight.

By default, when a box size is generated, Paccurate will trim down the dimensions to the bounds of the item inside the box. For example, if a generated box size was 8 x 10 x 12, but the boundaries of the items inside were at most 6.75 x 9.66 x 11.3, Paccurate returns a box size of 6.75 x 9.66 x 11.3. This feature can be turned off in the BTG's options by setting noTrimToMaxExtent to true. If you have configured your generator to make boxes with rounded/fixed dimensional increments, you would want to set "noTrimToMaxExtent":true to make sure the output boxes match the increments you had input. This default feature allow Paccurate to restrict the number of virtual boxes to choose from while still returning a box that precisely contains the item's inner dimensions, enabling precision without sacrificing processing speed.

Depending on your use case for Box Type Generators, it is often essential to control which items are eligible to be packed using the generator. Additionally, if you have multiple generators, you may only want specific items to use a specific generator. This is where the boxTypeDefaults come into play: since each BTG has a specific refId, it is just a matter of creating the appropriate exclude condition for an item, and using the BTG's refId for the targetBoxRefIds array.

Given the example request used earlier, if we add an exclude rule for the smaller items, they are now packed using a boxType in the provided array as opposed to in the BTG. The total cost increases to $20.76 from $17.00.

Here is the full body of the request, including the exclude rule and boxTypes array.

Take a look at the How To Construct A Rule article and exclude rules examples for more details on how to create and target items and boxes.

A final consideration for when implementing Box Type Generators is performance. Depending on the average quantity of items per order, range of size options, and number of generators in the request, processing times can increase significantly. There are a few ways to control this: first, ensuring that only items that should use the generator are eligible, using the exclude rules mentioned above. Second, if using a range axis value definition, you can decrease the increment value to reduce the number of options available to the range. Third, and perhaps most straightforward, is a request-level option called generatedBoxTypesMax. This option sets a limit for virtual box types to be generated, which is especially helpful if when using wide ranges that could produce thousands of box size options on each request.

For example, setting the max box types to 100 in the example above returns the 20 items in .5 seconds vs just over 3 seconds

For items that can either be packed with other items or shipped in its own packaging, the approach for constructing the request is twofold:

As discussed in the above guide, there are two possible values for a BTG's operation: "cartesian" and "pack-as-is". In the SIOC context we want to use "pack-as-is". The pack as is operation will generate a box that matches the dimensions of the item packed inside of it.

With the generator created, the next step is making sure that only items that can be shipped as-is are able to use the BTG. This can be done on a per item id rule, or by mapping the SIOC eligibility to an item property like name or sequence.

In the example above, we are leveraging the itemMatch feature of rule creation to make a rule that any item whose sequence does not (note the "negate":true) include the string "SIOC" is excluded from the box with the refId of 1000. The pack-as-is generator has the refID of 1000 in its boxTypeDefaults, enabling it to be targeted in this exclude rule.

With the generator and the rules created, a full request would look something like this:

In the above sample, there are 4 types of items, one of which is eligible for SIOC. Given the packing goal of "most-items", the whole order packs in one container.

Box Type Generators are a very powerful part of the Paccurate API. They consider and emulate the operational an financial constraints of real box-on-demand machines, and generate a packing solution optimized for those goals and constraints. Those packing solutions, available in the API response can then be used to instruct the hardware on what boxes to create to fulfill the order. We've learned how to create BTGs, set default information, configure range options, incorporate size limits, add pricing components, and even how to optimize performance and create rules to ensure the right items are being sent to the Box Type Generators. Thank you for reading, and as always, any questions, please reach out at [email protected], or visit our forums.