BoxIntellect – AI Box Packing & Package Dimensions for WooCommerce

Installation

1. Install and activate WooCommerce, then this plugin.
2. Go to WooCommerce → BoxIntellect → Boxes and enter the boxes you ship in (a starter set is already there).
3. For AI estimates (WordPress 7.0+): go to Settings → Connectors, install a provider plugin (OpenAI, Anthropic or Google) and add its API key.
4. Open WooCommerce → BoxIntellect to see which products are missing dimensions and estimate them.

Developers

BoxIntellect can be extended with PHP hooks and a small PHP API. Shipping methods and carrier plugins can read the parcels of every cart and order. The Pro add-on also adds a per-parcel shipping method, a REST API and WP-CLI commands.

All lengths are in centimetres and all weights in kilograms, whatever units the store uses. Convert with BoxIntellect_Units::from_cm() / from_kg() (to store units) and to_cm() / to_kg() (from store units).

Parcels in the cart

Every WooCommerce shipping package gets two extra keys before shipping rates are calculated, so any shipping method can use them in calculate_shipping( $package ):

• $package['boxintellect_parcels']: the list of parcels (see “Parcel” below).
• $package['boxintellect_totals']: count (parcels), weight (kg, boxes included) and volume (cm³, outer size).

If packing fails for any reason, the keys are left out and the cart keeps working. Call BoxIntellect_Cart::for_package( $package ) to pack a package yourself (cached for the request).

Parcels of an order

When “Calculate the parcels of every new order” is on (the default), the packing result of each new order is stored in the order meta _boxintellect_parcels (HPOS compatible). Read it with BoxIntellect_Order::get( $order ), which returns the packing result or null. BoxIntellect_Order::calculate( $order ) recalculates and stores it, like the Recalculate button on the order screen.

Packing result

BoxIntellect_Items::pack(), the order meta and the REST API return the same array:

• parcels: list of parcels.
• totals: count, weight (kg) and volume (cm³).
• approximate: true when the order had more items than the “Large orders” setting and was packed by volume instead of item by item.
• notes: product names by data source: missing (no dimensions), estimate (unsaved AI estimate used), default (fallback size used), no_weight.
• time: Unix timestamp of the calculation.
• review (orders only): why the order should be checked before shipping, from the “Check before shipping” settings: value (order total), fragile and data (product names), oversize (number of parcels that fit no box). Empty when there is nothing to check. Order meta _boxintellect_needs_check is yes while the order waits for a check; _boxintellect_checked holds who checked it and when.

Parcel

• type: box (packed in one of your boxes or mailers), own (ships in its own packaging) or oversize (fits no box and ships as it is).
• mailer: true when the box is a poly mailer. Its length, width and height are then the size of the contents, and inner is the room the bag had at that thickness.
• box_id, box_name: the box used (empty unless type is box).
• length, width, height: outer size in cm, the size the carrier measures.
• inner: inner length, width and height in cm.
• weight: gross weight in kg (items plus the empty box). items_weight: items only.
• fill: share of the box volume used, from 0 to 1.
• items: list of product_id, name and qty.
• placements: position of each unit in the box (x, y, z, l, w, h in cm), used for the 3D diagrams. Empty for approximate parcels.
• approximate: true for parcels packed by volume.

Parcels in the WooCommerce REST API

The WooCommerce REST API order response (/wp-json/wc/v3/orders and /wp-json/wc/v3/orders/{id}) has a read-only boxintellect_parcels field with the stored packing result (see “Packing result” above), or null when the order has none. Nothing is calculated on a GET.

ShipStation

With the ShipStation for WooCommerce plugin active, BoxIntellect adds to the orders ShipStation imports:

• Orders without parcels are packed first.
• XML export: when an order ships in one parcel, its Dimensions are the outer size of the parcel (in inches, as the ShipStation plugin sends them). ShipStation takes one package per order, so orders with several parcels keep what the ShipStation plugin sent. ShipStation adds up the item weights itself, so the weight of the empty box isn’t included.
• Custom field 3 (XML and REST exports) gets a parcel summary, such as 2 parcels: Medium box 31 × 26 × 21 cm, 1.4 kg (1 × Mug); …. Choose field 2 or turn it off with the boxintellect_shipstation_custom_field filter. A field another plugin already uses is never taken.

Parcel CSV export

The bulk action “Export parcels (CSV)” in the order list downloads one row per parcel (up to 500 orders), with these columns: order_number, order_id, parcel, parcels, name, company, address_1, address_2, city, state, postcode, country, phone, email, shipping_method, box, length, width, height, dimension_unit, weight, weight_unit, contents. Sizes and weights are in the store’s units with a point as the decimal mark. Orders without parcels are packed first. Change the rows with the boxintellect_csv_rows filter.

Box

BoxIntellect_Boxes::all() returns every box and `BoxIntellect_Boxes::enabled()` the boxes used for packing. Each box has `id`, `name`, `enabled`, `inner_length`, `inner_width`, `inner_height`, `outer_length`, `outer_width`, `outer_height`, `empty_weight`, `max_weight` (maximum content weight in kg, 0 for no limit) and `type` (`box` or `mailer`). For a mailer, the inner length and width are the lay-flat size and the inner height is the thickest it can be filled. `BoxIntellect_Boxes::make( $name, $length, $width, $height, $empty_weight, $max_weight, $type )` builds a box from its inner size, with outer sizes 1 cm larger (the same size for mailers).

