🛒 Shopping Agent with UCP

🌟Features

---

📋Requirements

• WordPress 5.8 or higher
• WooCommerce 5.0 or higher
• PHP 7.4 or higher

🚀Installation

1. Download the plugin zip file
2. Go to WordPress Admin → Plugins → Add New → Upload Plugin
3. Upload the zip file and click Install Now
4. Click Activate Plugin
5. Go to WooCommerce → UCP to configure

---

⚙️Configuration

Navigate to WooCommerce → UCP in WordPress admin.

General Settings

Setting	Description	Default
Enable UCP	Enable/disable UCP API endpoints	Yes
Rate Limit	Max requests per minute per API key	100
Cart Expiry	Hours until inactive cart expires	24
Checkout Expiry	Minutes until checkout session expires	30
Enable Logging	Log API requests for debugging	No

---

🔑Authentication

API Key Format

key_id:secret

Example: ucp_abc123:ucp_secret_xyz789

Header Authentication (Recommended)

curl -H "X-UCP-API-Key: ucp_abc123:ucp_secret_xyz789" \
  https://your-store.com/wp-json/ucp/v1/products

Query Parameter Authentication

curl "https://your-store.com/wp-json/ucp/v1/products?ucp_api_key=ucp_abc123:ucp_secret_xyz789"

Permission Levels

Level	Access
read	Browse products, categories, reviews
write	Create carts, checkout, orders, customers
admin	Full access including API key management

---

📡API Endpoints

Discovery

Method	Endpoint	Auth	Description
GET	/.well-known/ucp	No	Store discovery manifest
GET	/wp-json/ucp/v1/discovery	No	Same as above

Products

Method	Endpoint	Auth	Description
GET	/wp-json/ucp/v1/products	No	List products
GET	/wp-json/ucp/v1/products/{id}	No	Get product by ID
GET	/wp-json/ucp/v1/products/search	No	Search products
GET	/wp-json/ucp/v1/products/sku/{sku}	No	Get product by SKU

Categories

Method	Endpoint	Auth	Description
GET	/wp-json/ucp/v1/categories	No	List categories
GET	/wp-json/ucp/v1/categories/{id}	No	Get category
GET	/wp-json/ucp/v1/categories/{id}/products	No	Category products

Cart

Method	Endpoint	Auth	Description
POST	/wp-json/ucp/v1/carts	Write	Create cart
GET	/wp-json/ucp/v1/carts/{id}	Write	Get cart
DELETE	/wp-json/ucp/v1/carts/{id}	Write	Delete cart
POST	/wp-json/ucp/v1/carts/{id}/items	Write	Add item
PATCH	/wp-json/ucp/v1/carts/{id}/items/{key}	Write	Update item
DELETE	/wp-json/ucp/v1/carts/{id}/items/{key}	Write	Remove item
POST	/wp-json/ucp/v1/carts/{id}/checkout	Write	Convert to checkout

Checkout

Method	Endpoint	Auth	Description
POST	/wp-json/ucp/v1/checkout/sessions	Write	Create session
GET	/wp-json/ucp/v1/checkout/sessions/{id}	Write	Get session
PATCH	/wp-json/ucp/v1/checkout/sessions/{id}	Write	Update session
POST	/wp-json/ucp/v1/checkout/sessions/{id}/confirm	Write	Confirm checkout

Orders

Method	Endpoint	Auth	Description
GET	/wp-json/ucp/v1/orders	Write	List orders
GET	/wp-json/ucp/v1/orders/{id}	Write	Get order
GET	/wp-json/ucp/v1/orders/{id}/events	Write	Order timeline

Customers

Method	Endpoint	Auth	Description
POST	/wp-json/ucp/v1/customers	Write	Create customer
GET	/wp-json/ucp/v1/customers/{id}	Write	Get customer
PATCH	/wp-json/ucp/v1/customers/{id}	Write	Update customer
GET	/wp-json/ucp/v1/customers/email/{email}	Write	Find by email

Shipping

Method	Endpoint	Auth	Description
POST	/wp-json/ucp/v1/shipping/rates	No	Calculate rates
GET	/wp-json/ucp/v1/shipping/methods	No	List methods
GET	/wp-json/ucp/v1/shipping/zones	No	List zones

Reviews

