Welcome to the official documentation and user guide for Address Book – Multi-Address Shipping for WooCommerce (by Yeeplugin). This comprehensive guide walks you through installing, configuring, and utilizing all features of the plugin—from customer address books and multi-destination checkout splitting to product page shipping estimators and developer customization hooks.
1. Installation & System Requirements
Follow standard WordPress plugin installation procedures to set up the plugin on your store:
- Log in to your WordPress Admin dashboard.
- Navigate to Plugins → Add New Plugin.
- Click the Upload Plugin button at the top of the screen.
- Choose the plugin zip archive (
address-book.zip) from your computer. - Click Install Now and wait for the file to upload and unpack.
- Click Activate Plugin.
Minimum System Requirements & Compatibility:
• WordPress: Version 6.0 or higher
• WooCommerce: Version 7.0 or higher (Fully tested and certified up to WooCommerce 11.1+)
• PHP: Version 7.4 or higher (PHP 8.0, 8.1, 8.2, and 8.3 supported)
• HPOS: 100% High-Performance Order Storage (Custom Order Tables) certified
• Checkout Support: Compatible out-of-the-box with both Gutenberg Checkout Blocks and Classic Shortcode
Upon activation, the plugin automatically creates a new configuration tab located at WooCommerce → Settings → Address Book, and registers an Address Book endpoint in the customer’s My Account area.
2. Architecture & Core Components
The plugin is engineered around three interconnected modules designed to provide a frictionless multi-destination shipping journey:
| Module | Core Class | Functionality & Benefits |
|---|---|---|
| Customer Address Book | WCAB_Address_BookWCAB_My_Account | Allows logged-in customers to store unlimited shipping destinations with nicknames (e.g., Home, Office, Warehouse), select default addresses, and switch addresses instantly during checkout without manual retyping. Automatically imports existing customer profile addresses on first login. |
| Multi-Address Shipping | WCAB_Multi_Shipping | Enables customers to split item quantities across multiple addresses in a single order. Automatically breaks down the cart into independent shipping packages, calculates carrier shipping fees per package, and provides comprehensive multi-destination breakdowns in emails and admin orders. |
| Shipping Estimator | WCAB_Product_Shipping | Renders real-time shipping costs and estimated delivery arrival dates directly on single product pages. Automatically calculates rates based on the customer’s default address or zone, recalculates variation changes via AJAX, excludes weekends, and detects unserviceable zones. |
3. Customer Address Book (My Account & Checkout)
The Address Book module empowers shoppers to save, label, and manage all their frequent delivery destinations.
3.1 Managing Addresses in My Account
Customers can access their address manager by navigating to /my-account/address-book/:
- Saved Address Cards: Every address is presented as an organized card displaying its custom label/nickname, recipient name, full street address, contact phone number, and an active Default indicator badge.
- Set as Default Address: A single click sets an address as the primary shipping destination. This default address is automatically loaded at checkout and used for single product shipping estimations.
- Edit Address: Customers can update contact details or street addresses anytime.
- Delete Address: Remove obsolete addresses with confirmation prompts to prevent accidental deletions.
- Add New Address: Customers can register new addresses with custom nickname labels at any time.
3.2 Dynamic WooCommerce Checkout Fields & Localization
Unlike basic address plugins that use hardcoded static HTML inputs, our Address Book integrates natively with WooCommerce core field architecture (woocommerce_form_field()):
- Third-Party Custom Fields Inheritance: Any custom checkout fields added by third-party checkout field managers or localization plugins (such as Vietnam Wards/Districts, Brazil CPF, Italian Codice Fiscale, Building numbers, or delivery notes) are automatically loaded and saved without needing code changes.
- Dynamic Country & State Switching: Uses WooCommerce’s core
wc-country-selectandwc-address-i18nscripts to dynamically adjust state, province, and postal code requirements whenever the destination country changes.
💡 Smart Auto-Migration for Existing Customers:
When existing customers log in for the first time with an empty address book, the plugin checks their existing profile meta (shipping_* or billing_*) or their latest completed order (wc_get_customer_last_order()). It automatically creates their primary address card and sets it as the default address book entry.
4. Multi-Address Shipping Guide (Step-by-Step)
Multi-Address Shipping enables buyers to purchase multiple products or quantities and distribute them across different shipping addresses within a single checkout transaction.
Step 1: Smart Cart Threshold
The multi-shipping option automatically appears only when the cart contains more than 1 item or a quantity greater than 1. Single-item carts remain in standard single-shipping mode to prevent friction.
Step 2: Visual Item Allocation
Clicking “Ship to Multiple Addresses” opens an allocation modal. Customers assign quantities per product to saved addresses, or add new addresses on the fly with live quantity validation badges.
Step 3: Shipping Package Splitting
The cart is divided into distinct packages via woocommerce_cart_shipping_packages. Carrier rates (Flat Rate, Free Shipping, FedEx/UPS/DHL) calculate independently for each destination package.
Step 4: Safety Limit Enforcement
The store enforces a configurable maximum address limit per order (default: 5) to safeguard store owners from carrier API rate limits and complex logistics overload.
5. Product Page Shipping Fee & Delivery Date Estimator
Displaying upfront shipping fees and estimated delivery arrival dates directly on product pages builds customer confidence and reduces cart abandonment.
5.1 Real-Time Shipping Calculation Highlights
- Physical vs. Virtual Products: Automatically skips and hides the shipping widget for virtual or downloadable products where shipping is not required.
- Variable Product AJAX Recalculation: When shoppers select variation attributes (size, color, weight), the widget immediately updates shipping rates and delivery estimates via AJAX based on the exact variation’s weight and dimensions.
- Address-Aware Shipping: For logged-in customers, their saved default address is automatically loaded. For guests or new visitors, the plugin calculates based on the store’s default customer location and shows “Unserviceable Area” if no methods are available.
- Free Shipping Highlighting: Automatically highlights qualified free shipping when minimum order amounts or coupon requirements are met.
5.2 Estimated Delivery Dates with Weekend Exclusion
| Feature | How It Works |
|---|---|
| Per-Method Transit Days | Store admins define Min and Max delivery day ranges for each shipping method (e.g., Express Delivery: 1 – 2 business days, Standard Delivery: 3 – 5 business days). |
| Weekend Exclusion Algorithm | When enabled, the delivery date calculation skips Saturdays and Sundays, guaranteeing realistic delivery arrival projections. |
| Localized Date Display | Dates are formatted according to your WordPress localization settings (e.g., Mon, Oct 12 – Wed, Oct 14). |
6. Admin Settings & Configuration Reference
Go to WooCommerce → Settings → Address Book in your WordPress Admin dashboard to configure all plugin settings:
6.1 Product Page Shipping Estimator Settings
| Setting Name | Default | Description & Options |
|---|---|---|
| Enable Estimator | Yes (Checked) | Toggles the shipping calculator block on single product pages. |
| Display Position | Before Add to Cart Button | Select the widget placement on the product page: • Before Add to Cart Button • After Add to Cart Button • Below Price • Below Short Description • After Product Meta (SKU / Categories) • Below Product Summary (Before Tabs) •) |
| Exclude Weekends | Yes (Checked) | Skips Saturdays and Sundays when calculating projected arrival dates. |
| Estimated Delivery Days | Per-method inputs | Set Minimum and Maximum business delivery days for each shipping method registered in WooCommerce. |
6.2 Multi-Address Shipping Settings
| Setting Name | Default | Description & Options |
|---|---|---|
| Enable Multi-Address Shipping | Yes (Checked) | Enables the multi-destination shipping split banner and quantity allocation modal at checkout. |
| Max Shipping Addresses | 5 | Specifies the maximum number of distinct delivery addresses permitted per single checkout order. |
7. Checkout Compatibility (Gutenberg Block vs. Classic Shortcode)
The plugin is engineered with zero dependencies on legacy template hacks, offering deep support for both modern and classic checkout pages:
Modern Gutenberg Checkout Block
- Integrates natively with the WooCommerce Store API.
- Saved addresses appear in a responsive dropdown inside the shipping address block.
- Add or edit addresses directly inline without page reloads.
- Switching addresses triggers Store API recalculations for instant tax and shipping rate updates.
Classic Checkout
- Injects the saved address dropdown above shipping fields (via
woocommerce_before_checkout_shipping_form). - Includes a seamless “Save to Address Book” checkbox with custom nickname field for new addresses.
- Full AJAX synchronization with WooCommerce standard checkout updates.
8. Order Management, HPOS & Email Notifications
8.1 Admin Order Management
Store managers can easily review multi-destination orders under WooCommerce → Orders:
- Multi-Package Breakdown Box: Displays each package destination, recipient name, contact phone number, and the exact allocated items and quantities.
- Shipping Method & Cost: Clear visibility into the chosen shipping method and fee for each package.
⚡ 100% HPOS (High-Performance Order Storage) Certified:
The plugin declares full compatibility with WooCommerce HPOS (custom_order_tables). Package allocations and address identifiers are stored safely in wp_wc_orders_meta as well as synchronized with legacy post meta for maximum compatibility with third-party ERP, inventory, and fulfillment tools.
8.2 Customer Order Tracking & Transactional Emails
Both customers and fulfillment teams receive clear visibility over multi-package orders:
- Thank You (Order Received) Page: Renders a clear breakdown of each shipping package, recipient details, and assigned items.
- My Account → View Order: Persistent order overview allowing customers to review their multi-destination deliveries anytime.
- WooCommerce Transactional Emails: Injected automatically into customer order notifications and admin order emails via
woocommerce_email_after_order_table.
10. Frequently Asked Questions (FAQ) & Support
Q: Does this plugin work with both WooCommerce Block Checkout and Classic Checkout?
A: Yes! The plugin includes dedicated implementations for both the modern Gutenberg Checkout Block (via Store API) and the classic shortcode-based checkout.
Q: Can customers save custom address nicknames like “Mom’s House” or “Warehouse”?
A: Yes! Every address entry includes an optional label/nickname field that appears prominently on cards, checkout dropdowns, and multi-shipping allocation modals.
Q: What happens if a customer has only 1 item in their cart?
A: To maintain high checkout conversion rates, the Multi-Address Shipping option automatically hides when the cart contains only 1 product with a quantity of 1. It only activates when the order contains multiple items or quantities.
Q: How are shipping fees calculated for multi-address orders?
A: The plugin splits the cart into distinct shipping packages (woocommerce_cart_shipping_packages). WooCommerce calculates real-time shipping costs independently for each destination package based on your configured shipping zones and carrier rates.
Q: Does the product page shipping estimator support variable products?
A: Yes! When a customer selects different variations (e.g., XL or 10kg), the shipping estimator automatically recalculates shipping fees and delivery estimates based on the selected variation.