Skip to Content
LogoDevelopers
AI & AgentsAgentic CommerceGetting Started

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 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. Use 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.
  • Discovery is public. The shopping calls that follow use a channel API key: Authorization: Bearer fq_secret_…. See UCP authentication.
  • Your platform profile on every shopping call. See Capability negotiation:
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

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.

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.

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.

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.

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.

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.

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.

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:

{
  "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. 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.

{
  "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.