Document – Weight & Dimensional Weight Rates for WooCommerce

1. Plugin Overview & Core Value

Default WooCommerce shipping methods (Flat Rate, Free Shipping, Local Pickup) are static. They fail as soon as your catalog contains items with varying weights, oversized dimensions, or different handling requirements. YeeShipping replaces rigid flat rates with a dynamic conditional rules engine:

• Prevent Undercharging on Bulky Goods: Automatically calculate dimensional weight (L × W × H ÷ DIM Divisor) and charge whichever is greater between physical and volumetric weight.
• Per-Shipping-Class Calculation: Charge shipping individually for fragile, hazardous, or heavy items, aggregating the final total via Sum, Highest, or Lowest cost.
• Boost Conversion with Delivery Dates: Show dynamic transit estimates (e.g., “Standard Delivery (Est: 2 – 4 business days)”) with cutoff times and weekend exclusions.
• Zero Risk Testing: Built-in live simulator lets you test complex rule scenarios directly in your admin screen without placing fake orders.

2. Installation & Shipping Zone Setup

1. Download the yeeshipping.zip file.
2. In your WordPress dashboard, navigate to Plugins → Add New Plugin → Upload Plugin.
3. Select the zip file, click Install Now, and then click Activate Plugin.
4. Navigate to WooCommerce → Settings → Shipping → Shipping Zones.
5. Select an existing shipping zone (or click Add shipping zone to create a new one).
6. Click Add shipping method, select YeeShipping (Weight & Dim Weight), and confirm.
7. Click on the method title to access all configuration options.

3. Dimensional (Volumetric) Weight Explained

Modern carriers charge by cubic space rather than physical scale weight if a package is bulky. YeeShipping implements the universal carrier standard:

Chargeable Weight = MAX(Actual Physical Weight, Volumetric Weight)

Volumetric Weight = (Length × Width × Height) ÷ DIM Factor

Configuring the DIM Factor:

Under the Advanced Options section:

• DIM Factor: Default is 5000 for metric measurements (cm/kg) or 139 / 166 for imperial measurements (in/lbs).
• Example: A box containing a pillow weighs 0.8 kg, but measures 50cm × 40cm × 20cm.
  Volumetric Weight = (50 × 40 × 20) ÷ 5000 = 8.0 kg.
  YeeShipping bills the order at 8.0 kg instead of 0.8 kg, protecting your profit margins.

4. Estimated Delivery Date & Transit TimesNew in v2.0.0

Clearly informing customers when their order will arrive builds immediate trust and slashes cart abandonment. Configure this under the Estimated Delivery Time section:

Setting	Options	Behavior & Description
Enable Estimated Delivery	Checkbox (Yes / No)	Turns the transit time display on or off.
Delivery Type	Range of days Fixed days Estimated delivery date Custom text	Range of days: E.g., 2 – 4 business days. Fixed days: E.g., 3 business days. Estimated delivery date: Computes exact calendar dates, e.g., Friday, 24/10/2026. Custom text: Freeform string, e.g., Same-day courier within 2 hours.
Exclude Weekends	Checkbox (Default: Yes)	Skips Saturdays and Sundays so only legitimate business days are counted.
Order Cutoff Time	Time input (e.g. 14:00)	Orders placed past this hour automatically push the start date forward by +1 business day.
Date Format	Dropdown (d/m/Y, l, d/m/Y, F j, Y, etc.)	Formats calendar dates cleanly according to your WordPress site locale.
Display Format	Template string	Supports {title} and {delivery_time}. Default: {title} (Est: {delivery_time}).

5. Per-Shipping-Class Calculation EngineNew in v2.0.0

Under Cost Calculation, you can configure how orders containing diverse shipping classes are billed:

1. Calculation Type

• Per order: Evaluates your rules table once across the combined cart contents. (100% backward compatible).
• Per shipping class: Automatically splits the cart items into sub-packages by shipping class ID. Rules are executed independently for each shipping class group.

2. Class Cost Aggregation Modes

