Guest Author Management & Revenue Payouts

Paid pluginsize Mplanned, not built

Indicative price, not an offer: $40–100/mo, or commission 5–10% on author earnings routed through platform payments

Generated from docs/plan/paid/guest-author-management-revenue-payouts/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Merchants who publish guest content need a system to track author bylines, manage contributions (paid/unpaid), and execute payouts to multiple contributors. This feature ships author profiles, contribution tracking, revenue allocation rules, and integration with payment processors to split earnings automatically.

The problem

Right now I publish guest articles but I have no way to track who wrote what, whether they’ve been paid, or split revenue automatically. I’m managing it manually via email and spreadsheets, which doesn’t scale beyond a handful of authors.

What it does

• Author profile entity (name, email, bio, tax ID, bank account) stored per storage driver
• Contribution ledger: link each post to one or more authors with a role (primary/co-author) and revenue share percentage
• Revenue allocation on order line items: tag which author(s) the sale benefits, calculate splits (integer minor units)
• Payout schedule: daily/weekly/monthly, batch-process payouts to bank accounts or payment methods, mark as complete with transaction ID
• Admin UI: author directory, contribution history, payout status, unpaid balance ledger
• REST API: GET/POST authors, PATCH author profile, GET contribution history, GET payout status
• Webhook events: author.created, contribution.added, payout.initiated, payout.completed
• Audit trail: all payout attempts, reversals, reconciliation

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Tax document generation (W-9/1099/Umsatzsteuer) — that is per-country obligation and compliance, owned by paid infrastructure layer
• Real-time payment method validation — credit/debit/ACH verification is a payment processor concern; we interface through payment provider SDKs only
• Currency conversion — each payout goes in the merchant’s primary currency; multi-currency payouts require the payment layer’s FX handling
• Dispute resolution and chargeback handling — owned by the payment provider, not the CMS
• Author tax withholding — each country has different thresholds and rules; this is why payouts are paid tier (support commitment)

Data model

New entities: Author {id, name, email, bio, tax_id, bank_account, created_at, updated_at}; Contribution {id, post_id, author_id, role, revenue_share_percentage, created_at}; PayoutBatch {id, author_id, amount_minor_units, period_start, period_end, status, transaction_id, attempted_at, completed_at}. Schema migration: add author FK and role field to Contribution. Store across all three drivers using CustomEntity + normalized references.

API

• GET /api/authors — list all authors (paginated)
• POST /api/authors — create author (admin only)
• GET /api/authors/:id — fetch author profile
• PATCH /api/authors/:id — update author (admin only)
• DELETE /api/authors/:id — soft-delete or archive (admin only)
• GET /api/authors/:id/contributions — list authored/co-authored posts
• GET /api/authors/:id/payouts — payout history and balance
• POST /api/payouts/batch — trigger payout run (admin only, requires payment provider credential)
• GET /api/payouts/:batch_id — payout batch status

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Author manager screen: directory with search/filter, add/edit/archive author form (name, email, tax ID, bank account), contribution counter per author. Per-post editor: add/remove authors, set role and revenue share % (must sum to ≤100%). Payout dashboard: calendar view of next scheduled runs, current unpaid balance per author, history of completed batches with transaction IDs, ability to manually trigger or retry failed payouts.

The seam — why this is paid

Core owns the author entity model, contribution ledger, and REST API. Paid layer owns payment processor integration (credentials, API client, retry logic), tax compliance checks (validate tax ID format per country, hold withholding amounts where required), and payout orchestration. The boundary is the PayoutBatch creation: core stores the request; paid layer executes it and returns status.

Paid owns payment processing, per-country tax compliance for author payouts, and support for multi-author workflows. This is a per-country obligation (1099 tax filing, VAT, etc.) and payment infrastructure beyond core.

Dependencies

• Payment provider SDK integration (Stripe Connect or equivalent) must exist to execute payouts
• Audit log system (already shipping in core) must record all payout attempts
• Post entity and order system (already shipped in core)
• Assume: merchant has selected a primary payout currency at setup time

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• An author can be created with name, email, bio, and tax ID; the entry is stored and retrievable
• A post can link to two authors with revenue shares 60%/40%; the shares persist across restarts
• An order for €100 split between two authors generates two payout ledger entries of €60 and €40 (integer minor units)
• A payout batch can be manually triggered; it queries the unpaid balance for each author and returns a summary (amount, count)
• A failed payout attempt is logged with the error reason and can be manually retried
• An author’s historical contributions and total unpaid balance are queryable via API
• A payout for a non-existent bank account fails gracefully and logs the error without crashing the batch

Risks

Payout failures can leave merchants with stuck balances if retry logic is not defensive. Tax withholding thresholds vary per country — a merchant in Germany must not pay an author without collecting tax ID first. Payment processor API downtime blocks payout execution. Concurrent payout requests for the same author could double-pay — mutex required around payout ledger updates. Refunds/cancellations after payout are complex; reversing splits is a manual process initially.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.