Handle Gift N Thrift for your user

Claim for a user

1. 1

   Find a listing

   Open /browse, /categories, or a category such as /c/clothing-boys. Query params: q, category, condition, zip. Example searches: “kids coat 5T”, “free furniture”, “shoes”.

2. 2

   Choose SHIP or PICKUP

   On /listings/{slug}, pickup is always an option and is $0 / $0. Vehicles require pickup. For SHIP, fill toZip (Deliver to ZIP) and wait for the auto-calculated carrier quote. Do not invent a rate.

3. 3

   See the true total

   SHIP totals: item $0, all-in shipping, service fee $2.99. PICKUP totals: item $0, shipping $0, fee $0.

4. 4

   Sign in

   Use /login with callbackUrl=/checkout/{slug} (optional portal=buyer hint opens Claims / orders). Or create an account at /signup.

5. 5

   Complete checkout

   Open /checkout/{slug}. Set fulfillment=PICKUP or SHIP. Fill shipToName, shipToLine1, shipToCity, shipToState, shipToZip. PICKUP records the claim at $0 with no card charge. SHIP charges all-in shipping + $2.99. The item stays $0.

6. 6

   Track the order

   Confirmation is /orders/{id}/success (SHIP) or /orders/{id} (PICKUP). Follow /dashboard?tab=claims (Claims / orders tab in the one office) for tracking after the donor ships, or coordinate pickup from the origin ZIP. /dashboard/buyer redirects here.

Donate — humans (web UI)

People use the website camera on a phone. Agents must not follow this path. Agents use POST /api/agent/listings only (see Batch donate API).

1. 1

   Open your office

   Sign in at /login (optional portal=seller hint opens Donate / listings), then go to /dashboard/seller/listings/new. One office — not a separate seller app.

2. 2

   Add photos, then AI-draft

   Snap photos from the phone (Take photo / Upload from library — web PWA, or the Expo app). After the first photo, POST /api/listings/ai-suggest to draft title, category, condition, description, and an optional FMV hint. Donor edits every field. Never auto-publish.

3. 3

   Choose SHIP or PICKUP

   Field name=fulfillment. PICKUP is always allowed and stays $0/$0 for the claimer. Vehicles (vehicles) force PICKUP. Offering SHIP still leaves pickup available. Fill shipFromCity, shipFromState, shipFromZip. Packed weightLb / lengthIn / widthIn / heightIn are required when SHIP is offered.

4. 4

   Publish at $0

   There is no item price field. Donors list for free. Gift N Thrift does not pay donors. After Publish, the public listing URL is /listings/{slug}. List another keeps category, who/size, fulfillment, origin, and packed size. This web form is for humans only.

5. 5

   Hand off when claimed, then download the receipt

   On SHIP, pack the item after the claimer pays carrier + buffer + fee, mark shipped with tracking on /dashboard?tab=donate (Donate / listings). On PICKUP, arrange a meetup at the origin ZIP — no money changes hands. Download the donation PDF either way. /dashboard/seller redirects here. Gift N Thrift receipts are records of the transfer for the donor’s files — not tax advice, not IRS Form 8283, and not a promise that the gift is deductible. U.S. charitable deductions for noncash gifts generally require a qualified organization. Talk to a tax professional.

Form fields to fill

Listing create

• title — required. Short item name
• category — required. vehicles | clothing | clothing-boys | clothing-girls | clothing-men | clothing-women | shoes | furniture | electronics | kids | kitchen | home | misc
• condition — required. new | like_new | good | fair
• description — required. Honest condition notes
• estimatedFmv — required. Donor’s used-value estimate in USD. Not a charge. After a successful claim, the donor earns 1 bonus point per $1 FMV. Not a tax deduction.
• photos — optional. Up to 8 images for the human web form (client-compressed). Agents: one photo per listing on POST /api/agent/listings (max 12). App limit 12MB per photo / 20MB per request; server resizes to 1600px JPEG. HTTP 413 names those limits.
• fulfillment — required. SHIP | PICKUP | BOTH. SHIP = ship only (no pickup). PICKUP = free local. BOTH = either. Vehicles force PICKUP. Default BOTH.
• apparelSex — optional. boys | girls | men | women | unisex — required for clothing and shoes
• apparelSize — optional. Size as worn (2T, 5T, L, 10). Required for clothing and shoes.
• shipFromCity — required. Origin city (pickup meetup city, or ship-from)
• shipFromState — required. 2-letter US state
• shipFromZip — required. 5-digit origin ZIP for postage or pickup area
• weightLb — optional. Packed weight in pounds — required when offering SHIP
• lengthIn — optional. Packed length inches — required when offering SHIP
• widthIn — optional. Packed width inches — required when offering SHIP
• heightIn — optional. Packed height inches — required when offering SHIP

