Skip to main content

Checkout Kit for Web

Early access

Agentic commerce is rolling out to Dev Dashboard. Sign up to be notified.

The <shopify-checkout> web component embeds Shopify Checkout in web apps. Buyers complete their purchase without leaving your site. By default, checkout opens in a new tab. Authenticated embedders can render checkout inline, customize branding, and configure features like tipping and analytics.

Anchor to What you'll learnWhat you'll learn

In this guide, you'll learn how to do the following tasks:

  • Add the Checkout Kit script to your page
  • Present checkout using a checkout URL
  • Configure checkout behavior with attributes
  • Listen for checkout events

Anchor to RequirementsRequirements

  • A valid Shopify checkout URL (from the Storefront API cart.checkoutUrl field or a cart permalink)
  • For authenticated checkouts: client_id and client_secret provided by Shopify

Anchor to Step 1: Add the Checkout Kit scriptStep 1: Add the Checkout Kit script

Include the script from the Shopify CDN in your HTML:

Info

This CDN URL is a preview for development purposes only.

HTML

<script
type="module"
src="https://cdn.shopify.com/shopifycloud/checkout-web/component/unstable/kit.js"
></script>

Alternatively, import the @shopify/checkout-kit npm package:

JavaScript

import {Checkout} from '@shopify/checkout-kit';

customElements.define('shopify-checkout', Checkout);

Anchor to Step 2: Add the checkout elementStep 2: Add the checkout element

Add a <shopify-checkout> element to your HTML. Use the checkout URL as the href for an anchor element to provide a fallback if JavaScript is disabled:

HTML

<shopify-checkout></shopify-checkout>

<a id="checkout-button" target="_blank" href="https://yourshop.myshopify.com/cart/12345:1">
Checkout
</a>

Anchor to Step 3: Present checkoutStep 3: Present checkout

Set the src attribute to a checkout URL and call open() to present checkout:

JavaScript

const checkout = document.querySelector("shopify-checkout");
const checkoutButton = document.querySelector("#checkout-button");

checkoutButton.addEventListener("click", (event) => {
event.preventDefault();
checkout.src = checkoutButton.href;
checkout.open();
});

Anchor to Step 4: Listen for eventsStep 4: Listen for events

The <shopify-checkout> component dispatches DOM events at key points in the checkout lifecycle. The following example listens for the checkout:complete event:

JavaScript

const checkout = document.querySelector("shopify-checkout");

checkout.addEventListener("checkout:complete", (event) => {
const { orderConfirmation } = event.target;
console.log("Order completed:", orderConfirmation);
});

checkout.addEventListener("checkout:close", () => {
console.log("Checkout closed");
});

Anchor to ConfigurationConfiguration

Configure the <shopify-checkout> element using attributes.

Anchor to [object Object]src

Required. The checkout URL from the Storefront API or a cart permalink.

HTML

<shopify-checkout src="https://yourshop.myshopify.com/cart/c/abc123"></shopify-checkout>

Anchor to [object Object]target

Controls where checkout renders. Valid values:

  • auto (default): Opens checkout in a new tab.
  • popup: Opens checkout in a popup window.
  • inline: Renders checkout inline when the element connects to the DOM. You must provide a list of valid pages where you intend to embed checkout so that we can set the frame-ancestors value in the Content-Security-Policy response header.

JavaScript

// Open in popup
checkout.setAttribute("target", "popup");
checkout.open();

// Or render inline (renders immediately, open() has no effect)
checkout.setAttribute("target", "inline");

Anchor to [object Object]auth

The JWT that authenticates checkout. Required for inline embedding and configuration overrides.

HTML

<shopify-checkout src="https://..." auth="eyJhbGciOiJIUz..."></shopify-checkout>

Anchor to MethodsMethods

The <shopify-checkout> element exposes the following methods:

  • open(): Presents checkout in the configured target. Has no effect when target is inline.
  • close(): Closes checkout and its overlay. Has no effect when target is inline.
  • focus(): Brings checkout to the foreground. Has no effect when target is inline.

Anchor to EventsEvents

Anchor to [object Object]checkout:start

Emitted when checkout starts and is visible:

JavaScript

checkout.addEventListener("checkout:start", (event) => {
console.log("Checkout started, locale:", event.target.locale);
});

Anchor to [object Object]checkout:close

Emitted when the buyer closes checkout without completing payment:

JavaScript

checkout.addEventListener("checkout:close", () => {
console.log("Checkout closed");
});

Anchor to [object Object]checkout:complete

Emitted when checkout completes successfully, immediately after payment processing. The orderConfirmation property contains order details:

JavaScript

checkout.addEventListener("checkout:complete", (event) => {
const order = event.target.orderConfirmation.order;
console.log("Order " + order.id + " was completed");
});

Anchor to [object Object]checkout:error

Emitted when errors occur during checkout:

JavaScript

checkout.addEventListener("checkout:error", (event) => {
const error = event.error;
console.error("Error " + error.code + " was encountered");
});

Anchor to AuthenticationAuthentication

By default, anyone can use <shopify-checkout> without authentication. However, to embed checkout inline or apply configuration overrides, you need to authenticate using a JWT.

Caution

Never expose your client_id or client_secret in client-side code. Token generation must occur server-side.

Anchor to Generate a tokenGenerate a token

Create a secure server endpoint that generates tokens:

curl

curl -X POST "https://api.shopify.com/auth/access_token" \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"grant_type": "client_credentials"
}'

Tokens have a 60-minute time-to-live (TTL) and can be cached for that duration.

Anchor to Use the tokenUse the token

Fetch the token from your backend and pass it to the component's auth attribute:

JavaScript

async function presentAuthenticatedCheckout() {
const auth = await fetch("/api/checkout/auth", {
method: "POST",
body: JSON.stringify({ cartId: cart.id }),
}).then(res => res.text());

const checkout = document.querySelector("shopify-checkout");
checkout.src = checkoutUrl;
checkout.auth = auth;
checkout.open();
}

For details on configuring checkout features like branding, tipping, and analytics, refer to Authenticate checkouts.

Was this page helpful?