Muffs Warehouse Integration for WooCommerce

A WordPress plugin that automatically submits WooCommerce orders to the Muffs Warehouse Management System (WMS 2.0) via XML-RPC API.

Features

• Automatic Order Submission - Automatically send orders to the warehouse when they reach a specific status
• Stock Verification - Check warehouse inventory before submitting orders to prevent backorders
• Product Add-ons Support - Automatically includes WooCommerce Product Add-ons in warehouse orders
• Manual Submission - Manually submit orders from the order edit page with option to skip stock checks
• XML-RPC Integration - Secure communication with Muffs WMS 2.0 API
• Order Tracking - Track submission status and warehouse order IDs
• Error Handling - Comprehensive error logging and retry functionality
• Out of Stock Alerts - Visual indicators showing which items are out of stock and available quantities
• Flexible SKU Mapping - Support for custom SKU fields and add-on products
• Shipping Method Mapping - Automatic mapping of WooCommerce shipping methods to warehouse methods

Requirements

• WordPress 5.0 or higher
• WooCommerce 4.0 or higher
• PHP 7.4 or higher
• Muffs Warehouse account with XML-RPC access

Installation

1. Download the plugin files
2. Upload the muffs-warehouse-integration folder to /wp-content/plugins/
3. Activate the plugin through the 'Plugins' menu in WordPress
4. Go to WooCommerce → Muffs Warehouse to configure settings

Configuration

API Settings

1. Navigate to WooCommerce → Muffs Warehouse
2. Enter your API credentials:
   • API URL: Your warehouse API endpoint (e.g., muffsandcuffs.com/WMS/webservices/index.php)
   • Customer Number: Your Muffs customer account number
   • Access Key: Your XML-RPC access key (available in your Muffs account)
   • Use HTTPS: Enable for secure connections (recommended)

Order Settings

• Auto-Submit Orders: Enable to automatically submit orders
• Submit on Status: Choose which order status triggers submission (default: Processing)
• Check Stock Before Submission: Verify all items are in stock before submitting (recommended)
• Default Shipping Method: Set the default shipping method code (e.g., Priority, Ground, Express)
• Muffs SKU Meta Key: Custom field name for Muffs SKU (default: _muffs_sku)
• Product Add-ons SKU Mapping: Map add-on product labels to warehouse SKUs
• Enable Logging: Enable debug logging for troubleshooting

Testing the Connection

After entering your credentials:

1. Click the Test Connection button
2. Verify that the connection is successful
3. Check for any error messages

Usage

Automatic Submission

Once configured, orders will automatically submit to the warehouse when they reach the configured status (e.g., Processing).

Stock Checking: If stock checking is enabled, the plugin will:

1. Query the warehouse API for stock quantities for all items in the order
2. Compare required quantities with available stock
3. Only submit the order if ALL items are in stock
4. If any item is out of stock, the order will NOT be submitted automatically
5. An order note will be added showing which items are out of stock and their available quantities

Manual Submission

To manually submit an order:

1. Go to the order edit page
2. Look for the Muffs Warehouse meta box in the sidebar
3. Click Submit to Warehouse
4. Optionally check "Skip stock check" to force submission even if items are out of stock
5. View the submission status and warehouse order ID

Note: Manual submissions can bypass stock checking by selecting the "Skip stock check" option. This is useful when you know stock is being replenished or want to create a backorder.

Product SKU Mapping

The plugin looks for Muffs SKU in this order:

1. Custom meta field (configured in settings, default: _muffs_sku)
2. WooCommerce product SKU

To set a custom Muffs SKU:

1. Edit a product
2. Add a custom field with key _muffs_sku (or your configured key)
3. Enter the Muffs SKU value

Product Add-ons Support

The plugin automatically detects and includes WooCommerce Product Add-ons in warehouse orders.

How it works:

1. When a customer selects add-ons (e.g., "Toy Cleaner - 100ml"), the plugin detects them
2. Maps the add-on label to a warehouse SKU using the configured mapping
3. Includes the add-on products in the order submission
4. Quantity matches the parent product quantity

Default Add-on Mappings:

• "Toy Cleaner - 100ml" → SE238500
• "Pjur Anal Lube - 100ml" → PJC03002
• "Enema - 90ml" → WTC104CP
• "All - (Cleaner, Lube, & Enema)" → All three SKUs above (automatic)

Custom Mappings: You can customize add-on to SKU mappings in the settings page. This is useful if:

• You change add-on labels
• You add new add-on products
• SKUs change in the warehouse system

Example Order: If a customer orders:

• 1x Product ABC (SKU: ABC123)
• Add-on: Toy Cleaner - 100ml

The warehouse receives:

• 1x ABC123 (main product)
• 1x SE238500 (toy cleaner add-on)

