> ## 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](https://docs.clinkbill.com/guides/agent/wallet_service.md) and [Browser Pay](https://docs.clinkbill.com/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](https://docs.clinkbill.com/guides/agent/platform_integration/mcp_integration.md) 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.

### MCP call examples

The following examples use the MCP `tools/call` format. Before calling, use `tools/list` to confirm the tool names and full schema returned by the current server.

#### Create checkout

```json theme={null}
{
  "name": "create_checkout",
  "arguments": {
    "merchantId": "merchant_example",
    "items": [
      {
        "productId": "product_example",
        "quantity": 1,
        "selected": {
          "size": "L"
        }
      }
    ],
    "fulfillmentType": "NO_SHIPPING_REQUIRED"
  }
}
```

Keep the returned `operation_id`, current `action_id`, `revision`, and `next_action`. For physical goods that require shipping, change the fulfillment type to `PHYSICAL_GOODS_REQUIRES_SHIPPING` and provide a complete shipping address.

#### Update checkout and complete payment

When `next_action` asks for checkout information to be added or changed, update using the current revision; the update invalidates the old confirmation identifiers:

```json theme={null}
{
  "name": "update_checkout",
  "arguments": {
    "operationId": "<operation_id>",
    "actionId": "<current_action_id>",
    "expectedRevision": "<current_revision>",
    "shippingAddress": {
      "name": "Alex Smith",
      "addressLine1": "1 Example Street",
      "city": "San Francisco",
      "postalCode": "94105",
      "country": "US"
    }
  }
}
```

Read the updated response and complete the checkout with the latest confirmation identifiers:

```json theme={null}
{
  "name": "complete_checkout",
  "arguments": {
    "operationId": "<operation_id>",
    "actionId": "<latest_action_id>",
    "expectedRevision": "<latest_revision>",
    "maxWaitSeconds": 30
  }
}
```

If the response is still pending, or the response is lost after the call, read the Operation with the same `operationId`. Do not create a new checkout or pay again.

#### Read order and digital delivery

After checkout completes, read the order using `resources.ucp_order_id` from the Operation result:

```json theme={null}
{
  "name": "get_ucp_order",
  "arguments": {
    "orderId": "<ucp_order_id>"
  }
}
```

For digital goods, wait for delivery with the same order ID:

```json theme={null}
{
  "name": "wait_for_digital_delivery",
  "arguments": {
    "orderId": "<ucp_order_id>",
    "maxWaitSeconds": 120
  }
}
```

If the current server names the order tool `get_order`, use the exact name returned by `tools/list`.

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

## 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.