INSTRUCTIONS

Read Donations experience (opens in a new tab) before designing the donor surfaces. If that sibling skill is not installed, read the published overlay (opens in a new tab). It supplies the short, framework-independent page/form quality bar; the code contracts below supply the implementation. Apply its intent/draft recovery requirements in the UI layer: extend the supplied form/store where needed, retaining its validation and checkout exports. In-memory defaults alone do not survive an external checkout. Do not put donor notes in route parameters or reset them on an unverified return.

A donation is an eCom cart (Cart V2) with one line that references the campaign; in V2 the cart IS the checkout, so the cart’s id is the id the redirect session takes — there is no separate checkout entity. The cart’s donation options.amount is a number, even though campaign price amounts are strings. Omit options.frequency for one-time giving; send only WEEK, MONTH, YEAR for recurring giving. Wix’s hosted checkout takes the payment and the donor’s details, and the eCom order is the receipt. The campaign entity carries no description and no slug: the story on a campaign page is the site’s own copy, and routes key by the campaign id (/donate/<id>).

The file map (deployed into src/)

On Astro and React the shipped files are tested and work as they are — this table and the contracts below are everything you need to use them, so don’t spend the run reading their source; wire them and build your surfaces. Reading them is the right move when something is off (a runtime error, a field this playbook doesn’t cover) or when the brief wants a behaviour they don’t offer — then read the file that owns it and change or extend it. On lib, static, and a port the components don’t deploy at all, and each wiring section below opens with the files to read before writing their equivalents. Files you edit: SiteLayout.astro, styles/global.css, and the story copy on the campaign page. Files you create (skeletons below): your campaigns index island (or Astro markup), your campaign page layout, and your home page.

Astro stack additionally gets:

What you build — the design job

1. The campaign card + campaigns index — your tile (cover, name, the shipped GoalProgress compact, a Donate link; a closed campaign reads “Goal reached” / “Ended”, never “Donate”) and grid rhythm, an honest empty state. The index page ships with SSR data; render it in Astro markup or swap in an island on useCampaigns.
2. The campaign page’s layout — cover, name, the story (your copy from the brief — the API has none), GoalProgress, and the shipped DonateForm as the giving column; design it for the brand (a sticky form column, an editorial split, a full-bleed cover). Donation logic never leaves the shipped component and hook.
3. The home page — hero, a featured campaign strip (fetchCampaigns({ limit: 1 }) in frontmatter → name, GoalProgress, CTA to /donate/<id>), brand story.

Plus the theme (@theme block, one edit) and the chrome (SiteLayout, one pass).

The shared Donations experience overlay above owns page composition, mobile density, truthful progress/copy and return-state quality. The contracts below own the wiring; apply both rather than maintaining a second set of design rules here.

The contracts your components consume (tested and work as they are; read the source when something is off or the brief wants more)

The islands you create — skeletons

The pages ship; the surfaces they render are yours. Hooks first, branches after (an early return above a hook changes hook order between renders and React throws). client:load islands render on the server too — render every state totally; nothing in a render path may throw.

The reference files for stacks where the components don’t deploy

On lib, static, and a port, nothing under components/ or hooks/ arrives (on static, read static.md in this folder). The state machines behind the hooks do arrive — wix/donations/donation-store.ts, campaigns-store.ts, receipt-store.ts — so you never rewrite them: create a store per surface, subscribe, render from getState(), call its actions. Their *State interfaces are the render contract; read those. What you write is the rendering — grid, card, campaign page, the form, the thank-you page — and for that read first:

1. components/donations/DonateForm.tsx — the form as working code: which controls appear for which options, the preset/custom switch, the fee line, the note counter, when messages show, the in-flight label, the inline error, the closed state.
2. components/donations/GoalProgress.tsx — the progress block’s text rules (timeLeftLabel).
3. components/donations/DonationReceipt.tsx — the thank-you page’s three honest states.

Under templates/donations/app/.

Wiring — Astro (default)

1. Set the @theme tokens (one edit); brand SiteLayout.astro (one pass — merge into the other vertical’s layout instead if both are deployed).
2. Redesign components/donations/CampaignPage.astro around the two shipped components and pass the campaign’s story through story; restyle the card markup in pages/donate/index.astro (or mount your CampaignsGrid there with initialCampaigns). Author your surfaces in as few messages as possible — batch multiple Writes per message.
3. Write pages/index.astro (home) — it exists from the scaffold; Read it before overwriting.

Wiring — another JS framework (--stack lib: Vue, Svelte, Solid, plain Vite)

Read the reference files listed above before writing any surface.

