Digital products

Build product pages, free and paid checkout, the buyer's download page and purchase library, and manage products and sales through the Operator API.

By Abi Tyas Tunggal and Jack Walsh

Build the routes a board needs to sell digital products: a product list, product pages with reviews, free claims and embedded Stripe checkout, the buyer's download page, and the signed-in buyer's purchases. The last section covers the Operator API for products, files, sales and webhooks.

Operators create products in the dashboard (Sell digital products) or through the Operator API. Your frontend only reads and sells them. Method signatures are in the products and purchases references.

Prerequisites

A shared board client from Install as package.
@stripe/stripe-js in the browser that mounts paid checkout.
A server-owned session for board.purchases.mine() (the purchases tab). Everything else works without one.

Routes

Route	Path helper	Calls
Product list	`BOARD_PATHS.products` (`/products`)	`board.products.list`
Product page	`productPath(slug)` (`/products/<slug>`)	`board.products.get`, `board.products.reviews`, `board.products.checkout`, `board.products.getCheckout`
Download page	`purchasePath(token)` (`/purchases/<token>`)	`board.purchases.*`
Buyer's purchases	`BOARD_PATHS.mePurchases` (`/me/purchases`)	`board.purchases.mine`

The helpers come from @cavuno/board/paths. Use the downloadUrl the API returns rather than building the download page path yourself: it already follows your board's route manifest. Show a Products item in the header only when board.products.list() returns at least one product.

List products

1// src/data/products.ts
2import { board } from '../lib/board';
3
4export async function loadProducts(query: {
5  q?: string;
6  price?: 'free' | 'paid';
7  cursor?: string;
8}) {
9  return board.products.list({ ...query, sort: 'featured', limit: 24 });
10}

Each card has name, summary, coverImageUrl, price, rating (null when ratings are off), soldOut and url, the product page path. Only listed products appear. Product lists and product pages are public and can be cached like jobs.

Render a product page

1// src/data/product-page.ts
2import { isNotFound } from '@cavuno/board';
3
4import { board } from '../lib/board';
5
6export async function loadProductPage(slug: string) {
7  try {
8    const product = await board.products.get(slug);
9    const reviews = product.ratingsEnabled
10      ? await board.products.reviews(slug, { limit: 10 })
11      : null;
12    return { product, reviews };
13  } catch (error) {
14    if (isNotFound(error)) return null; // Render your 404.
15    throw error;
16  }
17}

price.kind is free, fixed or pay_what_you_want. For pay what you want, amountCents is the minimum and suggestedCents the amount to prefill. contents lists each file's type, size and page count, and facts holds the counted totals (fileCount, linkCount, fileTypes, pageCount, totalSizeBytes). summary is the seller's one-line "you'll get" text and details the rows of the product's facts box: each row is { kind: 'text', label, value } or a yes/no row { kind: 'check', label, checked }. Render a check row as a tick when checked is true and a cross when it is false, with "Yes" or "No" as its accessible text. The buy button's text is your site's own copy, like the rest of its interface text: for example "Buy now", or "Get it free" when price.kind is free.

descriptionHtml is the seller's formatted description as sanitized HTML (headings, lists, quotes, dividers, links and images uploaded to the board); render it in your prose styles, and fall back to the plain-text description when it is null. salesCount is set only when the seller shows the number of sales; otherwise it is null.

A product with isListed: false is link-only: render the page for anyone with the link, but keep it out of your product list, sitemap and search index (noindex). An unknown slug, an archived product and a product with no ready file are all products_not_found (404).

Start a checkout

Collect the buyer's email and the answers to product.questions in your own form, then call checkout from your server. The same call handles free claims and paid products.

