Mistake #1: Returning a partial catalog
The problem: The GET /ucp/v1/catalog endpoint paginates correctly but omits products without images, out-of-stock items, or products in certain categories. AI agents receive an incomplete view of your inventory.
The fix: Include all active products, including temporarily out-of-stock ones (with availability: "OutOfStock"). Agents use availability status to plan purchases, knowing a product exists but is currently unavailable is useful information. Never filter by stock status at the catalog level.
Mistake #2: Stale inventory data
The problem: The catalog endpoint returns stock levels updated every 24 hours, but your actual inventory changes in real time. An AI agent confirms stock for a customer, the customer approves the purchase, and the checkout fails because the item sold out 6 hours earlier.
The fix: Implement a dedicated GET /ucp/v1/products/{id}/availability endpoint that queries live inventory. The checkout flow must re-check availability at the moment of order creation, not rely on catalog cache. Webhook support for stock-level changes is strongly recommended.
Mistake #3: Missing required fields in product objects
The problem: UCP defines required fields for product objects: id, name, description, price, currency, availability, category. Many implementations omit category (using a proprietary taxonomy) or gtin / mpn (useful but treated as optional). Agents that filter by category or cross-reference GTINs across merchants will miss your products.
The fix: Map your internal categories to the UCP standard taxonomy. Include GTINs and MPNs for all products where these exist, they enable agents to compare identical products across multiple merchants.
Mistake #4: Authentication token expiry not handled
The problem: AP2 authentication tokens have a validity window. If your implementation doesn't handle token refresh, agentic checkout sessions that last longer than the token validity window fail mid-transaction.
The fix: Implement token refresh logic in your checkout handler. When an AP2 token is close to expiry during a transaction, request a refresh before proceeding. Log token expiry events to identify if this is causing abandonment.
Mistake #5: Non-descriptive product names
The problem: Product names like "Model XR-2200B" or "SKU-48291" are meaningful in your internal system but incomprehensible to an AI agent trying to match a user's natural-language request ("a stainless steel French press for 4 cups").
The fix: Product names in UCP catalog responses should be human-readable and descriptive. "Stainless Steel French Press, 4-Cup / 600ml" is far more useful to an agent than a model code. Consider having a separate agent_name field that is optimized for natural language matching.
Mistake #6: Return policy not machine-readable
The problem: The UCP spec includes a returnPolicy object in checkout responses. Many implementations return a URL linking to the return policy page rather than structured data. AI agents cannot parse HTML to extract policy terms.
The fix: Return a structured returnPolicy object with fields: returnWindowDays (integer), returnType ("free" / "paid" / "exchange-only"), conditions (array of plain-language strings). This allows agents to accurately inform users about return terms before purchase confirmation.
Mistake #7: Rate limiting set too aggressively
The problem: Merchants set rate limits on UCP endpoints to protect their infrastructure. Limits of 10 requests/minute might seem reasonable for human browsers but are inadequate for AI agents, which may make rapid sequential requests to compare products or check inventory across multiple categories.
The fix: Differentiate rate limits by endpoint type. Catalog reads can be served from cache with generous limits (100+ requests/minute). Checkout endpoints should have tighter limits (10–30/minute) since they involve inventory reservation. Implement proper HTTP 429 responses with Retry-After headers so agents can backoff gracefully rather than failing.
Mistake #8: HTTPS certificate issues on the UCP subdomain
The problem: Many merchants host UCP endpoints on a subdomain (e.g., api.yourstore.com) with a separately managed SSL certificate. Expired certificates, misconfigured SANs, or missing intermediate certificates cause agents to reject your endpoints as untrusted.
The fix: Use automated certificate renewal (Let's Encrypt with certbot, or your CDN provider's managed certificates). Set up monitoring alerts for certificates expiring within 30 days. Test your UCP subdomain with SSL Labs regularly.
Mistake #9: Checkout confirmation not returned in real time
The problem: Your POST /ucp/v1/checkout endpoint queues the order for processing and returns a 202 Accepted response, expecting the agent to poll for confirmation. Many agents interpret anything other than a synchronous 200 OK with an order ID as a failure.
The fix: Process checkout synchronously and return a 200 response with a complete order object (order ID, estimated delivery, confirmation number) within 3 seconds. If your backend requires async processing, implement a fast synchronous pre-validation step that returns an optimistic order ID, then update via webhook.
Mistake #10: Not testing with the official UCP test suite
The problem: Developers test UCP endpoints with manual curl commands or Postman, not with the official UCP certification test suite. These manual tests miss edge cases the spec defines: malformed requests, partial payloads, timeout handling, concurrent checkout attempts.
The fix: Run the official UCP test suite (available at ucp.dev/testing) against your staging environment before and after each release. Add the test suite to your CI/CD pipeline. UCP certification is increasingly referenced by major AI agent providers as a trust signal, maintaining certification status matters.