---
title: "WooCommerce plugin"
description: "The Sarvex UCP WooCommerce plugin integrates your WooCommerce store with Sarvex's Google UCP checkout platform. It handles:"
---

*Generated from `plugin/woocommerce/README.md` in the [Sarvex repository](https://github.com/sarvexlab/sarvex) — edit the source there, not this page.*

The Sarvex UCP WooCommerce plugin integrates your WooCommerce store with Sarvex's Google UCP checkout platform. It handles:

1. **Signal Sending** — Notifies Sarvex when products, prices, or inventory change
2. **Profile Proxy** — Serves the UCP profile and proxies checkout requests
3. **Pairing** — Securely pairs your store with Sarvex

## Installation

### Step 1: Download and Upload

1. Download the plugin directory from the Sarvex repository
2. Extract it to your WordPress `wp-content/plugins/` directory
3. The plugin should appear in your WordPress Admin dashboard under **Plugins**

### Step 2: Activate the Plugin

1. Go to **Plugins** in the WordPress Admin
2. Find **Sarvex UCP Gateway**
3. Click **Activate**

Upon activation, the plugin will create the required configuration entries in your WordPress database.

## Configuration

After activation, navigate to **Sarvex UCP** in the WordPress Admin menu to configure your store.

### Required Settings

#### Sarvex Endpoint URL
- **What it is:** The URL of your Sarvex backend server
- **Format:** `https://sarvex.example.com` (no trailing slash)
- **Example:** `https://api.sarvex.example.com`
- **Required:** Yes

#### Pairing Code
- **What it is:** A unique code generated by the plugin for pairing with Sarvex
- **How to use:** Provide this code to Sarvex during the pairing process
- **Status:** Read-only (displayed automatically)
- **Expires:** This code is valid until you pair with Sarvex

### How to Pair Your Store

1. **Get your Pairing Code**
   - Navigate to **Sarvex UCP** settings in WordPress Admin
   - Copy the **Pairing Code** displayed

2. **Complete Pairing with Sarvex**
   - Provide the pairing code to your Sarvex account manager or use the Sarvex console
   - Submit your store URL: `https://yourstore.example.com`

3. **Verify Configuration**
   - After pairing, the **Merchant ID** and **HMAC Secret** fields will populate automatically
   - Both fields will display as read-only (hidden for security)

4. **Start Sending Signals**
   - Once paired, any product, price, or inventory changes will automatically signal to Sarvex
   - Check the plugin logs to verify signals are being sent

## How It Works

### Product and Inventory Signals

Whenever you:
- **Add or update a product** — A product signal is sent
- **Update stock quantity** — An inventory signal is sent
- **Change stock status** (In Stock → Out of Stock) — An inventory signal is sent

The plugin automatically sends a lean signal to Sarvex (`{"sku": "...", "entity_kind": "product"}`). Sarvex pulls the full product details from your store, so the signal contains only the SKU and entity type.

### Profile Serving and Proxying

#### `/.well-known/ucp` (Profile Endpoint)
- Returns your store's UCP profile configuration
- Cached for 1 hour for resilience
- If Sarvex is unreachable, serves the last-known-good profile
- Never requires authentication

#### `/ucp/v1/*` (Checkout Requests)
- Proxies checkout operations live to Sarvex
- Not cached (always fresh)
- Returns Sarvex's response as-is to the agent

## Troubleshooting

### Signals Not Being Sent

**Check pairing status:**
- Verify **Sarvex Endpoint URL** is set
- Verify **Merchant ID** and **HMAC Secret** are populated (they appear after successful pairing)

**Check network connectivity:**
- Verify your server can reach the Sarvex endpoint URL
- Check firewall and proxy settings

**Review logs:**
- Log location: `/wp-content/uploads/sarvex-ucp.log`
- Check for errors like "Failed to send signal" or network timeouts

### Pairing Code Not Accepted

- **Verify the code is correct** — Copy it exactly from the WordPress Admin
- **Ensure it hasn't expired** — If pairing takes a long time, generate a new code by deactivating and reactivating the plugin
- **Check Sarvex backend** — Confirm the pairing request reached your Sarvex server

### Profile Not Loading

**If profile is unavailable:**
- Check network connectivity to Sarvex endpoint
- Verify `X-Sarvex-*` headers are being sent correctly
- Review logs for `Failed to fetch profile from Sarvex`

**If profile is cached:**
- The plugin will serve the last-known-good profile if Sarvex is temporarily unreachable
- This is intentional (graceful degradation)
- Check logs for `Serving cached profile due to Sarvex unreachable`

### Checkout Requests Failing

**Check request proxying:**
- Verify `/ucp/v1/*` requests are reaching Sarvex
- Check response status codes in logs
- Confirm HMAC headers are valid

**Check Sarvex endpoint:**
- Verify the endpoint URL is correct
- Confirm Sarvex is running and reachable

## Security Considerations

### HMAC Signing
- All requests to Sarvex are signed with HMAC-SHA256
- The **HMAC Secret** is stored securely in the WordPress database
- Never share or expose your HMAC Secret

### Credential Storage
- Merchant ID and HMAC Secret are stored in WordPress `wp_options`
- Ensure your WordPress database is backed up and access is restricted
- Regularly rotate your HMAC Secret through Sarvex

### Data in Signals
- Product signals contain only the SKU and entity type
- No payment credentials, PII, or sensitive data is sent in signals
- All data is encrypted in transit (HTTPS)

## Logging

The plugin logs all signals, profile fetches, and errors to:

```
/wp-content/uploads/sarvex-ucp.log
```

Log format:
```
[2026-06-15 14:30:45] [INFO] Signal sent {"signal":{"sku":"ABC123","entity_kind":"product"},"sequence":5}
[2026-06-15 14:31:00] [WARN] Failed to fetch profile from Sarvex {"error":"Connection timeout"}
```

## Development

### Running Tests

```bash
cd plugin/woocommerce
phpunit tests/
```

### Plugin Structure

```
plugin/woocommerce/
├── sarvex-ucp-gateway.php      # Main plugin file
├── src/
│   ├── Autoloader.php          # PSR-4 autoloader
│   ├── Plugin.php              # Main orchestrator
│   ├── Logger.php              # Logging utility
│   ├── HMAC.php                # HMAC signing
│   ├── SignalSender.php        # Product/inventory signals
│   ├── PairingManager.php      # Pairing handshake
│   └── ProfileProxy.php        # Profile serving and request proxying
├── tests/
│   ├── HMACTest.php
│   ├── PairingManagerTest.php
│   └── ProfileProxyTest.php
└── README.md                    # This file
```

## Support

For issues or questions:

1. **Check the logs** — `/wp-content/uploads/sarvex-ucp.log`
2. **Verify configuration** — Ensure all required fields are populated
3. **Contact Sarvex support** — Provide logs and configuration details (sanitize HMAC secret)

## License

This plugin is part of Sarvex and is licensed under the Apache License 2.0.

Note: the WordPress.org plugin directory requires GPL-compatible licensing, so this plugin is distributed from this repository rather than that directory.