Skip to main content
Shopify merchants have three paths to UCP: native Shopify UCP settings (fastest, if available on your plan), a custom manifest backed by Checkout Kit and the Storefront API (full control), or a headless Shopify setup where your own frontend domain hosts the manifest. This guide covers all three so you can choose based on your stack.
Native UCP availability varies by Shopify plan and region. If you don’t see an AI Commerce or Universal Commerce Protocol option in your Shopify Admin, use Option 2 (Checkout Kit) below.

​
Option 1: Native Shopify UCP

If UCP is available on your plan, this is the fastest path to going live:
1

Open checkout settings

In your Shopify Admin, go to Settings → Checkout.
2

Enable UCP

Look for the AI Commerce or Universal Commerce Protocol section. Toggle UCP on and follow the setup wizard.
3

Verify endpoints

Shopify will automatically expose your product catalog and checkout endpoints. Confirm your store is working by running:
curl https://yourshop.com/.well-known/ucp
Then run the Readiness Score to verify full UCP compliance.

​
Option 2: Custom manifest via Checkout Kit

Use this path if native UCP is unavailable or you need custom control over your catalog and checkout logic.
1

Generate your manifest

Use the Manifest Generator or create the file manually:
/.well-known/ucp
{
  "version": "1.0",
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourshop.myshopify.com/api/ucp/products"
    },
    "checkout": {
      "endpoint": "https://yourshop.myshopify.com/api/ucp/checkout"
    }
  }
}
2

Host the manifest

Shopify does not allow arbitrary files at the domain root, so you need to serve /.well-known/ucp through a Shopify app route or a custom domain proxy.
Add a route handler to your Shopify app (Remix-based apps are common):
routes/well-known.ucp.js
export async function loader({ request }) {
  return new Response(JSON.stringify({
    version: "1.0",
    capabilities: {
      product_catalog: {
        endpoint: `${process.env.SHOP_URL}/api/ucp/products`
      },
      checkout: {
        endpoint: `${process.env.SHOP_URL}/api/ucp/checkout`
      }
    }
  }), {
    headers: { "Content-Type": "application/json" }
  })
}
3

Build your catalog endpoint using the Storefront API

Query Shopify’s Storefront API and transform the response to UCP format:
// GET /api/ucp/products
const { products } = await shopify.storefront.query(`
  query UCPProducts($first: Int!) {
    products(first: $first) {
      nodes {
        id
        title
        description
        priceRange { minVariantPrice { amount currencyCode } }
        variants(first: 100) {
          nodes {
            id
            title
            selectedOptions { name value }
            price { amount currencyCode }
            availableForSale
          }
        }
      }
    }
  }
`, { variables: { first: 100 } })

// Transform to UCP format
return products.nodes.map(p => ({
  id: p.id,
  name: p.title,
  description: p.description,
  price: {
    amount: Math.round(parseFloat(p.priceRange.minVariantPrice.amount) * 100),
    currency: p.priceRange.minVariantPrice.currencyCode
  },
  availability: 'in_stock',
  variants: p.variants.nodes.map(v => ({
    id: v.id,
    attributes: Object.fromEntries(
      v.selectedOptions.map(o => [o.name.toLowerCase(), o.value])
    ),
    price: {
      amount: Math.round(parseFloat(v.price.amount) * 100),
      currency: v.price.currencyCode
    },
    availability: v.availableForSale ? 'in_stock' : 'out_of_stock'
  }))
}))
Shopify’s Storefront API returns prices as decimal strings (e.g. "129.99"). Multiply by 100 and round to an integer before returning them in UCP format — agents expect prices in the smallest currency unit (cents).
4

Build your checkout endpoint using Shopify Checkout Kit

Use Shopify’s cartCreate mutation to back your UCP checkout endpoint:
// POST /api/ucp/checkout
const checkout = await shopify.storefront.mutate(`
  mutation CartCreate($input: CartInput!) {
    cartCreate(input: $input) {
      cart {
        id
        checkoutUrl
        cost { totalAmount { amount currencyCode } }
        deliveryGroups {
          deliveryOptions {
            title
            estimatedCost { amount currencyCode }
          }
        }
      }
    }
  }
`, { variables: { input: { lines: cartItems } } })
Map the Shopify cart response to UCP checkout format, including the checkout_id, subtotal, shipping_options, and expires_at.
5

Validate your setup

Run the Asva readiness audit to confirm everything is correctly wired:
# Verify the manifest
curl https://yourshop.com/.well-known/ucp

# Run the full readiness audit
curl -X POST https://asva-ai.com/api/audit \
  -H "Authorization: Bearer $ASVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourshop.com"}'
Or use the browser tool: asva-ai.com/tools/readiness

​
Option 3: Headless Shopify

If you run a headless setup (Next.js + Shopify Hydrogen, or a similar combination), your own frontend domain hosts the /.well-known/ucp file. Follow the UCP getting started guide for endpoint setup, and use the Shopify Storefront API to back your catalog and checkout endpoints as shown in the Checkout Kit steps above.

​
Common issues

Native UCP is rolling out progressively by plan and region. If it is not visible in Settings → Checkout, use the Checkout Kit path (Option 2) above. Native availability is expected to expand in future Shopify releases.
Shopify blocks unknown paths at the domain root. You must serve the manifest via a Shopify app route or a Cloudflare Worker — you cannot place a static file at /.well-known/ucp directly in Shopify’s file system. See Step 2 above for both options.
Shopify returns prices as decimal strings ("1.29"). If you pass this directly as amount, the agent interprets it as 1.29 cents. Always multiply by 100 and round to an integer: Math.round(parseFloat("129.99") * 100) → 12999.
The Storefront API field availableForSale reflects combined variant availability. Map it directly: v.availableForSale ? 'in_stock' : 'out_of_stock'. For real-time inventory counts, use the Admin API instead.

UCP getting started

Full quickstart for UCP on any stack.

Google Merchant Center

UCP implementation via Merchant Center for Google AI Mode.

Checkout and payments

Checkout flow, payment token handling, and error responses.

UCP capability discovery

Hosting and validating your /.well-known/ucp manifest.