Packer item

BoxIntellect_Items::from_product( $product, $qty ) turns a product into a packer item. Variations use their parent's values when they have none of their own.

• product_id, name, qty.
• length, width, height (cm) and weight (kg).
• source: where the dimensions came from: product, ai (saved from an AI estimate), estimate (unsaved estimate), default (fallback size) or missing. weight_source: product, estimate, default or missing.
• padding: added once to each of length, width and height (cm, both sides together), from the Padding setting plus the fragile padding for fragile products.

• Packing rules: upright, separate (ship alone), own_packaging, no_mailer (never in a mailer; also true for fragile and keep-upright products), nest (height in cm that each extra unit adds to a stack) and boxes (allowed box ids, empty for any box).

  BoxIntellect_Items::from_order( $order ) and BoxIntellect_Items::from_package( $package ) return the items of an order (refunds removed, virtual products skipped) or a cart package.

Products

• BoxIntellect_Items::product_dimensions( $product ): the size and weight used for packing, with their sources.
• BoxIntellect_Rules::get( $product ): the product’s packing rules: fragile, upright, separate, own_packaging, no_mailer, nest and boxes.
• BoxIntellect_Estimator::estimate( $product ): asks the connected AI provider for an estimate and stores it. Returns the estimate or a WP_Error.
• BoxIntellect_Estimator::stored( $product ): the stored estimate, or null.
• BoxIntellect_Estimator::apply( $product, $estimate, $only_empty = false ): saves an estimate as the product’s dimensions and weight.

An estimate has length, width, height (cm), weight (kg), confidence (high, medium or low), fragile, upright, own_packaging and notes. Stored estimates also have model, time and status (pending, applied or rejected).

Product meta: _boxintellect_estimate (the stored estimate), _boxintellect_dims_source (ai when the saved dimensions came from an AI estimate), and the packing rules _boxintellect_fragile, _boxintellect_upright, _boxintellect_separate, _boxintellect_own_packaging, _boxintellect_no_mailer (yes or no), _boxintellect_nest (cm) and _boxintellect_boxes (box ids). Prefer the methods above to reading the meta directly.

Filters

• boxintellect_item ( $item, $product, $qty ): change a packer item, for example its size, padding or packing rules.
• boxintellect_boxes ( $boxes ): change the boxes used for packing.
• boxintellect_packing_result ( $result, $items ): change a packing result before it is used or stored.
• boxintellect_estimate_prompt ( $prompt, $product ): change the prompt sent to the AI.
• boxintellect_ai_prompt_builder ( $builder, $product, $prompt ): adjust the WordPress AI Client request before it is sent.
• boxintellect_max_tokens ( $max_tokens ): change the output limit (default 1024). Reasoning models count their thinking too.
• boxintellect_pre_estimate ( $error, $product, $args ): return a WP_Error to stop an AI estimate before it is sent ($args['source'] is manual, bulk, auto, cli or rest). The Pro add-on uses it for spending caps.
• boxintellect_admin_tabs ( $tabs ): add tabs to WooCommerce → BoxIntellect (id => array( label, capability )). Render a tab with the boxintellect_admin_tab_{id} action.
• boxintellect_test_result_html ( $html, $result, $items ): change the output of the Packing test tab.
• boxintellect_csv_rows ( $rows, $order, $result ): change the parcel CSV rows of an order (one per parcel, in the column order above).
• boxintellect_shipstation_custom_field ( $field ): ShipStation custom field for the parcel summary: 3 (default), 2, or 0 for none.
• boxintellect_order_review ( $reasons, $order, $items, $result ): why an order should be checked before shipping. Return an empty array for no check.

Actions

• boxintellect_loaded: the plugin is loaded (WooCommerce is active).
• boxintellect_order_packed ( $result, $order ): the parcels of an order were calculated and stored.
• boxintellect_order_flagged ( $reasons, $order ): an order started needing a check before shipping.
• boxintellect_order_checked ( $order ): someone marked an order as checked.
• boxintellect_boxes_saved ( $boxes ): the boxes were changed.
• boxintellect_estimated ( $estimate, $product ): an AI estimate was made and stored.
• boxintellect_estimate_applied ( $product, $estimate ): an estimate was saved as the product’s dimensions.
• boxintellect_usage ( $provider, $model, $input_tokens, $output_tokens ): reports the AI usage of each request.
• boxintellect_overview_after_stats ( $counts ): output below the statistics on the BoxIntellect overview.
• boxintellect_overview_after_table: output at the bottom of the BoxIntellect overview.
• boxintellect_order_box_actions ( $order ): output next to the Recalculate button in the order’s Parcels box.

Error codes

BoxIntellect_Estimator::estimate() returns a `WP_Error` with one of these codes:

