# Search products and complete payments with Universal Commerce Protocol

Search seller catalogs, obtain payment approval with a shared payment token, and complete purchases using the Link CLI over the UCP.

Use Link CLI to build an agent that discovers a product through the [Universal Commerce Protocol](https://docs.stripe.com/agentic-commerce/protocol.md) (UCP), creates a checkout, obtains buyer approval for a [shared payment token](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens.md) (SPT), and completes the purchase. Link CLI exposes native UCP commands, so your agent runs the full checkout flow without integrating with each seller directly.

> [Join the preview waitlist](https://go.stripe.global/agentic-commerce-contact-sales) to search the catalogs of sellers who have joined [Agentic Commerce Suite](https://docs.stripe.com/agentic-commerce/for-sellers.md) and uploaded their catalog to Stripe. Catalog search doesn’t return every seller that supports UCP. Agentic Commerce Suite is in private preview, supports purchases of physical goods, and is available in the US, Canada, and select European countries.

## Before you begin

Before you begin, make sure that:

- You’ve [set up OAuth](https://docs.stripe.com/agentic-commerce/link-cli/oauth.md), including the `payment_methods.agentic` scope. To authorize a local agent instead, see the [link-cli repository](https://github.com/stripe/link-cli).
- Your agent can run Link CLI commands directly or reach them through an MCP tool boundary.

## How UCP checkout works 

Your agent finds a product, confirms the price with the seller, gets the buyer’s approval to pay, and then completes the purchase:

1. Your agent [searches seller catalogs](https://docs.stripe.com/agentic-commerce/link-cli/commerce-agents-ucp.md#search-for-a-product) for what the buyer wants to buy.
2. Your agent [creates a checkout](https://docs.stripe.com/agentic-commerce/link-cli/commerce-agents-ucp.md#create-and-review-the-checkout) with the selected product and the buyer’s fulfillment details. The seller returns the authoritative cart and total.
3. Your agent [creates a spend request](https://docs.stripe.com/agentic-commerce/link-cli/commerce-agents-ucp.md#request-payment-approval) for a shared payment token and presents the purchase details to the buyer.
4. The buyer approves the request, and Link returns the token.
5. Your agent [completes the checkout](https://docs.stripe.com/agentic-commerce/link-cli/commerce-agents-ucp.md#complete-and-validate-the-checkout) with the token.

The `--schema` calls in the following steps allow your agent to inspect the current input contract.

## Search for a product

To find what the buyer wants to buy, inspect the current search schema, then run a global catalog search across all connected sellers. Translate the buyer’s request into a `--query`, which is required. Each result includes the seller profile that produced it:

```bash
link-cli ucp catalog search --schema

link-cli ucp catalog search --query="{{SEARCH_QUERY}}"
```

For example, if the buyer asks for running shoes, search across every connected seller:

```bash
link-cli ucp catalog search --query="running shoes"
```

The response contains matching products from across connected sellers:

```json
{
  "data": [
    {
      "id": "100076983",
      "object": "acs.product",
      "name": "New Balance 1906R Sneakers",
      "variants": [
        {
          "object": "acs.product_variant",
          "profile_id": "profile_1RExampleSeller",
          "merchant_name": "Example Outfitters",
          "price": {
            "amount": 15500,
            "currency": "usd"
          },
          "availability": {
            "status": "in_stock"
          }
        }
      ]
    }
  ]
}
```

After the buyer selects a product, save the following fields:

- `id`: The SKU to pass to checkout creation.
- `variants[].profile_id` (`profile_...`): The seller profile. Pass it to the checkout and spend request.
- `variants[].price` and `variants[].availability.status`: Confirm the item is `in_stock` and show the price to the buyer before you request payment approval.

Before you create the checkout, verify the seller and product.

## Create and review the checkout

Inspect the installed schema for the current checkout input shape, then create a checkout. Use the `id` and `profile_id` from the product the buyer selected. Pass each item as a `--line-item` with its `sku_id` and `quantity`, and provide the buyer’s `--fulfillment-details` so the seller can calculate shipping and tax:

```bash
link-cli ucp checkout create --schema

link-cli ucp checkout create \
  --network-id={{SELLER_PROFILE_ID}} \
  --line-item="sku_id:{{PRODUCT_SKU}},quantity:{{QUANTITY}}" \
  --fulfillment-details='{{FULFILLMENT_DETAILS}}'
```

For example, take the `id` and `profile_id` from the running-shoes search result and create a checkout for one pair with the buyer’s shipping address:

```bash
link-cli ucp checkout create \
  --network-id=profile_1RExampleSeller \
  --line-item="sku_id:100076983,quantity:1" \
  --fulfillment-details='{"name":"Jenny Rosen","address":{"line1":"123 Main St","city":"San Francisco","state":"CA","postal_code":"94111","country":"US"}}'
```

To buy more than one product, repeat `--line-item` for each SKU. The seller returns the authoritative cart, including the resolved line items, taxes, fulfillment options, and total.

Save the checkout token (`dcs_...`) from the response. Before you create a spend request, verify the seller profile, the SKUs and quantity, the currency, and the final total against what the buyer expects, and use the checkout amount the seller returned. Stop if anything differs.

## Request payment approval

Present the purchase details to the buyer by creating a [spend request](https://docs.stripe.com/agentic-commerce/link-cli/use-link-wallet-pay-online.md). Your agent must show the seller, selected products, quantity, currency, and final total before it requests approval.

```bash
link-cli spend-request create \
  --credential-type=shared_payment_token \
  --amount={{CHECKOUT_AMOUNT}} \
  --context="{{APPROVAL_CONTEXT}}" \
  --network-id={{SELLER_PROFILE_ID}} \
  --request-approval
```

The spend request starts in a pending state while it awaits approval. Save the returned spend request ID (`lsrq_...`). The `--request-approval` flag requests approval in Link. Don’t attempt checkout completion while the request is pending, denied, or expired, or while it’s waiting on another action from the buyer. For the full set of spend request statuses, see [Accept agent payments](https://docs.stripe.com/agentic-commerce/link-cli/use-link-wallet-pay-online.md#spend-request-statuses).

After the buyer approves the spend request, retrieve it:

```bash
link-cli spend-request retrieve lsrq_{{REQUEST_ID}} \
  --interval 2 --max-attempts 300
```

After approval, the response includes the approved SPT (`spt_...`):

```json
[
  {
    "id": "lsrq_1TlumsIM14ru2UNO7huBCrLz",
    "status": "approved",
    "credential_type": "shared_payment_token",
    "shared_payment_token": {
      "id": "spt_1Tlun3BfQCrp7lQIGDn7MwHw",
      "valid_until": "2026-06-25T05:40:34Z"
    }
  }
]
```

> #### Keep the shared payment token out of agent context
> 
> Save the approved SPT (`spt_...`) outside the model context. Never place it in an agent transcript, code repository, screenshot, or bug report.

## Complete and validate the checkout

Complete the matching checkout with the approved SPT:

```bash
link-cli ucp checkout complete dcs_{{CHECKOUT_TOKEN}} \
  --shared-payment-token=spt_{{TOKEN}}
```

A successful completion returns the order details, including the completion status and an order status URL for tracking.

Confirm the completion response before you mark the run successful. Capture the checkout token, spend request ID, completion status, and any order or reconciliation identifier. Arrange a refund when appropriate.

## See also

- [Accept agent payments](https://docs.stripe.com/agentic-commerce/link-cli/use-link-wallet-pay-online.md)
- [Shared payment tokens](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens.md)