> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog and UCP Checkout

> Supplementary MCP reference for product discovery, checkout, orders, and digital delivery.

These tools complement [Wallet Service](/guides/agent/wallet_service) and [Browser Pay](/guides/agent/browser_pay). Use them when the connected server's current rules select Catalog or UCP Checkout for the user's request. A search result is not authorization to purchase.

This page covers the main parameters. Discover the full schema with `tools/list`; see [MCP connection and OAuth](/guides/agent/mcp_integration) for calling tools. Even tools with no additional scope require the normal authenticated MCP connection.

## Search and product details

| Tool | Main arguments | Scope | Use |
| :- | :- | :- | :- |
| `discover_catalog` | `query`; optional `catalogLanguage`, `limit`, scope and pagination fields below | `wallet:read` | Main entry for product discovery across supported catalogs. |
| `list_catalog_merchants` | `{}` | No additional scope | List registered Catalog merchants when the user needs a merchant directory or a specific merchant scope. |
| `get_product` | `productId`, `target`; optional `selected`, `preferences`, `catalogLanguage` | `wallet:read` | Fetch details and required options for an exact product. Reuse its returned `target`. |
| `parse_product_item` | `productUrl` | No additional scope | Obtain selected SKU facts from a supported external HTTPS product URL. |
| `search_catalog` | `merchantId`, `query`; optional `limit` | `wallet:read` | Compatibility search for one known registered merchant. Use `discover_catalog` for new integrations. |

### Discover products

Example `tools/call` parameters:

```json theme={null}
{
  "name": "discover_catalog",
  "arguments": {
    "query": "coffee vouchers",
    "catalogLanguage": "en-US",
    "limit": 5
  }
}
```

| Parameter | Meaning |
| :- | :- |
| `query` | Required, non-empty buyer query. |
| `catalogLanguage` | BCP 47 language tag for the query, such as `en-US` or `zh-Hans`. |
| `merchantId` | Restrict to a registered merchant selected from `list_catalog_merchants`. Omit for broad discovery. |
| `order_channel_id`, `storeId`, `channelType` | External store scope when already known from an authoritative result. Do not infer IDs from names. |
| `sources` / `provider` | Explicit sources, or a specific provider for continuation. Use values returned or supported by the service. |
| `cursor` | Opaque continuation cursor. Broad-search continuation requires exactly one third-party source; preserve the returned source and cursor. |
| `limit` | Positive integer, at most 100. Broad discovery defaults to 10 products across sources. |

Registered-merchant scope cannot be combined with external-store or provider scope. Results can include `groups`, `provider_results`, and exact product `target` objects. Keep the original target when calling `get_product`; a store ID is not a registered merchant ID.

Pure search does not create a spending authorization or start payment. Resolve product variants and required options before checkout. Use returned or parsed prices in their documented units; do not multiply a minor-unit amount by 100 again.

## UCP Checkout

When the user chooses UCP Checkout for a purchase, first apply the connected server's purchase-authorization rules. If the stated budget requires preauthorization, activate a matching instruction before discovery. Without a budget, checkout can provide the actual total before authorization.

1. Obtain exact products from Catalog, or parse a product URL.
2. Confirm SKU, options, quantity, and fulfillment requirements.
3. Call `create_checkout`, then follow its `next_action` to supply information, authorize spending, or confirm the summary.
4. Use `update_checkout` for supported changes to that checkout. Review and confirm the updated summary.
5. Call `complete_checkout` once for the current confirmation. Read `get_operation` if the outcome is still pending or the response is lost.
6. Read the resulting UCP order and, for digital goods, wait for delivery if needed.

### Main checkout parameters

| Tool | Main arguments | Scope |
| :- | :- | :- |
| `create_checkout` | Exactly one of `merchantId` / `merchantUrl`; `items` and `fulfillmentType`, or native `line_items` and `fulfillment`; optional `buyer`, `shippingAddress`, `couponCode`, `buyerNote` | `wallet:read`, `payment:execute` |
| `update_checkout` | `operationId`, current `actionId`, `expectedRevision`, and the fields to update | `payment:execute`; `wallet:read` is also required when resuming purchase-instruction setup |
| `complete_checkout` | `operationId`, current `actionId`, `expectedRevision`; optional `maxWaitSeconds` (0–60) | `payment:execute` |

For the `items` form of `create_checkout`:

* **Registered merchant:** use the returned merchant ID and item IDs, quantities, and selected options. Catalog supplies prices; omit external `currency`, item `title`, and `unitPriceMinor` fields.
* **External product:** use the product URL as `merchantUrl`, provide `currency`, and include each item's exact `title` and `unitPriceMinor`. Preserve a returned `order_channel_id`. Obtain missing facts with `get_product` or `parse_product_item` before creating checkout.
* **Fulfillment:** use `PHYSICAL_GOODS_REQUIRES_SHIPPING` with complete shipping details, or `NO_SHIPPING_REQUIRED` when appropriate. Resolve an unknown fulfillment type with the user first.

`create_checkout` prepares a checkout; it does not complete payment. `update_checkout` invalidates the old confirmation. `complete_checkout` uses the current confirmation identifiers; it is not a place to submit a replacement amount or payment card. The legacy checkout `paymentInstrumentId` argument is ignored; checkout uses the wallet default.

Spending-authorization tools and their amount units are documented in [Wallet Service tools](/api-reference/mcp/wallet). Operation identifiers, revisions, and recovery are documented in [Operations](/api-reference/mcp/operations).

## Orders and delivery

| Tool | Arguments | Scope | Result |
| :- | :- | :- | :- |
| `get_order` | `orderId`: use `resources.ucp_order_id` from the checkout Operation | `payment:execute` | The UCP order, including fulfillment, adjustments, and digital-delivery state. |
| `wait_for_digital_delivery` | Same UCP `orderId`; optional `maxWaitSeconds` (1–900) | `payment:execute` | Delivery readiness, failure, or a bounded-wait timeout. Resume a timeout with the same order ID. |

Some server versions expose this UCP order reader as `get_ucp_order`. Use the exact name returned by the connected server's `tools/list`.

Payment completion and delivery completion are separate states. Reading an order or waiting for delivery never retries payment.

UCP order IDs and Clink direct-payment order IDs identify different records. Do not use them interchangeably or assume a UCP order ID can be submitted to Clink's refund tools. These UCP tools do not provide a general order-cancellation or refund operation.

## Keep the payment flows separate

UCP Checkout completes through `complete_checkout` and its operation. Browser Pay obtains a credential, pays on the merchant website, and reports the observed outcome through `confirm_result`. Do not call Browser Pay's `confirm_result` after UCP Checkout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.