Admin Subscription Workflow

Audience: backend, admin frontend, QA Scope: current admin routes and behaviors

Admin Route Groups

The current admin surface is split across six route groups:

All admin endpoints require:

• JwtAuthGuard
• RoleGuard
• matching @Permissions(...)

Catalog Setup Workflow

The current recommended setup order is:

1. create a subscription module
2. create tiers for that module
3. create one plan per tier
4. create one or more prices for the plan
5. create plan features

Important current rules:

• module slug is generated from module name in the service layer
• tier slug is generated from tier name in the service layer
• a tier belongs to exactly one module
• a tier can have only one plan
• a plan can have many prices
• a plan can have many features

Delete Semantics

Older docs described soft delete in several places. That is no longer accurate for this module.

Current behavior:

• modules are hard-deleted, but deletion is blocked if the module still has tiers
• tiers are hard-deleted, but deletion is blocked if the tier still has a plan
• plans are hard-deleted, but deletion is blocked if subscriptions reference the plan
• plan prices are hard-deleted
• plan features are hard-deleted

Inactive states still exist on several tables, but the controller delete endpoints are actual deletes.

Admin Grant

POST /admin/subscriptions/grant

Body:

• userId
• planId
• optional planPriceId
• optional customEndDate
• optional adminNote

Rules:

• either planPriceId or customEndDate must be provided
• the module is derived from the selected plan
• if the user already has a live active/trial subscription for that module, the existing row is updated
• otherwise a new active subscription is created

Side effects:

• subscription history gets admin_granted
• user_access is created or updated with grantType = "admin_grant"

Admin Extend

PATCH /admin/subscriptions/:id/extend

Body:

• optional durationDays
• optional newEndDate
• optional adminNote

Rules:

• one of durationDays or newEndDate is required
• newEndDate takes precedence if both are sent
• extension always updates the subscription and matching user_access

Side effects:

• subscription history gets admin_extended
• user access history gets extended

Admin Revoke

PATCH /admin/subscriptions/:id/revoke

Body:

• optional adminNote

Behavior:

• only live active or trial subscriptions can be revoked
• subscription status changes to cancelled
• cancelledAt = now
• cancelsAt = now
• matching user_access.revokedAt = now
• user access history gets revoked

This is immediate revocation, not period-end cancellation.

Analytics and Read APIs

/admin/subscriptions also exposes:

• GET /admin/subscriptions/analytics
• GET /admin/subscriptions
• GET /admin/subscriptions/:id

Analytics currently return:

• total active
• total trial
• total cancelled
• total expired
• total pending payment
• active/trial counts grouped by module

Workflow Summary