SaaS Pro Max
Sign inStart free
Menu
Documentation menu

WordPress + WooCommerce

Install the SaaS Pro plugin from Settings → Data → WordPress. The download bundles the browser SDK built with this deployment; no CDN dependency or editing theme files is required. WordPress 6.5+ and PHP 8.1+ are required. WooCommerce is optional.

Website setup

  1. Download the ZIP and upload it through WordPress → Plugins → Add New → Upload Plugin. Activate SaaS Pro.
  2. Open WordPress → Settings → SaaS Pro. Enter the SaaS Pro HTTPS origin and the full public ingest key for your environment.
  3. Add your WordPress origin to SaaS Pro → Settings → Data → Allowed origins. Remove previous SaaS Pro tracking tags.
  4. Keep Wait for consent selected. Connect a WP Consent API-compatible consent manager using the statistics category. Without a consent manager, your consent controls must call window.saasproConsent(true) to allow or window.saasproConsent(false) to revoke.
  5. Enable tracking. Visit your public site in a private window and allow analytics. Administrators, previews, login and administration pages are excluded.
  6. Copy the installation ID into SaaS Pro → Settings → Data → WordPress → Check receipt. A received spm_installation_ready event confirms delivery to that environment.

Use persistent identity for returning visitors and checkout linking. Short-lived mode keeps identity in memory and ignores identify calls. Do Not Track is honored. Query strings, fragments and page titles are omitted; order confirmation and payment paths use :order. Error capture and ad click IDs are disabled. Custom event names, paths and campaign parameters can still contain personal data.

The plugin supplies a consent integration, not a consent banner. Granting consent globally is an explicit operator setting; it does not determine your legal obligations. If you use a content security policy, permit the bundled scripts and connections to your SaaS Pro origin. Page caching must exclude checkout confirmation and customer account pages, as required by WooCommerce.

WooCommerce setup

  1. Use the Production environment. In Revenue → Connectors → Use another billing system, create a dedicated source for this store.
  2. In WordPress, enter the application UUID, source UUID and a dedicated Management API token. An ingest key cannot authorize payment reports. The token needs write scope and revenue.write in this organization; keep its role as limited as your integration allows.
  3. Enable payment reporting. Action Scheduler, bundled with WooCommerce, delivers newly paid orders and cumulative refunds in the background. Run WordPress cron reliably so scheduled actions execute.
  4. If your disclosure and consent setup allow it, enable checkout identity linking. A consenting visitor on a paid order confirmation page is identified with a pseudonymous customer ID and billing email. The order key and same-origin request protect the identity lookup. No email is embedded in the public HTML.
  5. Verify using an existing test order. The plugin’s Queue order report control retries one order; it never charges or refunds a customer. Check the payment and checkout identity cards in SaaS Pro. The linking worker runs every minute and needs both Analytics and Revenue enabled.

The plugin uses WooCommerce order APIs for HPOS and classic/block checkout. Unpaid orders are ignored. Payment reports contain order identifiers, amounts, currency, settlement time and cumulative refunds. Billing email is sent only when checkout linking is enabled. Card details, addresses, line items and customer names are never sent.

Amounts are integer hundredths of the named currency, including currencies commonly displayed with another exponent. Refunds cannot decrease. Original amount, currency, customer identity and settlement date cannot change after reporting; correct the source data instead of overwriting a settled report. Subscription MRR and bulk historical import are not inferred.

Delivery and credentials

Management tokens and pending snapshots are authenticated-encrypted using WordPress authentication salts. Tokens are replacement-only in the settings form and never appear in browser configuration or REST settings. Rotating salts requires replacing the token. Changing the destination or copied-site URL clears the old credential and creates a new installation identity.

A request is saved before delivery and reused exactly after an ambiguous timeout. Completed snapshots keep a digest and delivery metadata with the order. Temporary network, rate-limit and server failures retry up to ten attempts with backoff; other errors wait for operator correction. Only order and installation IDs enter Action Scheduler; jobs for an older installation cannot deliver to a replacement destination. A later refund may supersede an undelivered earlier state; the report represents cumulative current payment state.

Failed snapshots remain encrypted with their orders for explicit retry and disappear when the order is deleted. Deactivation cancels pending actions; reactivation does not bulk-import old orders. Uninstall removes settings and the saved token while retaining order receipts. Never enable this plugin against the same source after cloning a store without reviewing its application, keys and source.

Receipt checks

The console and GET /api/v1/apps/{app}/installations/wordpress?installation={uuid}&source={uuid}&env=production inspect up to seven retained days. Analytics and Revenue counts require their respective modules and read permissions. Results contain counts and timestamps, not identities or amounts.

  • Browser event: the installation marker reached ingest and remains retained.
  • Payment report: that source holds a WooCommerce payment with this installation prefix.
  • Checkout identity: a payment customer links to a person with an actual checkout event and the same customer ID.

A payment receipt alone does not imply a visitor link. WooCommerce reports are labeled server-reported and excluded from verified acquisition attribution. Neither a checkout page nor this plugin independently verifies a payment provider.

If a card stays waiting, check consent, origin allowlisting, module switches, environment, sampling/budgets and Action Scheduler’s queue. A disabled source or expired token produces an explicit delivery failure in WordPress settings. After fixing it, retry the affected paid order. A missing checkout link can be expected when the visitor declined consent or did not return to the confirmation page.

Development and protocol references

The source lives in integrations/wordpress/saaspro. Web builds package it with the current @saaspro/browser bundle into /downloads/saaspro-wordpress.zip. Local HTTP is permitted only with both WP_ENVIRONMENT_TYPE=local and SAASPRO_LOCAL_DEVELOPMENT=true; deployments use public HTTPS origins and WordPress safe HTTP requests with redirects disabled.

Primary references: WordPress Settings API, WP Consent API, WooCommerce HPOS integration, WooCommerce order hooks, Action Scheduler API.