Connect WooCommerce¶
Connect WooCommerce to read your store's recent order count and a geography breakdown from order billing addresses. The connector is in beta.
Orders only
Squoosh reads your order count. It does not yet change how your AI shoppers behave. WooCommerce supplies no session denominator, and Squoosh does not currently combine its orders with another source's sessions to calculate a conversion rate.
What the connection does¶
Squoosh reads completed and processing orders through the WooCommerce REST v3 Orders API. The snapshot contains the number of orders fetched and a breakdown of their billing countries. Geography is weighted by orders, not visits. Orders without a billing country count toward the order total but contribute no geography sample.
The connector has a conversion-only role. Its order geography is not a traffic calibration source. Device and traffic-source mix must come from a supported traffic connector such as Google Analytics or Plausible. Connecting WooCommerce is optional when running a test.
Connect WooCommerce¶
Your store needs HTTPS, an active WooCommerce installation, and pretty permalinks enabled under Settings > Permalinks. The vendor documents REST v3 support from WooCommerce 3.5 and WordPress 4.4. See WooCommerce REST API requirements.
- In WordPress admin, open WooCommerce > Settings > Advanced > REST API > Add key.
- Select a WordPress user who can read orders and choose Read permission. Generate the key pair.
- In Squoosh, open Integrations, find WooCommerce, and click Connect.
- Enter the Store URL, Consumer key, and Consumer secret. Use the HTTPS WordPress installation URL. If WordPress is installed at
https://example.com/shop, include/shop. - Click Connect.
Both key fields are private. Squoosh sends them in the HTTPS Authorization header. Before saving, it checks access to the Orders API with a one-order request that returns only the order ID. A store with no orders can still connect. The key needs order-read access; Squoosh does not use the System Status endpoint for verification.
The vendor's authentication guide describes key creation and permissions.
What Squoosh reads¶
| Data | Source | Limit |
|---|---|---|
| Order count | Completed and processing orders fetched in the requested rolling window | At most 500 orders per read, including a real zero when none are returned |
| Geography | Billing country on each fetched order | Weighted by order count; missing countries are skipped |
| Device and traffic source | Unavailable from this connector | No distribution is inferred |
| Conversion rate | Unavailable from this connector | No session denominator or cross-source pairing |
Snapshot requests currently receive full order objects. Squoosh derives only order counts and billing-country aggregates from them; it does not put customer names, emails, line items, or payment details into this calibration snapshot. The connector issues read-only GET requests and does not modify orders.
Limits and caveats¶
- Five pages of up to 100 orders. If the fifth page is full, the read is flagged partial with
order_cap_reached. Both geography and the order count are marked truncated. This means the local fetch cap was reached; it does not prove another page exists. - Fetched count, not the store's full total. Stores with more than 500 matching orders will have a lower count in this snapshot than in WooCommerce. The connector does not currently use the API's total-count header.
- Rolling window. Requests use the current time and the requested number of days before it, including the current partial day. Timezone interpretation on HPOS stores outside UTC remains under review, so window totals can differ from store reports.
- Orders represent buyers. Visitors who did not order are absent from the geography breakdown.
- Hosting affects availability. Each request has a 10-second timeout. Full order payloads and hosting performance can affect whether a read finishes.
Troubleshooting¶
| Problem | What to do |
|---|---|
| REST API route not found, HTTP 404 | Confirm WooCommerce is active, enable pretty permalinks, and include any WordPress installation subdirectory in the Store URL. |
| Authentication failed, HTTP 401 | Check the key pair. An unknown key, a host stripping the Authorization header, or a proxy that prevents WordPress from recognizing HTTPS can produce the same error. Ask your host to check header forwarding and HTTPS detection. |
| Key lacks Read permission | Generate a Read key for a WordPress user allowed to view orders. Write-only keys cannot read order data. |
| HTTP 403 | Check both the API key's Read permission and the associated WordPress user's access to orders. |
| HTTP 429 or a timeout | Try again later. Ask your host about request limits or slow REST API responses if the issue persists. |
| No geography sample | Check that your orders have billing countries. Small samples may also be omitted by Squoosh's shared calibration checks. |
WooCommerce documents query-string key authentication as a workaround for HTTPS hosts that do not parse the Authorization header. Squoosh uses header authentication and does not automatically retry with credentials in the URL. Ask your host to repair header forwarding; do not paste credentials into the Store URL field.