SipSop Commissions Module
A complete commission management system for intermediary sales reps (1099 contractors and MSP staff). Calculates, materializes, and pays commissions on the SaaS revenue from the tenants each rep brought in.
What it solves
SipSop bills its tenants via Stripe on a monthly basis. This module connects each tenant payment to the reps who brought them in, calculates how much each one is owed, generates a downloadable PDF statement, and keeps a record of who paid what and when.
Module sub-phases
The module was built in 4 cumulative sub-phases. Each one extends the previous.
| Sub-phase | Name | What it delivers |
|---|---|---|
| F-CMS-1 | MSP Core | CRUD for reps, assignments, revenue events, calculation engine, statement lifecycle, PDF, monthly cron |
| F-CMS-2 | Multi-rep + MLM | N-ary splits per assignment (shares sum to 100%), manager hierarchy with recursive override %, cycle detection |
| F-CMS-3 | Attribution + components | Public ref codes on landing, 90-day first-touch cookie, auto-assignment on lead conversion, different % per revenue component (base / phones / lines / overage) |
| F-CMS-4 | Seller portal | seller role in Better Auth, magic-link invitations, read-only portal /seller/* with 4 views |
Navigation
| Document | Contents |
|---|---|
| Key concepts | Glossary, domain model, roles, vesting |
| Happy path | The complete "Tienda Frescura" story with real numbers |
| Architecture | Schema (8 tables), calculator, statement lifecycle |
| Admin operations | Admin workflows step by step |
| Seller portal | Portal guide for external reps |
| API reference | All tRPC procedures + REST endpoints |
| FAQ | Frequently asked questions and troubleshooting |
| Deploy | Deploying this documentation to Cloudflare Pages |
Quick start (admin)
Three steps to start paying commissions:
1. Create a rep
Admin portal → /admin/commissions/vendedores → New rep. Enter name, email, payment method, and default terms (recurring %, one-time bonus, gross/net basis).
2. Assign a tenant
/admin/commissions/asignaciones → New assignment. Select the tenant and the rep (or multiple reps with their shares). Terms are resolved by cascade: input → rep default → global default.
3. Generate the month's statement
/admin/commissions/statements → Generate → enter the period. The engine calculates commissions on the tenant's revenue_events for that period and materializes a draft statement. Review the line items, finalize, and mark as paid.
The automatic cron runs on the 1st of each month at 3am UTC (configurable in /admin/commissions/configuracion).
Featured example
The Tienda Frescura story shows the complete module in action: 6 characters, a real sale with real numbers, 70/30 splits, 2-level MLM hierarchy, 3-month bonus vesting, and the month-by-month timeline.
Original specs
The 4 design specs live in the repo:
docs/superpowers/specs/2026-05-09-fcms1-comisiones-vendedores-design.mddocs/superpowers/specs/2026-05-10-fcms2-multi-vendedor-mlm-design.mddocs/superpowers/specs/2026-05-10-fcms3-attribution-component-design.mddocs/superpowers/specs/2026-05-10-fcms4-seller-portal-design.md