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,
			selectedOptions: ['Black', '10'],
		},
	],
});

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`
`selectedOptions`	`string[]`	One value per product option, in order, e.g. `['Black', '10']`. Spell each value as the store does, or a different variant can be bought
`selectedShipping`	`{ 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,
		selectedOptions: ['Black', '10'],
		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';
}

`prefill` `object`

Optional. Pre-fills the buyer’s details in checkout. All prefill.address fields are optional strings: firstName, lastName, email, line1, line2, city, province, postalCode, countryCode, and phone (E.164, e.g. +15555555555).

prefill: {
	address: {
		firstName: 'Jane',
		lastName: 'Doe',
		email: 'jane@example.com',
		line1: '123 Main St',
		city: 'San Francisco',
		province: 'CA',
		postalCode: '94105',
		countryCode: 'US',
	},
}

`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"`	Deprecated, ignored. Phone is always required

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.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 places the order. The purchase itself settles afterwards — read order.status, or use webhooks, for the outcome.

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

Field	Type	Description
`status`	`"success" \| "failure"`	Currently always `"success"`: the order was placed
`order`	`Order`	The order object

`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 Henry from '@henrylabs/js';

type CheckoutOptions = Parameters<typeof Henry.createCheckoutElement>[1];
type CartItem = CheckoutOptions['items'][number];

const items: CartItem[] = [{ link: 'https://www.nike.com/t/air-max-270/AH8050-002', quantity: 1 }];

const options: CheckoutOptions = {
	widgetId: 'widget_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
	items,
	display: { size: 'compact', theme: 'dark' },
};

React

Create the widget in an effect and destroy it in the cleanup. This also handles Strict Mode’s double mount:

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

function BuyNow({ productUrl }: { productUrl: string }) {
	useEffect(() => {
		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`

`prefill` `object`

`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

​prefill object

​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`

`prefill` `object`

`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