We're excited to announce that the plugin is is now owned by Meta, and we invite the developer community to join us in shaping its future through contributions.
Grow your business on Facebook, Instagram and WhatsApp. Easily promote your products and target accurately using powerful sales and marketing tools. Update your customers about their orders on WhatsApp at every step, freeing up more time for you to focus on your business. Reach new customers and drive traffic to your website with seamless ad experiences, from discovery to conversion. Automatically sync your eligible products to your Meta catalog, so you can easily create ads right where your customers are.
- Help drive better ad performance by setting up a conversion pixel
- Easily set up your ads with a one-time account connection
- Sell from one inventory that automatically syncs to your catalog used for ads
Please first take a look at the Meta helpcenter docs, by searching for keywords like 'WooCommerce' here. If you didn't find what you were looking for, you can go to Meta direct support and ask your question.
If you have a WooCommerce.com account, you can search for help or submit a help request on WooCommerce.com.
The plugin offers logging that can help debug various problems. You can enable debug mode in the main plugin settings
panel under the Enable debug mode section.
By default plugin omits headers in the requests to make the logs more readable. If debugging with headers is necessary
you can enable the headers in the logs by setting wc_facebook_request_headers_in_debug_log option to true.
A shutdown handler watches for fatal errors and uncaught exceptions raised in plugin files (including vendor/).
Each one increments a consecutive-crash streak for its request class. Requests are classed by who could have shaped
their input: trusted (WP-CLI, cron requests that carry no client input, and logged-in users who can manage
WooCommerce or the site) or untrusted (everyone else, logged-in customers included). A cron request is trusted only
when it looks like the one WordPress spawns itself: no cookies, no body, no referrer and no query argument other than
doing_wp_cron. Anyone can request wp-cron.php, and that request keeps the client's cookies and query string, so a
cron request that carries them is an outsider's request like any other. Crashes within 30 seconds of each other
count once, and any request that runs the plugin and finishes cleanly resets the streak of its class.
Three counted crashes in a row would pause the plugin. WP-CLI and bare cron crashes do so on the streak alone. For every other crash, a manager's browser included, the guard first runs a self-check: a plain loopback request that carries nothing the client sent (no cookies, query string or body), marked with a one-time token so the events tracker sends nothing to Meta for it. It targets the crashing page for a storefront GET, percent-encoding kept as sent, and the home page otherwise, admin-ajax, REST and cron included. If that request runs the plugin cleanly, the crash depends on client input, the streak resets and the plugin stays on. If it crashes too, the plugin pauses for 10 minutes, unless the crashing path was one WordPress did not resolve to a page: such a path is the requester's own input, so the home page is probed as well and decides. If no verdict can be obtained (loopback blocked, a cached page, an auth wall, a request that never bootstrapped the plugin), the crash is counted as unverified and the plugin stays on rather than let outside requests switch it off; the plugins screen shows a notice until the record decays after a day. A manager's request is the one exception: with no verdict at all it pauses on its streak, so a plugin broken everywhere is still caught through wp-admin where the loopback cannot run.
A full streak again within a day grows the pause to 1 hour, 6 hours and then 24 hours; it never becomes permanent,
a single crash after a pause never escalates on its own, and the level decays after a day without crashes. The
state lives in wp-content/uploads/facebook-for-woocommerce/.disabled; the plugins screen shows a notice with a
"Resume now" button while paused, and every crash writes one Meta for WooCommerce crash guard: line to the PHP
error log with the self-check result and the decision taken. See includes/Framework/CrashGuardState.php and
PluginCrashHandler::run_self_check().
Crash recovery uses a shutdown handler to write a disable flag and queue a sanitized crash report. In rare PHP memory-exhaustion fatals, the process may not have enough memory left to run the shutdown handler. When that happens, the site still recovers on the next request, but the disable flag and crash report may be skipped for that request.
- Offline (physical store) events — how in-store orders are detected, what is sent to Meta, and how to add a point-of-sale integration.
- Clone this repository into the
wp-content/plugins/folder your WooCommerce development environment. - Install dependencies:
npm installcomposer install
- Build assets:
npm startto build a development version
- Linting:
npm run lint:phpto run PHPCS linter on all PHP files
- Testing:
./bin/install-wp-tests.sh <test-db-name> <db-user> <db-password> [db-host]to set up testing environmentnpm run test:phpto run PHP unit tests on all PHP files./vendor/bin/phpunit --coverage-html=reports/coverageto run PHP unit tests with coverage
Use the helper script at tests/e2e/scripts/run-local-events.sh.
Before running it, export all required environment variables (the script reads values directly from your process environment):
export WORDPRESS_PATH="/absolute/path/to/wordpress"
export WORDPRESS_URL="http://your-local-site.test"
export WP_USERNAME="admin"
export WP_PASSWORD="admin"
export WP_CUSTOMER_USERNAME="customer"
export WP_CUSTOMER_PASSWORD="customer"
export TEST_PRODUCT_URL="${WORDPRESS_URL%/}/product/beanie/"
export TEST_CATEGORY_URL="${WORDPRESS_URL%/}/product-category/clothing/accessories/"
export TEST_FBCLID="IwAR123TestClickId456"
export FB_E2E_TEST_COOKIE_NAME="facebook_test_id"
export FB_E2E_LOGGER_PATH="/tests/e2e/helpers/php/event-logger.php"
export WP_DEBUG_LOG="${WORDPRESS_PATH}/wp-content/debug.log"
export WC_LOG_PATH="${WORDPRESS_PATH}/wp-content/uploads/wc-logs"Then run:
./tests/e2e/scripts/run-local-events.shOptional flags:
./tests/e2e/scripts/run-local-events.sh --project chromium-wp-customer --workers 1
./tests/e2e/scripts/run-local-events.sh --spec tests/e2e/theme-compatibility.spec.js
# Run with real browser binaries
./tests/e2e/scripts/run-local-events.sh --project edge-wp-customer --real-edge
./tests/e2e/scripts/run-local-events.sh --project firefox-wp-customer --real-firefox
./tests/e2e/scripts/run-local-events.sh --project brave-wp-customer --real-brave
./tests/e2e/scripts/run-local-events.sh --project opera-wp-customer --real-opera
# Allow script-driven install when browser is missing
./tests/e2e/scripts/run-local-events.sh --project edge-wp-customer --real-edge --auto-install
./tests/e2e/scripts/run-local-events.sh --project firefox-wp-customer --real-firefox --auto-install
./tests/e2e/scripts/run-local-events.sh --project brave-wp-customer --real-brave --auto-install
./tests/e2e/scripts/run-local-events.sh --project opera-wp-customer --real-opera --auto-install
⚠️ --auto-installmay runsudo, install system packages, and add apt repositories/keyrings on Linux. It is opt-in and should only be used in trusted local dev environments.
npm run build: Builds a production version.
Refer to the wiki for details of how to build and release the plugin.
We currently do not support PHPCS on PHP 8.1+ versions. Please run PHPCS checks on PHP 8.0 or lower versions. Refer #2624 PR for additional context.
Meta for WooCommerce is licensed under the GNU General Public License v2.0 (or later).
See the LICENSE file for the full license text.