---
title: "WooCommerce Integration Guide | Tajo"
description: "Connect your WooCommerce store to Tajo with the Tajo for WooCommerce plugin: engagement events, durable delivery, and privacy-minimized customer data. In progress, not yet verified end to end."
url: https://tajo.io/docs/ecommerce-platforms/woocommerce/
markdown: https://tajo.io/docs/ecommerce-platforms/woocommerce.md
lang: en-US
author: "Set Noa"
author_url: https://tajo.io/set-noa/
---

# WooCommerce Integration Guide

[Set Noa](https://tajo.io/set-noa/)

This guide connects a WooCommerce store to Tajo. The integration has two halves that work together:

- **Tajo for WooCommerce plugin** — captures engagement events (orders, carts, refunds, reviews, form submissions) inside WordPress as they happen and delivers them to Tajo through a durable, signed outbox. On 14 October 2026 the plugin was tested on a local site; delivery into Tajo has not been verified yet.
- **WooCommerce REST connection** — Tajo reads your store’s customers, orders, products, coupons, refunds, and reviews for historical import and ongoing sync. See the [WooCommerce connector reference](https://tajo.io/docs/connectors/ecommerce/woocommerce/) for the REST-only setup.

Marketing automation itself (email, SMS, WhatsApp via Brevo and other providers) is configured in Tajo, not in the plugin. The plugin’s job is to get trustworthy events out of WordPress.

## Prerequisites

- **WordPress 6.3+** with admin access
- **PHP 7.4+**
- **WooCommerce 7.0+** (the plugin also works on WordPress sites without WooCommerce — commerce adapters simply stay inactive)
- **Tajo account** with a WordPress connection created
- HTTPS on the Tajo endpoint (always true for hosted Tajo)

## Step 1: Install the Tajo for WooCommerce plugin

### Manual installation

```bash
# Download the plugin
cd wp-content/plugins
wget https://tajo.io/downloads/woocommerce/tajo-woocommerce-latest.zip

# Verify and unzip
unzip tajo-woocommerce-latest.zip
```

Then activate from WordPress admin:

1. Go to **Plugins → Installed Plugins**
2. Find “Tajo for WooCommerce”
3. Click **Activate**

You can also upload the zip directly via **Plugins → Add New → Upload Plugin**. A SHA-256 checksum is published alongside each release at [tajo.io/downloads/woocommerce/](https://tajo.io/downloads/woocommerce/tajo-woocommerce-1.0.0.zip.sha256). The plugin is not yet listed in the WordPress.org directory; manual installation is the supported path today.

## Step 2: Configure the connection

Navigate to **WooCommerce → Tajo** (on sites without WooCommerce: **Settings → Tajo**) and enter the three values from your Tajo WordPress connection:

| Field | Value |
| --- | --- |
| **Tajo endpoint** | The HTTPS webhook URL shown in Tajo, e.g. `https://alto.tajo.io/api/connectors/wordpress/webhooks/engagement` |
| **Binding ID** | The connection’s binding ID from Tajo |
| **Signing secret** | The shared secret (32–256 characters). The plugin generates a strong local secret on activation; paste it into Tajo, or paste Tajo’s secret here |

There are no API-key constants to add to `wp-config.php`. Events remain safely queued in the local outbox until all three values are saved.

Then verify the pipe end to end:

1. Click **Queue test event**, then **Process now**.
2. The delivery outbox table should show the event as delivered.
3. In Tajo, confirm the `connection.test` event arrived on the WordPress connection.

## What the plugin sends

Every event is a compact, privacy-minimized envelope signed with HMAC-SHA256. Only engagement identity fields (email, phone, local IDs) plus bounded event metadata leave WordPress — never names, postal addresses, IP addresses, user agents, comment bodies, arbitrary form fields, order notes, or payment details.

### WooCommerce events

| Hook | Event |
| --- | --- |
| `woocommerce_created_customer` / `woocommerce_update_customer` | `customer.created` / `customer.updated` |
| `woocommerce_new_product` / `woocommerce_update_product` | `product.created` / `product.updated` |
| `woocommerce_add_to_cart`, item removal, coupon apply/remove | `cart.updated` (with cart summary for abandonment flows) |
| `woocommerce_cart_emptied` | `cart.emptied` |
| `woocommerce_new_order` / `woocommerce_update_order` | `order.placed` / `order.updated` |
| `woocommerce_order_status_changed` | `order.status_changed` (+ `order.fulfilled` on completion) |
| `woocommerce_payment_complete` | `order.paid` |
| `woocommerce_order_refunded` | `refund.created` |
| WooCommerce Subscriptions status updates | `subscription.status_changed` |

Order events carry the order number, status, currency, totals, line items, and ready-to-use review/reorder URLs — enough for post-purchase and win-back automations without a follow-up API call.

### WordPress events

- `contact.created` / `contact.updated` / `contact.deleted` for user accounts
- `content.published` / `content.updated` / `content.unpublished` for public content
- `comment.created` / `comment.status_changed` for visitor comments and product reviews (internal WooCommerce order notes, pingbacks, and trackbacks are never emitted)
- `form.submitted` for successful **Contact Form 7**, **WPForms**, **Gravity Forms**, and **Fluent Forms** submissions — only typed email/phone identity fields and form metadata are extracted; arbitrary submitted fields are discarded

## Reliability: the delivery outbox

The plugin never fires events at Tajo directly from a page load. Every event is written to a local outbox table first, then delivered by WP-Cron with:

- Bounded exponential backoff (up to 8 attempts, honoring `Retry-After`)
- Dead letters with one-click **Replay dead letters** in the admin
- Retention limits so an unreachable endpoint can never hoard personal data (delivered: 7 days; queued: 30 days; dead letters: 30 days after last update)
- Idempotent event IDs, so retries and replays never duplicate downstream

If your host disables WP-Cron (`DISABLE_WP_CRON`), invoke `wp-cron.php` from a real scheduler at least once per minute.

## Consent is never inferred

Account creation, checkout, purchase, and generic form submissions are **not** treated as marketing consent. Built-in events carry an empty consent list. To record explicit consent (for example from a checked newsletter box), emit it through the extension hook:

```php
do_action(
    'tajo_engagement_emit',
    'consent.updated',
    array( 'email' => $email ),
    array( 'policyVersion' => '2026-07' ),
    array(
        array(
            'channel'  => 'email',
            'status'   => 'opt_in',        // or 'opt_out'
            'purpose'  => 'marketing',
            'source'   => 'newsletter_checkbox',
            'evidence' => array( 'formId' => 'newsletter-footer', 'field' => 'marketing_email' ),
        ),
    ),
    gmdate( 'c' )
);
```

The same hook lets any plugin or theme emit custom events; everything passes through the same sanitizer, outbox, and signature.

## Step 3: Historical import

Plugin events cover everything from installation onward. For the history that predates the plugin, Tajo’s WooCommerce REST connection imports existing customers, orders, products, coupons, refunds, and reviews — configured entirely on the Tajo side with a WooCommerce REST API key (**WooCommerce → Settings → Advanced → REST API**, read permission). See the [WooCommerce connector reference](https://tajo.io/docs/connectors/ecommerce/woocommerce/) for details.

## Privacy and GDPR

- The plugin registers with WordPress **Tools → Export Personal Data** and **Tools → Erase Personal Data**; retained outbox events for a matching email are exported or erased locally.
- Erasure and delivery share a fail-closed mutex, so an erasure can never report completion while a payload is mid-send.
- Local erasure covers the WordPress outbox only — submit the corresponding request in Tajo for downstream data.
- Deactivation pauses delivery but keeps configuration and queued events; **deleting** the plugin permanently removes the outbox, settings, secret, and schedules.

## Compatibility

- **HPOS**: the plugin declares WooCommerce High-Performance Order Storage compatibility and uses only CRUD objects and public hooks.
- **WooCommerce Subscriptions**: subscription status changes are captured when the extension is active.
- **Multisite**: uninstall cleans up every site in the network.

## Operations reference

Server-to-server discovery and outbox control are available to administrators via Application Password authentication:

| Method | Route | Purpose |
| --- | --- | --- |
| `GET` | `/wp-json/tajo/v1/capabilities` | Plugin version, detected adapters, event inventory, outbox health |
| `GET` | `/wp-json/tajo/v1/outbox` | Outbox counts (payloads are never exposed) |
| `POST` | `/wp-json/tajo/v1/outbox/process` | Process a batch immediately |
| `POST` | `/wp-json/tajo/v1/outbox/replay` | Replay dead letters |

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| Events stay “Queued” | Endpoint, binding ID, or secret not saved yet — delivery is paused until all three are configured |
| Events stay “Retrying” | Tajo endpoint unreachable from your host, or WP-Cron isn’t running — check the outbox table’s error column and your cron setup |
| Dead letters accumulate | A non-retryable error (usually a wrong binding ID or secret) — fix the configuration, then **Replay dead letters** |
| ”Enter a valid HTTPS Tajo webhook endpoint” | The endpoint must be HTTPS without embedded credentials |
| Test event delivered but nothing in Tajo | Check you pasted the binding ID from the same Tajo workspace/connection the endpoint belongs to |

## Next steps

- [WooCommerce connector reference](https://tajo.io/docs/connectors/ecommerce/woocommerce/) — REST sync, webhook signature details, config keys
- [Customer sync](https://tajo.io/docs/skills/data-sync/customer-sync/) — mapping WooCommerce customers into your system of record
- Configure abandoned-cart, post-purchase, and win-back automations in Tajo using `cart.updated`, `order.placed`, and `order.fulfilled` events