Catalog and UCP Checkout

These tools complement Wallet Service and 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 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:

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

Obtain exact products from Catalog, or parse a product URL.
Confirm SKU, options, quantity, and fulfillment requirements.
Call create_checkout, then follow its next_action to supply information, authorize spending, or confirm the summary.
Use update_checkout for supported changes to that checkout. Review and confirm the updated summary.
Call complete_checkout once for the current confirmation. Read get_operation if the outcome is still pending or the response is lost.
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. Operation identifiers, revisions, and recovery are documented in 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.

API Documentation

Clink MCP

Checkout Session

Payment

Payment Instrument

Order

Agent Payment Session

Refund

Product

Price

Coupon

Promotion Code

Subscription

Test Clock

Customer Portal

Webhook Endpoint Management

Webhooks

Search and product details

Discover products

UCP Checkout

Main checkout parameters

Orders and delivery

Keep the payment flows separate

​Search and product details

​Discover products

​UCP Checkout

​Main checkout parameters

​Orders and delivery

​Keep the payment flows separate

Search and product details

Discover products

UCP Checkout

Main checkout parameters

Orders and delivery

Keep the payment flows separate