How to Test Your UCP Implementation: A Checklist

Why Testing Matters

Shipping a UCP endpoint that returns invalid data is worse than not having one at all. Agents that encounter malformed responses will flag your endpoint as unreliable. Some agent platforms maintain quality scores. A bad first impression can follow you.

The good news: testing a UCP implementation is straightforward. The spec is well-defined, the required fields are documented, and there are tools that automate most of the validation. This checklist covers everything you need to verify before going live.

The Checklist

1. Endpoint Exists and Returns Valid JSON

The most basic check. Send a GET request to your /.well-known/ucp endpoint. You should get back:

• HTTP 200 status code
• Content-Type header of application/json
• A valid JSON response body that parses without errors

If you get a 404, your endpoint is not configured. If you get HTML back, your server is probably returning your website's homepage instead of the UCP data. If the JSON is malformed (missing quotes, trailing commas, unescaped characters), fix your serialization.

Test this with a simple curl command:

curl -s -o /dev/null -w "%{http_code}" https://yourstore.com/.well-known/ucp

You want to see 200. Anything else needs investigation.

2. Required Fields Are Present

Every product object in your UCP response must include these fields:

• productId - A unique identifier for the product
• title - The product name
• description - A text description of the product
• price - The numeric price value
• currency - ISO 4217 currency code (USD, EUR, GBP, etc.)
• availability - Whether the item is in stock
• checkoutUrl - A valid URL where the purchase can be completed

Missing any of these means agents cannot process that product. They will skip it. Partial data is treated as no data by most agent implementations.

Check each product object in your response. A common mistake is including the fields but leaving some empty or null. An empty checkoutUrl is the same as a missing one from the agent's perspective.

3. Data Types Are Correct

This catches more issues than you would expect.

• price should be a number, not a string. 29.99 not "29.99"
• currency should be a 3-letter string. "USD" not "us dollars"
• availability should be a boolean. true not "in stock"
• productId should be a string. Numeric IDs should be stringified
• checkoutUrl should be a fully qualified URL with protocol. https://yourstore.com/checkout/123 not /checkout/123

Type mismatches cause silent failures. The endpoint looks like it works, but agents cannot parse the values correctly. These are the hardest bugs to catch without a validator tool.

4. Spec Conformance

Beyond required fields and data types, the UCP spec defines structure and behavior requirements.

• The response should include a top-level merchant object with your store's name and URL
• Products should be in a products array
• If you support pagination, the pagination object should include totalItems, currentPage, and totalPages
• Checkout URLs should be stable. Do not use session-dependent URLs that expire
• If you support capabilities beyond basic checkout (identity linking, order management, payment token exchange), declare them in the capabilities array

The full spec is at ucp.dev. Read the "Merchant Implementation" section. It is not long.

5. Run the Validator

Manual checking catches obvious issues. Automated validation catches the rest.

The UCPList validator runs a comprehensive suite of checks against your endpoint:

• Endpoint availability and response time
• JSON structure validation
• Required field presence and type checking
• Spec conformance verification
• Checkout URL reachability
• Capability declaration validation

Enter your store URL and it will return a pass/fail report with specific issues listed. Fix everything flagged as an error. Warnings are worth addressing but will not block agent compatibility.

6. Test with a Real Agent

Validation tools check that your data is correct. Testing with a real agent checks that the end-to-end flow works.

If you have access to an AI shopping agent (through a developer program or your own agent implementation), run a test purchase flow:

1. Have the agent discover your products through your UCP endpoint
2. Verify the agent can read your product catalog correctly
3. Initiate a checkout session through the agent
4. Confirm the checkout URL loads correctly and the cart is pre-populated
5. Complete a test purchase if your payment processor supports test mode

This end-to-end test catches integration issues that no static validator can find: CORS problems, authentication requirements, redirect chains that break agent flows, checkout pages that require JavaScript execution an agent cannot provide.

7. Monitor After Launch

Testing is not a one-time event. Set up monitoring for:

• Uptime. Your UCP endpoint should have the same availability target as your storefront. If your website is up but your UCP endpoint is down, agents cannot reach you.
• Response time. Track p50 and p95 response times. Alert if p95 exceeds 1 second.
• Data freshness. If a product goes out of stock, your UCP endpoint should reflect that within minutes, not hours. Stale inventory data leads to failed checkouts and poor agent quality scores.
• Error rates. Monitor for 4xx and 5xx responses. A spike in errors might indicate a deployment broke your UCP endpoint.

How UCPList Verifies Listings

When a tool or merchant is submitted to UCPList, we run our own verification process. For merchants with UCP endpoints, we check endpoint availability, required field presence, spec conformance, and response time. Listings that pass get a "Verified" badge. Listings that fail stay in "Unverified" status until the issues are fixed.

We re-verify listings periodically. If a previously verified endpoint goes down or starts returning invalid data, the listing status updates to reflect that.

The directory shows verification status for every listing. Use it to gauge which implementations are production-ready and which are still in progress.