Turning UCP on for a shop

With UCP switched on, AI assistants and shopping platforms can find your shop's catalogue on your own domain, put together a cart and send the customer to your shop to finish the purchase. Payment always happens on your shop, with your payment methods; nothing is paid through the agent. What an agent can and cannot do is summed up in Agentic commerce (UCP).

UCP is switched on per storefront, in the storefront's settings. It is off for every storefront until you switch it on.

What the shop needs

Two things do not matter: whether the storefront runs on the classic storefront or on Storefront v2 — UCP works with both — and the storefront's design. Catalog mode does matter; see Catalog mode below.

Connect a custom domain

Skip this if the storefront already has a domain marked DNS verified and SSL active in the Custom Domains card.

1. Open the storefront

   Go to E-commerce → Storefronts (Opens in a new tab) and open the storefront. The Custom Domains card is near the bottom of the page.

2. Add the domain

   Click Add Domain, type the domain (for example shop.example.com) and click Connect. A storefront holds at most 5 custom domains. Monokaido's own domains cannot be added, and neither can a domain already connected to another storefront.

3. Create the two DNS records

   Under Configure DNS records the card lists an A Record pointing the domain at Monokaido's server and a TXT Record named _monokaido-verify. followed by your domain, holding a monokaido-verify=… value. Create both at your domain registrar. The card names the A record @; for a subdomain such as shop.example.com create it for that subdomain (at most registrars the name is shop). Changes can take up to 48 hours to propagate.

4. Check the DNS

   Click Check DNS Configuration. One check is allowed every 30 seconds. When both records are right the domain reads DNS verified and the message says the certificate will be provisioned shortly. Otherwise the card shows Verification failed with the reason.

5. Wait for the certificate

   Monokaido requests the SSL certificate by itself; the job runs every two minutes. The domain moves from SSL pending through SSL provisioning... to SSL active. SSL failed means the certificate could not be issued; write to Monokaido support at support@monokaido.com.

6. Choose the primary domain

   If the storefront has more than one domain, click Set Primary on the one agents and customers should use. Only a domain with verified DNS and an active certificate can be primary. All of the shop's traffic is then redirected to it, as the card says.

Switch UCP on

1. Open the storefront settings

   In E-commerce → Storefronts (Opens in a new tab) open the storefront. The switches are in the Storefront Settings card.

2. Make sure the storefront is on

   Storefront Enabled must be on. The UCP switch appears below it, indented, after the Storefront v2 and catalog mode switches where those apply — once the storefront is on and has a domain with verified DNS and an active certificate. If the certificate became active while the page was open, reload the page.

3. Turn on Buying through AI agents (UCP)

   The switch carries the AI mark. Once it is on, the field shows Shop profile for agents: with the address https://shop.example.com/.well-known/ucp (your domain in place of shop.example.com), a copy button, and the note Agents find it once the settings are saved. If the storefront is not Active or has expired, the field shows a warning instead — see What the switch tells you.

4. Save

   Click Save Changes at the top of the page. Nothing is published until you save. After the save the note disappears and the profile address stays.

5. Check it

   Open the profile address in a browser or with curl — see Check that it works.

What the switch tells you

While the switch is on, the field under it says whether agents are answered with the settings as they stand in the form, and if not, why. It reads the form, not the saved settings: turning Active off shows the warning at once, although agents are still answered until you save. Each message names its own fix.

The messages are checked in this order: the storefront first, then the key, then the domain.

Saving can also be refused, rarely — when the storefront or its domains changed after the page was loaded, for example in another tab — with one of these error messages:

• UCP can be turned on only while the built-in storefront is on. — the storefront is off.
• UCP can be turned on once a custom domain with verified DNS and an active certificate points at the shop. — the storefront has no such domain any more.

Reload the page: it then shows the switch only when it can be turned on.

Turning UCP on is checked only at the moment you switch it from off to on. Once it is saved on, a removed domain or a storefront switched off never blocks saving the storefront's other settings; UCP simply stops being served until the cause is fixed.

Check that it works

curl -si https://shop.example.com/.well-known/ucp

The address is exactly /.well-known/ucp, without a trailing slash.