• Sum: Adds up the calculated rates of all shipping classes present in the cart.
  Example: Standard item shipping ($5) + Heavy item shipping ($25) = $30 Total.
• Highest: Charges only the single highest shipping class cost in the cart.
  Example: Standard item ($5) + Heavy item ($25) = $25 Total.
• Lowest: Charges only the lowest shipping class fee among the items.

3. Products Without Class

• Apply rules: Treats unclassified products as their own sub-package and calculates their rule fee.
• Free: Does not bill additional shipping for items lacking a shipping class when other classed items are in the cart.

6. Free Shipping Threshold & Left For Free Shipping (LFFS) Notice

YeeShipping includes a built-in free shipping engine with dynamic progress bar notifications to boost Average Order Value (AOV):

• Free Shipping Requirements: Minimum order amount, minimum item quantity, free shipping coupon, or combinations.
• Left For Free Shipping Notice: Displays an alert informing customers how much more they need to spend to unlock free shipping. Available shortcodes:
  • {amount_left}: Remaining monetary value to reach the free shipping threshold.
  • {min_amount}: Free shipping threshold value.
  • {current_amount}: Customer’s current qualifying cart total.
• Visual Progress Bar: Displays an interactive percentage bar showing customer progress toward free delivery.
• Display Locations: Cart page, Checkout page, Product pages, and Mini-Cart widget.

7. Comprehensive Guide to All 22 Rule Conditions

Every rule in YeeShipping begins with a When condition. Below is the complete reference for all 22 condition types supported by the plugin, complete with exact operators and realistic configuration examples:

1. None (Always)

Condition: none | Category: General

This condition matches every order unconditionally. It is typically placed at the bottom of the table as a default fallback or at the top as a universal base rate.

Example: Universal Flat Rate

When: Always | Rule Cost: $10.00
Result: Every customer is charged $10 base shipping unless a higher-priority rule overrides it.

2. Price (Cart Subtotal)

Condition: price | Category: Cart | Operators: is (in range), is not (outside range)

Evaluates the qualifying cart subtotal. Works with pre-coupon or post-coupon totals based on your discount settings.

Example: Tiered Delivery by Order Value

Rule 1: Price is from $0.00 to $49.99 → Cost: $8.00
Rule 2: Price is from $50.00 to $99.99 → Cost: $4.00
Rule 3: Price is from $100.00 → Cost: $0.00 (Free Shipping)

3. Item Quantity (Units)

Condition: item | Category: Cart | Operators: is, is not

Counts the total number of individual product units across all items in the cart (e.g., 3 shirts + 2 hats = 5 items).

Example: Bulk Item Surcharge

When: Item is from 10 to 999 | Cost: $15.00 + Additional Cost: $1.00 per 1 item
Result: Orders with 12 items pay $15 base + $2 incremental = $17.00.

4. Cart Line Item (Unique Lines)

Condition: cart_line_item | Category: Cart | Operators: is, is not

Counts unique product entries (lines) in the cart regardless of the quantity of each. If a customer buys 10 notebooks and 1 pen, that equals 2 cart line items.

Example: Multi-Package Packing Fee

When: Cart line item is from 4 to 99 → Cost: $12.00 (Covers complex packing across multiple bins).

5. Actual Weight

Condition: weight | Category: Product | Operators: is, is not

Evaluates the combined physical scale weight of products in the cart using the store’s weight unit (kg or lbs).

Example: Heavy Freight Surcharge

When: Weight is from 30 kg to 500 kg → Cost: $50.00 (Triggers freight carrier).

6. Dimensional Weight (Volumetric Weight)

Condition: dimensional_weight | Category: Product | Operators: is, is not

Evaluates the volumetric weight calculated from product box dimensions (L × W × H ÷ DIM Factor).

Example: Bulky Box Threshold

When: Dimensional weight is from 15 kg → Cost: $35.00 (Accounts for airline cargo cubic size).

7. Volume (Total Cubic Volume)

Condition: volume | Category: Product | Operators: is, is not