Checkout

• listingId — required. Hidden; already on the checkout page
• fulfillment — required. SHIP or PICKUP. PICKUP is $0 shipping and $0 fee. Vehicles and pickup-only listings must use PICKUP.
• shipToName — required. Recipient / claimer name
• shipToLine1 — required. Street address (SHIP) or meetup note (PICKUP, e.g. Local pickup)
• shipToCity — required. City
• shipToState — required. 2-letter US state
• shipToZip — required. 5-digit destination ZIP — recalculates SHIP postage. Do not type a dollar amount.
• saveAddress — optional. Checkbox to store the address in the office (Claims / orders)

Batch donate presets

• category — optional. Locked for the pile when set. AI fills it only if omitted.
• condition — optional. Default good if omitted; AI may fill per photo.
• fulfillment — optional. BOTH | SHIP | PICKUP. Shared for the pile. Default BOTH. Vehicles force PICKUP.
• apparelSex — optional. boys | girls | men | women | unisex — required for clothing/shoes piles.
• apparelSize — optional. Size as worn (2T, 5T, L, 10). Required for clothing/shoes piles.
• shipFromCity — required. Origin city for the whole pile.
• shipFromState — required. 2-letter US state.
• shipFromZip — required. 5-digit origin ZIP.
• shipFromName — optional. Optional ship-from name for postage labels.
• shipFromLine1 — optional. Optional ship-from street for postage labels.
• weightLb — optional. Default packed weight in pounds — required when the pile offers SHIP.
• lengthIn — optional. Default packed length inches.
• widthIn — optional. Default packed width inches.
• heightIn — optional. Default packed height inches.
• estimatedFmv — optional. Optional default used-value USD for the pile. Per-item items[].estimatedFmv wins. AI fills if both omitted.
• referralCode — optional. Church/org referral code (aliases: ref, churchCode). Attributes the listing and reserves $1 from paid ship claims. Also honored from /r/{code} cookie or the donor's signup-attributed church.

Batch donate per-item overrides

• title — optional. Per listing. AI drafts from that listing’s photo if omitted.
• description — optional. Per listing. AI drafts if omitted.
• estimatedFmv — optional. Per listing USD. Falls back to presets.estimatedFmv, then AI.
• category — optional. Rare override. Prefer locking category on presets.
• condition — optional. Per listing condition slug.
• apparelSex — optional. Rare override of the pile Who lock.
• apparelSize — optional. Rare override of the pile size lock.

Listing preview ZIP uses toZip. Checkout destination ZIP uses shipToZip. Login uses email and password.

Demo logins

Seeded seller/buyer accounts exist only on a local database. This page does not publish passwords. In production, create a real account at /signup. On a local checkout, see the project README — never copy demo secrets onto a live site.

Organization (church) endpoints

Organizations sign up at /signup/organization. The referral code is also the activation / partner code for /church. Agents can attribute listings withpresets.referralCode (or ref / churchCode) on POST /api/agent/listings. Org agent auth uses HTTP Basic (referralCode:portalPassword) or x-church-code + x-church-password. Full detail: /agents.md and /llms.txt.

