WIZARD WASH · PROGRAM & INTEGRATION GUIDE

From the first wash
to the welcome shirt.

The customer experience is built. This guide explains the seven steps and the connections FlexWash / your POS team and the shirt supplier must complete before real orders begin.

Current release: staged preview. The public demo does not charge anyone, save shipping details, enroll a member, send email, or order a shirt.

One club, four houses

Every house costs $30/month. House assignment changes the crest, shirt color, and experience—not the club price. The welcome shirt is a one-time member gift. Membership renewals and quiz retakes do not create another shirt.

The seven customer steps

1. Club: Join through the POS. A verified first $30 payment creates one welcome-shirt entitlement and an acceptance email.
2. Quiz: Answer the existing eight car-cleaning personality questions. Each answer gives one house a point; ties use the latest answer among the tied houses.
3. House: Reveal the house, crest, personality, and motto. A real member’s first house assignment is saved.
4. Shirt: View the owner-approved front-and-back photo for the assigned house. Choose a configured shirt size and consult the final manufacturer’s chart.
5. Delivery: Enter US shipping details and an email for order updates. Confirm the address before submission.
6. Review: Confirm size, address, and the one-shirt benefit. Server validation checks paid eligibility and reserves a unique claim.
7. Welcome: The print provider makes and mails the shirt. Confirmation and tracking emails follow automatically after the connections are enabled.

What is built

Mobile enrollment preview, preserved quiz and house crests, all four exact approved shirt photos, shipping validation, protected member claims, durable member/order records, duplicate prevention, signed POS event intake, Printful draft/confirm and tracking adapters, an email outbox, and an authorized staff dashboard for exceptions.

House Outfitters & online sales

The full site now includes the homepage, four house pages, wash spell menu and comparison, shop filters, sixteen product detail pages, size selection, and a persistent preview bag. The four shirt photos are the exact owner-approved designs. Hoodie, tumbler, and sticker collection images are concepts; production artwork and products still need approval.

Proposed retail prices: house tee $25, hoodie $45, tumbler $24, crest sticker $8. These are suggested prices, not final retail offers. Merchandise sales are separate from the $30/month membership and its one-time welcome gift.

The catalog and server-side quote endpoint validate product IDs, size, and quantity and calculate prices from the catalog. Online checkout deliberately returns unavailable. It does not take card details, create orders, or call a payment API.

1. Supply the selected POS provider's checkout API documentation, sandbox credentials, payment/refund webhooks, tax and shipping support, and merchant account settings.
2. Approve the catalog, retail pricing, final specifications, size charts, production files, and provider SKU for every house / product / size combination.
3. Add durable retail carts, checkout sessions, paid orders, and payment-event reconciliation. Verify the captured amount, currency, and immutable line items on the server before fulfillment.
4. Connect a separate retail fulfillment path with stable external IDs, stock checks, shipping quotes, tracking, and staff exception handling. A retail order must never create or consume a welcome-shirt entitlement.
5. Publish shipping, returns, support, privacy, and membership billing terms. Test payment failure, duplicate callbacks, cancellation, refunds, out-of-stock items, and real shipment tracking before enabling sales.

Chosen domain

The intended address is GoWizardWash.com. Registration and DNS connection are pending; publishing this site does not purchase the domain. After registration, connect the domain to this existing site, validate HTTPS, and update SITE_ORIGIN and the approved POS return/webhook URLs. Email sending also needs separate sender-domain verification.

POS connection contract

This is a normalized adapter contract, not an assumption about the POS vendor’s API. The POS team must verify its own payment event using the vendor’s authentication, map the event to this payload, and sign the exact body. Browser form submissions never establish payment eligibility.

POST /api/hooks/pos
Content-Type: application/json
X-WW-Timestamp: <current Unix seconds>
X-WW-Signature: sha256=<HMAC-SHA256(secret, timestamp + "." + rawBody)>

{
  "event_id": "unique-pos-event-id",
  "type": "membership.first_payment_succeeded",
  "customer_id": "stable-pos-customer-id",
  "membership_id": "pos-membership-id",
  "payment_id": "unique-captured-payment-id",
  "plan_code": "wizard-house-club",
  "amount_cents": 3000,
  "currency": "USD",
  "name": "Customer name",
  "email": "customer@example.com"
}

The signature expires after five minutes. Retry deliveries with the same event ID and a fresh timestamp/signature. The customer ID must remain stable across renewals, cancellations, and rejoins. Different IDs for the same person cannot be deduplicated automatically.

Cancellation/refund events use membership.cancelled or membership.refunded, with event ID, customer ID, and membership ID. They block unsubmitted claims. Existing production orders require staff review with the printer; the application does not automatically refund or cancel a printed shirt.

Printful setup

1. Create four synced products with approved front and back files and the matching garment colors. Approve a physical sample of each before launch.
2. Map each available size to its exact sync_variant_id. Supply the selected garment’s real size chart. Previews are not print-ready files.
3. Connect billing and set an approved per-shirt cost ceiling. Wizard Wash pays product, shipping, and tax even though the customer sees a $0 welcome gift.
4. Configure order and shipping callbacks to /api/hooks/printful?key=YOUR_SECRET. Callbacks trigger an authenticated order lookup; their status fields are never trusted directly.
5. Schedule authenticated POST /api/jobs/process every five minutes using Authorization: Bearer JOBS_SECRET. This drains pending emails and reconciles orders when callbacks are missed. The staff dashboard can also process the queue.

Each claim uses one stable external order ID. The server finds an existing provider order before creating one, creates a draft, checks its total and items, then confirms it. Unexpected or ambiguous failures are held for staff review to avoid duplicate charges.

PRINTFUL_VARIANTS_JSON example shape (replace every ID):
{
  "s": {"S": 1001, "M": 1002, "L": 1003},
  "r": {"S": 2001, "M": 2002, "L": 2003},
  "g": {"S": 3001, "M": 3002, "L": 3003},
  "c": {"S": 4001, "M": 4002, "L": 4003}
}

Email & member links

Connect Resend with a verified Wizard Wash sender domain. The system prepares the acceptance invitation, claim confirmation, and shipping update. Each message has a stable idempotency key and a durable delivery record. Ambiguous retries outside the email provider’s idempotency window go to staff review.

Member links expire after 30 days. They contain a private claim token in the URL fragment. Staff can send a new link without issuing another shirt. Keep these links private. SMS delivery is not connected; the site itself can be shared by text, while private member links are emailed.

Server settings

Before switching on

1. Confirm membership wash benefits, billing/cancellation terms, shipping coverage, size/return policy, and privacy text.
2. Connect the POS adapter and test captured payment, failed payment, duplicate delivery, cancellation, and renewal events.
3. Approve four garment samples, artwork, size chart, variant availability, and the gift cost.
4. Verify email delivery and the background job, then complete one controlled paid enrollment through shipping confirmation.
5. Review access to the staff dashboard and move live ordering out of preview only after the end-to-end test passes.

Single-wash menu

Provider references: Printful API · Resend email API · Resend idempotency