Method	Endpoint	Auth	Description
GET	/wp-json/ucp/v1/reviews	No	List reviews
GET	/wp-json/ucp/v1/reviews/{id}	No	Get review
POST	/wp-json/ucp/v1/reviews	Write	Create review
GET	/wp-json/ucp/v1/reviews/product/{id}/summary	No	Rating summary

Coupons

Method	Endpoint	Auth	Description
GET	/wp-json/ucp/v1/coupons	No	List coupons
POST	/wp-json/ucp/v1/coupons/validate	No	Validate coupon
GET	/wp-json/ucp/v1/coupons/code/{code}	No	Get by code

---

📝Usage Examples

1. Discover Store

curl https://your-store.com/.well-known/ucp

2. Browse Products

curl "https://your-store.com/wp-json/ucp/v1/products?per_page=10&category=15"

3. Search Products

curl "https://your-store.com/wp-json/ucp/v1/products/search?q=shirt&min_price=20&max_price=100"

4. Create Cart & Add Items

# Create cart
curl -X POST \
  -H "X-UCP-API-Key: YOUR_API_KEY" \
  https://your-store.com/wp-json/ucp/v1/carts

# Add item to cart
curl -X POST \
  -H "X-UCP-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": 123, "quantity": 2}' \
  https://your-store.com/wp-json/ucp/v1/carts/{cart_id}/items

5. Checkout Flow

# Convert cart to checkout
curl -X POST \
  -H "X-UCP-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "123 Main St",
      "city": "Taipei",
      "country": "TW"
    }
  }' \
  https://your-store.com/wp-json/ucp/v1/carts/{cart_id}/checkout

# Confirm checkout
curl -X POST \
  -H "X-UCP-API-Key: YOUR_API_KEY" \
  https://your-store.com/wp-json/ucp/v1/checkout/sessions/{session_id}/confirm

---

🔔Webhooks

All webhook requests include signature headers:

X-UCP-Signature: sha256=<hmac_signature>
X-UCP-Event: order.created
X-UCP-Timestamp: 1705234567

Verify Signature (PHP)

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_UCP_SIGNATURE'];
$secret = 'your_webhook_secret';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    // Valid webhook
    $data = json_decode($payload, true);
}

---

🗄️Database Tables

Table	Purpose
wp_shopping_agent_ucp_api_keys	API key storage
wp_shopping_agent_ucp_cart_sessions	Persistent cart data
wp_shopping_agent_ucp_checkout_sessions	Checkout session data
wp_shopping_agent_ucp_webhooks	Webhook configurations

---

📁File Structure

shopping-agent-with-ucp/
├── shopping-agent-with-ucp.php       # Main plugin file
├── admin/
│   ├── class-shopping-agent-ucp-admin.php      # Admin functionality
│   ├── class-shopping-agent-ucp-settings.php   # Settings management
│   └── views/
│       └── settings-page.php    # Admin UI template
├── includes/
│   ├── api/                     # REST API controllers
│   │   ├── class-shopping-agent-ucp-rest-controller.php
│   │   ├── class-shopping-agent-ucp-auth.php
│   │   ├── class-shopping-agent-ucp-discovery.php
│   │   ├── class-shopping-agent-ucp-products.php
│   │   ├── class-shopping-agent-ucp-categories.php
│   │   ├── class-shopping-agent-ucp-cart.php
│   │   ├── class-shopping-agent-ucp-checkout.php
│   │   ├── class-shopping-agent-ucp-orders.php
│   │   ├── class-shopping-agent-ucp-customers.php
│   │   ├── class-shopping-agent-ucp-shipping.php
│   │   ├── class-shopping-agent-ucp-reviews.php
│   │   └── class-shopping-agent-ucp-coupons.php
│   ├── models/
│   │   ├── class-shopping-agent-ucp-api-key.php
│   │   └── class-shopping-agent-ucp-cart-session.php
│   ├── webhooks/
│   │   ├── class-shopping-agent-ucp-webhook-manager.php
│   │   └── class-shopping-agent-ucp-webhook-sender.php
│   ├── class-shopping-agent-ucp-activator.php
│   ├── class-shopping-agent-ucp-deactivator.php
│   ├── class-shopping-agent-ucp-loader.php
│   └── class-shopping-agent-ucp-i18n.php
├── assets/
│   ├── css/admin.css
│   └── js/admin.js
└── languages/
    └── shopping-agent-with-ucp.pot

---

🛠️Troubleshooting

---

📄License

This plugin is licensed under the GPL2 license.