HubACP Documentation

Welcome to the complete guide for HubACP - ChatGPT Commerce for WooCommerce. Transform your WooCommerce store into an AI-ready commerce platform that enables ChatGPT to browse products and complete purchases through conversational commerce.

Getting Started

HubACP enables ChatGPT to interact with your WooCommerce store through a secure REST API. This guide will help you get up and running in 5 minutes.

Quick Start (5 Minutes)

1. Install HubACP - Download and activate the plugin
2. Run Setup Wizard - Beautiful animated wizard guides you through setup
3. Register with OpenAI - Get approved as a merchant (free)
4. Generate API Credentials - Create your signing secret
5. Test Integration - Use built-in diagnostic tools to verify everything works

Installation

Option 1: Install from WordPress.org (Free Version)

1. Log in to your WordPress admin panel
2. Navigate to Plugins → Add New
3. Search for "HubACP"
4. Click Install Now and then Activate

Option 2: Manual Installation

1. Download the plugin ZIP file from WordPress.org
2. Navigate to Plugins → Add New → Upload Plugin
3. Choose the downloaded ZIP file and click Install Now
4. Click Activate Plugin

Option 3: Pro Version ($99/year)

The Pro version unlocks unlimited products in the feed and priority support. All checkout, payment, and webhook features are available in the Free version too!

1. Purchase Pro license via Freemius secure checkout
2. Download the Pro version ZIP file
3. Navigate to Plugins → Add New → Upload Plugin
4. Upload and activate (Pro overrides Free version)
5. License activates automatically - no manual key entry needed

First-Time Setup Wizard

On first activation, HubACP launches a beautiful setup wizard that guides you through:

• Step 1: Welcome - Introduction to HubACP capabilities
• Step 2: OpenAI Registration - Link to merchant approval form
• Step 3: API Configuration - Generate and copy your signing secret
• Step 4: Next Steps - Quick links to test and configure

The wizard features smooth animations, real-time validation, and AJAX-powered setup (8-10 seconds).

Configuration

Admin Pages

HubACP adds a top-level menu with modern navigation:

• Dashboard - Overview, onboarding checklist, quick start guide, stats (Pro)
• Settings - Technical configuration with 8 tabs (submenu)

Settings Tabs

Access via HubACP → Settings:

1. Webhooks - Configure OpenAI webhook URL (Free & Pro)
2. Shipping - Set delivery time estimates (Free & Pro)
3. Feed - Product feed settings (Free & Pro)
4. Diagnostics - 9 built-in testing tools (Free & Pro)
5. Payments - Choose payment mode (Pro only)
6. 👤 Account - Manage license and billing via Freemius (Free & Pro)
7. 🚀 Upgrade to Pro - Modal checkout experience (Free only)
8. 💬 Support - Priority email support (Pro only)

Onboarding Checklist (Dashboard)

Interactive checklist tracks your setup progress:

• ✅ Step 1: Plugin Activated (auto-complete)
• ✅ Step 2: OpenAI Merchant Approval (manual checkbox)
• ✅ Step 3: Webhook Secret Configured (validated)
• ✅ Step 4: OpenAI Webhook URL Set (optional)
• ✅ Step 5: Integration Tested (diagnostics required)

Progress shows "X of 5 complete" with visual bar. Celebration animation when 100% complete!

Generate Signing Secret

In HubACP → Settings → API Configuration, generate your webhook signing secret.

whsec_abc123def456ghi789jkl012mno345pqr678

Configure OpenAI Webhook URL

Provide your store's webhook endpoint to OpenAI:

https://yourstore.com/wp-json/acp/v1/webhooks

Diagnostic Tools

Test your integration without writing code (Settings → Diagnostics):

1. Test REST API - Verify API connectivity
2. Test Signature Verification - Verify HMAC algorithm
3. Test Create Checkout - Create test session
4. Test Update Checkout - Update with address
5. Test Complete Checkout - Complete and create order
6. Test Webhook - Send test webhook
7. Clear Caches - Clear shipping/product caches
8. View API Logs - Debug API requests
9. System Info - PHP version, extensions, permissions

API Overview

HubACP provides 8 REST API endpoints compatible with OpenAI's Agentic Commerce Protocol. The API follows REST principles with predictable URLs, standard HTTP methods, and JSON responses.

Base URL

https://yourstore.com/wp-json/acp/v1/

All Endpoints

Free vs Pro Features

Authentication

HubACP uses HMAC-SHA256 signature authentication - the same enterprise-grade security standard used by Stripe, GitHub, and other payment platforms.

Required Headers

X-ACP-Signature: 
X-ACP-Timestamp: 
Content-Type: application/json

Security Features

