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-08-25

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. Complete the purchase using supported fulfillment and checkout capabilities, with Finqu’s hosted payment handoff
7. Access orders where enabled and authorized

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 shopping and common services through REST and MCP. 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, payment handlers and public signing keys in keys.

Key fields to inspect:

Services are published under dev.ucp.shopping and dev.ucp.common. 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.

Release capabilities

The 2026-08-25 release covers catalog search and lookup, carts, checkout, fulfillment, discounts, orders, identity linking, buyer consent, permalinks, split payments, location search and lookup, and loyalty.

See the capability reference for identifiers and specification links. Check each store’s advertised configuration and your access tier before using a feature. Follow the extends relationships for capabilities that extend other operations.

For example, the release profile extends cart and checkout with discounts and buyer consent. Fulfillment advertises shipping or pickup, and split payments declares which gift-card and redirect combinations are allowed.

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-08-25)
• Only capabilities present in both profiles are active for the request
• Extension capabilities whose parent capability was not negotiated are automatically removed
• Inspect the ucp block and structured messages in responses using the advertised schema

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

Use the negotiated checkout capability and its extensions to prepare the purchase. Read the advertised checkout and fulfillment schemas for request fields and supported operations. A runnable checkout sequence is in Getting Started. Handle required buyer input and structured messages before proceeding.

Finqu advertises com.finqu.hosted_checkout with redirect and gift-card instruments. Follow the hosted payment handoff when the checkout flow requires buyer interaction. Use the payment configuration returned for the store and transaction; the discovery profile’s checkout_url alone does not represent an initialized payment session.

Offer only supported fulfillment methods and payment combinations. The release profile permits shipping or pickup and defines allowed split-payment combinations. Read these settings from each store’s profile instead of hard-coding them.

5. Continue after purchase

Use the order capability where authorized. Identity linking can grant buyer-scoped access; the release profile advertises an order-read scope. Follow the common service schema and authentication requirements for the relevant operation.

Location and loyalty capabilities can enrich the journey when the store supports them. Discover their configuration and extensions before including them in your experience.

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 tool discovery and metadata requirements.

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. Use supported fulfillment and checkout operations; follow Finqu’s hosted payment handoff when buyer interaction is required
8. Use order access and identity linking only where enabled and authorized
9. 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 
• REST common service schema 
• MCP common 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.