1// src/server/product-checkout.ts
2import type { ProductCheckoutBody } from '@cavuno/board';
3
4import { board } from '../lib/board';
5
6export async function startProductCheckout(
7  slug: string,
8  form: ProductCheckoutBody,
9) {
10  const result = await board.products.checkout(slug, {
11    email: form.email,
12    answers: form.answers, // [{ questionId, value }]
13    amountCents: form.amountCents, // pay what you want; omit to choose on Stripe's page
14    jobAlertOptIn: form.jobAlertOptIn, // free products, shown unticked
15    returnPath: `/products/${slug}`, // Stripe returns here with ?session_id=
16    website: form.website, // honeypot: render hidden, leave empty
17  });
18
19  if (result.status === 'complete') {
20    return { redirectTo: result.downloadUrl }; // free claim recorded
21  }
22  return { mount: result }; // paid: embedded Stripe Checkout mount kit
23}

status: 'complete' is a free claim (a free product, or amountCents: 0 on a pay-what-you-want product with a minimum of 0). Send the buyer to downloadUrl. They are also emailed the link.
status: 'open' is a paid checkout. Mount it in the browser with the kit's publishableKey, stripeAccountId and clientSecret. The session lasts 30 minutes.

Checkout questions are text (string answer), checkbox (boolean) or dropdown (one of options). Send one answer per question id; required questions must be answered.

When the request carries a signed-in board user's token, the purchase is also linked to that account.

Mount paid checkout

1// src/browser/mount-product-checkout.ts
2import type { ProductCheckout } from '@cavuno/board';
3import { loadStripe } from '@stripe/stripe-js';
4
5export async function mountProductCheckout(
6  kit: ProductCheckout,
7  selector: string,
8) {
9  if (!kit.publishableKey || !kit.clientSecret) {
10    throw new Error('Not a paid checkout');
11  }
12  const stripe = await loadStripe(kit.publishableKey, {
13    stripeAccount: kit.stripeAccountId ?? undefined,
14  });
15  if (!stripe) throw new Error('Stripe.js failed to load');
16
17  const checkout = await stripe.initEmbeddedCheckout({
18    clientSecret: kit.clientSecret,
19  });
20  checkout.mount(selector);
21  return () => checkout.destroy();
22}

Confirm a paid checkout

Stripe sends the buyer back to returnPath with session_id. Poll getCheckout for a few seconds: it reads awaiting_payment until the payment lands, then paid with downloadUrl.

1export async function waitForDownloadUrl(slug: string, sessionId: string) {
2  for (let attempt = 0; attempt < 10; attempt++) {
3    const status = await board.products.getCheckout(slug, sessionId, {
4      cache: 'no-store',
5    });
6    if (status.status === 'paid' && status.downloadUrl) {
7      return status.downloadUrl;
8    }
9    await new Promise((resolve) => setTimeout(resolve, 1000));
10  }
11  return null; // Show "We have emailed your download link".
12}

The purchase email goes out when the payment lands, so a buyer who closes the tab still gets their link.

Checkout errors

Code	Status	Show
`product_sold_out`	409	The product reached its sales limit.
`product_email_invalid`	400	Ask for a valid email.
`product_email_blocked`	403	This email cannot buy from the board.
`product_amount_below_minimum`	400	The amount is below `details.minimumCents`.
`product_amount_invalid`	400	The amount is not a whole number of cents, or is above the largest amount allowed.
`product_answers_invalid`	400	Point at `details.questionId`.
`stripe_not_connected`	409	The board cannot take payments yet.
`products_not_found`	404	Your 404.
`product_checkout_not_found`	404	`getCheckout` with an unknown session.
`rate_limited`	429	Wait `Retry-After` seconds.
`rate_limit_unavailable`	503	Try again shortly.

Build the download page

The download page lives at the downloadUrl path. Its token is the buyer's credential: never put it in a sitemap, analytics event or shared cache key, and render the page with noindex.

Pass the shared-link check

The buyer's first open of the link, and a request with the buyer's signed-in session, go straight through. Anyone else opening a forwarded link gets purchase_email_confirmation_required (403) and must type the purchase email.

When your frontend calls the API from its server, the API's own confirmation cookie never reaches the browser. Keep the confirmationToken the API returns in your own cookie for that purchase, and send it back on every call with the confirmationToken option, which sets the PURCHASE_CONFIRMATION_HEADER (X-Cavuno-Purchase-Confirmation) header.