Evaluates the combined cubic volume of all cart items in cubic centimeters (cm³) or cubic inches (in³).

Example: Van Space Surcharge

When: Volume is from 50000 cm³ → Cost: $25.00.

8. Max Dimension (Longest Side)

Condition: max_dimension | Category: Product | Operators: is, is not

Scans every product in the cart and checks the single longest side among Length, Width, and Height.

Example: Oversized Length Fee

When: Max dimension is from 120 cm → Cost: $45.00 (Curtain rods, fishing poles, or ski equipment).

9. Total Overall Dimensions (Girth / L+W+H)

Condition: total_overall_dimensions | Category: Product | Operators: is, is not

Calculates the sum of Length + Width + Height for products in the cart. Required by many national postal services (e.g., total length + girth ≤ 300 cm).

Example: Girth Limit Fee

When: Total overall dimensions is from 200 cm → Cost: $30.00.

10 – 12. Product Length / Width / Height

Conditions: product_length, product_width, product_height | Category: Product

Targets a specific axis independently. Perfect when a courier has a strict restriction on a single dimension (such as pallet width ≤ 80 cm).

Example: Over-width Pallet Handling

When: Width is from 85 cm → Cost: $60.00.

13. Specific Product

Condition: product | Category: Product | Operators: any, all, none

Triggers when the cart contains (or does not contain) specifically selected products.

Example: Promotional Gift Shipping

When: Product has any of [Sample Mug, Promo Hat] → Cost: $2.00.

14. Product Category

Condition: product_category | Category: Product | Operators: any, all, none

Applies rates based on WooCommerce product categories assigned to cart items.

Example: Furniture Freight Rate

When: Product category has any of [Living Room Furniture, Sofas] → Cost: $75.00.

15. Product Tag

Condition: product_tag | Category: Product | Operators: any, all, none

Targets items marked with specific tags (e.g., refrigerated, heavy, clearance).

Example: Cold-Chain Insulated Shipping

When: Product tag has any of [Frozen, Perishable] → Cost: $22.00 (Dry ice fee).

16. Shipping Class

Condition: shipping_class | Category: Product | Operators: any, all, none

Triggers when items in the cart belong to specific WooCommerce shipping classes. Seamlessly integrates with the Per-Shipping-Class calculation engine.

Example: Fragile Glassware Rate

When: Shipping class has any of [Fragile Glass] → Cost: $18.00.

17. Product Stock Quantity

Condition: product_stock_quantity | Category: Product | Operators: is, is not

Evaluates the remaining stock level of items in the cart. Useful for clearance discounts or low-stock fulfillment surcharges.

Example: Clearance Shipping Discount

When: Stock quantity is from 1 to 3 (low stock remaining) → Cost: $3.00.

18. Product Stock Status

Condition: product_stock_status | Category: Product | Operators: is, is not

Evaluates whether items in the cart are In stock, Out of stock, or On backorder.

Example: Split-Shipment Backorder Fee

When: Stock status is On backorder → Cost: $15.00 (Covers dispatching two separate parcels).

19. User Role

Condition: user_role | Category: User | Operators: any, all, none

Applies custom rates tailored to WordPress user roles (Wholesale, Retailer, VIP, Member, Administrator, Guest).

Example: B2B Wholesale Flat Freight

When: User role has any of [Wholesale Buyer, B2B Partner] → Cost: $40.00.

20. Day of the Week

Condition: day_of_the_week | Category: Destination & Time | Operators: any, all, none

Enables rates based on the current day of the week (Monday through Sunday), respecting the store’s timezone.

Example: Weekend Courier Surcharge

When: Day of week has any of [Saturday, Sunday] → Cost: $20.00.

21. Time of the Day

Condition: time_of_the_day | Category: Destination & Time

Applies rates within an active time window (e.g. From: 20:00 To: 06:00). Seamlessly supports windows spanning past midnight.

Example: Late-Night Express Delivery

When: Time from 21:00 to 04:00 → Cost: $30.00.

22. Distance (Google Maps API)