• HMAC-SHA256 Signatures - Cryptographically verify every request
• Timestamp Validation - 5-minute tolerance window prevents replay attacks
• Rate Limiting - Protection against abuse
• Idempotency Keys - Prevent duplicate orders from retries
• Signature Verification - All webhooks signed with HMAC

Generating Request Signature

All API requests must include a signature of: timestamp.request_body

#!/bin/bash

SECRET="your_webhook_signing_secret"
TIMESTAMP=$(date +%s)
BODY='{"items":[{"id":"123","quantity":1}]}'

# Generate signature
SIGNATURE=$(echo -n "${TIMESTAMP}.${BODY}" | \
  openssl dgst -sha256 -hmac "$SECRET" | \
  cut -d' ' -f2)

# Make request
curl -X POST "https://yourstore.com/wp-json/acp/v1/checkout-sessions" \
  -H "X-ACP-Signature: $SIGNATURE" \
  -H "X-ACP-Timestamp: $TIMESTAMP" \
  -H "Content-Type: application/json" \
  -d "$BODY"

const crypto = require('crypto');

const SECRET = process.env.HUBACP_SECRET;
const timestamp = Math.floor(Date.now() / 1000);
const body = JSON.stringify({ items: [{ id: "123", quantity: 1 }] });

// Generate HMAC signature
const payload = `${timestamp}.${body}`;
const signature = crypto
  .createHmac('sha256', SECRET)
  .update(payload)
  .digest('hex');

// Make API request
const response = await fetch('https://yourstore.com/wp-json/acp/v1/checkout-sessions', {
  method: 'POST',
  headers: {
    'X-ACP-Signature': signature,
    'X-ACP-Timestamp': timestamp.toString(),
    'Content-Type': 'application/json'
  },
  body: body
});

import hmac
import hashlib
import json
import time
import os

SECRET = os.getenv('HUBACP_SECRET')
timestamp = str(int(time.time()))
body = json.dumps({"items": [{"id": "123", "quantity": 1}]})

# Generate HMAC signature
payload = f"{timestamp}.{body}"
signature = hmac.new(
    SECRET.encode(),
    payload.encode(),
    hashlib.sha256
).hexdigest()

# Make API request
headers = {
    'X-ACP-Signature': signature,
    'X-ACP-Timestamp': timestamp,
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://yourstore.com/wp-json/acp/v1/checkout-sessions',
    headers=headers,
    data=body
)

API Endpoints

Products API

GET /wp-json/acp/v1/products?search=shirt&per_page=10
X-WCP-API-Key: wcp_abc123def456ghi789

{
  "products": [
    {
      "id": 123,
      "name": "Classic Cotton T-Shirt",
      "slug": "classic-cotton-tshirt",
      "price": "29.99",
      "regular_price": "39.99",
      "sale_price": "29.99",
      "on_sale": true,
      "stock_status": "instock",
      "stock_quantity": 50,
      "description": "Comfortable 100% cotton t-shirt",
      "short_description": "Classic everyday tee",
      "images": [
        {
          "src": "https://your-store.com/wp-content/uploads/tshirt.jpg",
          "alt": "Classic T-Shirt"
        }
      ],
      "categories": ["Clothing", "T-Shirts"],
      "variations": []
    }
  ],
  "pagination": {
    "total": 150,
    "pages": 15,
    "current_page": 1,
    "per_page": 10
  }
}

Checkout Sessions API

{
  "items": [
    {
      "product_id": 123,
      "quantity": 2,
      "variation_id": null
    }
  ],
  "customer": {
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "idempotency_key": "unique-request-id-123"
}

{
  "session_id": "cs_abc123",
  "status": "pending",
  "items": [...],
  "subtotal": "59.98",
  "tax": "5.40",
  "shipping": "0.00",
  "total": "65.38",
  "expires_at": "2025-01-15T18:30:00Z"
}

{
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postcode": "10001",
    "country": "US"
  }
}

{
  "shipping_methods": [
    {
      "id": "flat_rate",
      "label": "Flat Rate",
      "cost": "10.00",
      "delivery_time": "3-5 business days"
    },
    {
      "id": "express",
      "label": "Express Shipping",
      "cost": "25.00",
      "delivery_time": "1-2 business days"
    }
  ]
}

{
  "payment_method": "stripe",
  "payment_intent_id": "pi_xyz123",
  "billing_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postcode": "10001",
    "country": "US",
    "email": "customer@example.com",
    "phone": "+1234567890"
  },
  "shipping_method_id": "flat_rate"
}

{
  "order_id": 456,
  "order_number": "456",
  "status": "processing",
  "total": "75.38",
  "customer": {...},
  "items": [...],
  "created_at": "2025-01-15T15:30:00Z"
}

