# Integration Guide

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

**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)

```mermaid
flowchart LR
    Agent[Your agent / platform]
    Profile["/.well-known/ucp"]
    REST["/api/ucp/*"]
    MCP["/mcp"]
    Store[Finqu store channel]

    Agent -->|Discover| Profile
    Agent -->|REST calls| REST
    Agent -->|MCP tools| MCP
    Profile --> Store
    REST --> Store
    MCP --> Store
```

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:

| Transport | Endpoint | Best for |
|-----------|----------|----------|
| **REST** | `https://{shop-domain}/api/ucp` | Always available when UCP is enabled; browser and server integrations |
| **MCP** | `https://{shop-domain}/mcp` | AI agent frameworks with MCP tool support (when enabled by merchant) |
| **Embedded** | `/ucp/host.js` | Buyer-facing checkout iframe in your own site (when checkout is available) |

The discovery profile lists which transports are active for a given store. See [REST API](/reference/ucp/rest-api) and [MCP Transport](/reference/ucp/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:

| Field | Purpose |
|-------|---------|
| `ucp.version` | Protocol version — must match your integration |
| `ucp.services` | Available transports and their base endpoints |
| `ucp.capabilities` | Shopping capabilities the merchant advertises |

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

| Capability | Description |
|------------|-------------|
| `dev.ucp.shopping.catalog.search` | Full-text product search with filters and pagination |
| `dev.ucp.shopping.catalog.lookup` | Batch lookup of products or variants by ID |
| `dev.ucp.shopping.cart` | Create, read, update, and cancel shopping carts |
| `dev.ucp.shopping.discount` | Apply discount / coupon codes on carts (extension) |

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](https://www.rfc-editor.org/rfc/rfc8941) dictionary syntax:

```http
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:

```json
{
  "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](/reference/ucp/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](/reference/ucp/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](/reference/ucp/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:

```html
<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](./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](/reference/ucp/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](/reference/ucp/responses-and-errors)

## Specification references

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

- [UCP overview](https://ucp.dev/2026-04-08/specification/overview)
- [REST shopping service schema](https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json)
- [MCP shopping service schema](https://ucp.dev/2026-04-08/services/shopping/mcp.openrpc.json)
- 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.