WOOCOMMERCE AUTO COMPLETE ORDERS
Installation and user guide | Version 1.0.0

1. WHAT IT DOES

After a payment gateway calls WooCommerce's payment_complete() method, the
plugin changes an eligible paid order from Processing to Completed. The
customer does not need to return to your website. A gateway webhook can
trigger completion in the background.

WooCommerce already completes orders containing only products that are both
virtual and downloadable in many standard flows. Those orders remain
completed; this plugin does not repeat that transition or add its own note.

This plugin starts DISABLED. It does not collect payment, verify funds with
your payment provider, deliver physical products, or scan old orders.
It relies on the gateway's WooCommerce payment confirmation.

2. REQUIREMENTS AND SUPPORT SCOPE

* WordPress 6.5 or later; PHP 7.4 or later.
* WooCommerce 8.2 or later, installed and active.
* An administrator account to install and configure the plugin.
* A payment gateway that uses WooCommerce's payment_complete() method.

These are declared minimum requirements, not a tested version matrix.
The code uses WooCommerce order APIs and declares HPOS compatibility.
Legacy order storage and HPOS are intended to work without direct database
queries. Classic and block checkouts use the same server-side event.
Validate your actual versions, gateway and extensions on staging first.
Subscriptions, bookings, preorders and other extension-specific fulfilment
workflows have not been certified. Only shop_order objects are eligible;
renewal orders that are shop_order objects can still qualify.

3. INSTALLATION

1) Back up your site and database. Start on a staging copy of the store.
2) In WordPress, open Plugins > Add New Plugin > Upload Plugin.
3) Select woocommerce-auto-complete-orders-1.0.0.zip. Upload the ZIP as-is;
   you do not need to unzip or repackage it.
4) Choose Install Now, then Activate Plugin.
5) Open WooCommerce > Auto Complete Orders (or the plugin's Settings link).
6) Select the appropriate order eligibility mode.
7) Check Enable, then click Save Changes.
8) Run the tests in section 6 before enabling the plugin on your live store.

Manual installation: unzip the archive, then upload the complete
woocommerce-auto-complete-orders folder to wp-content/plugins/. Activate
the plugin in WordPress and follow steps 5-8 above.

If WooCommerce is missing or inactive, activate it first. WordPress dependency
handling may prevent activation; a fallback notice appears if needed.

4. SETTINGS

Enable
  Off by default. When off, the plugin makes no order status changes.
  WooCommerce's own completion behaviour still applies.

Every product is virtual (default)
  Every line item must reference an existing product marked Virtual.
  A mixed basket with a physical product stays Processing.

Every product is downloadable
  Every line item must reference an existing product marked Downloadable.
  Downloadable and Virtual are independent WooCommerce product settings.
  A downloadable physical product can qualify in this mode.

All products (including physical goods)
  Any nonempty basket of existing products can qualify. This marks physical
  orders fulfilled immediately after payment; select it only if that matches
  your fulfilment process.

Only administrators with manage_options can view or save these settings.
Shop managers without that capability cannot configure the plugin.

5. ELIGIBILITY AND DAILY USE

The plugin checks the current settings at the payment-complete event. The
order must be a regular shop order, currently Processing, with WooCommerce
reporting it paid and a paid date recorded. Every line item must match the
chosen mode. Empty orders and orders with missing/deleted products are skipped.

Cash on delivery (cod), direct bank transfer (bacs), and cheque (cheque) are
always excluded. This safeguard cannot be disabled in the settings. A custom
offline gateway using another ID is not automatically identified as offline;
confirm its integration before use. Free orders can qualify when WooCommerce
runs payment_complete() and all eligibility checks pass.

Pending, On hold, Failed, Cancelled, Refunded and already Completed orders
are not directly changed by this plugin. A legitimate later gateway payment
confirmation may first move an order into Processing through WooCommerce.
The plugin then checks its eligibility. It has no bulk or scheduled processing.
Manually setting an order to Processing does not trigger this plugin.
An existing unpaid order can qualify if its payment is confirmed later.

When the plugin completes an order it adds a private order note identifying
the automatic completion. View it under WooCommerce > Orders > the order.
Repeated payment events for an already completed order are ignored.

