Developer Changelog / UCP & Checkout

Cart/checkout permalinks now support UCP
/buy: a new route that takes buyers from add-to-cart through pre-filled details to checkout with a single link

As of UCP 2026-08-25, Shopify storefronts support the dev.ucp.shopping.permalink capability./buy links use the same format on any UCP-compatible store. Existing /cart links continue to work.

On this page
  1. What's changing (30-second overview)
  2. How it works: from creating a link to the buyer landing
  3. Anatomy of a /buy link
  4. What you can do with /buy links
  5. /buy vs. /cart
  6. How to migrate (3 steps)
  7. 5 key points for developers
  8. 3 practical use cases
  9. One-line summary for proposals

1What's changing

Shopify storefronts now have a new route: /buy . It supports the UCP (2026-08-25 and later) dev.ucp.shopping.permalink capability.
With a single link, you can add products to the cart, pre-fill checkout details, and send buyers to checkoutall in one go, andit uses the same format on any UCP-compatible store.
/cart

Before: /cart permalinks

Now treated as the "legacy format." Still supported and working, but no new features will be added.

/buy

Going forward: /buy permalinks

The UCP standard format. New features are added only to /buy. One shared format across UCP-compatible stores.

Existing integrations need no changesand will keep working. You can migrate at your own pace.

2How it works: from creating a link to the buyer landing

Discovery /.well-known/ucp permalink capability is listed ① Store profile config.endpoint The store's /buy route points to ② Read this Build the /buy link Path: token:quantity Query: UCP field paths ③ Share & place Buyer clicks Applied → Checkout Can't be applied continue_to present → Go to that destination Not present → Go to the storefront No error page is shown in either case
Don't build /buy URLs by hand.From the store's discovery profile (/.well-known/ucp), read config.endpoint and build your link from it. This is the official recommendation.

3Structure of a /buy link

{config.endpoint} /token:quantity... ?buyer/email=...&discounts/codes/0=... The store's /buy route Obtained from discovery Path: products Written as token:quantity pairs Query: cart and checkout fields Parameter name = UCP field path * Conceptual diagram. For exact formatting such as delimiters, see the "UCP permalink specification"
Path

Products as token:quantity pairs

Add one or more products by variant ID. The post doesn't say exactly which ID format the token uses (see the specification).

Query

Parameter names are UCP field paths

Examples given include buyer/email,discounts/codes/0 . The post doesn't give the parameter names for other fields (country, language, Shop Pay, etc.).

4What you can do with /buy links

Add products to the cart

Specify one or more items by variant ID.

Prefill buyer information

Prefill buyer details such as email address.

Set country and language

Set the buyer's country and language.

Apply discount codes

Example: discounts/codes/0 — specified with a field path like this.

Shop Pay

Indicate a Shop Pay preference

Links can signal that the buyer prefers Shop Pay.

Send to a specific page

continue_to parameter sends buyers to a specific page in the store.

5/buy vs. /cart

Item/cart (legacy)/buy(UCP)
Status Legacy format Still supported Recommended Use for new links
New features Not added Added to /buy only
Cross-store compatibility Not specified Shared Same format on any UCP-enabled store
Selling plans Supported Not supported
Line item properties Supported Not supported
Cart notes / cart attributes Supported Not supported
When it can't be applied Not specified continue_to destination first, otherwise redirects to the storefront (no error page)
Subscriptions (selling plans), line item properties, cart notes, or cart attributes: if you rely on any of these, keep using /cart for now. There's no word yet on when /buy will support them.

6Migration in 3 steps

1

Inventory your existing /cart links

Keep links that use selling plans, line item properties, cart notes, or cart attributes on /cart.

2
endpoint

Build links from config.endpoint

Create new links with /buy. Don't assemble URLs by hand; read the values from the discovery profile.

3

Move what you can to /buy

/cart keeps working, so you can migrate gradually on your own schedule.

There's no need to switch everything at once.Start by using /buy for new links , and your existing flows keep running.

75 key points for developers

.well-known

1. Don't hardcode URLs

/.well-known/ucp discovery profile: read dev.ucp.shopping.permalink 's config.endpoint and build your links from it./buy should never be hardcoded.

2. No capability negotiation needed

Permalinks don't use negotiation, so you don't need to declare dev.ucp.shopping.permalink in your agent profile.

a/b/0

3. Query names are UCP field paths

buyer/email,discounts/codes/0 : specify them as slash-separated paths like this, with array items referenced by index. Products are handled separately, in the path's token:quantity segment.

4. Failures redirect instead of showing an error page

Links that can't be applied redirect to the continue_to destination, or to the storefront if none is set. Buyers never see a broken page, butit's easy to miss that a link failed to apply, so keep that in mind.

5. Never put sensitive data in links

Never include payment details or access tokens in a link.For widely shared links (social media, newsletters, ads, etc.), also leave out buyer personal data such as email addresses.

83 practical use cases

USE CASE 1

Generating purchase links that work the same on any store, from AI agents and external channels

Challenge
Agents and comparison services that send shoppers to multiple stores build and maintain separate cart-link logic for each store.
Approach
From each store's /.well-known/ucp , retrieve config.endpoint , and consolidate into a single implementation that generates /buy links in a common format.
Impact
The same logic works for any UCP-enabled store, reducing per-store branching and letting you send buyers straight to checkout.
Technical notes
No capability negotiation is required, so you don't need to declare permalinks in the agent profile. Links must not contain payment details or tokens.
USE CASE 2

Send newsletter and LINE subscribers straight to a cart with the discount code already applied

Challenge
Even when a campaign hands out coupons, buyers drop off partway through adding items to the cart or entering the code.
Approach
In the /buy link, include the target products (token:quantity) and discounts/codes/0 , set the country, language, and Shop Pay preference, then send it out.
Impact
A single click adds the products, applies the code, and takes buyers to checkout, which reduces drop-off along the way.
Technical notes
Don't put buyer/email or other personal information in broadcast links. In case the discount can't be applied, usecontinue_to to send buyers back to the campaign landing page.
/cart /buy
USE CASE 3

Audit existing store permalinks and migrate in stages

Challenge
/cart links are scattered across ads, QR codes, social media, blogs, and more, so they won't benefit from upcoming features.
Approach
List all links, then switch to /buy starting with those that don't use selling plans, line item properties, cart notes, or cart attributes. Keep the ones that do on /cart.
Impact
You can shift toward /buy, where new features are added, without disrupting existing customer journeys.
Technical notes
Stores that sell subscriptions (selling plans) currently still need /cart. Hard-to-replace media such as printed QR codes keep working on /cart, so there's no rush.

9One-line summary for proposals

"With a single link, buyers get products added, details prefilled, and discounts applied, then go straight to checkout — a UCP common-format /buy permalink.
Use /buy for new links, and stay on /cart for now where subscriptions or cart attributes are needed; existing links keep working, so you can migrate at your own pace."