# Cart and checkout permalinks for AI shopping agents

> A checkout permalink is a URL that builds a cart from item IDs and quantities, then redirects the shopper to checkout. It lets any AI agent, even one without protocol support, give a shopper a ready-to-pay link. The UCP permalink capability standardizes the format.

- Source: https://is-agentic-storefront.com/checks/checkout-permalinks
- Updated: 2026-10-15
- Category: Agentic commerce (15% of score)
- Impact: Medium
- Spec: [UCP permalinks](https://ucp.dev/2026-08-25/specification/permalink/)
- Scanner check: Cart/checkout permalinks agents can hand to shoppers

## Why do cart and checkout permalinks matter for AI agents?

Most AI shopping agents still finish purchases on the merchant's own checkout. ChatGPT, for example, moved away from in-chat Instant Checkout in March 2026 and now sends buyers to merchant checkout ([Digital Commerce 360](https://www.digitalcommerce360.com/2026/03/06/openai-shifts-checkout-plans-agentic-commerce-strategy/)). The cleanest handoff is a **permalink**: a single URL that creates a cart with the right variants and quantities and opens checkout.

Permalinks work for agents with no protocol support at all. An assistant can build the link from product data and give it to the shopper, who lands on a ready-to-pay page. The [UCP permalink spec](https://ucp.dev/2026-08-25/specification/permalink/) standardizes the URL format and makes the endpoint discoverable from your [UCP profile](https://is-agentic-storefront.com/checks/ucp-profile).

## What does the scanner check?

1. **UCP permalink capability.** If `/.well-known/ucp` declares a capability ending in `.permalink` (normally `dev.ucp.shopping.permalink`) with `config.endpoint`, the scanner requests that endpoint without items.
2. **Platform patterns**, used only when there's no UCP permalink:
   - The store runs on a platform with a known built-in cart link format (`/cart/{variant_id}:{quantity}`).
   - Sampled product pages contain `name="add-to-cart"` or a `?add-to-cart={id}` link.

| Result      | When                                                                                                                                          |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pass**    | UCP permalink endpoint declared and responds below HTTP 500.                                                                                  |
| **Partial** | UCP permalink declared but the endpoint gives no response or a 5xx, **or** no UCP permalink but a recognized platform cart link is available. |
| **Fail**    | No UCP permalink and no recognized platform pattern.                                                                                          |

The scanner doesn't place real items in a cart. It confirms the endpoint exists and answers.

## How do I add checkout permalinks?

1. **Add a GET route** that parses line items from the path, creates a cart, and redirects with `303 See Other` to checkout. Following the UCP format:

```http
GET /buy/variant_123:2,variant_456:1?discounts/codes/0=WELCOME10

HTTP/1.1 303 See Other
Location: https://store.example/checkout?cart=cart_abc
```

2. **Handle bad input explicitly.** Return `410` or `404` for unknown or discontinued variants instead of an empty cart.
3. **Never require login** to open the link. A redirect to `/account/login` blocks guest checkout for every agent-referred shopper.
4. **Declare it in your UCP profile:**

```json
{
  "ucp": {
    "capabilities": {
      "dev.ucp.shopping.permalink": [{ "version": "2026-08-25", "config": { "endpoint": "https://store.example/buy" } }]
    }
  }
}
```

5. **Verify** by opening the permalink with a real variant ID. It should land on checkout with that item in the cart.

## How to fix it on Medusa

Permalinks are not built into Medusa. Build one as a storefront route that:

1. Parses the line items from the path.
2. Creates a cart and adds the line items through the [Store API](https://docs.medusajs.com/api/store). Every `/store/*` request needs the `x-publishable-api-key` header.
3. Redirects with `303` to the storefront's checkout page.

Then declare the route in your UCP profile. See the [Medusa agent-readiness guide](https://is-agentic-storefront.com/guides/medusa-agent-readiness).

## Sources

- [UCP permalink specification](https://ucp.dev/2026-08-25/specification/permalink/)
- [UCP checkout specification (`continue_url`)](https://ucp.dev/2026-08-25/specification/shopping/checkout/)
- [OpenAI shifts checkout plans (Digital Commerce 360)](https://www.digitalcommerce360.com/2026/03/06/openai-shifts-checkout-plans-agentic-commerce-strategy/)
- [Medusa Store API reference](https://docs.medusajs.com/api/store)

## Frequently asked questions

### What is a cart permalink?

A GET URL that encodes line items, such as /buy/variant_123:2, and redirects to a checkout pre-filled with those items. Agents can generate it without calling an API.

### What is the UCP permalink format?

The UCP permalink spec uses {endpoint}/{item}:{qty},{item}:{qty}, with optional query parameters such as discount codes and buyer email, and a 303 redirect to checkout. The endpoint is declared in the dev.ucp.shopping.permalink capability.

### Why do built-in platform cart links only get partial credit?

They work, but agents have to know each platform's URL pattern. Declaring a permalink endpoint in a UCP profile makes it discoverable, which earns a full pass.

## Run your store on a platform built for agentic commerce

Medusa is open-source, headless commerce with a full Store API agents can call and storefronts you control end to end.

### Deploy on Medusa Cloud

Open-source commerce with a full Store API, hosted and scaled for you. Your storefront, your data model.

- [Deploy on Medusa Cloud](https://cloud.medusajs.com?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Fcheckout-permalinks)
- [Medusa Cloud docs](https://docs.medusajs.com/cloud?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Fcheckout-permalinks)

### Storefront skills for coding agents

Teach Claude Code, Cursor or Codex to build storefronts with the patterns these checks look for.

```bash
npx skills add medusajs/medusa-agent-skills
```

[View the skill on GitHub](https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/ecommerce-storefront/skills/storefront-best-practices)

---

Scan your store for free at https://is-agentic-storefront.com/