Fundraising Site

The fundraising site is the public home for groups raising money with salsa and for the people buying to support them. It replaces the old BigCommerce Stencil site at josemadridsalsafundraising.com with pages in the josemadridsalsa.com design, while BigCommerce's fundraising store stays the system of record for the catalog, checkout, payment and orders.

How the app works

The fundraising site is its own Next.js app, apps/fundraising, deployed as its own Vercel project. It serves:

• the site's own pages (app/(site)/): home, shop, groups, cart, blog and the rest below;
• every fundraiser page that used to live on the main site: /fundraising, /fundraisers/..., /fundraise/..., /f/..., /arena/..., the fundraiser portal (/fundraiser-portal/...), fundraiser sign-up (/auth/fundraiser-signup) and the share-shield links (/s/...);
• their APIs (/api/fundraiser/..., /api/fundraisers/..., /api/fundraiser-portal/..., /api/fundraising-site/..., /api/participants/..., /api/fundraiser-signups);
• the checkout, order confirmation and sign-in pages it shares with the main site, from packages/core/routes (see Shared Code Strategy).

The main site redirects (308) its old fundraiser paths to the same path on NEXT_PUBLIC_FUNDRAISING_SITE_URL (apps/storefront/proxy.ts), and the fundraising app sends main-site pages that shared components link to (/products, /salsas, /account, …) back to NEXT_PUBLIC_SITE_URL (apps/fundraising/next.config.mjs).

Staff still manage fundraisers in the main site's admin. Two things stay on the main site for now: the fundraiser mobile app's API (/api/fundraiser-app, because the app has the main site's address built in) and the BigCommerce and payment webhooks.

Local development: npm run dev:fundraising serves it on http://localhost:3001.

Pages

Order-form packs and fliers are static files in apps/fundraising/public/fundraising/downloads/. Replace a file there to update it.

Signing up

The organizer account form (/sign-up step 1, and /auth/fundraiser-signup) sets up the whole store before anyone reviews it:

• Salsa package (required). 9, 16 or 25 flavors. The kits are defined once, in packages/core/lib/fundraising/flavor-kits.ts, which also maps each flavor to its Product.slug. The order-form submission page reads the same lists.
• Fulfillment (required). Order forms + bulk delivery, or online only. The brochure choice is not asked at sign-up; an admin settles it on the fundraiser.
• Colors (required). Main, secondary and accent, matched to the school, team or business. They are stored in Fundraiser.brandColor, secondaryColor and accentColor (on the sign-up request, teamColor is the main one). These are the same three colors the admin Branding tab edits. The main color accents the public campaign page.
• Branding (optional). Logo, cover photo, mission statement and an about-us bio. Images upload through fundraiserSignupImage, the one UploadThing route that needs no session (images only, 4MB, 10 uploads per IP per hour). The API accepts image URLs only from UploadThing hosts.

Approving the account at Admin → Fundraisers → Accounts activates the fundraiser and enables the package's salsas on its store (kit-catalog.server.ts). Salsas an admin has already set up are left as they are. The Battle Arena signup (/fundraise/signup, approved under Signups) asks the same questions and stocks its store the same way.

Old josemadridsalsafundraising.com URLs (/start-your-fundraiser/, /original-mild-salsa/, /cart.php…) redirect permanently to their new paths (lib/fundraising-site/legacy-redirects.ts), so they keep working once that domain points here.

Groups and attribution

A sale is credited to a group the same way it always has been: the fundraising store's checkout asks two required questions, Fundraising Group name (a dropdown) and Salesperson (free text), and BigCommerce stores the answers on the order.

The group list is the BigCommerce checkout dropdown. The site reads it live from the store's public form-fields endpoint, so staff keep managing groups where they always have:

1. BigCommerce control panel › Settings › Form fields › Address fields › Fundraising Group name › add the group as a new option.
2. Within five minutes the group appears on /groups and in the cart's dropdown. Remove the option when the fundraiser ends and it disappears from both.

When a buyer checks out, the site creates the BigCommerce cart and tries to pre-fill the group and salesperson answers. If BigCommerce does not accept the pre-fill, the buyer simply picks them again at checkout — both fields are required there, so a sale can never go uncredited because of it.

Orders placed in the fundraising store are copied into this site's order table and credited to a fundraiser record per group — see BigCommerce cutover.

Pricing and shipping

Both are set in the BigCommerce fundraising store, not here: jars are $10, and shipping is a $10 flat rate per order. The cart shows the flat rate as an estimate; BigCommerce charges the real total.

Going live on a domain

1. Add the domain to the fundraising Vercel project (Settings › Domains); see the cutover runbook for setting that project up. fundraising.josemadridsalsa.com needs a CNAME to cname.vercel-dns.com in that domain's DNS (already in place).
2. Make sure BIGCOMMERCE_FUNDRAISING_STORE_HASH, _ACCESS_TOKEN, _CLIENT_ID and _CLIENT_SECRET are set in Vercel production.
3. When the canonical host changes, set NEXT_PUBLIC_FUNDRAISING_SITE_URL to it and redeploy; canonical URLs, the sitemap and robots.txt follow it.
4. Search Console: add the new host as a property, submit https://<host>/sitemap.xml, and run URL Inspection on the home page.

Moving josemadridsalsafundraising.com here

Adding the old domain to the fundraising Vercel project turns its URLs into redirects to the new site — but the BigCommerce hosted checkout lives on that domain today. Before moving it, have BigCommerce move the fundraising store's checkout to its own subdomain and set BIGCOMMERCE_FUNDRAISING_STOREFRONT_URL to it, exactly as the main store's cutover does. Then use Search Console's Change of Address tool.