--- title: How To Construct A Rule slug: docs/building-rules description: Learn how to construct and apply rules in Paccurate's cartonization engine. This comprehensive guide explains how to select items using RefIds, Sequence, and ItemMatch properties, define rule targets, and apply operations like exclude and pack-as-is. icon: 🛠️ docTags: createdAt: 2025-05-29T15:35:31.516Z --- As established in our first [Getting Started with Paccurate: Anatomy of a Pack Request](docId\:cqipxt5FBov7hNj01j34c) article, the key elements to cartonizing with Paccurate are Items and Boxes. With Paccurate, you can configure your requests to handle sophisticated packing requirements. Locking orientation, excluding items from containers or other items, or defining Pack as-is (aka ship in own container) are just a few examples of rules that can be processed in each request. In this article, we’ll cover how to build and apply rules for packing. Paccurate builds rules on a per-item level. A rule denotes a relationship between an item and a target — that target is either another item, a carton, or even itself. Paccurate rules use an **item**, a **target**, an **operation**, and **options**. We’ll be exploring how to select items and their targets in the sections below. ## Selecting items for a rule There are three ways to define an item in a rule `itemRefId`, `itemSequence`, and `itemMatch`. There are implications to each approach, which we will investigate below. ## Using Ref Ids An item's RefId is *typically* a unique identifier for that item. Using the item's refId is a straightforward way of specific exactly which item the rule needs to be applied. ```json { "itemRefId": 11, "operation": "exclude-all" } ``` The rule above uses `itemRefId` — it means items in the request with the `refId`\*\* of `11` \*\*can only be packed with items that share that `refId` (because we are using the “exclude-all” operation in the example). :::BlockQuote 🚧 ImportantRefId is **not** a required attribute of all items, and it *must* be an integer when provided. Using this rule when numeric refIds are not present in the request will prevent the rule from being applied. ::: For customers with a smaller set of SKUs and requiring basic rule assignment, `itemRefId` is a simple, straightforward way of assigning rules to an item. ## Using Sequence Paccurate items support the inclusion of a `sequence` attribute. This can be used for a number of things, including rule targeting. It can be helpful to consider an item's sequence as a category -- it is a string value that is not exclusive from item to item. ```json { "itemSequence": "A100", "operation": "pack-as-is" } ``` In the rule above, we are targeting any `item` with the `sequence` value of `A100`. Using the `itemSequence` approach to targeting items is helpful when you have a handful of product categories (sequences) that share specific packing behavior. In this case, the "pack-as-is" rule would make any item with the sequence A100 be packed in its own outer box, no matter what. Both the `itemSequence` and `itemRefId` methods of targeting items work well when your item refs and sequences are of a manageable size, or you are able to intelligently create rules on the fly. For more complex categories and and item targeting however, you may want to use `itemMatch`, which we will cover next. ## Item Match For more powerful item targeting, ItemMatch is essential. It allows you to create rules that look at parts of attributes (name or sequence), and even invert the items you are targeting (think: "every item that's not polybag eligible", or "any item whose sequence begins with HM"). There are 5 attributes to an `itemMatch` object: `all`, `property`, `expression`, `expressions`, and `negate`. ### All The `all` attribute is a `boolean`; setting `all:true` would apply the rule to all items in the request. ```json { "itemMatch":{ "all":true }, "operation":"pack-as-is" } ``` In the above example, all items in the order would have the pack-as-is rule applied to them, and ship in a carton of the item's dimensions. Another example use case where using `all` would be useful is simulating donnage or packing material. If you know that all of your items must have 1/4" of packing material on them , you could use an `alternate-dimensions` operation to add the extra length/width/height on all items, and Paccurate would pack using those changes. ### Property The `property` attribute is used much more commonly than `all`. It tells the match function *where* to look for the rule. The options for property `name`, `sequence`, or any defined custom item property that is a **string** value. Read more about custom properties in the [Properties and Constraints](docId\:rVC_7fOhEpSLjWbYE5rgM) guide. ### Expression The `expression` attribute defines *what* to look for in the specified `property`. It is a string to search for in the property. ```json { "itemMatch":{ "property":"name", "expression":"HEAVY" }, "operation":"pack-as-is" } ``` In the above example, any item that has "HEAVY" in its name will be packed as-is and shipped in its own packaging. Items named "Dog Food HEAVY" or "Cat Litter HEAVY" would have the above rule applied. We see customers using this to build item *categories* using either the name or the sequence. :::BlockQuote 📘 NoteExpressions are case-sensitive, so you may want to review your item names and/or sequences and make sure any instance of the expression is captured. ::: ### Expressions If you have a rule that applies to multiple categories, the `expressions` attribute should be used. It works the same way as `expression` but supports multiple values. ```json { "itemMatch":{ "property":"name", "expressions":["HEAVY", "XL", "OVERSIZE"] }, "operation":"pack-as-is" } ``` Similar to the previous example, this rule would apply the "pack-as-is" behavior to items such as "Cat food XL", "Crate OVERSIZE", and "Dog Food HEAVY". ### Negate The `negate` option is a way of inverting the match rule. It is effectively saying "anything that does NOT match the expression in this property" should have this rule applied. A practical application of this logic is carton type exclusion. ```json { "itemMatch":{ "property":"sequence", "expression":"BAGGABLE", "negate":true }, "operation":"exclude", "targetBoxRefIds":[800,900] } ``` The rule above is excluding non-baggable items (items without "BAGGABLE" in their sequence property) from two types of cartons (in this case, bags) with the refIds of 800 and 900. ## Rule Targets While there are numerous ways to select an item for a rule, defining the rule's *target* is a bit more straightforward. Since rule targets are exclusively used for the `exclude` operation, the target defines what the item is being excluded from. The options for rule targets are `targetItemRefIds`, `targetItemSequences`, and `targetBoxRefIds`. All three are arrays. ### Item RefIds ```json { "itemRefId":1, "targetItemRefIds":[2, 3, 4], "operation":"exclude" } ``` Here, we are excluding an item with the refId of 1 from being packed with items of refIds 2, 3, or 4. The `targetItemRefIds` array must only contain integers. ### Item Sequences ```json { "itemRefId":1, "targetItemSequences":["HM300", "UN835", "1100"], "operation":"exclude" } ``` Similar to the refId approach, we are specifying the sequences of the items of which we want item with refId 1 to be excluded. The `targetItemSequences` array must only contain strings. ### Target Item Match With the release of Packer `1.9.0` it is possible to use the same `itemMatch` syntax for targeting items for exclusion. In the example below, we’ll be excluding heavy items from any item that has a UN code in its sequence. ```javascript { "operation":"exclude", "itemMatch":{ "property":"sequence", "expression":"HEAVY" }, "targetItemMatch":{ "property":"sequence", "expression":"UN" } } ``` ### Box RefIds ```json { "itemRefId":1, "targetBoxRefIds":[800, 900, 1100], "operation":"exclude" } ``` In order to exclude items from being packed in specific boxes, we use the parameter `targetBoxRefIds` which is an array of integers that represent specific boxes (or any type of container). This can be used to exclude items from mailers, branded boxes, or any box type provided to the request that may not apply to all items in a given request. ### Target Box Match Similar to `targetItemMatch`, we can now use a box’s name as an exlcusion target. In the example, below we’ll look for items flagged as “RIGID” or “HEAVY” and exclude them from mailers. ```javascript "rules":[ { "operation": "exclude", "itemMatch":{ "property":"sequence", "expressions":["RIGID", "HEAVY"] }, "targetBoxMatch":{ "property":"name", "expression":"MAILER" } } ], "boxTypes":[ { "name":"MAILER-12x14", "weightMax":20, "dimensions":{ "x":4, "y":12, "z":14 }, { "name":"MAILER-10x8", "weightMax":20, "dimensions":{ "x":4, "y":8, "z":10 }, { "name":"MAILER-14x18", "weightMax":20, "dimensions":{ "x":4, "y":14, "z":18 } ] ``` ## Conclusion To recap: the first step in building rules is determining which *items* the rules apply to, along with the *target* of the rule (if the item has specific exclusions from a target). Once these relationships for the rule have been determined, the next step is defining what the rule does. We'll cover *operations* and *options* in their own article.