WP Manifestindependent plugin directory
manifest / ecommerce / nv-boxpacker

FunnelKit USPS Priority Shipping Optimizer for US & Canada

NV Digital BoxPacker - ShipEnine | Shipstation API - USPS Priority Shipping Optimizer

by NV Digital Solutions · github.com/nvdigitalsolutions/nv-boxpacker

★ 0stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/nvdigitalsolutions/nv-boxpacker/archive/refs/heads/main.zip

Readme

USPS Priority Shipping Optimizer

A WooCommerce plugin that optimizes USPS Priority Mail shipping for WooCommerce orders by packing items into custom cubic boxes and USPS flat-rate boxes, rate-shopping through ShipEngine or ShipStation, and producing package-level plans suitable for PirateShip export.

Author: NV Digital Solutions License: GPLv3 or later — see LICENSE for details.

Table of Contents

  1. Overview
  2. Requirements
  3. Installation
  4. Configuration
  5. Features
  6. Architecture
  7. WordPress Hooks and Filters
  8. Box Definition JSON Schema
  9. Development
  10. Changelog

Overview

When a customer completes checkout, this plugin:

  1. Collects all shippable items from the WooCommerce order.
  2. Packs them using the dvdoug/boxpacker library (falls back to a single-item-per-box strategy when the library is unavailable).
  3. For each configured carrier/service pair, evaluates all packed boxes and picks the cheapest rate from ShipEngine, ShipStation, or both. Each service is offered as a separate shipping option at checkout (e.g. "USPS Priority $7.25" and "UPS Ground $8.50").
  4. Stores a complete, package-level shipping plan on the order for admin review.
  5. Generates PirateShip-compatible CSV rows for bulk label purchase.

Managers can also use the WooCommerce → USPS Test Pricing admin page to preview packing and rates for arbitrary items and addresses without placing a real order.

Requirements

Dependency Minimum version
PHP 8.0
WordPress 6.0
WooCommerce 7.0
dvdoug/boxpacker ^3.12 (optional; installed via Composer)

Installation

Production

  1. Download or build the plugin zip (see bin/build.sh).
  2. Upload and activate through Plugins → Add New → Upload Plugin in WordPress, or extract to wp-content/plugins/fk-usps-optimizer/.
  3. Open WooCommerce → USPS Optimizer to complete configuration.

Note: vendor/ is excluded from the repository. Run composer install --no-dev inside the plugin directory before deploying, or use the build script which handles this automatically.

Development

# Clone the repository
git clone https://github.com/nvdigitalsolutions/nv-boxpacker.git
cd nv-boxpacker

# Install all dependencies including dev tools
composer install

# Verify the setup
composer test   # PHPUnit
composer phpcs  # PHP CodeSniffer (WPCS)

Configuration

Navigate to WooCommerce → USPS Optimizer to manage all plugin settings.

Enabled Carrier APIs

Setting Values Default
Enabled Carrier APIs ShipEngine, ShipStation (checkboxes) ShipEngine

Enable one or more carrier APIs for live rate requests. When multiple carriers are enabled, the plugin fetches rates from all of them and uses the cheapest option. Checking or unchecking a carrier immediately shows or hides its credential fields without saving the page.

ShipEngine Settings

Setting Description
ShipEngine API Key API key from app.shipengine.com → API Management.
ShipEngine Carrier ID The carrier ID for your USPS account (e.g. se-123456). Found in Carriers on the ShipEngine dashboard.
ShipEngine Service Code Service code sent to ShipEngine for rate requests (e.g. usps_priority_mail). Default: usps_priority_mail.

ShipEngine uses a header-based API-Key authentication scheme and calls the POST /v1/rates endpoint.

ShipStation Settings

Setting Description
ShipStation API Key API key from ShipStation → Account Settings → API Settings.
ShipStation API Secret API secret from the same page.
ShipStation Carrier Code Primary carrier code to rate against (e.g. stamps_com, ups_walleted). Default: stamps_com.
ShipStation Service Code Service code sent to ShipStation for rate requests (e.g. usps_priority_mail). Default: usps_priority_mail. Leave empty to match any service from the carrier.
ShipStation Additional Services Optional JSON array of extra carrier+service pairs to rate-shop alongside the primary pair. Each entry needs carrier_code and service_code. Example: [{"carrier_code":"ups_walleted","service_code":"ups_ground"}]. Rates from all pairs are compared and the cheapest wins.

ShipStation uses HTTP Basic Authentication (API Key:API Secret) and calls the GET /shipments/getrates endpoint.

You can override the ShipStation API base URL using the fk_usps_optimizer_shipstation_api_url filter (see Filter Hooks).

Service Codes

Each carrier now has its own service code setting. This replaces the previous shared USPS Service Code field.

Setting Carrier Default
ShipEngine Service Code ShipEngine usps_priority_mail
ShipStation Service Code ShipStation usps_priority_mail

Common service codes include usps_priority_mail, usps_first_class_mail, and usps_ground_advantage. The legacy shared service_code setting is still respected as a fallback when per-carrier codes are empty (backward compatibility).

Display Settings

These settings control how shipping rates appear in the WooCommerce cart and checkout.