1// src/server/download-page.ts
2import { isBoardApiError } from '@cavuno/board';
3
4import { board } from '../lib/board';
5
6export async function loadDownloadPage(
7  token: string,
8  confirmationToken: string | null, // from your cookie for this purchase
9) {
10  try {
11    const purchase = await board.purchases.get(token, {
12      confirmationToken,
13      cache: 'no-store',
14    });
15    // Store purchase.confirmationToken in your cookie when it is set.
16    return { kind: 'ready' as const, purchase };
17  } catch (error) {
18    if (isBoardApiError(error)) {
19      if (error.code === 'purchase_email_confirmation_required') {
20        return { kind: 'confirm-email' as const };
21      }
22      if (error.code === 'purchase_access_removed') {
23        return { kind: 'access-removed' as const };
24      }
25    }
26    throw error;
27  }
28}
29
30export async function confirmPurchaseEmail(token: string, email: string) {
31  const { confirmationToken } = await board.purchases.confirmEmail(token, {
32    email,
33  });
34  return confirmationToken; // Save it in your cookie, then reload the page.
35}

A wrong email is purchase_email_mismatch (403). Confirmation attempts are throttled per link.

Render files and downloads

purchase.files lists each file and link in the operator's order. A file has state (ready, preparing while the buyer's stamped PDF is made, limit_reached), downloadsLeft, sizeBytes, pageCount and stamped. A link has url; open it directly. The page also carries product, downloadCap, stamping (off, preparing, ready), receiptUrl (null for free claims), refundPolicy and the buyer's own review.

Downloads are POST requests that count one download each, so start them from a button, never on page load:

1export async function downloadFile(
2  token: string,
3  fileId: string,
4  confirmationToken: string | null,
5) {
6  const { url } = await board.purchases.download(token, fileId, {
7    confirmationToken,
8  });
9  return url; // Redirect the browser to it now: it is short-lived.
10}
11
12export async function downloadEverything(
13  token: string,
14  confirmationToken: string | null,
15) {
16  const zip = await board.purchases.downloadAll(token, { confirmationToken });
17  // zip.preparing and zip.limitReached list the file ids left out.
18  return zip.url;
19}

The signed url downloads as an attachment from private storage. It stays valid long enough for the file's size (10 minutes to 3 hours), so a slow connection can finish a large file. Download all streams one ZIP of every ready file and counts one download of each. Show its button only while the page's downloadAllAvailable is true: the ready files must total 500 MB or less, and above that the buyer downloads them one by one.

Code	Status	Meaning
`purchase_file_preparing`	409	The buyer's stamped copy is being made. Nothing was counted; the buyer is emailed when it is ready.
`purchase_download_limit_reached`	409	No downloads left for this file. Not a rate limit: do not retry. The board can reset the buyer's downloads.
`purchase_download_all_unavailable`	409, 503	409: the files total more than 500 MB. 503: the ZIP is not available right now. Either way nothing was counted; offer the files one by one.
`purchase_awaiting_payment`	409	The payment has not arrived yet.
`purchase_access_removed`	410	The board ended this buyer's access.
`purchase_unavailable`	410	The product can no longer be delivered.
`purchase_file_not_found`	404	The file id is not on this purchase.
`purchases_not_found`	404	Unknown token.

Purchase-token routes skip the board password and the board's plan checks: a buyer always reaches what they paid for.

Reviews

When purchase.ratingsEnabled is true, show a review form. One review per purchase: writing again replaces it.

1await board.purchases.review(
2  token,
3  { stars: 5, comment: 'Exactly what I needed', displayName: 'Ada' },
4  { confirmationToken },
5);

Omit displayName to stay anonymous. The result's counted says whether the stars count toward the rating. Ratings off is product_reviews_disabled (404), a refunded purchase is purchase_refunded (409), and invalid stars or a comment over 2,000 characters is purchase_review_invalid (400).

Resend the download link

"Already bought it? Get your download link" on the product page posts the email to resend. It always answers 202, so it never reveals whether that email bought anything.

1await board.purchases.resend({
2  email: 'ada@example.com',
3  productSlug: 'salary-guide', // omit to resend every purchase on the board
4  website: '', // honeypot
5});

Show the buyer's purchases

