Checkout Widget

The Checkout Widget renders a buy-now button directly in your page. When clicked, it opens Henry’s hosted checkout modal where the buyer completes payment, address, and order confirmation. Henry handles everything - you supply the product links and listen for events.

Usage

import Henry from '@henrylabs/js';

const el = Henry.createCheckoutElement('#checkout-container', {
	widgetId: 'widget_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
	items: [
		{
			link: 'https://www.nike.com/t/air-max-270/AH8050-002',
			quantity: 1,
			variant: { size: '10', color: 'Black' },
		},
	],
});

Add a container in your HTML:

<div id="checkout-container"></div>

Options

`widgetId` `string` `*required`

Your Widget ID from the Henry Dashboard.

`items` `CartItem[]` `*required`

One or more products to include in the checkout. Each item requires a link (a direct product page URL) and optionally accepts:

Field	Type	Description
`link`	`string`	Direct product URL
`quantity`	`number`	Number of units. Defaults to `1`
`variant`	`string \| Record<string, unknown>`	Variant selection, e.g. `{ size: "10", color: "Black" }`
`shippingOption`	`{ id?: string; value?: string }`	Pre-select a shipping option
`coupons`	`string[]`	Coupon codes to apply
`metadata`	`Record<string, unknown>`	Arbitrary metadata passed through to orders

items: [
	{
		link: 'https://www.nike.com/t/air-max-270/AH8050-002',
		quantity: 2,
		variant: { size: '10', color: 'Black' },
		coupons: ['SAVE10'],
		metadata: { source: 'product-page' },
	},
];

`display` `object`

Controls how the widget is rendered.

`display.size`

Value	Description
`"full"`	Full-width button
`"comfortable"`	Standard-sized button with logo and label
`"compact"`	Smaller button, good for tight layouts
`"bubble"`	Floating circular button
`"direct"`	Opens the checkout iframe directly without a button trigger

display: {
	size: 'compact';
}

`display.theme`

Value	Description
`"light"`	Light color scheme
`"dark"`	Dark color scheme
`"system"`	Follows the user’s OS preference

display: {
	theme: 'system';
}

`settings` `CartSettings`

Optional settings that control checkout behavior, service fees, and event triggers.

`settings.options`

Field	Type	Description
`allowPartialPurchase`	`boolean`	Whether the buyer can remove items and check out with a subset
`collectBuyerEmail`	`"off" \| "required" \| "optional"`	Controls email collection
`collectBuyerAddress`	`"off" \| "required" \| "optional"`	Controls address collection
`collectBuyerPhone`	`"off" \| "required" \| "optional"`	Controls phone collection

settings: {
  options: {
    allowPartialPurchase: true,
    collectBuyerEmail: "required",
    collectBuyerAddress: "optional",
  },
}

`settings.serviceFeeFixed`

Add a fixed service fee to every checkout.

settings: {
  serviceFeeFixed: { value: 2.99, currency: "USD" },
}

`settings.serviceFeePercent`

Add a percentage-based service fee (0–100).

settings: {
  serviceFeePercent: 5,
}

`settings.events`

Fire webhooks or send emails on order state changes.

settings: {
  events: [
    {
      type: "order.purchase.full.complete",
      data: [{ type: "send_webhook", webhookUUID: "..." }],
    },
  ],
}

Events

Use .on() to subscribe to checkout events and .off() to remove a listener.

`checkout-complete`

Fires when the buyer successfully completes checkout.

el.on('checkout-complete', ({ status, order }) => {
	console.log('Status:', status);
	console.log('Order ID:', order?.id);
});

Field	Type	Description
`status`	`string`	Final order status
`order`	`Order \| undefined`	Order object if available

`checkout-closed`

Fires when the checkout modal closes, either by the buyer or programmatically.

el.on('checkout-closed', ({ source }) => {
	console.log('Closed by:', source); // "user" | "system"
});

Methods

`.on(event, callback)` → `this`

Subscribe to a checkout event. Returns the element instance for chaining.

el.on('checkout-complete', handler);

`.off(event, callback)` → `this`

Remove a previously registered listener.

el.off('checkout-complete', handler);

`.destroy()`

Unmount the widget and clean up all event listeners. Call this when navigating away or unmounting a component.

el.destroy();

TypeScript

import type { CartItem, CheckoutOptions } from '@henrylabs/js';

const options: CheckoutOptions = {
	widgetId: 'widget_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
	items: [{ link: 'https://www.nike.com/t/air-max-270/AH8050-002', quantity: 1 }],
	display: { size: 'compact', theme: 'dark' },
};

React

Use a ref guard to prevent double-mounting in Strict Mode:

import { useEffect, useRef } from 'react';
import Henry from '@henrylabs/js';

function BuyNow({ productUrl }: { productUrl: string }) {
	const initialized = useRef(false);

	useEffect(() => {
		if (initialized.current) return;
		initialized.current = true;

		const el = Henry.createCheckoutElement('#checkout-container', {
			widgetId: 'widget_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
			items: [{ link: productUrl, quantity: 1 }],
			display: { size: 'comfortable', theme: 'system' },
		});

		el.on('checkout-complete', ({ status, order }) => {
			console.log('Order placed:', order?.id, 'Status:', status);
		});

		return () => el.destroy();
	}, [productUrl]);

	return <div id='checkout-container' />;
}

Card Element

Embed a secure card input for custom payment flows

Server SDK - Checkout

Build headless checkout flows server-side

Getting Started

Widgets

Elements

Info

Usage

Options

`widgetId` `string` `*required`

`items` `CartItem[]` `*required`

`display` `object`

`display.size`

`display.theme`

`settings` `CartSettings`

`settings.options`

`settings.serviceFeeFixed`

`settings.serviceFeePercent`

`settings.events`

Events

`checkout-complete`

`checkout-closed`

Methods

`.on(event, callback)` → `this`

`.off(event, callback)` → `this`

`.destroy()`

TypeScript

React

Card Element

Server SDK - Checkout

​Usage

​Options

​widgetId string *required

​items CartItem[] *required

​display object

​display.size

​display.theme

​settings CartSettings

​settings.options

​settings.serviceFeeFixed

​settings.serviceFeePercent

​settings.events

​Events

​checkout-complete

​checkout-closed

​Methods

​.on(event, callback) → this

​.off(event, callback) → this

​.destroy()

​TypeScript

​React

​Related

Card Element

Server SDK - Checkout

Usage

Options

`widgetId` `string` `*required`

`items` `CartItem[]` `*required`

`display` `object`

`display.size`

`display.theme`

`settings` `CartSettings`

`settings.options`

`settings.serviceFeeFixed`

`settings.serviceFeePercent`

`settings.events`

Events

`checkout-complete`

`checkout-closed`

Methods

`.on(event, callback)` → `this`

`.off(event, callback)` → `this`

`.destroy()`

TypeScript

React

Related