Shipping Method Mapping

The plugin uses intelligent shipping method detection based on order destination and shipping options:

Custom Rules (Priority Order):

1. International Orders (non-US) → Always use BESTRATE
2. US Orders with "3-5 Business Day: Free" → Use BESTRATE
3. US Orders with "2-3 Business Day" → Use Priority

Fallback Mapping (for other shipping methods):

• flat_rate → Ground
• free_shipping → Ground
• local_pickup → Pickup
• priority → Priority
• express → Express

The plugin automatically detects the shipping country and method name to apply the correct warehouse shipping code.

Order Data Format

Orders are submitted to Muffs with the following information:

• Customer name (shipping or billing)
• Shipping address
• Email address
• Phone number
• Product SKUs and quantities
• Shipping method
• Order notes
• Reference fields (WooCommerce Order ID and Order Number)

Troubleshooting

Orders Not Submitting

1. Check that auto-submit is enabled in settings
2. Verify the order status matches your configured submission status
3. Check if items are in stock - Look at the order edit page for stock information
4. Check the order notes for error messages
5. Enable logging and check WooCommerce → Status → Logs

Out of Stock Items

If an order fails due to out of stock items:

1. The order meta box will show which items are out of stock and their available quantities
2. The order note will list the specific SKUs and stock levels
3. You can wait for stock to be replenished and retry submission
4. Or manually submit with "Skip stock check" enabled to create a backorder

Recommendation: Enable stock checking to prevent overselling and ensure orders can be fulfilled immediately.

API Connection Errors

1. Verify your API credentials are correct
2. Test the connection using the Test Connection button
3. Ensure HTTPS is properly configured
4. Check that your server can make outbound HTTP requests

Missing SKU Errors

1. Ensure all products have a SKU or custom Muffs SKU
2. Check the SKU meta key in settings matches your custom field
3. Review the order notes for which products are missing SKUs
4. For add-ons, verify the add-on labels match the configured mapping

Add-on Products Not Included

If add-on products aren't being sent to the warehouse:

1. Check that WooCommerce Product Add-ons plugin is active
2. Verify the add-on label exactly matches the mapping in settings (case-insensitive)
3. Check the logs to see if add-ons are being detected
4. Ensure the add-on field name contains "add-on" or "addon"

Stock Check Performance

If stock checking is slow:

1. The plugin makes one API call per product SKU in the order
2. Consider caching product stock levels in your own system
3. For high-volume stores, you may want to disable automatic stock checking and verify manually

API Methods Used

This plugin uses the following Muffs XML-RPC methods:

• weborders.submitOrder - Submit orders to warehouse
• weborders.findOrderById - Retrieve order status
• catalog.findProductBySku - Look up product information
• catalog.getStockQuantity - Check stock levels
• system.listMethods - Test connection

File Structure

muffs-warehouse-integration/
├── muffs-warehouse-integration.php    # Main plugin file
├── includes/
│   ├── class-muffs-api-client.php     # XML-RPC API client
│   ├── class-muffs-order-handler.php  # Order submission logic
│   └── class-muffs-settings.php       # Admin settings page
└── README.md                          # This file

Hooks and Filters

Actions

• woocommerce_order_status_changed - Triggers order submission on status change

Custom Hooks (for developers)

You can extend the plugin functionality using these hooks:

// Modify order data before submission
add_filter('muffs_order_data', function($order_data, $order) {
    // Modify $order_data array
    return $order_data;
}, 10, 2);

Support

For issues with:

• The plugin: Check the logs and error messages
• Muffs API: Contact Muffs support for API credentials and access
• WooCommerce integration: Review WooCommerce documentation

Changelog

1.0.0 - Security Hardened (2026-01-05)

• Initial release
• XML-RPC integration with Muffs WMS 2.0
• Automatic and manual order submission
• Real-time warehouse stock checking before order submission with 5-minute caching
• WooCommerce Product Add-ons support with SKU mapping
• Visual out-of-stock indicators in order meta box
• Option to skip stock check for manual submissions
• Configurable add-on to SKU mapping with default mappings
• Automatic detection of "All" add-on option (includes all 3 products)
• Intelligent shipping method detection (international/US, business day rules)
• Settings page with API configuration
• Order meta box with submission status
• Comprehensive error handling and logging
• Order notes with detailed stock availability information
• Security Features:
  • Comprehensive input sanitization on all settings
  • Secure API key storage (masked in UI, not exposed in HTML)
  • SKU meta key validation to prevent arbitrary field access
  • Customer PII protection in logs (GDPR compliant)
  • Enhanced XML-RPC error handling
  • Capability checks on admin functions
  • Stock caching for performance and rate limit protection

License

GPL v2 or later

Credits

Developed for integration with Muffs Warehouse Management System (WMS 2.0)