• boxintellect_no_ai: no AI provider is connected in Settings → Connectors.
• boxintellect_http_429: the AI provider is rate-limiting requests. Retry later.
• boxintellect_http_5xx (for example boxintellect_http_503): the AI provider is temporarily unavailable. Retry later.
• boxintellect_http_error: network error reaching the AI provider. Retry later.
• boxintellect_ai_error: any other AI request failure, for example an invalid API key. Don’t retry.
• boxintellect_parse: the AI reply could not be read or had no usable dimensions.

Examples

Charge for each parcel in your own shipping method:

public function calculate_shipping( $package = array() ) {
    $parcels = isset( $package['boxintellect_parcels'] ) ? $package['boxintellect_parcels'] : array();
    $cost    = 0;
    foreach ( $parcels as $parcel ) {
        // Dimensional weight with a divisor of 5000 (cm³ per kg).
        $chargeable = max( $parcel['weight'], $parcel['length'] * $parcel['width'] * $parcel['height'] / 5000 );
        $cost      += 4.5 + 0.8 * $chargeable;
    }
    $this->add_rate( array( 'label' => $this->title, 'cost' => $cost ) );
}

Ship every product of the “Furniture” category alone:

add_filter( 'boxintellect_item', function ( $item, $product ) {
    $id = $product->get_parent_id() ? $product->get_parent_id() : $product->get_id();
    if ( has_term( 'furniture', 'product_cat', $id ) ) {
        $item['separate'] = true;
    }
    return $item;
}, 10, 2 );

Use a large box only in December:

add_filter( 'boxintellect_boxes', function ( $boxes ) {
    if ( '12' === gmdate( 'm' ) ) {
        $boxes[] = BoxIntellect_Boxes::make( 'Holiday box', 60, 40, 40, 0.9, 25 );
    }
    return $boxes;
} );

Send the parcels of each new order to a warehouse system:

add_action( 'boxintellect_order_packed', function ( $result, $order ) {
    foreach ( $result['parcels'] as $parcel ) {
        my_warehouse_add_parcel( $order->get_id(), $parcel['box_name'], $parcel['length'], $parcel['width'], $parcel['height'], $parcel['weight'] );
    }
}, 10, 2 );

Pack products without a cart, for example for a quote:

$items = array(
    BoxIntellect_Items::from_product( wc_get_product( 12 ), 3 ),
    BoxIntellect_Items::from_product( wc_get_product( 34 ), 1 ),
);
$result = BoxIntellect_Items::pack( $items );
printf( '%d parcels, %.2f kg', $result['totals']['count'], $result['totals']['weight'] );

Shipping method (Pro)

The Pro add-on adds the shipping method “BoxIntellect per-parcel rates” (method id boxintellect_rates). It charges a cost per order, a cost per parcel and a cost per weight unit of chargeable weight (the higher of the actual and dimensional weight of each parcel). Each rate carries the meta data “Parcels” and “Chargeable weight”. BXIP_Shipping_Method::chargeable_weight( $parcel, $divisor ) returns the chargeable weight of a parcel in kg.

REST API (Pro)

The Pro add-on adds routes under /wp-json/boxintellect/v1. To call them from outside WordPress, sign in with an application password (Users → Profile → Application Passwords) using HTTP Basic auth. Lengths are in cm and weights in kg.

• GET /orders/{id}/parcels: the stored packing result of an order, calculated first if there is none. Needs the edit_shop_orders capability.
• POST /orders/{id}/parcels: recalculates and stores the parcels of an order. Needs edit_shop_orders.
• POST /pack: packs products without an order, for example for quotes. Body: {"items":[{"product_id":12,"qty":3},{"product_id":34,"qty":1}]}. Products that don’t need shipping are skipped; returns 400 when none are left. Needs manage_woocommerce.
• POST /products/{id}/estimate: asks the AI for an estimate of one product. Add save=true to save it as the product’s dimensions. Returns 429 when the provider is rate-limiting, 503 when no provider is connected and 502 for other AI errors. Needs permission to edit the product.

• GET /boxes: all boxes. Needs manage_woocommerce.

  curl -u ‘admin:xxxx xxxx xxxx xxxx’ -X POST \ -H ‘Content-Type: application/json’ \ -d ‘{“items”:[{“product_id”:12,”qty”:3}]}’ \ ‘https://example.com/wp-json/boxintellect/v1/pack’

WP-CLI (Pro)

wp boxintellect pack 1234 1235
wp boxintellect pack 1234 --format=json
wp boxintellect estimate 42 43
wp boxintellect estimate --missing --limit=500 --save
wp boxintellect quality --format=csv
wp boxintellect advise --boxes=4 --days=90 --add

• pack: calculates and stores the parcels of orders.
• estimate: estimates products with AI. Without --save the estimates wait on the Review tab; with --save they fill empty fields only.
• quality: lists products whose dimensions or weight look wrong.
• advise: finds the box sizes that fit your recent orders best; --add adds them to your boxes.

Run wp help boxintellect for the full reference.

Pro hooks

• bxip_advisor_catalog ( $boxes ): change the standard carton sizes the box advisor chooses from (cm / kg).