• 200 with JSON and cache-control: public, max-age=300 — UCP is on. The body is the shop's business profile, shown in full on Agentic commerce (UCP). Its endpoint names your primary domain.
• 404 with {"code":"not_found","content":"No UCP business on this host"} — this domain serves no UCP. The answer is the same whatever the reason (UCP off, storefront off, key inactive or expired, the domain removed from the storefront, e-shop module off, or a *.shop.monokaido.com address), on purpose. The message under the switch tells you which of the storefront's own conditions is missing. Most changes show here at once; a certificate that has just become active, or an Expires At date just reached, takes up to 30 seconds — see How fast changes take effect.
• 503 with {"code":"service_unavailable","content":"This shop is temporarily unavailable"} — the company is deactivated or locked for an unpaid subscription. The same answer can also come from a short fault on Monokaido's side; try again after a minute.
• A certificate error (curl refuses the connection) — the domain has no certificate of its own yet: its DNS is not verified yet, or its status is still SSL pending, SSL provisioning... or SSL failed.
• An HTML page instead of JSON — the address is not exactly /.well-known/ucp, or the domain does not point at Monokaido.

The catalogue, cart and checkout calls under /ucp/v1 need an agent's own profile in every request, so they cannot be tried with a bare curl. The Developer quickstart shows how a developer tests them.

Which domain agents use

Agents may find the profile on any served domain of the storefront, but every address the shop publishes — the API endpoint, the link that takes the buyer to your checkout, the order confirmation link and the product links — uses the primary domain. Keep the primary domain verified with an active certificate. If it is not, each served domain publishes its own address, and the address on the screen is the first served domain in the list.

What customers and agents see

Customers browsing your shop see no change at all.

Agents read what your storefront shows: the same products (products the storefront's exclusion filters hide stay hidden in the agent's search and lookup), the same prices with VAT and your price markup rules, the stock status, your shipping methods with their fees, and your discount codes, validated by the same rules. A line of an agent's cart, however, is checked against the company's published products only: an agent that already knows the id of a hidden product can still put it in a cart. The legal links an agent shows next to a checkout come from your Checkout consents: each active consent whose link is a full https:// (or http://) address or a path on your shop (starting with /) is offered, at most 10. It is offered as a privacy policy when its name, link text or address contains, in any letter case, one of privacy, gdpr, osobn, súkrom, sukrom, soukrom, adatvédel, adatved, datenschutz or ochrana, and as terms of service otherwise — so a consent called "Ochrana spotrebiteľa" is offered as a privacy policy too. A shop without such links offers none.

A customer sent by an agent opens a link on your domain. For a moment they see a page with your company name; then the agent's items and discount code are added to their cart and your checkout opens (your cart page, when the agent handed over a cart). Items already in their cart stay; items that can no longer be bought are skipped. If their cart already holds items in a currency the agent's items cannot be priced in, nothing is added and the cart opens. If they are signed in to your shop in the same browser tab, the items go to their customer cart, otherwise to a guest cart. They then fill in contact details, address, shipping and payment as any customer would — those details are not carried over from the agent. A link whose agent cart or checkout has expired, was cancelled or already ended in an order shows a page with your company name and a link to your home page.

The order is an ordinary order of your shop: the same e-mails, payment methods, stock reservation and order list. It is not marked as coming from an agent.

Cart statistics: each agent cart or checkout is priced by a guest cart of your shop. Left untouched for more than an hour, it counts as abandoned in the cart statistics (see Carts) until the agent's session ends: it is cancelled, handed to the customer, or expires (an expired one leaves the statistics within the next hour).

Catalog mode

A storefront on Storefront v2 with catalog mode on sells nothing, and the same holds for agents. Its profile offers only catalogue search and product lookup; agents can show your products and prices and send people to the product pages, but every cart or checkout request is answered as not supported. An agent cart or checkout created before you switched catalog mode on can no longer be used, and its link only opens your home page.

Switching UCP off

Turn Buying through AI agents (UCP) off and click Save Changes. Switching off is always allowed, and the switch stays on the screen while it is saved on — even after the domain or the storefront went away — so there is always a way to turn it off.

What happens then:

• The profile and the whole agent API answer 404 on all of the storefront's domains.
• Platforms may keep your profile cached for up to 5 minutes; their calls in that time get 404 too.
• Open agent carts and checkouts stay stored but can no longer be reached. A link an agent already gave to a customer opens an empty page. Carts expire 7 days and checkouts 24 hours after the agent's last change; the stored data is deleted 30 days after that. If you switch UCP on again before they expire, agents can continue them.
• Orders already placed are not affected.

UCP also stops on its own, with the switch still on, when the domain is removed or its certificate is no longer active, when Storefront Enabled is turned off, when the storefront is deactivated or expires, when the e-shop module is switched off, or when the company is deactivated or locked for an unpaid subscription. Because the switch stays saved on, UCP comes back by itself once the cause is fixed.

How fast changes take effect

Common problems