A shopper asks an AI assistant for “lightweight carry-on luggage under $200.” That sounds simple. Behind the scenes, though, a useful answer depends on a catalog search that can interpret a product request, apply the right constraints, return current items, and point the shopper toward the merchant’s existing purchase flow.
SuggestAPI now supports UCP Catalog Search. The update exposes each merchant catalog through the Catalog Search contract defined by the Universal Commerce Protocol, or UCP. For commerce teams building toward UCP-compatible experiences, it is a straightforward way to put product discovery on a standard interface without replatforming the storefront or checkout.
The UCP Catalog Search capability covers free-text queries, category and price filters, and pagination across a business’s product catalog. [1]
This gateway implements that capability over REST, scoped to one merchant at a time. Cart, checkout, and payment stay out of scope: SuggestAPI returns discovery results and commerce handoff metadata, not in-protocol checkout.
Discovery needs a shared contract
UCP is an open standard aimed at making AI-driven commerce interactions more actionable. Google describes it as a way to support agentic commerce across AI surfaces such as AI Mode in Google Search and Gemini, beginning with direct buying. [2] That “direct buying” path is part of the broader protocol. SuggestAPI’s first UCP surface is catalog search.
For discovery, the important bit is the contract. An agent or platform needs a predictable way to ask a merchant’s catalog a question. The merchant, in turn, needs room to keep inventory, merchandising, and policy logic in their own stack. UCP Catalog Search gives both sides a common shape for that exchange.
That is where this SuggestAPI support comes in. Rather than bolting a separate search endpoint onto each new surface, a registered tenant can advertise a UCP profile and serve catalog search through the same gateway that already fronts plugin search. Results come from the merchant’s published catalog, and from backend search when that transport is configured. SuggestAPI then applies its own query ranking and category or price filters before returning UCP-shaped products. See how it works for the broader discovery architecture.
Search when there is a query. Browse when there is not.
The UCP contract allows a request to include a free-text query, one or more filters, or an extension-defined input. A filter-only request is treated as a browse operation. In other words, the business returns products that match the criteria without text-relevance ranking. [1] SuggestAPI follows that split: ranking runs only when query is present.
That is not a minor distinction. “Show me lightweight carry-on luggage” is a search. “Show me carry-on luggage under $200” may be a browse request, a search request, or a mixture of both. The contract can express each of those cases without forcing a merchant into a single retrieval model.
| SuggestAPI UCP Catalog Search | What it gives an integration |
|---|---|
| Free-text query | A place to send the shopper’s natural-language product request. SuggestAPI token-ranks matching catalog records. |
| Filter-only browse | A way to return items by category or price when there is no search phrase. |
| Category and price filters | Standard ways to narrow a result set. Combined filters use AND; a list of categories uses OR. [1] |
| Context currency | context.currency scopes the price filter to products already denominated in that currency. SuggestAPI does not convert prices. Other context fields, plus spec-defined signals and attribution, are not used yet. |
| Cursor pagination | A stable way to retrieve additional result pages without leaning on offset-based pagination. [1] |
Tenant-scoped discovery, then search
SuggestAPI hosts many merchant catalogs on one hostname, so catalog search is never global. The preferred flow is:
- Fetch
GET https://agent.suggestapi.com/oks/demo.suggestapi.com/.well-known/ucp - Call
POST https://agent.suggestapi.com/oks/demo.suggestapi.com/catalog/search
{tenant} is the merchant domain, for example demo.suggestapi.com. The tenant-scoped profile already binds the REST endpoint to that catalog, so the search body does not need an extra tenant field.
Gateway POST /catalog/search is also available. It requires tenant in the JSON body, in filters.tenant, or as ?tenant=. A request without a merchant domain returns 400 with tenant_required.
Registered tenants get UCP search by default. A merchant that already hosts UCP can turn the gateway copy off by publishing ucp_supported: false and, optionally, ucp_profile_url so clients can continue at the merchant’s own /.well-known/ucp. The same global switch is DEFAULT_UCP_SUPPORTED=false.
Here is an illustrative tenant-scoped request that combines a shopper query, a category filter, a price range, and a requested page size:
POST /oks/demo.suggestapi.com/catalog/search
Content-Type: application/json
{
"query": "lightweight carry-on luggage",
"filters": {
"categories": ["luggage"],
"price": {
"min": 10000,
"max": 20000
}
},
"context": {
"currency": "USD"
},
"pagination": {
"limit": 12
}
}A few details are easy to miss. Filters that are specified together use AND logic. A list of categories uses OR logic, so a product in any listed category can match. Price values are expressed in ISO 4217 minor units: 20000 with currency: "USD" is $200.00. And limit is a request, not a guarantee: an implementation can return fewer products than the number asked for. [1]
When context.currency is set, SuggestAPI applies the price filter only to products already priced in that currency. It does not convert between currencies. If some catalog items use another presentment currency, the response may include a price_filter_currency_mismatch message.
A response returns the matching products together with UCP metadata. It may also contain pagination information and messages. When there is another page, the response includes an opaque cursor that the client can use to continue. The specification requires that cursor when has_next_page is true. [1]
UCP Catalog Search over REST
SuggestAPI implements UCP Catalog Search over REST. It advertises dev.ucp.shopping.catalog.search from the tenant UCP profile and serves POST /oks/{tenant}/catalog/search. [1]
The UCP Catalog Search specification is currently a draft, so teams should work from the versioned documentation as they plan an implementation. That matters for details that are not just technical housekeeping, including price-currency handling, validation of empty requests, context handling, and checkout-time policy enforcement. [1] Checkout-time policy remains the merchant’s job: SuggestAPI does not execute UCP checkout.
What to review before you expose catalog search
UCP Search support does not mean rebuilding your catalog from scratch. It does make a good audit prompt. Can your search return relevant products for a natural-language request? Are categories and prices consistently structured? Is pagination dependable? Do product records contain the information an agent needs to hand the shopper to the merchant’s existing purchase flow?
Those questions were always worth asking. Agent-driven discovery just gives them a wider audience.
If you are preparing a UCP-compatible commerce experience, SuggestAPI can now serve as the discovery layer for a registered tenant. Read the UCP Catalog Search specification, fetch GET /oks/{tenant}/.well-known/ucp, and call POST /oks/{tenant}/catalog/search. If the merchant already hosts UCP, leave gateway search off and point clients at their existing profile instead.
Frequently asked questions about UCP Catalog Search
What is UCP Catalog Search?
UCP Catalog Search is the Universal Commerce Protocol capability for querying a merchant catalog with free-text search, category and price filters, and pagination. SuggestAPI implements that contract over REST, scoped to one tenant at a time.
How do I call SuggestAPI’s UCP Catalog Search?
Fetch the tenant profile at GET https://agent.suggestapi.com/oks/demo.suggestapi.com/.well-known/ucp, then POST https://agent.suggestapi.com/oks/demo.suggestapi.com/catalog/search. The tenant is the merchant domain, for example demo.suggestapi.com.
Does UCP Catalog Search include checkout or payments?
No. SuggestAPI returns discovery results and commerce handoff metadata. Cart, checkout, and payment stay on the merchant’s existing purchase flow.
When is a UCP request a search versus a browse?
Ranking runs only when a free-text query is present. A filter-only request is a browse: products match category or price criteria without text-relevance ranking.
What if a merchant already hosts Universal Commerce Protocol?
Publish ucp_supported: false and, optionally, ucp_profile_url so clients continue at the merchant’s own /.well-known/ucp instead of the gateway copy.