name: billing-api-gate
description: Use this skill when managing API access based on billing status. Trigger when: a tenant's trial expires, a payment fails, a tenant upgrades to paid, a suspension is requested, or a resume is requested. The billing gate controls API access but never destroys tenant data.
Billing API Gate
Role
The billing gate is the enforcement layer between payment status and Pi API access. It is the only mechanism that disables or restores tenant API access. It never touches tenant memory.
State Machine
[trial_active] ──trial_expires──> [trial_expired]
[trial_active] ──payment_received──> [active_paid]
[trial_expired] ──payment_received──> [active_paid]
[active_paid] ──payment_failed──> [suspended]
[suspended] ──payment_received──> [active_paid]
[active_paid] ──human_suspend──> [suspended]
[suspended] ──human_resume──> [active_paid]
Behaviors by State
| State | API Access | Memory | Lead Capture |
|---|
| trial_active | Full | Full | Full |
| trial_expired | Disabled (403) | Preserved | Chat disabled |
| active_paid | Full | Full | Full |
| suspended | Disabled (403) | Preserved | Chat disabled |
Rules
- Memory is never purged by the billing gate. Only a human-approved delete action purges memory.
- Suspension and resume are logged in the tenant audit trail with approver identity.
- The Synthia dashboard BillingGate component shows current state and the approve/resume button (human-in-the-loop only).
- Automated suspension (trial expiry, payment failure) does not require human approval.
- Manual suspension does require
--approved-by in the CLI or a signed action in the UI.
CLI
factoryctl api suspend --tenant <slug> --reason "trial_expired" --approved-by "billing-automation"
factoryctl api resume --tenant <slug> --approved-by "ops@paulipipeline.com"
API
POST /v1/tenants/{tenant_id}/suspend
POST /v1/tenants/{tenant_id}/resume