Setting Type Default Description
Show All Options Checkbox Off Display every combination of rated box candidates as a separate shipping option. Candidates are grouped per carrier service — the cartesian product runs within each service, not across services, preventing nonsensical cross-service combinations. Labels use the carrier-specific service name (e.g. "USPS Priority", "UPS Ground") derived from each plan's actual API-returned service code. Repeated box names are consolidated (e.g. "2× Small Flat Rate Box + Large Flat Rate Box"). When disabled, only the cheapest combined rate per service is shown.
Show Package Count Checkbox Off Append the package count to each shipping option label. Example: "USPS Priority (2 packages)". Uses proper singular/plural forms.
Show Estimated Delivery Date Checkbox Off Show the carrier-provided estimated delivery date on a separate line below each shipping option label. Example: "USPS Priority (1 package)" on the first line, "Est. delivery: Mon, Jan 15" on the second. For ShipEngine, the estimated_delivery_date field from the rate response is used directly. For ShipStation, the transitDays field is converted to a calendar date. The formatted date is also passed as WooCommerce rate metadata for themes and FunnelKit Checkout pages that render it.
Additional Business Days Number (0–30) 0 Extra business days (Monday–Friday) added to every estimated delivery date. Use this to account for order processing or handling time. Weekends are skipped, so a 2-business-day buffer applied on a Thursday pushes the estimate to the following Monday. Applies to both carrier-returned and default transit-day estimates.
PirateShip Notification Emails Text empty Comma-separated list of email addresses (newlines and semicolons also accepted) to notify after every order. Each recipient receives the suggested packages, packing list, and a CSV attachment that can be imported directly into PirateShip. Invalid addresses are dropped on save and reported via an admin notice. Leave blank to disable.

Test ShipEngine Connection

Below the settings form a Test Connection button verifies that:

  1. The configured ShipEngine API Key authenticates successfully against the ShipEngine API.
  2. The configured Carrier ID belongs to an active USPS carrier account (stamps_com, usps, or endicia).

Clicking the button fires an AJAX request — the result is displayed inline immediately below the button without reloading the page. Save your settings before running this test so the current values are used.

Tip: For sandbox testing, enter a TEST_-prefixed API key from your ShipEngine dashboard and enable Sandbox Mode above.

Sandbox Mode

When Enable Sandbox Mode is checked:

  • All ShipStation and ShipEngine log entries are prefixed with [SANDBOX] so they are distinguishable from production calls.
  • A yellow warning banner is displayed on the USPS Test Pricing admin page.
  • The test pricing results table shows a notice that rates are from a sandbox environment.

Use sandbox mode during development and testing to clearly mark non-production API calls in the WooCommerce log viewer.

Ship-From Address

Field Description
Ship From Name Sender full name.
Ship From Company Company name (optional).
Ship From Phone Sender phone number.
Ship From Address 1 Street address.
Ship From Address 2 Suite/unit (optional).
Ship From City City.
Ship From State Two-letter state abbreviation (e.g. CA).
Ship From Postal Code ZIP code.
Ship From Country Two-letter country code. Default: US.

The ship-from address is passed directly to both ShipEngine and ShipStation for rate calculations. It can also be overridden via the fk_usps_optimizer_ship_from_address filter.

Debug Logging

When Enable Debug Logging is checked, all API requests, responses, and packing errors are written to the WooCommerce logger under the fk-usps-optimizer source. View logs at WooCommerce → Status → Logs.

Box Definitions

Box definitions are managed via a compact visual table in the Box Definitions section of the settings page. Each row represents one physical box and can be added, edited, or removed directly in the UI. The table uses grouped column headers — "Outer (in)" and "Inner (in)" — with fixed-width columns and a horizontally scrollable wrapper so it fits within the standard WordPress admin layout without forcing the page wider.

Each box has inner/outer dimensions (inches), empty weight (ounces), maximum payload weight (lbs), a type (cubic or flat_rate), and an optional Carrier restriction (Any, USPS, UPS, FedEx). The Enabled checkbox lets you temporarily exclude a box from packing/rating (for example, when a box is out of stock) without deleting its configuration — uncheck it to disable, re-check it when stock is replenished. Boxes saved before this setting existed are treated as enabled by default.

See Box Definition JSON Schema for the full field reference and a worked example.

Features

WooCommerce Shipping Zones Integration

The plugin registers a native WC_Shipping_Method (fk_usps_optimizer) so it appears in WooCommerce → Settings → Shipping → Shipping Zones. Add the USPS Priority Optimizer method to any zone to enable live, optimized USPS Priority rates during cart and checkout.

How it works:

  1. Cart items are extracted and converted to the item format expected by Packing_Service::pack_items().
  2. Items without WooCommerce product dimensions (length, width, or height not set) are detected and packed individually via the fallback packer — one item per box. This prevents the BoxPacker default of 1×1×1 inch dimensions from producing incorrect packing results.
  3. Each configured carrier/service pair rates all packed packages independently. The cheapest rate per service is offered as a separate checkout option — customers see one shipping rate per service (e.g. "USPS Priority $7.25" and "UPS Ground $8.50" as distinct choices). Service labels are derived from the actual API-returned serviceCode, not the configured setting, ensuring accuracy even when the carrier returns a different service than requested.
  4. Rates are cached in a transient for 30 minutes. The cache key includes carrier, service code, box configuration, display settings, item dimensions, and destination — so rates update immediately when any of these change.

When Show All Options is enabled, each rate option shows a descriptive label built from the carrier service name and the box names in that combination, such as "USPS Priority — 2× Small Flat Rate Box + Large Flat Rate Box" or "UPS Ground — 2× Bag". The cartesian product is grouped per carrier service — candidates from different services are never mixed. Repeated box names are consolidated (e.g. "2× Small" instead of "Small + Small"). Duplicate combinations are removed and results are sorted cheapest-first.

Read the full README on GitHub →