# Get started

The Packaging Planner API typically is called with three different kinds of data, depending on the use case: full linear dimensions, packaging IDs, or package set IDs. To call the API using full linear dimensions, you can begin with the instructions in this document.

To use the Packaging Planner API with packaging or package set IDs, you must first configure your account. Guidance can be found in the Packaging Planner documentation.

## Retrieve packaging guidance from the Packaging Planner API

The Shipium Packaging Planner API assumes you're using one of the authentication mechanisms detailed in our authentication documentation. The endpoint for Packaging Planner API calls is included in the table below.

| API type | API endpoint |
| --- | --- |
| POST | `https://api.shipium.com/api/v1/packaging/planner` |

### **Authentication for API Calls**

In the cURL examples on this page, the environment variable AUTHSTRING is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

### Shipium assumptions for the Packaging Planner API

### Package and content properties

All items being packed and all packages being packed into are three-dimensional, solid, rectangular objects or can be represented as such.

### Packing strategies

When retrieving packaging guidance, you can specify different options that affect which packing algorithm is used. You also can include a compression factor to be applied to your packing strategy.

### Packing algorithms

The packing algorithms currently supported are listed in the following table.

| Algorithm name | Packing algorithm value | Description |
| --- | --- | --- |
| Standard | standard | A cubic packer that uses an algorithm to place items in packages based on their size and how they can fit together in packaging |
| Volumetric | volumetric | A volumetric or "liquid" packing algorithm that fits items in packaging by first making sure that no item goes into a package if the item's height, width, or length exceeds the height, width, or length of a given package and after that assumes perfect volumetric packing within the package. |

### Volumetric packing algorithm options

When using the volumetric algorithm, you can specify a `packingAlgorithmOptions.volumetricPackingEfficiency` that will allow your packing to be constrained more (less than 1) or less (greater than 1) than the raw dimensions of the packaging.

Another optional specification within `packingAlgorithmOptions` is `pureVolumetricPacking`. This option does not place restrictions on product height, width, or length relative to the size of the packaging.

#### Packing algorithm block example

```json
{
  "packingStrategyOptions": {
    "packingAlgorithm": "volumetric",
    "packingAlgorithmOptions": {
      "pureVolumetricPacking": true,
      "volumetricPackingEfficiency": 1.0
    }
  }
}
```

### Packing compression

You can opt to include a compression factor in your packing strategy, whether standard or volumetric, that reflects the degree to which a product can be compressed in one or more dimensions. You'll specify values for the `productCompressionFactor` property within the items array.

#### Packing compression block example

```json
{
  "productCompressionFactor": {
    "compressionFactor": 0.2,
    "compressHeight": true,
    "compressWidth": false,
    "compressLength": false
  }
}
```

#### Packaging compression block in context of the items block

```json
{
  "items": [
    {
      "productId": "item1",
      "productLinearDimensions": {
        "width": 1,
        "length": 1,
        "height": 1,
        "linearUnit": "in"
      },
      "productWeight": { "weight": 1, "weightUnit": "oz" },
      "quantity": 5,
      "productCompressionFactor": {
        "compressionFactor": 0.1,
        "compressDepth": true,
        "compressWidth": true,
        "compressHeight": true
      }
    }
  ]
}
```

## Retrieve packaging guidance by including full linear dimensions in the API call (primary use case)

The following tables provide all required and optional fields for calling the Packaging Planner API with full linear dimensions of your package contents. You can find additional support in the Packaging Planner API Reference.

### Required fields

| Field | Details |
| --- | --- |
| `items` | **Type:** Array of item objects<br>**Description:** A list of the items to be packed into an available box |
| `packaging` | **Type:** Array of packaging objects<br>**Description:** Dimensions and restrictions for available boxes to pack the items into. Must contain at least one item. |
| `packaging.linearDimensions` | **Type:** Object (`linearDimensions`)<br>**Description:** The linear dimensions and unit of a box available for packing |
| `packaging.linearDimensions.length` | **Type:** Decimal<br>**Description:** Length of the longest side of the box to be packed. Must be a value greater than zero. |
| `packaging.linearDimensions.width` | **Type:** Decimal<br>**Description:** Length of the second longest side of the box to be packed. Must be a value greater than zero. |
| `packaging.linearDimensions.height` | **Type:** Decimal<br>**Description:** Length of the shortest side of the box to be packed. Must be a value greater than zero. |
| `packaging.linearDimensions.linearUnit` | **Type:** String (enumeration)<br>**Values:**`in` (inch), `cm` (centimeter)<br>**Description:** The unit of measurement in which the linear dimensions of the box are specified |
| `packaging.maxContentWeight` | **Type:** Object (`maxContentWeight`)<br>**Description:** The maximum total combined weight of the items packed into the box |
| `packaging.maxContentWeight.weight` | **Type:** Decimal<br>**Description:** The maximum weight of all the packed items. Must be a positive value. |
| `packaging.maxContentWeight.weightUnit` | **Type:** String (enumeration)<br>**Values:**`lb` (pound), `kg` (kilogram)<br>**Description:** The unit of measurement in which the maximum weight is specified |
| `packaging.packagingWeight` | **Type:** Object (`packagingWeight`)<br>**Description:** The weight of the empty box |
| `packaging.packagingWeight.weight` | **Type:** Decimal<br>**Description:** The weight of the empty box. Must be a positive value. |
| `packaging.packagingWeight.weightUnit` | **Type:** String (enumeration)<br>**Values:**`lb` (pound), `kg` (kilogram)<br>**Description:** The unit of measurement in which the empty box weight is specified |
| `packaging.packagingMaterial` | **Type:** String (enumeration)<br>**Values:**`box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet`<br>**Description:** The type of packaging used to create the package for the shipment |
| `packaging.packagingSizeName` | **Type:** String<br>**Example:**`A1`, `12x12x6 box`<br>**Description:** The name your organization assigned to the specified box size |

