✨ Wix UCP Implementation Guide

Why Add UCP to Wix?

Wix powers millions of online stores worldwide. Adding UCP (Universal Commerce Protocol) support makes your Wix store discoverable by AI shopping assistants, enabling automatic product discovery and purchases.

• Visual Editor: Wix makes building beautiful stores easy
• Velo by Wix: Use Wix's development platform for custom implementations
• Built-in Hosting: No server configuration needed
• Wix Stores Integration: Works seamlessly with Wix eCommerce

Implementation Methods

Method 1: UCP Proxy by Shopify (Recommended)

UCP Proxy is an open-source proxy by Shopify that enables UCP checkout capabilities for Wix stores. It handles cart building via API and redirects to Wix's hosted checkout for payment.

1. Go to Wix Developer Tools → OAuth Apps
2. Create new app with permissions:
   • wix.ecom.cart.read
   • wix.ecom.cart.update
   • wix.ecom.checkout.read
   • wix.ecom.checkout.update
3. Copy the Client ID

# Clone the repository
git clone https://github.com/Shopify/ucp-proxy
cd ucp-proxy

# Create config file
cp config.example.json config.wix.json

Edit config.wix.json:

{
  "port": "8080",
  "adapter_type": "wix",
  "merchant_id": "my-wix-store",
  "merchant": {
    "store_url": "https://your-site.wixsite.com/store",
    "store_domain": "your-site.wixsite.com",
    "wix_client_id": "your-oauth-client-id",
    "merchant_name": "My Store",
    "policy_links": {
      "privacy_policy": "https://your-site.wixsite.com/store/privacy"
    }
  }
}

# Start the proxy
CONFIG_FILE=config.wix.json go run ./cmd/proxy

# Test discovery endpoint
curl http://localhost:8080/.well-known/ucp

Method 2: Velo Backend (Discovery Only)

Use Wix Velo to create a backend HTTP function that serves your UCP profile.

1. Open your Wix site in the Editor
2. Click Dev Mode in the top menu
3. Click Turn on Dev Mode

1. In the Site Structure panel, expand Backend
2. Create a new file: http-functions.js
3. Add the following code:

// Backend/http-functions.js
import { ok, serverError } from 'wix-http-functions';

// This creates the endpoint: /_functions/ucp
export function get_ucp(request) {
    const profile = {
        profile_version: "1.0",
        merchant: {
            name: "Your Store Name",
            url: "https://www.yoursite.com",
            description: "Your store description",
            contact: {
                email: "support@yourstore.com"
            }
        },
        capabilities: ["browse", "search"],
        policies: {
            returns_url: "https://www.yoursite.com/returns-policy",
            shipping_url: "https://www.yoursite.com/shipping-policy",
            privacy_url: "https://www.yoursite.com/privacy-policy"
        }
    };

    const options = {
        headers: {
            "Content-Type": "application/json",
            "Access-Control-Allow-Origin": "*"
        },
        body: JSON.stringify(profile, null, 2)
    };

    return ok(options);
}

Create a new file routers.js in the Backend folder:

// Backend/routers.js
import { ok, WixRouterSitemapEntry } from 'wix-router';

export function wellknown_Router(request) {
    if (request.path[0] === 'ucp') {
        // Redirect to HTTP function
        return ok('ucp-page', {});
    }
}

1. In the Wix Editor, go to Site Menu → Add Page
2. Choose Router Page
3. Set prefix to .well-known
4. Connect it to your router

Click Publish to make your changes live. Your UCP profile will be available at:

• https://yoursite.com/_functions/ucp (HTTP function)
• https://yoursite.com/.well-known/ucp (if router works)

Method 3: External Hosting with Redirect (Discovery Only)

If Velo isn't available or the router doesn't work, host your UCP profile externally and redirect.

Upload your UCP JSON file to a service like:

• GitHub Gist (get the raw URL)
• JSONBin.io
• Your own server or CDN

If you're using a custom domain with Wix, you can set up a redirect at the DNS level or use Cloudflare Workers:

// Cloudflare Worker example
addEventListener('fetch', event => {
    event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
    const url = new URL(request.url)
    
    if (url.pathname === '/.well-known/ucp') {
        const ucpUrl = 'https://your-hosted-ucp-url.com/ucp.json'
        const response = await fetch(ucpUrl)
        return new Response(response.body, {
            headers: {
                'Content-Type': 'application/json',
                'Access-Control-Allow-Origin': '*'
            }
        })
    }
    
    return fetch(request)
}

Schema.org Markup

Wix Stores automatically adds basic Schema.org markup to product pages. For enhanced AI compatibility:

1. Go to your site's SEO Settings
2. Navigate to SEO Tools → Structured Data
3. Ensure Product schema is enabled

Validate Your Implementation

Common Issues & Solutions

🤖 Test with AI Agents

Resources

• UCP Proxy by Shopify (GitHub)
• Official UCP Specification
• Velo API Reference
• Wix HTTP Functions Guide
• What is UCP? Complete Guide
• UCP vs Schema.org Comparison
• Compare UCP Validation Tools
• All Platform Guides
• Browse UCP-Enabled Stores