Subscription API Reference

Audience: frontend developers and API consumers Scope: current controllers in apps/api/src/modules/subscription

Authentication

Mobile

Base controller: Controller("subscriptions")

• GET /subscriptions/modules is public
• all other mobile subscription endpoints require JwtAuthGuard

Admin

Admin endpoints require:

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

Mobile Endpoints

GET /subscriptions/modules

Public.

Returns active modules with:

• active tiers
• each tier's plan
• each plan's active prices
• each plan's features

GET /subscriptions/plans

Authenticated.

Optional query:

• moduleId uuid

Returns active plans with:

• tier
• module
• active prices
• features

GET /subscriptions/access

Authenticated.

Returns the caller's non-revoked access rows with:

• module
• plan
• computed isActive

GET /subscriptions

Authenticated.

Returns the caller's active/trial subscriptions with lightweight module and plan data.

GET /subscriptions/:id

Authenticated.

Returns one subscription with:

• module
• plan
• plan tier
• plan prices
• plan features
• plan price
• subscription history

POST /subscriptions/trial/:planId

Authenticated.

Starts a trial for the selected plan.

Important current rules:

• planId is a route param
• the plan must be active
• the plan must have trialDays > 0
• the user must not have already consumed a trial for that module
• the user must not already have a live active/trial subscription for that module

Admin Catalog Endpoints

Subscription Modules

Base path: /admin/subscription-modules

Permissions:

• SubscriptionModules_READ
• SubscriptionModules_CREATE
• SubscriptionModules_UPDATE
• SubscriptionModules_DELETE

Routes:

• GET /admin/subscription-modules
• GET /admin/subscription-modules/:id
• POST /admin/subscription-modules
• PATCH /admin/subscription-modules/:id
• DELETE /admin/subscription-modules/:id

Body notes:

• create/update accept name, description, icon, isActive
• slug is generated from name by the service

Subscription Tiers

Base path: /admin/subscription-tiers

Permissions:

• SubscriptionTiers_READ
• SubscriptionTiers_CREATE
• SubscriptionTiers_UPDATE
• SubscriptionTiers_DELETE

Routes:

• GET /admin/subscription-tiers
• GET /admin/subscription-tiers/:id
• POST /admin/subscription-tiers
• PATCH /admin/subscription-tiers/:id
• DELETE /admin/subscription-tiers/:id

Body notes:

• create requires moduleId and name
• optional fields include description, displayOrder, parentTierId, isActive
• slug is generated from name by the service

Subscription Plans

Base path: /admin/subscription-plans

Permissions:

• SubscriptionPlans_READ
• SubscriptionPlans_CREATE
• SubscriptionPlans_UPDATE
• SubscriptionPlans_DELETE

Routes:

• GET /admin/subscription-plans
• GET /admin/subscription-plans/:id
• POST /admin/subscription-plans
• PATCH /admin/subscription-plans/:id
• DELETE /admin/subscription-plans/:id

Body notes:

• create requires tierId and name
• optional fields include description, trialDays, trialRequiresCc, isActive, displayOrder
• current rule: one plan per tier

Subscription Plan Prices

Base path: /admin/subscription-plan-prices

Permissions:

• SubscriptionPlanPrices_READ
• SubscriptionPlanPrices_CREATE
• SubscriptionPlanPrices_UPDATE
• SubscriptionPlanPrices_DELETE

Routes:

• GET /admin/subscription-plan-prices
• GET /admin/subscription-plan-prices/:id
• POST /admin/subscription-plan-prices
• PATCH /admin/subscription-plan-prices/:id
• DELETE /admin/subscription-plan-prices/:id

Body notes:

• create requires planId, label, durationDays, mrpNpr, spNpr
• optional flags: isBase, isFeatured, isActive, displayOrder
• service validation rejects spNpr > mrpNpr

Subscription Plan Features

Base path: /admin/subscription-plan-features

Permissions:

• SubscriptionPlanFeatures_READ
• SubscriptionPlanFeatures_CREATE
• SubscriptionPlanFeatures_UPDATE
• SubscriptionPlanFeatures_DELETE

Routes:

• GET /admin/subscription-plan-features
• GET /admin/subscription-plan-features/:id
• POST /admin/subscription-plan-features
• PATCH /admin/subscription-plan-features/:id
• DELETE /admin/subscription-plan-features/:id

Body notes:

• create requires planId, moduleId, featureKey, featureText
• optional fields: featureDetails, value, icon, displayOrder, enabled
• feature key must be unique within a plan

Admin Subscription Endpoints

Base path: /admin/subscriptions

Permissions:

• Subscriptions_READ
• Subscriptions_CREATE
• Subscriptions_UPDATE

Routes:

• GET /admin/subscriptions/analytics
• GET /admin/subscriptions
• GET /admin/subscriptions/:id
• POST /admin/subscriptions/grant
• PATCH /admin/subscriptions/:id/extend
• PATCH /admin/subscriptions/:id/revoke

GET /admin/subscriptions

Query supports:

• userId
• moduleId
• status
• standard QueryDto fields:
  • pagination
  • page
  • size
  • sort
  • order
  • search where applicable

POST /admin/subscriptions/grant

Body:

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

Rule:

• either planPriceId or customEndDate must be present

PATCH /admin/subscriptions/:id/extend

Body:

• optional durationDays
• optional newEndDate
• optional adminNote

Rule:

• one of durationDays or newEndDate is required

PATCH /admin/subscriptions/:id/revoke

Body:

• optional adminNote

Behavior:

• revokes current access immediately

Important Non-Endpoints

The following service methods exist but are not currently exposed by the mobile subscription controller:

• createPendingPurchase()
• activateSubscription()
• handlePaymentFailure()

Do not rely on older docs that describe payment initiation and verification endpoints under the current subscription controller.