### Optional fields

| Field | Details |
| --- | --- |
| `includeDetails` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** A flag indicating whether to include dimensional details of the items to be packed in the API call response. Defaults to `true`, which results in full linear dimensions of the items being returned in the API call response. |
| `maxItemsPerPackage` | **Type:** Integer (int32)<br>**Description:** Passing this option will prevent any package returned from containing more than this number of items. Must be a value greater than 0. |
| `referenceIdentifier` | **Type:** String<br>**Description:** String passed to carriers as a reference. This field can be expanded to include multiple reference identifiers by adding sequential numbers to the field name (e.g., `referenceIdentifier2`) up to 5 reference identifiers. |
| `packaging.maxItemsPerPackage` | **Type:** Integer (int32)<br>**Description:** Passing this option will prevent any package returned from containing more than this number of items, at the individual packaging level. This value overrides the top-level `maxItemsPerPackage` value, if one was included. Must be a value greater than 0. |
| `packaging.unsupportedProductDetails` | **Type:** String (enumeration)<br>**Values:**`ormd` (other regulated materials—domestic), `lio` (lithium-ion), `fragile`<br>**Description:** Restricted product types that cannot be packed into this box (e.g., hazmat) |

## Packing strategy options (applies to all use cases)

The following optional fields can be included with any of the above use cases to specify packing algorithm behavior.

### Optional fields

| Field | Details |
| --- | --- |
| `packingStrategyOptions.packingAlgorithm` | **Type:** String (enumeration)<br>**Values:**`standard`, `volumetric`<br>**Description:** Specifies which packing algorithm to use. `standard` is a cubic packer that places items based on their size and how they fit together. `volumetric` is a "liquid" packing algorithm that fits items by ensuring no item dimension exceeds the package dimension, then assumes perfect volumetric packing. |
| `packingStrategyOptions.packingAlgorithmOptions                             .volumetricPackingEfficiency` | **Type:** Decimal<br>**Condition:** Applies only when using the `volumetric` algorithm<br>**Description:** Constrains packing to be more (less than 1) or less (greater than 1) than the raw dimensions of the packaging. |
| `packingStrategyOptions.packingAlgorithmOptions                             .pureVolumetricPacking` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Condition:** Applies only when using the `volumetric` algorithm<br>**Description:** When `true`, does not place restrictions on product height, width, or length relative to the packaging size. |

## Packing compression options (applies to all use cases)

The following optional fields can be included within the `items` array for any use case to specify compression behavior.

### Optional fields

| Field | Details |
| --- | --- |
| `items.productCompressionFactor` | **Type:** Object (`productCompressionFactor`)<br>**Description:** Compression factor settings that reflect the degree to which a product can be compressed in one or more dimensions (height, width, length) |
| `items.productCompressionFactor.compressionFactor` | **Type:** Decimal<br>**Description:** A value less than 1 that represents the degree to which any given dimension should be compressed. |
| `items.productCompressionFactor.compressHeight` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** Indicates whether the compression factor should apply to the height dimension |
| `items.productCompressionFactor.compressWidth` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** Indicates whether the compression factor should apply to the width dimension |
| `items.productCompressionFactor.compressLength` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** Indicates whether the compression factor should apply to the length dimension |

### Example request body

```json
{
  "packaging": [
    {
      "linearDimensions": {
        "height": 1,
        "length": 1,
        "linearUnit": "in",
        "width": 1
      },
      "maxContentWeight": { "weight": 50, "weightUnit": "lb" },
      "packagingMaterial": "box",
      "packagingSizeName": "1x1x1",
      "packagingWeight": { "weight": 1, "weightUnit": "lb" },
      "maxItemsPerPackage": 10
    },
    {
      "linearDimensions": {
        "height": 10,
        "length": 10,
        "linearUnit": "in",
        "width": 10
      },
      "maxContentWeight": { "weight": 50, "weightUnit": "lb" },
      "packagingMaterial": "box",
      "packagingSizeName": "10x10x10",
      "packagingWeight": { "weight": 1, "weightUnit": "lb" },
      "maxItemsPerPackage": 20
    },
    {
      "linearDimensions": {
        "height": 6,
        "length": 6,
        "linearUnit": "in",
        "width": 6
      },
      "maxContentWeight": { "weight": 50, "weightUnit": "lb" },
      "packagingMaterial": "box",
      "packagingSizeName": "6x6x6",
      "packagingWeight": { "weight": 1, "weightUnit": "lb" },
      "maxItemsPerPackage": 15
    }
  ],
  "referenceIdentifier": "PACKAGE_A",
  "items": [
    {
      "productLinearDimensions": {
        "width": 2,
        "length": 2,
        "height": 2,
        "linearUnit": "in"
      },
      "productId": "item1",
      "productWeight": { "weight": 2, "weightUnit": "oz" },
      "quantity": 1
    },
    {
      "productLinearDimensions": {
        "width": 4,
        "length": 4,
        "height": 4,
        "linearUnit": "in"
      },
      "productId": "item2",
      "productWeight": { "weight": 1, "weightUnit": "oz" },
      "quantity": 1
    }
  ]
}
```

# Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)

Updated 6 months ago