• Pastor video: portal UI at /church/video (record or upload mp4/mov/webm, max ~90s / 200MB). Public share page /v/{code} plays the published clip; if the partner exists but has no video yet, that page returns a friendly empty state (200) with a Donate button to /r/{code}. Unknown codes stay 404.
• Congregation members: POST /api/church/members — JSON { text|emails, attestation: true } or multipart file (CSV / XLSX / TXT / text PDF) + attestation=true. Max 5MB / 5000 addresses. Response counts: added, duplicates (same file or already on this church’s list), invalid, suppressed (global unsubscribe block), skipped, totalActive. Invalid-only or duplicates-only uploads return 400 with a clear message. Consent attestation is required.
• Announcements: POST /api/church/announcements — JSON { personalNote?, attestation: true }. First send (and sends over 500) go to office review. Preview HTML uses a placeholder unsubscribe token (preview-token); real tokens are minted only when mail is actually sent.
• Unsubscribe: links look like /unsubscribe?t={unsubToken}. POST /api/unsubscribe with that token marks the member UNSUBSCRIBED and adds a global emailSuppression row so later uploads skip them (suppressed count). Preview tokens are rejected.

Sales rep program endpoints

Independent sales reps earn $1 per paid shipped transaction from the people and organizations they refer, up to $10,000 per rep per calendar month (America/Denver). Pickup claims ($0 / $0) earn nothing. At most one rep is credited per transaction. Reps are independent referrers, not employees; terms can change. The church/organization $1 is separate and unaffected.

• Public page: /reps. Human signup: /signup/rep (legal name, email, phone, mailing address, password, optional preferred code, agreement checkbox). Rep dashboard: /rep (email + password; own session, separate from donor, org, and office logins).
• People link: /rep/{code} sets a 90-day rep cookie (gnt_rep_ref) and lands on /signup; ?rep={code} on any page does the same. A person who signs up with that cookie is attributed to the rep. A church ref cookie can coexist; both are kept.
• Organization link: /signup/organization?rep={code} stamps the new organization as recruited by the rep.
• Rep and church codes share one namespace, so a code never belongs to both. Reps live under /rep/{code}; churches under /r/{code}.
• Attribution per paid shipped claim (one rep max): 1) rep who recruited the organization the listing is attributed to, else 2) rep who referred the listing's donor, else 3) rep who referred the claimer. Suspended reps are skipped.
• Ledger statuses: FUNDED (credited), PENDING (earned while the rep awaits approval), CAPPED ($0, past the monthly cap, still shown), REVERSED (refund or cancel, $0).
• Rate and cap are office settings (defaults $1 and $10,000/month). Payouts: monthly Stripe transfers around the 5th for everything earned through the end of the previous month, once the rep finishes Stripe payout setup on /rep (Stripe collects tax info). $25 minimum; smaller balances roll over. Until the office switches automatic payouts on, the office pays by hand and records it.
• Churches/organizations are paid the same way: $1 per paid shipped claim on their code, monthly Stripe transfer around the 5th after they set up payouts in the /church portal (Stripe collects the organization's bank and tax details), $25 minimum with rollover.

Rep API

• POST /api/agent/reps — register a rep. Auth: Authorization: Bearer gnt_live_… (a Gift N Thrift agent token). JSON: legalName, email, phone, street, city, state, zip, password, optional code, agree:true (the person must accept the agreement). 201 → rep {id, code, status}, links {individual, organizationSignup, dashboard}, repApiToken (gnt_rep_…, shown once), welcomeEmailSent.
• GET /api/agent/reps/me — live stats. Auth: Authorization: Bearer gnt_rep_…. Returns links, settings, stats (peopleReferred, organizationsRecruited, paidTransactionsThisMonth, earnedThisMonthCents, capPercent, lifetimeEarnedCents, paidOutCents, owedCents), organizations, transactions, payouts.
• POST /api/agent/reps/organizations — create an organization recruited by the calling rep. Auth: Bearer gnt_rep_…. JSON: displayName, contactEmail, password, optional charityName, zip, code. 201 → organization {code, …}, links {share /r/{code}, portal /church}.
• Reps can mint or rotate their gnt_rep_ token on /rep. Never invent earnings, payout dates, or tax advice; read /api/agent/reps/me.

Public explainer: /reps. Full detail and curl examples: /agents.md.