WooCommerce fetch handlers: orders, subscriptions, products

[chubes4]

Summary

Add WooCommerce fetch handlers to data-machine-business — enabling DM flows to query WooCommerce orders, subscriptions, and products as data sources.

Why a Dedicated Handler (Not WordPress Posts Fetch)

The existing wordpress_posts fetch handler in core cannot support WooCommerce orders due to three fundamental incompatibilities:

1. HPOS (Custom Order Tables) — Default Since WC 8.2 (Nov 2023)

Modern WooCommerce stores orders in custom tables (wc_orders, wc_orders_meta, wc_order_addresses), not wp_posts. WP_Query on shop_order returns empty results on any HPOS-enabled install.

2. shop_order Is Not Public

The WordPress Posts handler filters to get_post_types(['public' => true]). shop_order is public => false and does not appear in the UI dropdown. Same for shop_subscription.

3. Wrong Data Extraction

Even if queries worked, the handler extracts post_title and post_content — meaningless for orders. All real order data (line items, totals, customer info, addresses) is in WC's order objects, not post fields.

Proposed Handlers

woocommerce_orders (Fetch)

// Uses wc_get_orders() — HPOS-compatible
$args = [
    'date_created' => '2026-02-01...2026-02-28',  // or 'previous_month'
    'status'       => ['completed', 'refunded'],
    'limit'        => -1,
    'orderby'      => 'date',
    'order'        => 'DESC',
];
$orders = wc_get_orders($args);

DataPacket output per order:

[
    'title'    => "Order #12345",
    'content'  => "",  // or formatted summary
    'metadata' => [
        'source_type'       => 'woocommerce_orders',
        'order_id'          => 12345,
        'order_date'        => '2026-02-15 10:30:00',
        'order_status'      => 'completed',
        'order_total'       => '149.99',
        'order_currency'    => 'USD',
        'payment_method'    => 'stripe',
        'customer_name'     => 'John Doe',      // PII — transform step strips
        'customer_email'    => 'john@example.com', // PII
        'billing_address'   => '...',            // PII
        'shipping_address'  => '...',            // PII
        'line_items'        => [
            ['product_name' => 'Widget Pro', 'quantity' => 2, 'total' => '99.98'],
            ['product_name' => 'Addon Pack', 'quantity' => 1, 'total' => '50.01'],
        ],
        'order_type'        => 'single',  // or 'renewal' for subscription renewals
        'coupon_codes'      => ['SAVE10'],
        'refund_total'      => '0.00',
    ],
]

woocommerce_subscriptions (Fetch)

For sites with WooCommerce Subscriptions plugin. Uses wcs_get_subscriptions().

Config options:

• Status filter: active, on-hold, cancelled, expired
• Date range: created/modified/next_payment
• Include related orders (parent + renewal)

woocommerce_products (Fetch)

Products ARE public post types, but the WP Posts handler misses pricing, inventory, variations, and other meta. A dedicated handler extracts the full product data.

Config options:

• Product type: simple, variable, grouped, external
• Stock status: instock, outofstock, onbackorder
• Category/tag filtering
• Price range

Handler Config Schema

{
  "handler": "woocommerce_orders",
  "config": {
    "date_range": "previous_month",
    "custom_date_start": "",
    "custom_date_end": "",
    "statuses": ["completed", "processing", "refunded"],
    "include_line_items": true,
    "include_customer_info": true,
    "include_addresses": true,
    "order_types": ["single", "renewal"],
    "posts_per_page": -1
  }
}

Flow Example: Katie Keith's Monthly Sales Export

Flow: Monthly Sales Export
Schedule: Monthly (1st of month)

Step 1: FETCH (woocommerce_orders)
  config: { date_range: "previous_month", statuses: ["completed", "refunded"] }

Step 2: TRANSFORM (#3)
  operations:
    - remove_fields: [customer_name, customer_email, billing_address, shipping_address]
    - split: { field: "order_type", groups: { sales: ["single"], renewals: ["renewal"] } }
    - format: { output: "csv", filename: "{group}-{month}-{year}.csv" }

Step 3: PUBLISH (email — core #341)
  to: accountant@example.com
  subject: "Monthly Sales & Renewals Report - {month} {year}"
  attachments: [from transform step]

Requirements

• WooCommerce 8.0+ (HPOS support)
• data-machine core
• data-machine-business (for Transform step when anonymization needed)
• WooCommerce Subscriptions (optional, for subscription handler)

Implementation Notes

• Must use wc_get_orders() / WC CRUD API — never WP_Query on shop_order
• Must check class_exists('WooCommerce') before registering handlers
• Handler registration follows existing pattern: HandlerRegistrationTrait::registerHandler()
• Deduplication via order ID in ProcessedItems table (existing DM system)