# Launch Readiness

What to expect in the first 30 days of a Guild integration. Read this before go-live.

## Wallet is display-only at launch

At the v1 launch posture, user redemption is **gated behind a feature flag** while we finalize the payouts integration with [Tremendous](https://tremendous.com) (the partner that lets recipients redeem to Visa prepaid, Amazon, Venmo, PayPal, ACH, and 1000+ retailers — no per-user KYC required for amounts under the IRS $2000/year reporting threshold).

> **Why not Stripe Connect?** Stripe Connect Express requires every recipient to complete KYC (SSN, ID upload, bank verification) before they can claim their first payout. For a rewards program where the median user earns single-dollar amounts, that friction kills conversion. Tremendous treats payouts as rebates rather than money transmission, so users can claim a $5 reward in 30 seconds without surrendering their SSN. Stripe Connect remains an opt-in path for power users who want direct ACH and pass a higher threshold — that's a follow-on, not v1.

### What this means for your users

- They see their token balance accumulating in the hosted `/wallet` page
- The balance displays in cents (via daily settlement)
- They **cannot redeem** until the feature flag flips
- The hosted `/wallet` page surfaces a provider-neutral banner explaining the state — it doesn't promise a specific partner

### What this means for you

- You do **not** need any payouts integration configured on your side for the v1 launch
- You should communicate the display-only state to your users in your own messaging too — not just rely on Guild's banner
- When the flag flips, payouts will retroactively cover accrued balance (subject to any compliance review gate on the marketplace's side)
- 1099 reporting: Tremendous tracks recipient totals across the year; over the $2000 threshold, you (the marketplace) are responsible for filing via the [Tax1099 integration](https://help.tremendous.com/hc/en-us/articles/46653020084499-Preparing-1099s-with-Tax1099) (Tremendous gives clients a 10% discount). Guild surfaces export tooling in the admin console.

### When does the flag flip?

When KYC, compliance, and tax workflows are verified end-to-end across the portfolio. No dated commitment in v1. Follow the release log or check directly with us.

## First-transaction bonus skews early-period math

Every `tenant_user` receives a **2x token multiplier** on their first 3 settled earning events on your marketplace.

### What this means in weeks 1–4 of your launch

- Every user is new → effectively every earning event during the launch window gets the 2x bonus
- Reward payouts during this period will be approximately **2x the steady-state rate**
- Token value (cents-per-token) will be approximately half of steady-state because more tokens are chasing the same pool

### How to budget

If your steady-state expected reward-budget rate is "21% of commission" (see [the onboarding guide's reward mechanics](../onboarding/marketplace-onboarding.md#reward-mechanics)), model the first 4–6 weeks at **up to 42% of commission** going into the user rewards pool.

This is not a bug. The bonus is a deliberate design choice to reward early participants and kickstart the viral loop. Plan for it in your finance model.

### How to message it

- Safe framing: "rewards compound with participation"
- Avoid: publicly quoting a fixed "X% of sale" rate in marketing materials
- Prefer: directing users to their `/wallet` to see actual earned value

## No outbound webhooks yet

Guild has no mechanism today to push state changes to your system.

### What this means

- You cannot trigger real-time user notifications based on Guild events
- You cannot write real-time accounting entries when Guild settles
- You cannot run real-time fraud checks when tokens are minted

### What to do instead

Poll the relevant endpoints on the cadence appropriate to your use case:

- `GET /v1/wallet/:tenant_user_id` — per-user balance state
- Admin endpoints (see `frontend-admin.ts` if you have ops console access) — aggregate state

A 15-minute polling cadence is usually plenty. Don't hammer the API.

### On the roadmap

See [Outbound Webhook Subsystem PRD](../prd/Outbound%20Webhook%20Subsystem%20PRD.md) for the committed scope and timeline.

## `POST /v1/transactions` is fire-and-forget — you need a retry queue

The Guild integration is designed so that a Guild outage never blocks your user flow. The tradeoff: **you** are responsible for retrying failed calls.

### What happens without a retry queue

If Guild is unreachable for 5 minutes during a spike of settled transactions:

- Your own marketplace continues to function normally
- 5 minutes of commissions are silently not reported to Guild
- Affected users do not receive referral attribution on those transactions
- There is no automatic catch-up

### What a retry queue looks like

See [`examples/retry-queue/`](../../examples/retry-queue/) for a reference implementation. Minimum requirements:

- Persist the transaction payload to your own database **before** calling Guild
- Attempt the Guild call inline
- On failure (any non-2xx, any network error), keep the row in a "pending" state
- Retry with exponential backoff via a worker
- Mark as "complete" only after a 2xx from Guild
- Include a dead-letter escalation path after N retries

### Idempotency key is what makes retries safe

Guild enforces uniqueness on `(tenant_id, idempotency_key)`. A retry with the same key is a no-op — the original result is returned. This is why the key must be **deterministic**:

- ✅ derived from your internal `transaction_id`
- ✅ `sha256(tenant_id + transaction_id)` or just `transaction_id` if it's a UUID you own
- ❌ `Date.now()` — different on every retry, creates duplicates
- ❌ `crypto.randomUUID()` — same problem
- ❌ anything that would be a different value on a retry

## Delinquency: what happens if you miss an invoice

Protocol fees are billed monthly via Stripe Invoice (workflow on the 1st of the month for the prior month's accrued fees).

### If you pay on time

- Nothing changes; program continues
- Your users continue to earn on settled transactions

### If you're late (past due but not long-overdue)

- Program continues for now
- You receive payment reminders from Stripe
- Your users are not affected

### If you're extended-delinquent

- Guild ops escalates
- Program may be paused for your tenant until the invoice is resolved
- **Accrued user balances are preserved** through any pause; users do not lose their ledger state

### If you leave Guild

- You pay the final accrued protocol fee invoice on exit
- Your users' accrued balance becomes a settlement obligation between you and your users
- Guild does not unilaterally clear or transfer user balances

## Uptime expectations

See the [SLA document](./sla.md) for detailed commitments. Short version:

- Core API paths (`/v1/users/link`, `/v1/transactions`, `/v1/wallet/:id`): target **99.9%**
- Hosted pages (`/join`, `/login`, `/wallet`): target **99.9%**
- Settlement workflow (daily, midnight UTC): must complete within 6 hours of scheduled start

If Guild is down, your integration should:

- Queue `/v1/transactions` calls for retry
- Continue operating normally in your own app
- Not block user signups — handle the `/v1/users/link` failure gracefully and retry

## Pre-launch checklist

Run through this before enabling transactions in production:

- [ ] Retry queue for `POST /v1/transactions` built and tested (simulate a 1-hour Guild outage and verify zero drops)
- [ ] Idempotency keys confirmed deterministic via a deliberate retry test
- [ ] User-facing communication of display-only wallet state in your own app copy
- [ ] Finance model accounts for 2x bonus-multiplier dynamics in weeks 1–4
- [ ] Compliance checklist complete (see [Compliance Checklist](./compliance-checklist.md))
- [ ] Decide on billing method: auto-pay (card on file) or manual (net-7 PDF invoices). Either works — set up auto-pay at `/ops/billing` if you want hands-off invoicing.
- [ ] Polling cadence decided for state reads (default: 15 min)
- [ ] Incident notification channel set up (see [SLA](./sla.md) for how to reach us)

## First 30 days: what to watch

- Retry queue depth — should be near zero; spikes indicate Guild trouble
- User signup conversion on `/join` — drop-off indicates SMS deliverability issue in your market
- Reward rate as % of commission — will be elevated in weeks 1–4 due to bonus multiplier
- Protocol fee accrual vs expected — should match your internal model
- Any `reverseTransaction` calls — if >0, validate your fraud response workflow