deploy.mjs donations --stack lib put the data layer in src/wix/ and nothing else: sdk.ts (the visitor client, configured with the public client id), media.ts, money.ts, and wix/donations/ — campaigns.ts, donate.ts, types.ts, donations-core.ts, and the three stores. None of it is React. The hooks and components don’t ship on this stack; the stores replace the hooks, and you write the components in your framework to the contracts on this page:

• bind the stores with your framework’s external-store primitive (Vue: shallowRef updated in subscribe; Svelte: readable(store.getState(), (set) => store.subscribe(() => set(store.getState()))); Solid: a signal set in subscribe). createCampaignsStore({ initialCampaigns? }) per listing (start() when mounted, stop() when unmounted), createDonationStore(campaign, { paths? }) per campaign surface (donate() navigates the document itself), createReceiptStore() on the thank-you page (start() once mounted). State in, actions out — exactly the hooks’ contracts above;
• your form to the DonateForm.tsx contract: the controls the options allow, buttonLabel on the CTA, disabled with “Redirecting…” while submitting, messages once showErrors, error inline, the closed state when available is false.

Routes /donate, /donate/:id (via fetchCampaign, null → your 404), /donate/thank-you; dev server on 4321; a static build goes through npx @wix/cli@latest release with site.outputDirectory pointing at the build folder, an SSR build is hosted by you. Page title from the DTO’s name; the description is your copy — campaigns carry no seoData.

Wiring — static site (--stack static, no bundler)

Read static.md in this folder: it is the whole playbook for this stack, in one file. The pages import the layer from the site’s js/wix/ folder and write every control on the stores; static.md shows how to drive each store, with the routes, the rules and the seed.

Wiring — server-rendered, another language (Flask, Laravel, Rails, …)

Read the reference files listed above before writing any surface.

Run deploy.mjs donations --stack static in the project folder anyway: js/wix/ is both the browser-side code and the readable spec. Then split by where the call runs. Reads on the server: port js/wix/campaigns.ts and donations-core.ts to your language — the same functions returning the same DTO shapes as dicts (the literal bodies are in the file), one anonymous visitor token per process for these public reads (mint and refresh per client.ts) — and render the index and the campaign page in your templates to the contracts above, so campaign names and goals are in the HTML. Donating in the browser: the form on ./js/wix/donation-store.js (pass the campaign DTO rendered into the page as JSON), exactly as the static wiring above — the checkout and the redirect session are created by the visitor’s own token from the page, so the server never handles per-visitor tokens; the thank-you page mounts createReceiptStore() the same way. Routes stay /donate, /donate/<id>, /donate/thank-you. Add your public https origin to the OAuth app’s allowed domains before the hosted checkout can return.

Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted. Same port for the reads, run at build time with one anonymous token; the generator emits /donate and one page per campaign from fetchCampaigns() (at most 100 — one call). Goal progress is frozen at build time — say so to the owner, or render GoalProgress client-side from a fetchCampaign on load. Run deploy.mjs donations --stack static --out <build dir> so js/wix/ is inside the output the pages import from, point site.outputDirectory at that folder, wix release. Pages sit at different depths (/, /donate/…): give the templates one base path to js/wix/ (root-relative /js/wix/…), never a relative ./js/wix/. The frozen page is the first paint; the form still runs client-side through createDonationStore(). Close with the live URL, the rebuild + release command, and one line for the owner: dashboard edits to campaigns reach the site when that command runs; donating is live regardless.

Wiring — React SPA (Vite etc.)

Import ./styles/global.css once at the app entry (needs @tailwindcss/vite in the vite plugins — deploy added the dep). Routes: /donate → your grid (useCampaigns() fetches client-side when no initialCampaigns is passed); /donate/:id → fetchCampaign(id) client-side, then your page around <DonateForm campaign={c} /> (null → your not-found state); /donate/thank-you → <DonationReceipt />. Deploy wrote the public client id into wix/config.ts; nothing else to configure.

Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly — hash routes, or one HTML file per route, decided before the first route is written; any URL handed to Wix as a return target must be one the host serves (SKILL.md step 1) — pass it through paths.

Hard rules

