Shipping a Product Feed for AI Marketplaces: A Step‑by‑Step Packaging Template

AI agents and agent-driven marketplaces don’t browse HTML— they parse canonical machine-readable artifacts. Three artifacts matter in practice: (1) JSON‑LD product records (Schema.org Product + Offer) embedded or served from product pages, (2) an OpenAPI-backed Product Catalog API for search, pricing and availability checks, and (3) a manifest that declares capabilities, endpoints and commerce flows (UCP/ACP style) so agents know how to discover and transact with your store.

Failing to publish any one of these makes your catalog invisible or unsafe for agents. The UCP/manifest concept has already been adopted across several agent marketplace projects; it’s the discovery surface agents hit to verify you sell an item, what you support (search, cart, checkout), and which checkout protocol to call (ACP or platform-specific checkout).

Design one canonical product record per SKU that maps directly to Schema.org Product and Offer properties. Minimum fields: id (canonical URL), name, description, images, brand, category tags, price (currency + amount), availability, sku/gtin when available, and canonical product URL. Embed this as <script type="application/ld+json"> on the product page or expose it via your product API.

Expose an OpenAPI path /products and /products/{id} that returns the same canonical record as JSON‑LD (or JSON) and supports query parameters for price range, capabilities (e.g., 'agent-friendly': true), and real-time availability. Include a /pricing or /offers endpoint that lists Offer objects for variants and a /webhook/subscribe endpoint to register webhook URLs for inventory or price updates.

Below is the practical mapping engineers need: a JSON‑LD snippet that lives on your product page and an OpenAPI response schema for the same record. Use JSON‑LD for search/discovery and OpenAPI for agent-driven queries that require authentication or realtime checks.

Ship both artifacts. Agents will typically read the manifest first, then call your catalog API to filter and validate items (price, stock), and finally follow ACP checkout endpoints defined in the manifest.

Publish a UCP-style manifest at /.well-known/ucp (or platform-required path) that declares services (shopping/search/cart/checkout), the transport (e.g., mcp or a2a), and the endpoints agents should call. The manifest must include capability identifiers and the pointer to the checkout handler (ACP endpoint). This is the single discovery file agent ecosystems use to decide whether to include you in results.

For commerce execution, implement an ACP-compatible checkout endpoint (e.g., POST /acp/checkout) that accepts a machine-readable order envelope, validates the agent’s authorization/delegation, returns a payment link or a status object, and triggers webhook events (order.created, order.fulfilled, inventory.updated). Provide a simple webhook subscription API so marketplaces can subscribe to inventory and price updates.

Implementation checklist you can hand to a contractor: (1) produce canonical product JSON‑LD for all live SKUs and deploy to product pages, (2) build a small OpenAPI Product Catalog with /products and /offers endpoints, (3) publish a UCP manifest at /.well-known/ucp pointing to your catalog and checkout, (4) implement an ACP-compatible checkout endpoint and webhook subscription flow, (5) test with a sandbox agent or marketplace.

Rollout tips: start with a subset of best-selling SKUs, keep offers normalized (one canonical record per variant), and instrument webhooks and request logs so you can respond quickly to agent preflight checks. Monitor agent requests to tune capability declarations — overstating capabilities (e.g., claiming checkout support when your endpoint rejects orders) will get you de-indexed by marketplaces.