shopify-ucp-next

server-only toolkit for using shopify's ucp-compliant mcp tools from next.js (app router).

install

bun add shopify-ucp-next

usage

create the client

import { createShopifyUcpClient } from 'shopify-ucp-next';

const client = createShopifyUcpClient({
	clientId: process.env.SHOPIFY_MCP_CLIENT_ID!,
	clientSecret: process.env.SHOPIFY_MCP_CLIENT_SECRET!,
	platformProfileUrl: 'https://your.app/.well-known/ucp',
});

well-known ucp profile route

import { createUcpWellKnownRoute } from 'shopify-ucp-next';

export const GET = createUcpWellKnownRoute({
	platformProfileUrl: 'https://your.app/.well-known/ucp',
	platformId: 'your-app',
	platformName: 'your app',
});

catalog routes

import { createCatalogSearchRoute } from 'shopify-ucp-next';

export const POST = createCatalogSearchRoute(client);

checkout routes

import { createCheckoutRoutes } from 'shopify-ucp-next';

export const { create, status, update, complete, cancel } =
	createCheckoutRoutes(client);

api surface

client

• createShopifyUcpClient(config)
• client.catalog.searchGlobalProducts(input)
• client.catalog.getGlobalProductDetails(input)
• client.checkout.createCheckout(input)
• client.checkout.getCheckout(input)
• client.checkout.updateCheckout(input)
• client.checkout.completeCheckout(input)
• client.checkout.cancelCheckout(input)

routes

• createUcpWellKnownRoute(config)
• createCatalogSearchRoute(client)
• createCatalogLookupRoute(client)
• createCheckoutCreateRoute(client)
• createCheckoutStatusRoute(client)
• createCheckoutUpdateRoute(client)
• createCheckoutCompleteRoute(client)
• createCheckoutCancelRoute(client)
• createCheckoutRoutes(client)

notes

• this package is server-only. do not import from client components.
• catalog route responses include Cache-Control: no-store.
• completeCheckout and cancelCheckout require idempotencyKey.