1export async function loadMyPurchases(accessToken: string) {
2  return board.purchases.mine({
3    cache: 'no-store',
4    headers: { authorization: `Bearer ${accessToken}` },
5  });
6}

It lists purchases made while signed in and purchases made with the user's verified email, each with its downloadUrl. Render it as a tab in your account area.

Manage products with the Operator API

The Operator API (https://api.cavuno.com/v1, API key) manages products, files and sales for automations and AI agents. Products are plans of purpose digital_product.

Task	Operation	Permission
Create a product	`POST /plans` with `purpose: "digital_product"`, `kind` (`free` or `one_time`) and `digitalProduct.pricing`	`plans.manage`
Edit product fields, list or unlist	`PATCH /plans/{id}` (`digitalProduct`, `isPublic`, `isArchived`)	`plans.manage`
List or read products	`GET /plans`, `GET /plans/{id}` (`digitalProduct` holds the fields)	`plans.read`
List files and links	`GET /plans/{id}/files`	`plans.read`
Upload a file	`POST /plans/{id}/files/uploads`, then `POST /plans/{id}/files/uploads/{uploadId}/complete`	`plans.manage`
Add a link	`POST /plans/{id}/files`	`plans.manage`
Rename, reorder, disable, replace	`PATCH /plans/{id}/files/{fileId}`	`plans.manage`
Delete a file or link	`DELETE /plans/{id}/files/{fileId}` (`204`)	`plans.manage`
List sales	`GET /plans/{id}/purchases`	`billing.read`
Correct a buyer's email	`PATCH /plans/{id}/purchases/{purchaseId}`	`plans.manage` and `billing.read`
Reset downloads	`POST /plans/{id}/purchases/{purchaseId}/downloads/reset`	`plans.manage` and `billing.read`
Resend the download link	`POST /plans/{id}/purchases/{purchaseId}/resend` (`202`)	`plans.manage` and `billing.read`
List reviews, reply or hide	`GET /plans/{id}/reviews`, `PATCH /plans/{id}/reviews/{reviewId}`	`plans.read` / `plans.manage`

New products start unlisted. List one with PATCH /plans/{id} and isPublic: true once it has a ready file or link. Full schemas are in the API reference.

Create a product

bash

1curl https://api.cavuno.com/v1/plans \
2  -X POST \
3  -H "Authorization: Bearer $CAVUNO_API_KEY" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "name": "Climate salary report 2026",
7    "kind": "one_time",
8    "purpose": "digital_product",
9    "digitalProduct": {
10      "pricing": { "kind": "fixed", "currency": "usd", "amountCents": 2900 },
11      "downloadCap": 5,
12      "stampPdfs": true
13    }
14  }'

pricing is { "kind": "free" }, { "kind": "fixed", "currency", "amountCents" } or { "kind": "pay_what_you_want", "currency", "minimumCents", "suggestedCents" }. A paid product needs the board's Stripe connection only at checkout.

Upload a file

POST /plans/{id}/files/uploads with fileName, the exact sizeBytes (up to 500,000,000) and an optional displayName (the name buyers see; fileName when omitted). The response reserves a file (fileId, state uploading) and returns transfer: one presigned url for a small file (method: "single"), or parts with one URL per part (method: "multipart", every part but the last exactly partSizeBytes).
PUT the bytes to each URL. The URLs expire at expiresAt; an upload not completed within a day is stopped.
POST /plans/{id}/files/uploads/{uploadId}/complete. The file moves to checking, then to ready, flagged (flagReason threat or unscannable) or blocked (blockedReason). Poll GET /plans/{id}/files.

bash

1# 1. Start the upload
2curl https://api.cavuno.com/v1/plans/$PLAN_ID/files/uploads \
3  -X POST \
4  -H "Authorization: Bearer $CAVUNO_API_KEY" \
5  -H "Content-Type: application/json" \
6  -d '{ "fileName": "salary-report.pdf", "sizeBytes": 4823311 }'
7
8# 2. Send the bytes to transfer.url (single) or each transfer.parts[].url
9curl -X PUT --upload-file salary-report.pdf "$UPLOAD_URL"
10
11# 3. Finish it
12curl https://api.cavuno.com/v1/plans/$PLAN_ID/files/uploads/$UPLOAD_ID/complete \
13  -X POST \
14  -H "Authorization: Bearer $CAVUNO_API_KEY"