Condition: distance | Category: Destination & Time | Operators: is, is not

Measures actual driving distance from your store origin to the customer’s shipping address using the Google Distance Matrix API.

Example: Tiered Local Delivery Radius

Rule 1: Distance is from 0 km to 5 km → Cost: $5.00
Rule 2: Distance is from 5.01 km to 15 km → Cost: $12.00
Rule 3: Distance is from 15.01 km to 30 km → Cost: $25.00

8. Additional Costs Engine (Multiplier Formulas)

Every rule can have multiple Additional Costs added to its base cost, creating dynamic pricing formulas:

Based On Metric	Formula	Example Setting & Result
Weight	CEIL(Total Weight ÷ Per) × Cost	Cost $2.00 per 1 kg: An 8.4kg parcel adds 9 × $2 = $18.00.
Dimensional Weight	CEIL(Dim Weight ÷ Per) × Cost	Cost $3.00 per 2 kg: A 10kg volumetric box adds 5 × $3 = $15.00.
Item (Quantity)	CEIL(Item Qty ÷ Per) × Cost	Cost $1.50 per 1 item: 4 items in cart adds 4 × $1.50 = $6.00.
Cart Line Item	CEIL(Line Items ÷ Per) × Cost	Cost $2.00 per 1 line: 3 unique products adds 3 × $2 = $6.00.
Volume	CEIL(Volume ÷ Per) × Cost	Cost $5.00 per 10,000 cm³ of cubic space.
Distance	CEIL(Distance ÷ Per) × Cost	Cost $1.00 per 1 km: A 12km trip adds 12 × $1 = $12.00.
Price (Subtotal)	CEIL(Subtotal ÷ Per) × Cost	Cost $3.00 per $100.00: Acts as an insurance fee based on order value.
Shipping Cost	CEIL(Base Cost ÷ Per) × Cost	Cost $10.00 per $100.00 base: Functions as a 10% fuel surcharge multiplier.

9. Special Rule Actions

Control rule processing flow using the Action dropdown on each row:

• None: Normal execution. Rule cost is collected and aggregated based on your Rules Calculation setting (Sum, Lowest, Highest).
• Stop (Stop rule processing): If this rule matches, the system calculates its fee and immediately stops evaluating any lower-priority rules. Prevents accidental stacking of fees.
• Hide other methods: When this rule matches, YeeShipping becomes the sole method displayed at checkout, hiding standard WooCommerce Flat Rate, Local Pickup, etc.
• Hide method: If this rule matches, the entire YeeShipping method is concealed. Useful for blocking orders that exceed carrier safety or dimension limits.

10. Interactive Test Rate Simulator & Rule DebuggerNew in v2.0.0

The Test Rate Simulator is situated right below the rules table. It runs a full sandbox calculation using the exact live values in your form:

Test Before Saving: Edit your rules in the table and immediately hit Run Test Calculation. The simulator sends your un-saved rules via AJAX and shows you the result instantly!

Testing Inputs:

• Cart & Items: Cart Subtotal ($), Item Quantity, Line Item Count, and Shipping Class.
• Weight & Dimensions: Actual Weight (kg/lbs), Dimensions L × W × H (cm/in), and Distance (km/mi).
• Customer & Time: User Role, Day of the Week, and Time of Day.

Understanding the Audit Log:

• MATCHED: The rule’s condition was satisfied. Shows the base fee and itemized breakdown of additional cost multipliers.
• SKIPPED: Explains why the rule failed (e.g., Subtotal: $45.00 | Range: [$50.00 – $100.00]).
• STOPPED: Indicates execution stopped due to a preceding rule with the “Stop” action.
• INFO: Displays delivery time estimate preview and parameter summaries.

11. One-Click Rules Backup & JSON Import/Export

Never lose your complex shipping rules or waste hours manually recreating them on new sites:

• Export Rules: Click Export Rules at the top of the table to download a structured .json file containing all your rule conditions, operators, costs, and priority order.
• Import Rules: Click Import Rules, select your previously saved JSON file, and your entire table will populate immediately.