How to upgrade donation code

Use the fp-nationbuilder-donation-upgrade Codex skill to upgrade or repair a site's Donation v2 form. The skill follows this guide and NationBuilder's instructions, adapts the changes to the current theme, and checks that the site's custom donation and membership flows still work.

NationBuilder's October 2025 donation upgrade introduced one-time, monthly, and annual frequency options on one form, updated express payments, direct debit for GBP processing, and improved employer and occupation handling. Our Public Theme uses Bootstrap v4 and staged donation forms, so both the template upgrade and the staged-form changes apply.

The FP Public Theme was updated on 17 February 2026. Review sites split before that date, and any later sites with custom donation code or payment issues.

#Upgrade a site with Codex

1. Open the correct theme and provide context

Open the site's current theme repository in Codex. Confirm the NationBuilder nation, theme, branch, and donation page URLs, and keep any existing uncommitted changes intact.

Tell Codex about the behaviour that must be preserved: membership payments and wording, custom donation fields and visibility rules, tag-driven people fields, URL parameters such as org_id or ?amount=50, ticket orders, contribution rules, and privacy controls. Include the single-panel and two-panel layouts if the site uses both.

2. Make the skill available

The skill name is fp-nationbuilder-donation-upgrade. Eric's installed copy is at:

~/.agents/skills/fp-nationbuilder-donation-upgrade/SKILL.md

Another team member needs a copy of the skill in their own Codex environment. If it is not available in the skill picker, ask Eric for the current skill folder. You can also give Codex the path to a readable copy of SKILL.md and explicitly ask it to follow those instructions.

Mention the skill explicitly when starting the upgrade. Codex CLI and the IDE extension support $ skill mentions or /skills; select the skill in your app's picker where available. See OpenAI's skill documentation for the current interface and setup instructions.

3. Give Codex the upgrade task

Replace the placeholders in this prompt and add the site's specific requirements:

Use $fp-nationbuilder-donation-upgrade to upgrade the Donation v2 form
in this theme.

Project/site: [project name and site URL]
Nation / theme: [nation slug / theme identifier]
Donation pages and layouts to check: [URLs, single-panel/two-panel]
Custom behaviour to preserve: [membership, custom fields, URL presets,
ticket orders, contribution rules, privacy controls, and other details]

Read the current Mauhanga guide and NationBuilder's Bootstrap v4 and
staged donation upgrade instructions. Trace the active templates,
includes, JavaScript, and Sass before editing. Compare reference code
with this theme and preserve its custom behaviour, wording, and branding.

Apply the required payment, frequency, validation, native amount-event,
and presentation changes. Run the available local checks and report
changed files, checks performed, mocked payment boundaries, and the
checks that still need an authenticated NationBuilder preview.

Leave the changes ready for review and preview. Do not publish the theme
or submit a transaction as part of this task.

The skill provides a repeatable procedure; Codex still needs to inspect the target theme and implement the changes. It does not automatically enable page settings, publish a theme, or prove that a payment can be processed.

4. Review, preview, and record the upgrade

Review the diff and Codex's verification report against the requirements below. Compile Sass using a compiler compatible with the theme, then check the draft in an authenticated NationBuilder preview. Once the changes have been reviewed and verified, publish through the project's normal workflow and check the live donation pages.

Update the site/theme tracker at the bottom of this document. Keep a link to the commit or PR and the preview results in the project's work record, including any checks still outstanding.

What the upgrade must change

Read the current Bootstrap v4 upgrade kit alongside the additional staged donation changes. The following sections explain how we apply those requirements to For Purpose themes.

Find the active files first

Start at pages_show_donation_v2_wide.html and follow its include chain. Check every layout that renders a donation form, including any single-panel fallback. Common files are:

File What to review
pages_show_donation_v2_wide.html and its layout includes Which form actually renders, payment-field detection, and any separate single-panel form.
_z_pages_show_donation_v2_wide_form.html Stages, frequency and amount controls, demographic fields, payment and billing markup, and form enhancement scripts.
staged-donations-v2.js Stage validation, preset selection, native amount events, navigation, summaries, and scrolling to validation errors.
_stripe.scss Payment-container height and border.
_staged-donations.scss and _z_staged_donations.scss Base staged-form styles and For Purpose overrides.
_z_template_2_panels.scss, where used Two-panel layout and the target theme's colours and button states. Confirm the actual filename before adding an import.
theme.scss, _z_theme.scss, and later overrides such as _z_z_eric.scss Import order, payment visibility rules, and styles that override the donation form.

