Create hosted checkout from an application

Call the live Orderboost API from browser or server code and open the returned hosted checkout.

Use the public HTTPS API to create hosted buyer checkout. Orderboost does not currently publish a JavaScript, React, or widget package to npm.

Confirm merchant access

Orderboost resolves products only for merchants whose catalog and canonical storefront origin are already registered. Merchant onboarding is currently coordinated by Orderboost rather than exposed as a self-service API.

Use this production API origin:

https://capi.orderboost.org

The public catalog and buyer-checkout routes do not require merchant credentials or agent OAuth. Do not expose any separately issued merchant backend credentials in browser code.

Create checkout from a product URL

Open a blank popup during the buyer’s click, then create checkout and navigate that popup to the returned URL:

const ORDERBOOST_API = "https://capi.orderboost.org";

type BuyerCheckoutResult = {
	checkoutUrl: string;
	status: { endpoint: string; token: string };
};

export async function openOrderboostCheckout(productUrl: string) {
	const popup = window.open("about:blank", "orderboost-checkout", "popup,width=680,height=800");
	if (!popup) throw new Error("Pop-ups are blocked.");

	const response = await fetch(`${ORDERBOOST_API}/api/v1/buyer-checkouts`, {
		body: JSON.stringify({ productUrl, quantity: 1 }),
		credentials: "omit",
		headers: { "content-type": "application/json" },
		method: "POST",
		referrerPolicy: "no-referrer",
	});

	if (!response.ok) {
		popup.close();
		throw new Error(`Checkout preparation failed (${response.status}).`);
	}

	const result = (await response.json()) as BuyerCheckoutResult;
	popup.location.replace(result.checkoutUrl);
	return result;
}

Send the canonical product URL, quantity, and only option labels missing from the URL. Do not send a browser-calculated price. Orderboost resolves the merchant and variant, then requotes price and availability before returning checkout.

The checked-in reference storefront provides a live catalog example:

https://store.orderboost.org/product/acme-mug

Create checkout from a cart

Send items instead of productUrl for a multi-item checkout:

const response = await fetch("https://capi.orderboost.org/api/v1/buyer-checkouts", {
	body: JSON.stringify({
		items: cart.lines.map((line) => ({
			productUrl: line.productUrl,
			quantity: line.quantity,
			selected: line.selected,
		})),
	}),
	headers: { "content-type": "application/json" },
	method: "POST",
});

Every item must resolve to the same registered merchant. Open the returned checkoutUrl; the hosted page owns buyer input, payment, and order completion.

Create a stable Buy Now link

Use the public /buy route when an email, message, anchor, or QR code should contain product intent instead of a checkout capability:

const productUrl = "https://store.orderboost.org/product/acme-mug";
const href = new URL("/buy", "https://capi.orderboost.org");
href.searchParams.set("product", productUrl);

GET /buy does not create checkout. The buyer’s browser submits the page to create a fresh authoritative checkout.

Read terminal order status

Buyer-checkout creation also returns status.endpoint and status.token. Keep the token private to the calling application and send it only to the returned endpoint:

const response = await fetch(result.status.endpoint, {
	headers: { authorization: `Bearer ${result.status.token}` },
});
const status = (await response.json()) as
	{ status: "pending" | "canceled" | "expired" } | { status: "completed"; orderId: string };

The status token cannot read or mutate checkout details. Report success only after receiving status: "completed" and a persisted orderId.

Treat optional payment protocols as advertised capabilities

If the buyer-checkout response includes mpp.endpoint, a Tempo wallet may pay that exact hosted checkout through the documented MPP flow. If mpp is absent, open checkoutUrl for the buyer.

Orderboost does not expose a built-in x402 checkout endpoint. Do not construct one from the API origin.

Validate the integration

• Use a canonical product URL on a registered merchant origin
• Open checkout only from the exact checkoutUrl returned by Orderboost
• Keep checkout URL fragments and status tokens out of logs and analytics
• Treat Orderboost’s returned line items and totals as authoritative
• Require a persisted orderId before reporting completion

Browse the HTTP API reference for the current request and response schemas.