WooCommerce's ordinary completion events still run: completed-order emails,
download permissions and connected automations follow your store setup.
Depending on gateway flow and other hooks, customers may receive a Processing
email before the Completed email. This plugin does not suppress emails.

6. STAGING ACCEPTANCE TESTS

Use your payment gateway's sandbox/test mode and test email addresses.

* Enable Virtual mode. Pay for a virtual, non-downloadable product using a
  supported online gateway: expect Completed plus the plugin's order note.
* Pay for a mixed virtual/physical basket in Virtual mode: expect Processing.
* In Downloadable mode, pay for an all-downloadable basket: expect Completed.
  Add a non-downloadable item: expect Processing.
* In All-products mode, pay for a physical product: expect Completed.
* Place a bank transfer, cheque or cash-on-delivery order: expect the usual
  WooCommerce/gateway status and no plugin completion note.
* Leave payment pending or fail a sandbox payment: expect no plugin completion.
* Disable the plugin setting and pay for a virtual, non-downloadable product:
  expect standard WooCommerce behaviour, typically Processing.
* Confirm an already completed order receives no extra plugin completion note
  when your gateway safely replays its sandbox payment notification.
* Check stock changes, completed-order email, downloads and any fulfilment,
  subscription or accounting integration used by your store.
* If your store uses HPOS, perform the same tests with HPOS enabled. Test the
  checkout type(s) you offer and each payment gateway you intend to use.

Payment methods and other plugins may change the standard expected status.
Review their configuration if results differ.

7. TROUBLESHOOTING

Order stays Processing
  Confirm Enable is checked and saved. Check each product's Virtual or
  Downloadable setting, including the variation actually purchased. Confirm
  the order has a paid date and its gateway is not excluded. Ask your gateway
  provider whether successful payment calls WC_Order::payment_complete().
  Gateways that only assign a status are not supported by this trigger.

Order stays On hold or Pending payment
  Resolve payment confirmation or webhook delivery with your payment provider.
  This plugin does not override an unpaid order.

Completed but no plugin note
  WooCommerce or another extension may have completed the order itself.

Missing email
  Check WooCommerce > Settings > Emails and your site's mail delivery. The
  plugin uses ordinary WooCommerce status transitions and email settings.

Settings page missing
  Verify WooCommerce and the plugin are active and you are an administrator.

Unexpected behaviour
  Disable Enable and save. Inspect order notes and WooCommerce > Status >
  Logs for source wc-auto-complete-orders if a caught completion error occurred.
  On staging, check for conflicting order-status or fulfilment plugins.

8. DISABLE, UPDATE AND REMOVE

Uncheck Enable and save to stop new plugin-driven changes, or deactivate
the plugin. Existing order statuses and notes are retained. Deactivation
retains settings. Deleting the plugin through WordPress removes this site's
wcao_settings option but does not edit orders or delete order notes.

For updates, back up first, test the replacement ZIP on staging, then use
WordPress's upload-and-replace workflow. Settings are retained when replacing
files without deleting the plugin through the Plugins screen.

Multisite: configure settings separately on each site. Deletion only cleans
the current site's option; remove other sites' settings separately if needed.

9. PRIVACY AND LICENSE

No external services, telemetry, scheduled jobs or new database tables.
Settings are stored in WordPress options. Private order notes and caught error
logs are stored by WooCommerce. No payment credentials are stored by this plugin.
License: GNU GPL version 2 or later; see LICENSE.txt.

10. VALIDATION STATUS

The distribution structure and source safety checks were validated during
packaging. A PHP interpreter and a live WordPress/WooCommerce instance were
not available in the build environment. PHP linting and runtime integration
tests have therefore not been performed. Complete section 6 before live use.
For a PHP-equipped environment, also run:
  php -l woocommerce-auto-complete-orders.php
  php -l uninstall.php

OFFICIAL TECHNICAL REFERENCES

WooCommerce order payment_complete() implementation:
https://woocommerce.github.io/code-reference/files/woocommerce-includes-class-wc-order.html
WooCommerce order statuses:
https://woocommerce.com/document/managing-orders/order-statuses/
WooCommerce HPOS extension guidance:
https://developer.woocommerce.com/docs/features/orders/high-performance-order-storage/recipe-book/
WordPress Settings API:
https://developer.wordpress.org/plugins/settings/settings-api/