Donation v1 files such as _z_pages_show_donation_wide_form.html and staged-donations.js are separate from this Donation v2 upgrade. Change them only if an active site workflow also requires it, and verify that workflow separately.

Older themes may contain _z_staged-donations.scss (hyphen), _staged-dontations-v2.scss (misspelling), or _z_pages_show_donation_v2_wide_form_upgrade.html / _z_pages_show_donation_v2_wide_form_wip.html. Confirm they are unused before marking them deprecated with the current date or removing their imports. The active _z_staged_donations.scss uses underscores. Compare each client's code with the reference; preserve existing customisations and only add behaviour that belongs to that site.

Replace the card field and update its surrounding markup

Replace the legacy card element with the payment element:

{% payment_field 'payments' %}

Keep the integration hooks around it: cc-info, address-info, demographics-info, data-payment-disclaimer / cc-disclaimer, submitted-payment-method, and apple-pay-notice. The saved-method control should use a button with the change-submitted-payment-method class.

Remove obsolete express-payment controls and read-only demographic/address blocks from the active v2 form, including the legacy your-info ID. Review matching styles so old visibility rules do not hide the upgraded form. Keep required name and email attributes, the applicable native no_employer checkbox, reCAPTCHA, contribution rules, and privacy controls. Align activity-stream consent with the site's and page's stream settings. These template changes are detailed in NationBuilder's Bootstrap v4 kit.

Collect payment and billing details on the final stage

For the standard three-stage For Purpose form, the intended flow is:

  1. Select donation frequency and amount.
  2. Enter personal details and any site-specific fields.
  3. Select a payment method, provide billing details where required, and submit.

Move the payment element and billing fields together into the final submission stage, with billing fields inside address-info. Express wallets can supply the billing address; other methods show the address fields. NationBuilder specifies this placement for staged donation pages.

Update validateDonations and any custom validation to match the new field locations. Stage two must not demand an address that will be collected on stage three or by a wallet. Keep required personal/custom-field checks and let the native no_employer behaviour handle its applicable fields.

Update frequency controls and preserve the real amount

Use the modern frequency helpers, rather than relying only on the old any condition or monthly-only buttons:

{% if page.donation_v2.show_frequency_radio_buttons? %}
  {{ page.donation_v2.recurring_radio_buttons }}
{% endif %}

Render the options configured for that page and handle fixed monthly or annual frequencies when there are no radio buttons. Preserve NationBuilder's controls and hooks, including form_amount_options, amount_other, .nb_donation_v2_amount, the canonical donation[amount] input, and .nb_donation_v2_interval where used for frequency updates.

For a fixed amount, convert amount_in_cents numerically to currency units when populating the input. Removing $ from formatted currency fails for other symbols and thousands separators. Keep ticket-order amounts and payment wording intact when there are no amount-selection controls.

Notify NationBuilder when custom code selects an amount

NationBuilder's /assets/liquid/theme_donation_v2.js listens for native change events and uses set:amount events. Updating a summary or calling jQuery's .trigger('change') alone can leave the payment integration without the selected amount.

If custom code selects a preset before advancing the stage, explicitly dispatch a native event:

// amountRadio is the preset radio being selected.
amountRadio.checked = true;
amountRadio.dispatchEvent(new Event('change', { bubbles: true }));

Do this even for a label click: setting checked first can prevent the label's default action from producing a change event. Initialise payment state from the checked preset, or from the fixed/Other amount input when no preset is selected. An already highlighted preset still needs to reach NationBuilder's handlers.

Run URL presets and form enhancements after the staged handlers have registered. When staged code uses jQuery ready, use $(initDonationFormUI) for the enhancement initialiser so it runs in that order; a separate DOMContentLoaded callback can run earlier.

Check the canonical donation[amount] value and the payment integration's event handling as well as the visible summary. A correct .donation-amount display alone does not verify the payment amount.

Apply the For Purpose presentation defaults

Preserve the client's branding and any established membership or ticket-order presentation. For the standard staged donation form:

Style the payment iframe using Stripe's Appearance API through NB.payments.elementsOptions. Preserve existing options and match the site's fonts and colours. Legacy NB.payments.elementOptions.style card styling does not replace the payment element's Appearance configuration.

