Integration Guide

This guide walks through building an agent integration against a Finqu-powered store using the Universal Commerce Protocol (UCP) . For endpoint specifications, authentication tiers, and MCP tool details, see the UCP API Reference.

Audience: Developers building shopping agents, agent platforms, or commerce integrations.

Protocol version: 2026-04-08

Integration flow

A typical agent integration follows these steps:

1. Discover the merchant profile at https://{shop-domain}/.well-known/ucp
2. Authenticate using one of the supported agent tiers
3. Negotiate capabilities by sending your platform profile
4. Browse the catalog and build a cart
5. Handle structured messages and errors in every response
6. Direct buyers to continue_url for storefront checkout (until the checkout API is available)

All UCP API traffic is scoped to the merchant’s storefront domain. Requests to a domain where UCP is not enabled receive 404.

Choose a transport

Finqu exposes UCP capabilities through multiple transports. Choose based on your agent framework:

The discovery profile lists which transports are active for a given store. See REST API and MCP Transport for endpoint and tool details.

Discovery profile

Before calling any API, fetch the merchant’s discovery profile:

GET https://{shop-domain}/.well-known/ucp

This endpoint is public, unauthenticated, and cacheable. It returns a JSON document describing the protocol version, available transports, advertised capabilities, and (when enabled) payment handlers and signing keys.

Key fields to inspect:

The shopping service is published under dev.ucp.shopping. Treat the capability list in the discovery profile as the source of truth for what a store supports.

Capabilities

Capabilities are named with reverse-DNS identifiers (for example dev.ucp.shopping.cart). Finqu computes the active set per request by intersecting what the merchant advertises with what your platform declares.

Currently available on Finqu

The discount capability extends cart. When negotiated, cart create/update requests may include a discounts.codes array.

Planned / not yet exposed

The following capabilities are part of the broader UCP specification but are not available via the public API today:

• dev.ucp.shopping.checkout — checkout sessions and payment completion
• dev.ucp.shopping.fulfillment — shipping option selection
• dev.ucp.shopping.order — order retrieval and lifecycle webhooks
• dev.ucp.shopping.buyer_consent — consent capture during checkout
• dev.ucp.common.identity_linking — OAuth-based buyer identity linking

Integrations should gracefully handle capabilities that are advertised but not yet callable.

Capability negotiation

Negotiation ensures both sides agree on protocol version and feature set. Publish your own platform profile at https://your-platform.example/.well-known/ucp, then declare it on each request.

If you omit a platform profile, the merchant’s full advertised set is used.

REST

Send the UCP-Agent header using RFC 8941  dictionary syntax:

UCP-Agent: profile="https://your-platform.example/.well-known/ucp"

Finqu fetches your platform profile over HTTPS, validates the protocol version matches, and returns responses scoped to the intersection of capabilities.

MCP

Pass your platform profile in tool call metadata:

{
  "meta": {
    "ucp-agent": {
      "profile": "https://your-platform.example/.well-known/ucp"
    }
  }
}

Negotiation rules

• Protocol versions must match exactly (for example 2026-04-08)
• Only capabilities present in both profiles are active for the request
• Extension capabilities whose parent capability was not negotiated are automatically removed
• Every successful response includes a ucp block with version, status, and the negotiated capabilities

Building a shopping flow

1. Search or look up products

Use catalog capabilities to find products and variant IDs. Pass an optional context object to localize results (language, currency, country).

Search responses include products and pagination with a cursor for the next page. Lookup and product responses return full product objects including variants, pricing, and customization metadata.

See REST API — Catalog for endpoint details.

2. Handle product customizations

Many Finqu products support buyer customizations (text fields, option groups, required selections). Before adding items to a cart:

1. Look up or search for the product first
2. Read metadata.customizations on the chosen variant
3. Include a customizations array on each line item with { "id": "…", "value": "…" }
4. Ensure required customization groups have at least one selection

Missing or invalid customizations return validation errors with field-level messages.

3. Create and update carts

Line items reference a variant by item.id and quantity. Cart responses include:

• id, currency, line_items, totals (in minor currency units)
• continue_url — a buyer-facing URL to continue to checkout in the storefront
• discounts — when the discount capability is negotiated
• messages — warnings or recoverable errors (for example rejected coupon codes)

Use Idempotency-Key on cart create and cancel operations to prevent duplicate side effects.

See REST API — Carts for endpoint details.

4. Complete checkout

Checkout session endpoints are not yet published on Finqu. Until they are available, direct buyers to the continue_url returned on the cart to complete checkout in the merchant’s storefront.

MCP transport

When the merchant enables the MCP server, the same shopping capabilities are available as MCP tools at https://{shop-domain}/mcp.

UCP MCP tools replace the former Storefront MCP tool names. For example, use search_catalog instead of search_products, and update_cart instead of add_cart_lines / update_cart_lines / remove_cart_lines.

Each tool requires meta.ucp-agent.profile. See MCP Transport for the full tool list and metadata requirements.

Embedded checkout

For buyer-facing checkout inside your own site, UCP defines an embedded transport using a hosted iframe and JSON-RPC messages between host and guest.

Finqu provides a host helper script:

<script src="https://{shop-domain}/ucp/host.js"></script>

Use UcpEmbeddedHost.mount() to embed the checkout iframe and exchange ec.start, ec.auth, ec.complete, and ec.error events as defined in the UCP embedded checkout specification.

Embedded checkout requires a checkout session and is tied to the checkout capability when that becomes available.

Integration checklist

1. Obtain a storefront domain with UCP enabled — see Activating UCP
2. Fetch /.well-known/ucp and confirm advertised capabilities
3. Create a channel API key (token tier) or implement signed requests — see Authentication
4. Publish your own /.well-known/ucp platform profile
5. Call catalog endpoints to discover products and variant IDs
6. Create and update carts with correct customizations
7. Direct buyers to continue_url for storefront checkout (until checkout API is available)
8. Handle messages, rate limits, and idempotency in your agent loop — see Responses & Errors

Specification references

Finqu implements the canonical UCP specification. For schema details, field definitions, and normative behavior, refer to:

• UCP overview 
• REST shopping service schema 
• MCP shopping service schema 
• Individual capability specs linked from the merchant discovery profile

The discovery profile’s spec and schema URLs are always the authoritative link for the version a given store supports.