OutloopAI Headless Checkout self-updates

Connect your WooCommerce catalog seamlessly with the standalone OutloopAI Headless Checkout application (checkout.outloopai.com) and central backend (circle-api).

---

Overview

The OutloopAI Headless Checkout plugin transforms your WooCommerce store into an authoritative catalog provider while offloading conversion-critical checkout flows to OutloopAI's ultra-fast Next.js checkout infrastructure.

Customers browsing products on your store can click Buy Now to instantly launch the optimized headless checkout experience, complete with multi-gateway payments, dynamic coupons, and automated student onboarding, while WooCommerce remains your central system of record for inventory and orders.

---

Features

• Authoritative Catalog Architecture: WooCommerce retains all products, variations, inventory, and order history.
• Dynamic Headless URLs: Generates clean, secure URLs (https://checkout.outloopai.com/billing/{slug}) for simple and variable products.
• Product-Level Overrides: Set custom checkout slugs or disable headless checkout per product with a live URL preview and one-click copy.
• Variable Product & Dynamic Quantity Tracking: Client-side listeners automatically capture variation selections and cart quantities.
• Flexible Button Placement: Choose whether to display Buy Now alongside Add to Cart or replace it completely.
• Idempotent Order & Payment Synchronization: Sends signed HMAC-SHA256 order events (order.created, order.paid, order.completed) to circle-api.
• Integrated Diagnostics: Built-in AJAX connection tester checks network health with circle-api directly from the admin panel.
• Native GitHub Releases Auto-Updates: Seamless WordPress update notifications and one-click updates directly from GitHub Releases without requiring the WordPress.org Plugin Directory.
• High-Performance Order Storage (HPOS): Fully compatible with WooCommerce HPOS (custom_order_tables).
• Zero Theme Alteration: Compatible with Astra, Astra Child, and all standard WooCommerce themes without template modifications.

---

Requirements

Component	Minimum Version	Recommended Version
WordPress	6.0	6.4+
WooCommerce	8.0	8.5+
PHP	7.4	8.1+
cURL & OpenSSL	Enabled	Enabled (TLS 1.2+)

---

Installation

Method 1: WordPress Admin Upload (Recommended)

1. Download outloopai-headless-checkout-plugin.zip from the Latest GitHub Release.
2. Go to WordPress Admin → Plugins → Add New → Upload Plugin.
3. Choose the downloaded ZIP file and click Install Now.
4. Click Activate Plugin.

Method 2: Manual (FTP / Server)

1. Download and extract outloopai-headless-checkout-plugin.zip.
2. Upload the outloopai-headless-checkout-plugin folder to your WordPress installation's wp-content/plugins/ directory.
3. Activate the plugin via WordPress Admin → Plugins.

---

Configuration

Navigate to WooCommerce → Settings → OutloopAI Headless to configure the plugin:

1. General & Headless Checkout

• Enable Integration: Check to enable headless checkout routing across your store.
• Headless Checkout URL: Base URL of your checkout application (default: https://checkout.outloopai.com).
• Checkout Path: Checkout path prefix (default: billing).
• Button Placement: Choose between Show beside Add to Cart or Replace Add to Cart button.
• Buy Now Button Text: Label for the checkout button (default: Buy Now).

2. Circle API Backend

• Circle API Base URL: Endpoint of your central API backend (e.g., https://api.outloopai.com or local dev http://localhost:3002).
• Circle API Authentication Key: Server-to-server authorization key. Stored securely and never exposed to frontend JavaScript.

3. Webhooks & Event Synchronization

• Circle API Webhook URL: Endpoint for order lifecycle events (e.g., https://api.outloopai.com/api/v1/webhooks/woocommerce).
• Webhook Secret: Shared secret for HMAC-SHA256 signature verification matching WOOCOMMERCE_WEBHOOK_SECRET in circle-api.
• Synchronize Order Events: Check to dispatch real-time creation and payment webhooks.
• Enable WooCommerce Logging: Logs diagnostic events to WooCommerce system logs (WooCommerce → Status → Logs).

---

WooCommerce Integration

Product-Level Settings

When editing any WooCommerce product, navigate to the Headless Checkout tab in the Product Data panel:

• Enable Headless Checkout: Enable or disable headless routing for this specific product.
• Custom Checkout Slug: Override the default product slug (e.g., national-ai-challenge).
• Live Preview: Inspect and copy the exact generated headless checkout URL.

Variable Products

For variable products, the frontend script dynamically observes:

1. User variation dropdown selections (variation_id).
2. Quantity input changes.
3. Appends ?variant={id}&qty={n} to the checkout URL seamlessly.

---

OutloopAI API Integration

Webhook Event Payloads

When orders are created or paid in WooCommerce, the plugin sends signed POST requests to circle-api:

• Header: X-WC-Webhook-Signature containing the base64-encoded HMAC-SHA256 signature of the payload.
• Header: X-WC-Webhook-Topic (order.created, order.updated, order.paid).
• Payload: Standard sanitized WooCommerce order representation including line items, student email, and totals.

Connection Diagnostics

Under WooCommerce → Settings → OutloopAI Headless, use the Test Circle API Connection button to verify server-to-server connectivity without executing test transactions.

---

Security

• Server-Side Secrets: API keys and webhook secrets are stored exclusively in WordPress options and are never rendered in frontend scripts or HTML markup.
• Cryptographic Signature: All webhooks dispatched from WordPress are signed with HMAC-SHA256 using your shared webhook secret.
• Input Sanitization: All product slugs, URLs, and incoming requests are validated using strict WordPress sanitization APIs (esc_url_raw(), sanitize_text_field(), wp_verify_nonce()).
• HTTPS Enforcement: Remote package downloads and API calls strictly enforce valid SSL/TLS connections (sslverify => true).

---

Updates & GitHub Releases

The plugin includes a native, lightweight GitHub Releases updater:

How Updates Work

1. When a new version is released on GitHub (e.g., v1.0.1), the plugin checks https://api.github.com/repos/outloopai/outloopai-headless-checkout-plugin/releases/latest.
2. WordPress Admin displays:

   There is a new version of OutloopAI Headless Checkout available.

3. Clicking View version details displays the GitHub release changelog and upgrade notes.
4. Clicking Update now automatically downloads, verifies, and installs the update.
5. If Enable auto-updates is active in WordPress, updates are applied automatically in the background.

Release Cadence & Safety

• Push vs Release: Normal code pushes to main do NOT trigger WordPress update notices. Only official GitHub Releases / Tags trigger updates.
• Transients & Caching: Update checks are cached for 6 hours using WordPress transients to eliminate unnecessary API requests and respect GitHub rate limits.
• Directory Normalization: The updater guarantees that the extracted plugin directory is always outloopai-headless-checkout-plugin, preventing broken paths.

---

GitHub Actions Release Workflow

The repository includes .github/workflows/release.yml to automate production builds:

1. Triggers whenever a tag is pushed (e.g., git push origin v1.0.1).
2. Validates that the version declared in outloopai-headless-checkout-plugin.php matches the Git tag.
3. Validates that readme.txt stable tag matches the Git tag.
4. Packages clean production files into outloopai-headless-checkout-plugin.zip.
5. Attaches the ZIP asset to the GitHub Release.

---

Release Process

To publish a new version:

1. Update the version in outloopai-headless-checkout-plugin.php:

   define( 'OUTLOOPAI_HEADLESS_CHECKOUT_VERSION', '1.0.2' );

2. Update Stable tag: 1.0.2 in readme.txt.
3. Add release notes to CHANGELOG.md.
4. Commit and push changes:

   git add .
   git commit -m "chore(release): prepare v1.0.2"
   git push origin main

5. Create and push Git tag:

   git tag v1.0.2
   git push origin v1.0.2

6. Create the Release on GitHub (https://github.com/outloopai/outloopai-headless-checkout-plugin/releases/new):
   • Choose tag v1.0.1.
   • Title: OutloopAI Headless Checkout v1.0.1.
   • Paste changelog notes.
   • GitHub Actions will automatically attach outloopai-headless-checkout-plugin.zip.

---

Troubleshooting

Buy Now button is not appearing on product pages

• Ensure Enable Integration is checked in WooCommerce → Settings → OutloopAI Headless.
• Check if the individual product has headless checkout enabled under the Headless Checkout tab.
• Confirm WooCommerce is active and High-Performance Order Storage settings are standard.

Circle API connection test fails

• Verify your server can make outbound HTTPS requests to your API domain.
• Check firewall and Cloudflare security settings if hosting circle-api behind a proxy.
• Inspect logs under WooCommerce → Status → Logs for detailed cURL error codes.

Update notice does not appear immediately

• WordPress caches update checks for 6–12 hours.
• Go to Dashboard → Updates and click Check Again to force a refresh.

---

Support

For technical questions or integration support:

• Website: outloopai.com
• Documentation: docs.outloopai.com
• Issues: GitHub Issues