Freento_DimensionalShipping

A Magento 2 module for calculating shipping costs based on product dimensions using 3D bin packing via REST API.

Features

• 3D Bin Packing: Calculates optimal packing of items into shipping boxes via external REST API
• Product Dimensions: Custom product attributes for length, width, height, and shipping constraints
• Multiple Product Types Support:
  • Simple products
  • Configurable products
  • Bundle products
  • Grouped products
• Shipping Carrier Integration: Works with FedEx, UPS, and USPS carriers
• Package Box Management: Configure multiple box sizes with dimensions and weight limits
• Smart Caching: Stores packing results to avoid redundant calculations
• Ships Separately Option: Mark products that must ship in their own box
• Rotation Control: Prevent specific items from being rotated during packing
• Admin UI:
  • Manage package boxes
  • Import/export product dimensions via CSV
  • View packing results for orders
• REST API Integration: Uses external packing service for calculations

Requirements

• Magento 2.4.7 or higher
• PHP 8.1 or higher
• External Dimensional Shipping REST API service (see API Requirements below)

Installation

1. Add Module Files

composer require freento/module-dimensional-shipping

Or copy the module to your Magento installation:

cp -r app/code/Freento/DimensionalShipping /path/to/magento/app/code/Freento/

2. Enable the Module

bin/magento module:enable Freento_DimensionalShipping
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Configuration

1. Module Settings

Navigate to: Stores → Configuration → General → Dimensional Shipping

Configure the following:

• Enable Dimensional Shipping: Yes/No
• API Key: Your API key for authenticating with the dimensional shipping REST API service
• Dimension Unit: Select unit for dimensions (inches, cm)

Note: Weight unit is taken from the global Magento setting: Stores → Configuration → General → General → Locale Options → Weight Unit

2. Carrier Configuration

Navigate to: Stores → Configuration → Sales → Shipping Methods

For each carrier (FedEx, UPS, USPS):

• Use Package Dimensions: Enable to use dimensional shipping with this carrier

These options will only appear when Dimensional Shipping is enabled.

3. Configure Package Boxes

Navigate to: Dimensional Shipping → Package Boxes

Add boxes with:

• Name
• Length, Width, Height (in your configured dimension unit)
• Maximum weight (in your configured weight unit)
• Enabled status

Example boxes (in inches):

Small Box:  12" × 10" × 8", max 20 lbs
Medium Box: 18" × 14" × 12", max 50 lbs
Large Box:  24" × 18" × 16", max 70 lbs

Product Configuration

Adding Dimensions to Products

For each product, configure the following attributes:

Required Attributes:

• Package Length (dimensional_shipping_package_length)
• Package Width (dimensional_shipping_package_width)
• Package Height (dimensional_shipping_package_height)
• Weight (standard Magento attribute)

Optional Attributes:

• No Rotation Allowed (dimensional_shipping_no_rotation_allowed): Prevent item rotation during packing (useful for fragile items)
• Ships Separately (dimensional_shipping_ships_separately): Item must ship in its own box

Product Types

Simple Products

Set dimensions directly on the product.

Configurable Products

Set dimensions on the child simple products (selected variant).

Bundle Products

Set dimensions on the component simple products.

Grouped Products

Set dimensions on the child simple products. The grouped product parent does not need dimensions.

How It Works

1. Customer Adds Products to Cart

Products with configured dimensions are added to the shopping cart.

2. Shipping Calculation Triggered

When the customer views shipping methods, the module:

1. Collects all cart items and their dimensions
2. Loads configured package boxes
3. Sends data to REST API for optimal packing calculation (authenticated with API key)
4. Receives packed box configurations
5. Caches results to database

3. Packing Results Used

The calculated box dimensions and weights are passed to shipping carriers (FedEx, UPS, USPS) for rate calculation.

4. Smart Caching

The module caches packing results and checks timestamps to determine if recalculation is needed:

• Quote items changed
• Products updated
• Package boxes modified

Import/Export Product Dimensions

Export Dimensions to CSV

Navigate to: Dimensional Shipping → Package Dimensions

Click Export to download CSV with all product dimensions.

Import Dimensions from CSV

Navigate to: Dimensional Shipping → Package Dimensions

1. Click Import
2. Upload CSV file with columns:
   • sku
   • length
   • width
   • height
   • no_rotation_allowed (0/1)
   • ships_separately (0/1)
3. Click Import

Admin Features

View Order Packing Details

Navigate to: Sales → Orders → View Order

Under the Packaging tab, you can see:

• Which boxes were used
• Item placement within each box
• 3D positions of each item
• Items that couldn't be packed

Troubleshooting

No Shipping Rates Displayed

Check:

1. Module is enabled in configuration
2. API Key is correctly configured
3. API service is running and accessible
4. Products have dimension attributes set
5. At least one package box is configured and enabled
6. Carrier's "Use Package Dimensions" option is enabled

View Logs:

tail -f var/log/system.log | grep -i "dimensional"

API Connection Errors

Common Issues:

• No API key provided: Set API Key in admin configuration
• Incorrect API key validation result: Verify the API key is correct? is not expired and does not exceed usage limit

Items Not Packing

Possible Causes:

1. Missing dimensions: Products must have length, width, and height
2. Items too large: No box is big enough to fit the items
3. Weight exceeded: Items exceed maximum box weight
4. Wrong units: Verify dimension and weight units match your configuration

Debug:
Enable developer mode and check var/log/system.log for detailed error messages.

Grouped Products Not Working

Solution:

• Ensure child simple products (not the grouped parent) have dimension attributes
• Check logs for "No children found for grouped product"
• Verify grouped product has children in the cart
• Confirm each child product has valid dimensions

Support

For issues, feature requests, or questions:

1. Check TROUBLESHOOTING section
2. Review logs: var/log/system.log
3. Check module configuration
4. Verify API service is running and API key is valid

License

Proprietary

Credits

Developed by Freento