# UCP API Reference

This reference documents how Finqu exposes the [Universal Commerce Protocol (UCP)](https://ucp.dev) on each sales channel. For implementation guidance, see the [Integration Guide](/agentic-commerce/integration-guide).

**Protocol version:** `2026-04-08`

## Base URLs

All UCP API traffic is scoped to the merchant's storefront domain.

| Resource | URL |
|----------|-----|
| Discovery profile | `GET https://{shop-domain}/.well-known/ucp` |
| REST API | `https://{shop-domain}/api/ucp` |
| MCP server | `https://{shop-domain}/mcp` (when enabled) |
| Embedded checkout host | `https://{shop-domain}/ucp/host.js` |

Requests to a domain where UCP is not enabled receive `404`.

## Discovery profile

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

Public, unauthenticated, cacheable. Returns a JSON document describing:

| Field | Purpose |
|-------|---------|
| `ucp.version` | Protocol version the store supports |
| `ucp.services` | Available transports and their base endpoints |
| `ucp.capabilities` | Shopping capabilities the merchant advertises |
| `ucp.payment_handlers` | Payment handlers available for checkout (when checkout is enabled) |
| `signing_keys` | Public keys for verifying signed webhooks (when order webhooks are enabled) |

The shopping service is published under `dev.ucp.shopping`. Each transport binding includes `transport`, `endpoint`, `version`, `spec`, and `schema` URLs pointing to the canonical UCP specification.

**Transports advertised:**

| Transport | Endpoint | When available |
|-----------|----------|----------------|
| REST | `https://{shop-domain}/api/ucp` | Always when UCP is enabled |
| MCP | `https://{shop-domain}/mcp` | When the merchant enables the MCP server |
| Embedded | Documented via UCP embedded checkout spec | For hosted checkout iframe flows |

## Capabilities

| 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 following capabilities are part of the broader protocol but **not available via the public API today**: checkout, fulfillment, order, buyer consent, and identity linking.

## Reference pages

- [Authentication](./authentication) — Token, signed, and anonymous tiers
- [REST API](./rest-api) — Catalog and cart endpoints, headers, idempotency
- [MCP Transport](./mcp-transport) — MCP tools and metadata
- [Responses & Errors](./responses-and-errors) — Envelopes, error codes, rate limiting

## Specification references

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