_catalog.json generator and validator

How to add checkout to a static site

Three steps, no shop platform and no embedded widget. The catalogue is a file you deploy; the checkout is a POST from your own domain.

1. List your products. One per line above: sku, name and price are required, and an image path, a description and a billing interval are optional. Or paste a catalogue you already have and the panel validates it instead of generating one.
2. Deploy the file at the site root. Download the generated _catalog.json, put it beside your index.html, and deploy. A bad catalogue is refused at deploy time rather than at checkout, so a broken price cannot reach a customer.
3. Paste the markup into the page that sells. One button per SKU carrying data-clize-add, a checkout button, a cart counter, and the cart script. The browser sends only SKUs and quantities; the server prices the basket from the deployed file.

Why the price must not live in your HTML

Almost every walkthrough for putting a payment button on a static site ends at the same place: an amount written into the page, a little JavaScript that posts it to an endpoint, and an endpoint that creates a checkout session for whatever amount it received. It works on the first try, which is the problem — a tampered payment succeeds exactly as smoothly as a real one, and nothing in your logs looks unusual afterwards.

The rule underneath is short. The browser may say what is being bought. It must never say how much it costs. Anything reachable from the page — a data attribute, a hidden input, a JSON blob fetched at load, a value in localStorage — is editable in ten seconds by anyone with developer tools open, and no amount of minification changes that. Prices have to be resolved on the server, from a source the customer cannot reach.

This is also why the hosted options that do work, work. A Stripe Payment Link or Buy Button is safe because the price lives in Stripe's account, not in your markup; the page only carries an identifier. The unsafe version is the do-it-yourself middle ground, where your own function accepts an amount and trusts it.

A Clize-hosted site takes the same shape, with the catalogue as the trusted source. The page posts { items: [{ sku, quantity }] } to /_clize/checkout on your own domain. The server loads the _catalog.json that was deployed with the site, looks up each SKU, and builds the Stripe Checkout line items from the catalogue price. An unknown SKU fails the order. A non-positive price fails the order. Quantities are clamped to a sane range. The number the browser sent, if it sent one at all, never enters the calculation.

One consequence worth planning for rather than discovering: because the price lives in a deployed file, changing a price is a deploy, not an edit. That is a real trade against a dashboard you can click in, and it buys you a catalogue that is diffable, reviewable and in version control next to the page it prices.

The catalogue contract, field by field

_catalog.json is a small object with an optional currency, optional shipping countries, and an array of products. Nothing else is read, and unknown keys are ignored rather than rejected — so you can annotate the file for your own tooling if you want.

Two honest caveats, both of which the panel raises as warnings rather than burying in a footnote. Subscriptions need the direct payout mode, where charges settle into a merchant's own connected Stripe account — and that mode is not switched on at the platform level, so a checkout containing a product with an interval comes back with an explicit error instead of quietly charging once. Subscriptions and one-off products also cannot share a basket, because Stripe Checkout will not mix the two modes in one session; a mixed cart is refused rather than split.

The same contract is printed by the CLI if you would rather read it from the tool that consumes it:

$ clize shop init

It returns the catalogue shape, the markup and the next steps for the store bound to the current project.

Wiring it to checkout

Three attributes and one script, and there is no cart library to choose:

<button data-clize-add="tee-blk-m">Add to cart</button>
<button data-clize-add="poster-a2" data-clize-qty="2">Add two posters</button>

<button data-clize-checkout>Checkout</button>
<span data-clize-count></span>

<script src="/_clize/cart.js"></script>

The script is served from your own domain, keeps the basket in localStorage, and delegates clicks, so buttons rendered after page load still work. It also exposes window.clizeCart with add, checkout, count and clear, which is what you want if your page is built by a framework rather than by hand. Pressing checkout posts the basket to /_clize/checkout — same origin, so no CORS, no preflight and no third-party script in your page — and the response carries the Stripe Checkout URL the browser then goes to.

The failures you will actually meet, and what each one means:

• No catalogue deployed. The site has no _catalog.json at its root yet. Deploy the file, not just the page.
• Unknown SKU. The button says something the catalogue does not contain — usually a rename that shipped in the HTML but not in the file.
• Mixed basket. A subscription and a one-off product in the same order. Split them into two checkouts.
• Too many distinct items. One basket carries at most fifty different products; quantities are unlimited within a per-line ceiling.
• Invalid order amount. The total came out at zero or above the order cap, which almost always means a price got mangled on the way in.

None of these should reach a customer, because a malformed catalogue is rejected when you deploy rather than when somebody tries to buy. That is the point of validating the file before it ships — and the reason this page exists as a validator and not only as a generator. When you want to exercise the checkout itself afterwards, the Stripe test card table has the numbers for every decline, dispute and 3D Secure branch.

What the validator flags — and what it cannot know

Errors are the things that stop the file being deployed or stop a basket becoming an order. Warnings are things that are legal and still likely to bite you.

What it deliberately does not do: it never fetches your site, so it cannot tell you whether the file is actually deployed or whether an image path resolves. It does not know your stock — there is no inventory field and no stock count anywhere in this product, so overselling is possible and refunding is the remedy. It does not calculate tax. And it will not invent a SKU for a product you forgot; if a row is missing, the file is quietly, validly wrong, and only you can see that.

What happens after they pay

The catalogue is the front half. The back half is an order that has to be sourced, shipped and explained to a customer, and it is worth knowing it exists before you commit to an approach.

On a Clize-hosted store, a paid checkout becomes an order the platform keeps: line items with their SKUs and the prices they were charged at, the delivery address if you asked for one, and a status that only Stripe's webhook can move to paid. From there clize shop todo lists what needs doing today, clize shop fulfill --tracking records a shipment and registers it with a tracking service, and every site serves a buyer-facing lookup at /orders that answers "where is my order" without an email to you.

Two things there are gated on purpose: refunding and emailing a customer both return a preview first and need an explicit confirmation flag, which matters most when the thing running the commands is an agent rather than a person. The Agent Storefront overview covers the loop end to end, and if the site itself is not built yet, hosted deploys are the other half of the same product.

$ npm i -g @clize/clize && clize login
$ clize deploy --handle yourshop
$ clize shop init