# Operator FAQ

Honest answers to the diligence questions marketplace operators actually ask.

## Economics

### How much does Guild cost?

9% of your settled platform commission. No SaaS fee. No per-transaction API fee. No user-volume fee.

You report your contribution margin via `contribution_margin_cents` on `POST /v1/transactions`. Contribution margin = your platform's revenue from a transaction minus its direct variable costs. The Guild takes 30% of that.

Example: $100 sale, 10% platform fee = $10 revenue, $1 payment processing cost → contribution margin = $9. Guild's protocol fee = $0.81 (9% of $9). User reward pool = $1.89 (21% of $9).

### Does Guild audit or validate the contribution margin I report?

**No.** Guild operates on the honor system — you report an integer, Guild takes 30% of it, and that's the end of the math. There is no validation, no cross-check against gross, no warnings, no auditing.

Every marketplace defines contribution margin differently depending on its cost structure. Rather than enforce a one-size-fits-all rule that would be wrong for most tenants, we trust you to report a number that reflects your real economics. If you under-report, your users' reward pool shrinks and the viral loop weakens. If you over-report, your bill goes up. Report in good faith — both sides work.

### Is the rate negotiable?

Not in v1. Every marketplace pays the same rate regardless of volume. See [Per-Tenant Rate Negotiation PRD](../prd/Per-Tenant%20Rate%20Negotiation%20PRD.md) for the committed roadmap on enterprise rate negotiation.

### When does Guild actually get paid?

Monthly. Protocol fees accrue to a ledger liability throughout the month. On the 1st of the following month, Guild's Temporal billing workflow generates a Stripe Invoice to your marketplace for the prior month's total. Net terms are auto-charge if a payment method is on file; net-7 otherwise.

### Do I have to set up Stripe to pay you?

No. Stripe auto-pay is optional. You have two options:

**Auto-pay (recommended for scale):** Add a card via the [Billing page in your ops console](https://guildapi.dev/ops/billing) — click "Set up auto-pay". You'll be taken to a Stripe-hosted portal to enter your card. After that, monthly invoices charge automatically on the 1st. You can add, change, or remove your card there at any time.

**Manual / wire (fine for early-stage or enterprise):** Don't set up anything. Invoices will be sent as net-7 PDFs to your operator email. Pay by card link, ACH, or wire — whatever works for your accounts payable process.

Fees accrue either way. The only difference is how you receive and pay the invoice. You can switch to auto-pay at any time from `/ops/billing`.

### How do I set up auto-pay later if I skipped it at signup?

Go to `/ops/billing` in your ops console and click "Set up auto-pay". It takes about 60 seconds — we'll ask for your card details on a Stripe-hosted page and redirect you back. No re-signup or new credentials needed.

### When do users get paid?

Tokens accrue on every settled transaction you report. Daily at midnight UTC, tokens are priced against that tenant's daily reward pool, and each user's `balance_cents` is updated in the append-only wallet ledger.

**Cash withdrawal is display-only at v1 launch.** Users see their balance but cannot redeem until our payouts integration ships. Redemption will offer Visa prepaid, Amazon, Venmo, ACH, and 1000+ retailer gift cards (via [Tremendous](https://tremendous.com), so no per-user KYC for amounts under the IRS $2000/year reporting threshold). See [Launch Readiness](./launch-readiness.md).

## Integration

### How long does integration take?

Minimum integration is two API calls:

- `POST /v1/users/link` when a user signs up on your marketplace
- `POST /v1/transactions` when a commission settles

A competent engineer with the [onboarding guide](../onboarding/marketplace-onboarding.md) open should have a staging integration working in 2–4 hours. Production-ready (with retry queue, idempotency discipline, observability) is a 1–3 day project depending on how your transaction pipeline is structured.

### Can I host the join/wallet pages on my own domain?

Not in v1. `/join`, `/login`, `/wallet` are served from `guildapi.dev` with tenant-specific branding. White-label hosting is post-v1 scope.

### What about my existing authentication system?

Guild's hosted auth uses Stytch SMS OTP as its user identity primitive. Your marketplace's auth and Guild's auth are linked at signup via `POST /v1/users/link`, which takes your internal `marketplace_user_id` and returns a `tenant_user_id`.

You continue to authenticate users on your marketplace however you already do. Guild only owns authentication for the hosted reward pages.

### Does Guild work for non-US marketplaces?

Technically yes. Practically, there are considerations:

- SMS OTP via Stytch works globally but deliverability varies
- Protocol fee invoicing is in USD today
- User payout rails (when enabled) use Stripe Connect, which has country limits
- Tax and compliance posture (see [Compliance Checklist](./compliance-checklist.md)) is US-focused in our current docs

Reach out directly if you're operating primarily outside the US.

## Data and ownership

### Can I get my referral graph if I leave Guild?

Not today. See [Tenant Graph Export PRD](../prd/Tenant%20Graph%20Export%20PRD.md) for committed roadmap work.

We recognize this is a data-lock-in concern and are building toward resolving it. In the meantime: if you are evaluating Guild and this is a blocker, tell us — we will work out a custom export arrangement as a contractual commitment.

### Who owns user data?

You own the relationship with your users. Guild stores:

- Hashed phone number (SHA-256 of normalized E.164)
- Internal IDs (`guild_user_id`, `tenant_user_id`)
- Referral graph edges scoped to your tenant
- Settled transaction records you reported
- Append-only wallet ledger

Guild does not store transaction-level PII beyond what you send in `POST /v1/transactions`.

### Is Guild part of a larger network?

Yes. The Guild is wired into the **Serendipity Network**, a portfolio-wide trust graph that spans every marketplace in the ecosystem.

**Today (shipping):** Your integration automatically contributes canonical v3 signals — verified signups, referral edges, and settled-commission events — to the network. You do nothing extra; emission is atomic with your business writes and happens behind the existing `/v1/users/link` and `/v1/transactions` endpoints.

**What you get from contributing today:** portfolio-wide identity resolution (a user verified on another Guild marketplace is recognized on yours instantly), cross-marketplace anti-fraud posture, and a durable place in the graph that grows more valuable as the portfolio grows.

**On the roadmap:** the read-side — network-derived recommendations, cross-marketplace reputation scores, and an optional reputation-aware bonus multiplier. See the [Network-Derived Recommendations PRD](../prd/Network-Derived%20Recommendations%20PRD.md).

Full detail in [Network Participation](./network-participation.md).

### Is user data shared across marketplaces in the portfolio?

Identity is portfolio-scoped: one person with one phone number is one `guild_user` across all Guild marketplaces. This lets them sign into their wallet on any Guild marketplace without a new account.

**However:** referral graphs and earning records are **tenant-local**. Your users' earning history on your marketplace is not visible to other Guild marketplaces. Another marketplace can see that a `guild_user` exists, but not what they've earned or with whom on your platform.

See the [main PRD's tenant-scoped cash attribution section](../prd/The%20Guild%20PRD.md#2-why-marketplaces-integrate) for the full model.

### What about GDPR / CCPA / data subject requests?

Guild supports user deletion via the Event Hub `user.deletion_requested` event, initiated by your app's normal GDPR/CCPA flow. See [Compliance Checklist - Privacy](./compliance-checklist.md#privacy-and-data-handling).

## Reliability

### What's your uptime commitment?

Target 99.9% on core API paths, rolling 30-day window. See [SLA document](./sla.md) for full detail including data durability, incident response, and deprecation policy.

### What happens if Guild has an outage during my peak traffic?

Your marketplace continues to operate normally if you have implemented the recommended [retry queue pattern](./launch-readiness.md#postv1transactions-is-fire-and-forget--you-need-a-retry-queue). Settled commissions queue locally and flush to Guild when we're back.

### Is there a status page?

Not yet. Planned. Until it ships, Guild ops notifies affected tenants via email on any external-impacting incident.

### What if I need to contact you urgently?

- Incidents: `incidents@guildapi.dev`
- Security: `security@guildapi.dev`
- General: `support@guildapi.dev`

## Compliance and legal

### Do I need to register as an MLM?

Maybe. The Guild model is a 3-level-deep referral structure with a new-user bonus multiplier. In several US states this triggers registration or disclosure obligations. See [Compliance Checklist - Multi-level payout structure](./compliance-checklist.md#multi-level-payout-structure) for the detailed list and action items.

Get counsel review before launch. Guild does not provide legal advice.

### Who issues 1099s to earning users?

You do. User rewards flow from your Stripe connected account to users' accounts. You are the payer of record, not Guild. See [Compliance Checklist - Tax reporting](./compliance-checklist.md#tax-reporting-us-marketplaces) for the detailed obligation.

### Is Guild a money transmitter?

No. Guild never holds user funds. Stripe is the licensed money transmitter; Guild issues transfer instructions to Stripe on your behalf. Guild's own Stripe balance only holds Guild's protocol fee revenue.

### Can Guild shut off my tenant unilaterally?

Operationally, yes — Guild ops can disable a tenant's API keys, pause their settlement workflows, and stop accepting their transactions. In practice, this happens only in response to:

- Unresolved protocol fee delinquency (after multiple reminders and escalation)
- Confirmed fraud or abuse
- Regulatory action

Accrued user balances are preserved through any pause. User ledger state is not unilaterally cleared.

## Strategic

### Why is there no SaaS subscription?

By design. v1 revenue comes entirely from protocol fees on settled commission. Guild earns when you earn; Guild doesn't earn when you don't. This is a deliberate alignment of incentives.

Post-v1 may introduce premium analytics tiers, white-label deployments, or per-transaction API fees for specific use cases. Protocol-fee-only remains the default.

### What happens if Guild goes out of business?

- Your users' accrued balances become a settlement obligation between you and your users (Guild never holds the funds)
- The monthly WORM snapshots of settlement state are in an Object-Lock bucket you can recover from if needed
- We would provide a minimum 90 days notice and a graph export before any wind-down

### Why should I trust Guild over building this myself?

A working referral program needs: auth, ledgers, idempotency, reversals, daily settlement, notifications, a referral graph, hosted user pages, tax workflow integration, and immutable audit trails. That's a 6–12 month build with ongoing maintenance.

Guild ships it on day one for 9% of commission. The rate becomes a real question only if your settled commission volume is very large — in which case, see [Per-Tenant Rate Negotiation PRD](../prd/Per-Tenant%20Rate%20Negotiation%20PRD.md).

### I have a question not covered here.

Ask us directly. We would rather answer a hard question privately than lose trust over an unanswered public one.

`support@guildapi.dev`