## Instructions - Baseline stack: WordPress + WooCommerce + Storefront/Blocks theme + child theme for CSS; PHP 8.1+, HTTPS everywhere before accepting payments. - Products: choose correct type — Simple (one SKU), Variable (size/color variations with per-variation price/stock/image), Grouped, External, Downloadable/Virtual (no shipping). - Attributes: global attributes (pa_color) for filtering/variations vs custom per-product; set SKUs, weights, dimensions, stock at variation level. - Payments: Stripe + PayPal standard; develop in sandbox/test mode with `4242 4242 4242 4242`, webhooks configured, then switch to live keys + real $1 charge + refund. - Shipping: zones (domestic/intl/local pickup) → methods (flat rate per zone, free over $X, table-rate plugin if needed); test every zone postcode path. - Tax: enable taxes, configure standard/reduced/zero rates per nexus, display prices incl/excl per locale, validate with TaxJar/Avalara if multi-state/EU VAT. - Coupons: one rule per coupon (percent/fixed/product/cart), usage limits + expiry + minimum spend; test stacking/exclusion logic before launch. - Checkout: Blocks checkout, guest + account flows, required fields minimal, address autocomplete, error messages inline; never customize core templates — use hooks. - Order flow: Pending → Processing → Completed (+ On-hold/Refunded/Failed); test full lifecycle: place → pay → fulfill → ship → email → refund path. - Harden: daily backups (files+DB), staging clone, update order (staging → backup → Woo → theme → plugins → test checkout), lock `wp-config.php`/admin with 2FA. - Measure: HPOS enabled, object cache, image sizes capped, `wc_get_orders` over raw SQL; monitor abandoned carts + gateway decline codes. - Legal: privacy/refund/shipping/terms pages, cookie consent, GDPR export/erase hooks, invoice numbering for EU compliance. ## Examples - T-shirt shop: global `pa_size/pa_color` attributes, variable product (12 variations), per-variation stock/photos, flat-rate shipping + free over $75. - Digital course: downloadable/virtual product, expiring links, Stripe checkout, coupon `WELCOME10` (10% first order, min $20, one use per email). - Subscription box: Woo Subscriptions, monthly variable box, PayPal Reference Transactions, trial coupon, dunning emails for failed renewals. ## Workflows 1. Setup: staging site → HTTPS → install Woo → wizard (currency, locale, tax) → payment sandbox keys → shipping zones draft. 2. Catalog: global attributes → simple product first → variable product with variations → coupons → cross-sells/upsells. 3. Checkout test matrix: guest/account, each gateway, each shipping zone, coupon valid/expired/minimum, tax-exempt address. 4. Go live: switch Stripe/PayPal to live, $1 real purchase + refund, webhook logs green, order emails deliverable (SPF/DKIM). 5. Launch care: backup schedule on, update runbook pinned, uptime + order-failure alerts, weekly abandoned-cart + top-search-terms review. ## Templates ```php // child-theme/functions.php — Woo hooks, never edit core templates add_action('woocommerce_before_shop_loop', function () { echo '

Free shipping over $75 — no code needed.

'; }); // Free shipping over $75 programmatically add_filter('woocommerce_package_rates', function ($rates, $package) { if (WC()->cart->get_subtotal() >= 75) { foreach ($rates as $id => $rate) { if ($rate->method_id !== 'free_shipping') unset($rates[$id]); } } return $rates; }, 10, 2); ``` ```bash # smoke-test orders via WP-CLI + HPOS check wp wc shop_order list --status=processing --format=table wp wc product list --type=variable --format=ids wp option get woocommerce_custom_orders_table_enabled ``` ## Tools - SARAH `shell_run`: `wp wc ...` for products/orders/coupons, `wp option get woocommerce_*` for settings, `wp db export` before changes. - SARAH `file_write`: custom CSS/PHP only in child theme (`wp-content/themes/storefront-child/`); hooks/filters over template overrides. - SARAH preview: run checkout end-to-end in sandbox (test card + PayPal sandbox buyer), screenshot each order status + customer email. ## Advanced - Debugging: enable `WooCommerce → Status → Logs` + `WP_DEBUG_LOG`; declined card codes live in Stripe dashboard, not Woo; webhook failures almost always missing HTTPS or blocked `/wc-api/` path. - HPOS: keep compatibility (`woocommerce_custom_orders_table_enabled=yes`), query with `wc_get_orders(['status'=>'processing'])`, migrate legacy meta carefully. - Troubleshooting: variations all greyed → no price/stock on that combo; tax wrong → wrong nexus/address base; emails in spam → no SPF/DKIM/DMARC on sending domain. - Perf: limit variations (<50 per product), compress images to WebP ≤1600px, cache with Woo-aware host (exclude cart/checkout/account from cache). - Pro tip: test webhooks locally with Stripe CLI (`stripe listen --forward-to /?wc-ajax=checkout`); snapshot DB before every live gateway flip. ## Documentation - WooCommerce docs: https://woocommerce.com/documentation - Stripe testing: https://docs.stripe.com/testing - WP-CLI Woo commands: https://github.com/woocommerce/woocommerce/wiki/WC-CLI