WooCommerce UCP integration

Available since FiboSearch 1.35.0, in both Free and Pro. Requires WooCommerce 11.3 or newer. On older versions, FiboSearch leaves UCP search to WooCommerce.

An AI shopping agent looks for products on a customer’s behalf. It doesn’t type into your search bar. It sends a phrase to your store through the Universal Commerce Protocol (UCP), and whatever your store sends back is all it has to work with.

On its own, WooCommerce answers that request by looking for the exact phrase in product titles and SKUs. One typo, or two words in an unexpected order, and a full shelf of wallets turns into an empty result.

FiboSearch takes over that request. The phrase goes through the same search engine your customers use, so the agent gets the same products, in the same order, as your search results page.

This integration doesn’t turn FiboSearch into an AI search engine. The agent is a separate service, and FiboSearch answers its search the way it answers a customer’s.

Here is one test store with 180 products, searched for wallet leather (two words swapped) and lether walet (two typos). Each number shows how many products matched:

SearchWord orderTypos
WooCommerce alone00
FiboSearch Free150
FiboSearch Pro1515

FiboSearch Free handles word order. Correcting typos takes FiboSearch Pro and its fuzzy search.

Setting up FiboSearch for WooCommerce UCP

There is nothing to set up in FiboSearch. When UCP is active in WooCommerce, FiboSearch answers UCP search requests on its own. When UCP is off, nothing changes.

WooCommerce marks UCP as experimental and keeps it disabled by default, and its standard settings have no switch for it. The extension or service that connects your store to AI shopping agents turns it on. WooCommerce describes one such setup in Enable agentic commerce in WooCommerce AI.

FiboSearch changes how the search phrase is matched in UCP search requests (POST /wp-json/wc/ucp/v1/catalog/search), and with it the order of the results. Everything around it still works the WooCommerce way:

  • Category and price filters narrow down the FiboSearch results.
  • Pagination moves through the full result list, in order of relevance.
  • Prices, images and other product data come from WooCommerce.
  • A phrase longer than 256 bytes is rejected with a WooCommerce validation error.
  • A request with only category or price filters, and no phrase, is answered by WooCommerce.

The rest of the API is untouched. /catalog/lookup and /catalog/product fetch products by ID, and the WooCommerce Store API (wc/store/v1/products?search=) keeps its own search, so a typo there still finds nothing.

FiboSearch treats an AI shopping agent like any other customer: it looks at SKUs only when “Search in SKU” is enabled in WooCommerce > FiboSearch > Search config. With that option off, AI shopping agents can’t find products by SKU, even though WooCommerce alone would find them.

FiboSearch Pro rebuilds the search index by itself after you save this option.

UCP search before the first FiboSearch index is ready

FiboSearch Pro answers from its search index. Until the first index is built, WooCommerce answers the agent instead, so a new installation doesn’t leave AI shopping agents with an empty catalog. FiboSearch takes over by itself once the index is ready.

FiboSearch Free has no index, so it answers UCP search from the start.

UCP search on multilingual stores

AI shopping agents usually call the address your store publishes in /.well-known/ucp, and that address doesn’t name a language. What FiboSearch Pro searches then depends on your multilingual plugin:

PluginWhat FiboSearch Pro searches
PolylangAll languages, default first. To search one language, add ?lang=pl.
qTranslate-XTAll languages, default first. To search one language, use /pl/wp-json/....
WPMLThe default language. To search another one, use /pl/wp-json/... or ?lang=pl.
TranslatePressThe default language. To search another one, use /pl/wp-json/....

On Polylang and qTranslate-XT, WooCommerce itself searches every language, and FiboSearch Pro searches every language too. An agent asking for spodnie, Polish for trousers, finds the Polish products on a store whose default language is English. On such a store, the agent can see more than your search results page, which shows one language at a time.

On Polylang and WPML, FiboSearch Free searches the same languages as WooCommerce. The context.language field of a UCP request doesn’t change the language in FiboSearch Free or Pro.

To confirm that FiboSearch answers UCP search on your store, send a phrase WooCommerce can’t match on its own. In FiboSearch Pro, use a misspelled product name. In FiboSearch Free, swap two words of a product name. This test needs a terminal, so you may want to ask your developer to run it:

curl -X POST https://yourdomain.com/wp-json/wc/ucp/v1/catalog/search \
  -H "Content-Type: application/json" \
  -d '{"query":"lether walet","pagination":{"limit":5}}'

Then repeat the request with ?nofibosearch=1 at the end of the address. This parameter turns FiboSearch off for that request, as described in Debugging FiboSearch. If the first request finds products and the second finds none, FiboSearch is answering.

A 404 response means UCP isn’t active on your store, or WooCommerce is older than 11.3. A 401 response usually means your store accepts only signed requests, which is the default in WooCommerce AI. See its UCP REST API guide.

Further reading about WooCommerce UCP