Static

The layer

/js/wix/campaigns.js: fetchCampaigns({ limit }) (summaries, up to 100), fetchCampaign(id) (the detail with its donation options; null when the id resolves to nothing), fetchDefaultCampaign(). /js/wix/donate.js holds donationCheckoutUrl and fetchDonationReceipt; the pages reach them through the stores.

Three stores: createCampaignsStore({ initialCampaigns }) in /js/wix/campaigns-store.js for the index, createDonationStore(campaign, { paths }) in /js/wix/donation-store.js for one campaign’s donate flow, and createReceiptStore(orderId) in /js/wix/receipt-store.js for the thank-you page. The donation store owns the rules: which amount is in play, the fee and the total, the button’s label, validation and its messages, the hosted checkout and its redirect. A page reads the state and calls the actions; it computes nothing of its own. Amounts come formatted: goal.raised, goal.target, each preset’s label, the store’s feeLabel, totalLabel and buttonLabel, receipt.amount.

Every .js opens with its declarations: the state fields and the actions, with a comment on each. Read the declarations of the store you are about to use.

The pattern

One shape for every store: create it, subscribe a render function, render once, start where the store has a start(). A store calls the listener on every change and not on subscribe, so the first render is yours. Controls call the store’s actions; delegate from the surface’s root and read what to do from the element, so a re-render keeps the listeners.

The visitor token persists in localStorage on its own; never mint one in a page.

The campaigns index

donate.html on createCampaignsStore(). The state: campaigns (null while the first load is in flight: a loading state, not an empty one) and error. A campaign summary carries id, name, status (“collecting”, “goalReached”, “expired”), acceptsDonations, imageUrl (“” when none) and goal (null when the campaign has none). A card shows the cover when present, the name, the goal block, and a link to the campaign page that reads “Donate” when acceptsDonations, else “Goal reached” or “Ended” by status.

esc escapes &, <, > and " in anything that came from the API.

The goal block

campaign.goal is the whole input; a campaign without a goal shows no block. The fields: raised and target (formatted money), percent (Wix’s rounding, may pass 100: cap the bar’s width at 100 and show the number as it is), donationCount, reached, and the deadline: endDate (null when none), ended, lastDay, daysLeft, hoursLeft. The time left reads nothing without endDate, “Ended” when ended, the hours on the lastDay, else the days. The bar is a track and a fill; the fill carries the width, the stylesheet gives both a height and a background. The numbers raisedAmount and targetAmount serve aria-valuenow and aria-valuemax, never the visible text.

The campaign page

campaign.html?id=… reads the id and calls fetchCampaign. Null is the not-found state, with nothing else on the page. Otherwise the page shows the cover, name, the story, the goal block and the donate flow, and sets document.title from name. The story is the site’s own copy, written from the brief: the campaign entity carries no description.

The donate flow is createDonationStore(campaign, { paths }). paths names where the hosted checkout returns: thankYou on success (Wix appends ?orderId=) and campaign on abandon, both files of this site. The store has no start().

campaign.options decides which controls exist, so a dashboard edit reaches the page on the next load:

• frequencies (value, label): a picker only when there is more than one; the first is the default. setFrequency(value).
• presets (amount, label, impact): one choice per preset with its label and impact text; the first is the default. selectPreset(amount). The chosen one is the state’s presetAmount while customMode is false.
• customAmount.enabled: an “Other amount” choice that calls selectCustom(), and a text field calling setCustomAmount(text) on input, shown while customMode; minLabel and maxLabel give the limits for the placeholder or a help line. currency names the unit.
• askCoverFee: a checkbox calling setCoverFee(checked), labelled with the state’s feeLabel once an amount is in play.
• commentsEnabled: a note field calling setNote(text), with commentMaxLength as its limit and a counter from note.length.
• The submit reads buttonLabel (“Donate $25 Monthly”), “Redirecting…” while submitting, and calls donate().

From the state: amount, fee, total, totalLabel for a summary line; valid; showErrors turns true after the first donate(), and only then do messages show, each under its field (amount, customAmount, frequency, note), the field marked aria-invalid. error is the last checkout failure, shown by the submit. available is campaign.acceptsDonations; when false, the page shows a closed message in place of the controls and nothing else of the flow. donate() validates, then starts the hosted checkout; when it resolves the browser is leaving, or messages are showing. It rejects, with error set, when the checkout could not start.

Rebuild the text of a field only when its value changed and it does not hold the focus, so typing in the custom amount or the note keeps the caret.

The thank-you page

thank-you.html is where the hosted checkout returns after a payment, with ?orderId= appended. createReceiptStore(orderId) with the id from the URL; the state: orderId (“” on a direct visit), loading, receipt (null when there was no id or the order could not be read). A receipt carries orderNumber, donorFirstName, donorLastName, amount (formatted) and paid (anything else reads as pending, never “paid”). Three states: loading, a receipt with its facts, and a plain thank-you without order facts. The page never invents an amount, a name or a payment.

The home page

The hero, a featured campaign strip and the brand story. The strip takes fetchCampaigns({ limit: 1 }) or fetchDefaultCampaign(): the name, the goal block, and a link to the campaign page.

Pages and routes

Wix static hosting serves files. Make every page a file in the root and link to the file: /donate.html, /campaign.html?id=…, /thank-you.html. A link to a folder gives the visitor a 404 page. Every page declares its charset in the head; the host sends none. The paths given to the donation store point at these files, so the hosted checkout returns to them. Keep each page’s script small; a page’s code travels as text in the upload call.

Rules

• Donating goes through the donation store: it owns the checkout line and the hosted redirect. The page never builds a checkout URL, creates an order or marks anything paid.
• The controls follow campaign.options and the closed state follows available; the page decides neither.
• Amounts are display-only, as the layer formats them. Progress renders only from goal; a campaign without one shows none.
• The thank-you page reads the order when it can and shows a plain thank-you otherwise.
• The story copy is the site’s; the campaign data is the API’s. No fabricated figures, beneficiaries or urgency; live data or an honest empty state.
• Browsing and donating need no login; the visitor session is already there.
• Render form inputs once; a render touches their values, the button and the error, not the inputs.
• Every control on the page has a rule in the stylesheet; the submit is the one primary action, the presets and frequencies are chips with a selected state, the rest compact.

Verify before the close

Follow the anonymous smoke test in the published recipe https://www.wix.com/skills/wix-headless/references/inline-recipes/how-to-code-donations.md (section 5): a campaign read, one cart, calculated totals, a redirect session, on one visitor. A session URL is proof of the handoff, not of a payment. Report the API check, the hosted checkout and the payment separately.

The owner’s links

https://manage.wix.com/dashboard/{siteId}/ followed by app/333b456e-dd48-4d6b-b32b-9fd48d74e163 (campaigns and settings), ecom-platform/orders-list (every donation is an order), wix-cashier/payments (connect a payment method); the plan upgrade is https://www.wix.com/upgrade/website?metaSiteId={siteId}. Real donations need a connected payment method and a payments-capable plan; recurring frequencies also need a provider that supports recurring payments. Until then the hosted checkout tells the visitor the site cannot accept payments yet. Give the links in the close.

Seeding

Per seed/SEED.md and seed/seed-donations.mjs: a plain-data plan, run in the script’s order with its waits. It installs what the site needs, creates the campaigns, verifies each reads back and attaches a cover image to each. Seed one approved cause unless the brief names several; the amounts, the custom-giving rules and the recurring settings are the owner’s choices, and a goal or deadline appears only when the brief gives one. Read what the site already holds first; a campaign that was there before the seed is named in the close with the dashboard link, and nothing on the site is deleted.