To replace a file, start an upload, pass its id to PATCH /plans/{id}/files/{fileId} as replaceWithUploadId (with notifyBuyers: true to email past buyers once it is live), then send the bytes and complete it. Buyers keep the current version until the new one passes its checks. The file keeps its displayName, the name buyers see and download under; fileName becomes the new upload's name.

A product holds up to 50 files and links. disabled: true on PATCH hides a file from new buyers while earlier buyers keep it; DELETE removes it for everyone.

Operator API errors

Code	Status	Meaning
`digital_product_not_found`	404	Not a digital product (or sale) of this board.
`digital_product_file_not_found`	404	Unknown file.
`digital_product_upload_not_found`	404	Unknown upload.
`digital_product_invalid`	400	A field is invalid for this product.
`digital_product_email_invalid`	400	Not an email address.
`digital_product_upload_invalid`	400	Invalid upload request.
`digital_product_upload_too_large`	400	Over 500 MB.
`digital_product_slug_taken`	409	Another product uses the slug.
`digital_product_no_ready_deliverable`	409	Listing a product with no ready file or link.
`digital_product_taken_down`	409	Cavuno took the product down.
`digital_product_file_limit`	409	The product already has 50 files and links.
`digital_product_purchase_paid`	409	Ending or restoring access on a paid sale; use its transaction instead.
`digital_product_file_state`	409	The file's state refuses the change.
`digital_product_last_deliverable`	409	Removing a listed product's last ready file or link. Unlist it first.
`digital_product_purchase_inactive`	409	Resending while unpaid or after access was removed.
`digital_product_upload_state`	409	The upload is already finished or stopped.
`digital_product_upload_in_progress`	409	The file already has an upload in progress.
`digital_product_upload_mismatch`	409	The bytes sent do not match the declared size.

Sales, refunds and webhooks

GET /plans/{id}/purchases lists each sale as a plan_purchase: email, status (awaiting_payment, paid, free, access_removed), amountCents, currency, answers, downloadsUsed with a per-file breakdown, and transactionId, the sale on GET /v1/transactions (null for a free claim). The three sale actions name the sale by its purchase id and return it.

Refunds and ending access are also on the Transactions page of the dashboard; see Sell digital products. In the Operator API, act on a paid sale by its transaction (the purchase's transactionId):

POST /v1/transactions/{id}/refunds (refundTransaction) refunds a sale in full or in part.
POST /v1/transactions/{id}/remove-access (removeTransactionAccess) and POST /v1/transactions/{id}/restore-access (restoreTransactionAccess) end or give back the buyer's access without moving money.

A free claim has no transaction, so use the purchase instead: POST /v1/plans/{id}/purchases/{purchaseId}/remove-access (removePlanPurchaseAccess) and POST /v1/plans/{id}/purchases/{purchaseId}/restore-access (restorePlanPurchaseAccess). A paid purchase answers digital_product_purchase_paid; use its transaction instead.

All five need the plans.manage and billing.read permissions. These routes ship with the board sale refunds release.

Subscribe a webhook endpoint to digital_product.purchased and digital_product.refunded (they need billing.read). Each carries a digital_purchase object: id, product_id, product_slug, product_name, email, amount_cents, currency, refunded_amount_cents, status, purchased_at and revision. Treat refunded_amount_cents as the current total: it goes up with each refund and down when a refund fails. See Events.

Verify the result

The product list shows only listed products, and a link-only product page renders with noindex.
A free claim lands on the download page and the buyer receives the purchase email.
A paid test checkout mounts, returns with session_id, and getCheckout reaches paid.
A forwarded download link asks for the email, and the confirmation survives a reload.
A file at its limit shows no download button, and purchase_download_limit_reached is not retried.
Download pages, checkout status and /me/purchases are never cached publicly.

Continue with Frontend infrastructure to make these routes canonical and indexable.