# Getting Started

Connect your shopping agent to one Finqu store. This REST walkthrough covers discovery, product search, carts and hosted checkout. Use the [Prompting guide](./prompting) to connect the shopping flow to your agent’s instructions.

Connect these commerce operations to your own agent runtime. Your agent handles the conversation and calls the store; the customer completes payment through Finqu’s hosted checkout handoff. Each call below names the matching MCP tool for when the merchant enables that transport.

Your first successful step is a public discovery request. Its response lists the store’s available capabilities and connection methods. Full path tables live in the [REST API reference](/reference/ucp/rest-api). Use [Identity linking](./identity-linking) before you read an order.

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

## Prerequisites

- A Finqu storefront domain with UCP enabled on its channel. See [Activating UCP](./activating-ucp).
- Discovery is public. The shopping calls that follow use a channel API key: `Authorization: Bearer fq_secret_…`. See [UCP authentication](/reference/ucp/authentication).
- Your platform profile on every shopping call. See [Capability negotiation](./integration-guide#capability-negotiation):

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

The examples below repeat those two headers. Replace `{shop-domain}` with the storefront host.

## Discover the store

```bash
curl -sS "https://{shop-domain}/.well-known/ucp"
```

This call is public. Treat the profile as the source of truth for protocol version, transports, and capabilities. On this release, `ucp.version` is `2026-08-25`.

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

## Search, then open a product

Search the catalog. MCP tool: `search_catalog`.

```bash
curl -sS -X POST "https://{shop-domain}/api/ucp/catalog/search" \
  -H "Authorization: Bearer fq_secret_…" \
  -H 'UCP-Agent: profile="https://your-platform.example/.well-known/ucp"' \
  -H "Content-Type: application/json" \
  -d '{"query":"linen shirt","context":{"language":"en","currency":"EUR"}}'
```

`context.language` is a BCP 47 tag. `context.currency` is an ISO 4217 code. You can also pass `limit` and `cursor` at the top level, or nest them under `pagination`.

Open one product from the search result. MCP tool: `get_product`.

```bash
curl -sS -X POST "https://{shop-domain}/api/ucp/catalog/product" \
  -H "Authorization: Bearer fq_secret_…" \
  -H 'UCP-Agent: profile="https://your-platform.example/.well-known/ucp"' \
  -H "Content-Type: application/json" \
  -d '{"id":"{product-id}"}'
```

A cart line buys a **variant**, not the parent product. Use `variants[].id`.

Read `metadata.customizations` on that variant before you add a line. Each group has `id`, `title`, `required`, `input_type`, and `options`. On the line, `customizations[].id` is an **option** id (`options[].id`), not the group id. A required group needs at least one of its option ids. For `select`, `radio`, and `checkbox`, set `value` to the option id or its title. For `text` and `textarea`, `value` is the entered text. Honor `min_length` and `max_length` only when they are greater than 0.

## Create a cart

MCP tool: `create_cart`. Send `Idempotency-Key` so a retry does not create a second cart. The call returns `201`.

```bash
curl -sS -X POST "https://{shop-domain}/api/ucp/carts" \
  -H "Authorization: Bearer fq_secret_…" \
  -H 'UCP-Agent: profile="https://your-platform.example/.well-known/ucp"' \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "line_items": [
      {
        "item": { "id": "{variant-id}" },
        "quantity": 1,
        "customizations": [
          { "id": "{option-id}", "value": "{option-id}" }
        ]
      }
    ]
  }'
```

Omit `customizations` when the variant has none. Keep the returned cart `id`.

## Checkout

Create a checkout session from that cart. MCP tool: `create_checkout`. The call returns `201`.

```bash
curl -sS -X POST "https://{shop-domain}/api/ucp/checkout-sessions" \
  -H "Authorization: Bearer fq_secret_…" \
  -H 'UCP-Agent: profile="https://your-platform.example/.well-known/ucp"' \
  -H "Content-Type: application/json" \
  -d '{"cart_id":"{cart-id}"}'
```

Pass `cart_id` and omit `line_items`. The cart already holds the customization selections.

If the store advertises identity linking and this request still uses the channel key, the session includes a message with `code` `identity_optional`. Checkout continues as a guest. Linking is covered in [Identity linking](./identity-linking).

Update the session with buyer contact, fulfillment, and discounts. MCP tool: `update_checkout`. Restate `line_items`. Copy method, destination, group, and option ids from the session you just received. Do not guess fulfillment fields.

```bash
curl -sS -X PUT "https://{shop-domain}/api/ucp/checkout-sessions/{checkout-id}" \
  -H "Authorization: Bearer fq_secret_…" \
  -H 'UCP-Agent: profile="https://your-platform.example/.well-known/ucp"' \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "item": { "id": "{variant-id}" }, "quantity": 1 }
    ],
    "buyer": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com",
      "phone_number": "+358401234567"
    },
    "fulfillment": {
      "methods": [
        {
          "id": "{method-id}",
          "type": "shipping",
          "line_item_ids": ["{line-item-id}"],
          "selected_destination_id": "ship-1",
          "destinations": [
            {
              "id": "ship-1",
              "type": "shipping_address",
              "first_name": "Ada",
              "last_name": "Lovelace",
              "street_address": "Testikatu 1",
              "address_locality": "Helsinki",
              "postal_code": "00100",
              "address_country": "FI"
            }
          ],
          "groups": [
            { "id": "{group-id}", "selected_option_id": "{shipping-option-id}" }
          ]
        }
      ]
    },
    "discounts": { "codes": ["{code}"] }
  }'
```

Call complete only when `status` is `ready_for_complete`. If `status` is `incomplete`, read `messages` and supply the missing buyer or fulfillment data first. MCP tool: `complete_checkout`.

```bash
curl -sS -X POST "https://{shop-domain}/api/ucp/checkout-sessions/{checkout-id}/complete" \
  -H "Authorization: Bearer fq_secret_…" \
  -H 'UCP-Agent: profile="https://your-platform.example/.well-known/ucp"' \
  -H "Content-Type: application/json" \
  -d '{}'
```

When a balance remains, payment goes to `com.finqu.hosted_checkout`. The response sets `status` to `requires_escalation` and tells the buyer to continue:

```json
{
  "status": "requires_escalation",
  "continue_url": "https://{shop-domain}/checkout/…",
  "messages": [
    {
      "type": "info",
      "code": "payment_escalation",
      "content": "Payment must be completed by the buyer on the hosted checkout page (continue_url)."
    }
  ]
}
```

Send the buyer to `continue_url`. That URL is the initialized session. The discovery profile's `checkout_url` is not a payment session. A zero balance can complete without this handoff.

## Read the order

Read `GET /api/ucp/orders/{id}` only after the buyer is linked. MCP tool: `get_order`.

Switch the `Authorization` header to the buyer token (`ucp_at_…`) from [Identity linking](./identity-linking). Do not send `fq_secret_…` on that request. The token needs scope `dev.ucp.shopping.order:read`.

## Responses you handle every time

Successful bodies put the `ucp` block next to the resource. Amounts in `totals` are integers in minor currency units (`type` `subtotal` and `total`; a `discount` amount is negative). Read `messages` on every call.

```json
{
  "ucp": {
    "version": "2026-08-25",
    "status": "success"
  },
  "currency": "EUR",
  "totals": [
    { "type": "subtotal", "amount": 4900 },
    { "type": "total", "amount": 4900 }
  ],
  "messages": [
    {
      "type": "info",
      "code": "identity_optional",
      "content": "This store supports identity linking. Linking the buyer's customer account adds order history and saved details; checkout also works without it."
    }
  ]
}
```

`4900` means 49.00 in a two-decimal currency. The `identity_optional` message appears on an open, unlinked checkout when the store advertises identity linking and the caller did not present a buyer token.

Error shapes, severity, and rate limits are in [Responses & Errors](/reference/ucp/responses-and-errors).