UCP API Reference

Finqu exposes Universal Commerce Protocol on each sales channel. This reference describes the 2026-08-25 release. Start with the Integration Guide for the end-to-end shopping flow.

Discovery and service endpoints

Resource	URL
Discovery profile	`GET https://{shop-domain}/.well-known/ucp`
REST service endpoint	`https://{shop-domain}/api/ucp`
MCP endpoint	`https://{shop-domain}/mcp` (when enabled)

The discovery endpoint is public. Requests to a store domain where UCP is disabled receive 404.

Discovery profile

Always read the store’s profile before choosing capabilities or transports. Stores can enable different features and access tiers.

Field	Purpose
`ucp.version`	Protocol version
`ucp.services`	Service bindings with transport, endpoint, version, specification, and schema URLs
`ucp.capabilities`	Capabilities, versions, extensions, and configuration advertised by this store
`ucp.payment_handlers`	Payment handlers and their supported instruments
`keys`	Public signing keys published by the store

The release profile exposes dev.ucp.shopping and dev.ucp.common, each with REST and MCP bindings. Use the endpoint and schema from the relevant service binding. A capability being part of this release does not mean it is enabled or authorized for every store or request.

Capabilities

The release profile advertises the following capabilities. Each name links to its specification; read the spec, schema, extends, and config fields in the store’s profile for the exact advertised version and behavior.

Capability	Purpose
`dev.ucp.shopping.catalog.search`	Search the product catalog
`dev.ucp.shopping.catalog.lookup`	Look up products and variants
`dev.ucp.shopping.cart`	Create and manage carts
`dev.ucp.shopping.checkout`	Manage the checkout journey
`dev.ucp.shopping.fulfillment`	Select supported fulfillment options; the release profile allows shipping or pickup
`dev.ucp.shopping.discount`	Apply discounts to carts and checkout
`dev.ucp.shopping.order`	Access order information with the required authorization
`dev.ucp.common.identity_linking`	Link buyer identity; the release profile includes an order-read scope
`dev.ucp.shopping.buyer_consent`	Capture buyer consent in carts and checkout
`dev.ucp.shopping.permalink`	Use the store’s advertised purchase-link endpoint
`dev.ucp.common.payment.split_payments`	Combine supported payment instruments according to the store’s configuration
`dev.ucp.common.location.search`	Search locations
`dev.ucp.common.location.lookup`	Look up locations
`dev.ucp.common.loyalty`	Use loyalty extensions in catalog, cart, and checkout flows

Hosted payments

Finqu advertises the com.finqu.hosted_checkout payment handler. Its configuration contains a store-specific checkout_url and available instruments: redirect and gift card.

Use the supported checkout flow to determine when buyer interaction is required, then follow the hosted payment handoff. Discovery configuration alone is not a completed checkout or payment session.

The release profile’s split-payment configuration allows a redirect payment with at most one gift card, or one gift card on its own. Read each store’s advertised combinations before offering payment choices.

Reference pages

Authentication — Agent access tiers and capability negotiation
REST API — Catalog and cart operations, service schemas, and request conventions
MCP Transport — Tool discovery and call metadata
Responses & Errors — Response handling and error semantics

Service specifications

Use the schema URLs advertised by the store. The release profile points to:

These schemas define operation contracts. Do not infer operation paths, request fields, or MCP tool names from capability identifiers.