Webhooks

Webhooks provide real-time notifications when events occur in your WooCommerce store. Perfect for keeping ChatGPT synchronized with order status changes. Available in both Free and Pro versions.

Supported Events (6 Types)

Webhook Features

• Automatic Retry - Exponential backoff with 5 retry attempts
• Signed Payloads - HMAC-SHA256 signature on every webhook
• Event Logging - Complete delivery history in WP admin
• OpenAI ACP Compliant - Follows official specification
• Background Processing - Uses WC Action Scheduler (non-blocking)

Webhook Payload

{
  "event": "order.created",
  "timestamp": "2025-01-15T15:30:00Z",
  "data": {
    "order_id": 456,
    "order_number": "456",
    "status": "processing",
    "total": "75.38",
    "customer": {
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "items": [...]
  }
}

Verifying Webhook Signatures

All webhooks include both X-Signature and X-ACP-Signature headers. Always verify to ensure authenticity.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return signature === expectedSignature;
}

// Express.js webhook endpoint
app.post('/webhooks/hubacp', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-acp-signature'] || req.headers['x-signature'];
  const payload = req.body.toString('utf8');

  if (!verifyWebhook(payload, signature, process.env.HUBACP_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(payload);
  console.log('Received event:', event.type, 'for order', event.data.order_id);

  // Process webhook asynchronously
  processWebhookAsync(event);

  // Respond immediately
  res.status(200).json({ received: true });
});

Automatic Retry Policy

If your endpoint returns non-2xx status, HubACP retries with exponential backoff:

Security Best Practices

Idempotency Keys

To prevent duplicate orders from network retries, include an idempotency key with checkout requests:

{
  "items": [...],
  "customer": {...},
  "idempotency_key": "unique-request-id-" + Date.now()
}

If the same idempotency key is used within 24 hours, HubACP will return the original response instead of creating a duplicate.

Code Examples

Complete Purchase Flow

const HubACPClient = require('hubacp-client');

const client = new HubACPClient({
  baseUrl: 'https://your-store.com',
  apiKey: process.env.HUBACP_API_KEY,
  signingSecret: process.env.HUBACP_SIGNING_SECRET
});

async function completePurchase() {
  // 1. Search for products
  const products = await client.products.list({
    search: 'laptop',
    per_page: 5
  });

  console.log(`Found ${products.pagination.total} laptops`);

  // 2. Create checkout session
  const session = await client.checkout.createSession({
    items: [
      { product_id: products.products[0].id, quantity: 1 }
    ],
    customer: {
      email: 'customer@example.com',
      first_name: 'John',
      last_name: 'Doe'
    },
    idempotency_key: `order-${Date.now()}`
  });

  console.log(`Session created: ${session.session_id}`);

  // 3. Calculate shipping
  const shipping = await client.checkout.calculateShipping(session.session_id, {
    shipping_address: {
      first_name: 'John',
      last_name: 'Doe',
      address_1: '123 Main St',
      city: 'New York',
      state: 'NY',
      postcode: '10001',
      country: 'US'
    }
  });

  console.log('Shipping options:', shipping.shipping_methods);

  // 4. Complete the order
  const order = await client.checkout.complete(session.session_id, {
    payment_method: 'stripe',
    payment_intent_id: 'pi_123abc',
    billing_address: { /* ... */ },
    shipping_method_id: shipping.shipping_methods[0].id
  });

  console.log(`Order created: #${order.order_number}`);
  return order;
}

Python Example

from hubacp import HubACPClient
import os

client = HubACPClient(
    base_url='https://your-store.com',
    api_key=os.getenv('HUBACP_API_KEY'),
    signing_secret=os.getenv('HUBACP_SIGNING_SECRET')
)

# Search products
products = client.products.list(search='laptop', per_page=5)
print(f"Found {products['pagination']['total']} laptops")

# Create checkout session
session = client.checkout.create_session(
    items=[
        {'product_id': products['products'][0]['id'], 'quantity': 1}
    ],
    customer={
        'email': 'customer@example.com',
        'first_name': 'John',
        'last_name': 'Doe'
    },
    idempotency_key=f"order-{int(time.time())}"
)

# Complete order
order = client.checkout.complete(
    session['session_id'],
    payment_method='stripe',
    payment_intent_id='pi_123abc',
    billing_address={...},
    shipping_method_id='flat_rate'
)

print(f"Order created: #{order['order_number']}")

Troubleshooting

Common Issues

Debug Mode

Enable debug mode in the HubACP settings to log all API requests and responses:

1. Go to WooCommerce → Settings → HubACP
2. Enable Debug Mode
3. Check logs at WooCommerce → Status → Logs

Frequently Asked Questions

Need Help?