• Donate only through the shipped exports — DonateForm / useDonation / donationCheckoutUrl own the checkout line and the hosted redirect session. Never hand-build a checkout URL, never create an order, never mark anything paid.
• Never promise a completed donation from the return URL. postFlowUrl (the campaign page) is hit on abandon too; landing on /donate/thank-you?orderId= is the success redirect. The thank-you page reads the order when it can and degrades to a thank-you without order facts otherwise — never an invented amount, name or “paid”.
• Amounts are display-only. label, target, raised, amount come pre-formatted from the API; the only computed money is the fee preview — Wix’s fixed 2.9% — and the button total. Wix prices the line, tax and schedule at the hosted checkout.
• No invented goal numbers. Progress renders only from goal; a campaign without one has none.
• The form is the shipped DonateForm (on static, the page’s own markup on the donation store) — it alone decides which controls appear (frequencies, presets, custom amount, fee, note) and when a campaign is closed; a page never rebuilds that.
• The story copy is yours, the campaign data isn’t. The API has no description: write the cause’s story from the brief; never fabricate figures, beneficiaries or urgency.
• Don’t wrap shipped calls in your own API routes — they run client-side by design.
• Where the shipped components deploy (Astro, React): theme via the @theme tokens, and your markup uses Tailwind utilities on the same tokens — one design system across shipped and written code. No parallel theme files, no hardcoded palette values. Where they don’t (lib, static, a port): style with whatever your stack does well, on one token set of your own.
• Live data or an honest empty state — never mock campaigns, amounts, or progress.
• Call every hook before any conditional return. Hooks first, branches after.
• Browsing and donating need no login. They run on the visitor session the shipped client already holds; don’t gate campaigns behind sign-in.

Verify the donation handoff

Before calling this build working, follow the bounded anonymous API smoke test in How to Code Donations (opens in a new tab): campaign read → one Cart V2 → calculated line/totals → redirect session, using the same visitor. Use the sibling file when installed, otherwise https://www.wix.com/skills/wix-headless/references/inline-recipes/how-to-code-donations.md. Do not add a V1 Create Checkout step. A local test or a session URL is not proof of payment. Report API, hosted-checkout and payment verification separately; no payment without explicit authorization. For ITEM_NOT_FOUND_IN_CATALOG, inspect numeric amount, app/campaign IDs and frequency first, not reinstallation or premium. Keep sanitized error code/body/stage for diagnosis; do not swallow failures.

Out of scope (don’t improvise these)

A donor’s history or receipts page (member-only order reads), managing a recurring donation (Wix’s emails and hosted member flows do that), campaign creation or editing from the site (owner-only — server-side per templates/shared/CUSTOM_OPERATIONS.md, or the dashboard). If the user asks for a donor account area, deploy the members vertical beside this one rather than shipping code that returns nothing for visitors.

Point the user to their dashboard

Hand the owner these links — {siteId} is siteId in wix.config.json (the deploy JSON prints it as dashboardUrl).

Taking real donations needs a connected payment method plus a payments-capable plan. Cart/session creation can succeed before these are ready; it does not prove a charge can succeed. Do not use a premium explanation for a malformed catalog reference. A visitor can encounter an unavailable-payments message at hosted checkout until setup is complete. Recurring frequencies (WEEK/MONTH/YEAR) additionally need a payment provider that supports recurring payments. Mention it; don’t treat it as a code failure. The cover-fee 2.9% is added to every recurring charge.

Seeding

Per seed/SEED.md — plain-data plan.json into seed-donations.mjs from the project root. Seed one approved cause for a new setup unless the brief lists several. Do not invent impact claims, goals or deadlines to exercise every form branch, and never reseed for a frontend-only request. Optional form states can be tested in local fixtures. Ongoing edits use the shared management recipe linked there.

Caveats — verified against the SDK, not yet against a live site

The shipped code guards each of these, so a refusal degrades instead of breaking; confirm them on the first real site and read the owning file if one bites.

• Visitor reads. Whether an anonymous visitor token may query campaigns and read /metrics is unverified. Metrics are caught per campaign: a refusal leaves goal.raised “” (the target still shows) and options.currency “” (the button reads “Donate” without an amount; preset labels still carry the API’s own formatted amounts). If the campaign query itself is refused, the pages render their empty state.
• Create Cart is the whole path (Cart V2). donationCheckoutUrl creates one fresh cart with the donation line (cart.source.channelType: WEB, the donor note as cart.note) and hands that cart’s id straight to the redirect session — the cart is the checkout, so there is no separate Create Checkout call and nothing merges into a storefront visitor’s current cart.
• Site currency. Comes from the metrics response (“returns only the site’s default currency”); On a campaign nobody has donated to yet the metrics carry no currency either, so the transports read the site’s currency once from the eCommerce settings (BUSINESS_INFO); unknown → “”.
• Reading the order on the thank-you page. GET /ecom/v1/orders/{id} with the visitor’s token is unverified; any failure → receipt null and the page thanks without order facts.
• orderId spelling. The redirect-session contract appends orderId; the Wix widget’s own success URL uses orderid. Both are read.
• Cover image update shape (seed) — inferred from the SDK; a failed attach is reported, never fatal.
• App installation (seed) — installing Donations through the installer API, and whether it provisions eCom, is unverified; the seed installs both and reports each result.
• Dashboard route. The app/<appDefId> link redirects to the app’s slug route; the slug itself was not resolved live.
• The donorCoveringFees flag, 2.9% and one-time frequency omission are documented in the public donation eCommerce integration (opens in a new tab).