Set .StripeElement height to auto and remove an unwanted outer border as needed. Review payment-container visibility and the staged form's height. In the older Public Theme import structure, the base staged-donations styles load before z_theme, with z_staged_donations providing the For Purpose overrides and z_template_2_panels supporting the panel layout. Adapt imports to the target theme and check later overrides, especially _z_z_eric.scss, before adding competing rules.

Verify that NationBuilder recognises the upgrade

When the form lives in an include, check the top-level pages_show_donation_v2_wide.html detection requirement as well as the rendered form. Verify that NationBuilder recognises the payment-field upgrade and that the expected page settings are available.

Historical note — 15 May 2026: adding a Liquid comment containing the payment-field tag to the Living Wage top-level template removed the control-panel warning, while the real upgraded field was in an include. This records an observed warning workaround; it does not establish that the new settings or payment behaviour work. Verify recognition and the form's behaviour before considering the upgrade complete.

The legacy any frequency value can represent one-time plus monthly recurring donations. An older control-panel label alone does not explain a missing payment element. Trace native amount events and template detection before changing the page's configured frequencies.

Check the form before publishing

Use the site's actual Donation v2 pages and every active layout. Compare the current live page with the authenticated draft preview, on desktop and mobile.

Check Expected result
Select a preset, including one already highlighted on load The canonical amount updates, the payment element becomes available, and the amount disclaimer clears.
Enter Other, continue, go back, and change the amount The input, later-stage summaries, and payment amount stay aligned.
Open a fixed-amount page, ?amount=50, or a ticket order, where supported The amount reaches the payment integration even without a fresh preset click or amount-selection controls.
Change between the configured one-time, monthly, and annual options Both later stages show the correct combined summary; choices stay stacked at all viewport widths.
Select Other with pointer and keyboard input The field receives focus, its outline is visible, and the associated bold label has no container outline or separate tab stop.
Move forward and back through the stages Required personal fields validate; stage two does not block on final-stage billing fields.
Inspect payment and billing presentation Bold headings, normal paragraph typography in country selects, and the site's fonts and colours in the payment element.
Use the site's custom flows Membership wording, custom-field filters, tag-driven fields, parameter prefilling, contribution rules, privacy, and orders retain their behaviour.

For local browser checks, use NationBuilder's actual amount script or a fixture that preserves its native-event semantics. A jQuery-only amount mock can conceal the event failure described above. Report any mocked Stripe/payment boundaries and distinguish local UI checks from successful payment processing.

If an unauthenticated ?preview=1 URL redirects or shows a different page, the draft has not been inspected. Open an authenticated preview and record what remains unchecked. Any transaction or payment-failure testing should be explicitly arranged and performed in the appropriate test environment.

If styling is still wrong, inspect the Sass import order and later overrides. If the payment element is missing, inspect amount initialisation, native events, and template detection. Ask Eric for help with unresolved theme-specific behaviour, and add useful findings to the project's work record and the skill when appropriate.

NationBuilder references

Sites / Themes converted

Add one row per upgraded theme, keeping the project/site name, nation slug, exact theme identifier, and upgrade date. These existing conversion records do not indicate whether the Codex skill was used. Record later follow-up work and its checks in the project record.

Project / site Nation Theme Upgrade date
FP Public theme forpurposehq fp-public-theme-2023-63e9ee7d4445ea7e56609ee2 17 February 2026
UMedics umedics fp-umedics-628d67ac4764e8a9d4fa5191 17 February 2026
Landcare WA landcarewa fp-landcare-wa-688961cb24e8bdd0fd744326 24 February 2026
Living Wage nzlivingwage lw-2019-fp-5d9524ff45de94013a7f1a7f 15 May 2026
Te Ohu Whakawhanaunga nzlivingwage te-ohu-tamaki-verve-2025-67ce08e250ac114adc415e5d 15 May 2026
Long Bay - Okura Great Park Society okura long-bay-okura-great-park-society-6108760c4764e8b644785e86 21 August 2026
Climate and Health Alliance caha climatehealth-fp-61a00a8645de9454c9bbc757 6 October 2026
Access Matters accessalliance fp-ama-2025-691e28cb77f8ef3bc1522525 9 October 2026
Landcare Tasmania landcaretas fp-landcare-tas-681d6bfcca9e4f5b9d86c804 9 October 2026