Subscriptions
The SubscriptionManagementService manages the complete subscription lifecycle for tenants. Subscriptions link tenants to pricing plans and control their access to platform features and resources. The service supports plan changes, pausing, resuming, cancellation, discounts, and credit management.
Subscription Endpoints
Get Active Subscription
Endpoint: GET /api/v1/billing/tenants/:tenantId/subscription
List All Subscriptions
Endpoint: GET /api/v1/billing/tenants/:tenantId/subscriptions
Create Subscription
Endpoint: POST /api/v1/billing/tenants/:tenantId/subscriptions
| Parameter | Type | Description |
|---|---|---|
planId | UUID | Plan to subscribe to |
stripeCustomerId | String | Optional Stripe customer ID |
curl -X POST "http://localhost:8087/api/v1/billing/tenants/550e8400/subscriptions?planId=plan-pro" \
-H "Authorization: Bearer ${TOKEN}"Plan Management
Change Plan
Endpoint: POST /api/v1/billing/subscriptions/:subscriptionId/change-plan
| Parameter | Type | Description |
|---|---|---|
newPlanId | UUID | Target plan ID |
Handles prorated billing for mid-cycle plan changes. Syncs with Stripe if a Stripe subscription exists.
List Available Plans
Endpoint: GET /api/v1/billing/plans
Get Plan Details
Endpoint: GET /api/v1/billing/plans/:planId
Subscription Lifecycle
Cancel
Endpoint: POST /api/v1/billing/subscriptions/:subscriptionId/cancel
| Parameter | Type | Default | Description |
|---|---|---|---|
immediately | boolean | false | Cancel immediately or at period end |
reason | String | null | Cancellation reason |
Reactivate
Endpoint: POST /api/v1/billing/subscriptions/:subscriptionId/reactivate
Reactivates a cancelled subscription before its end date.
Pause
Endpoint: POST /api/v1/billing/subscriptions/:subscriptionId/pause
Temporarily suspends billing and access without cancelling.
Resume
Endpoint: POST /api/v1/billing/subscriptions/:subscriptionId/resume
Resumes a paused subscription.
Discounts and Credits
Apply Discount
Endpoint: POST /api/v1/billing/subscriptions/:subscriptionId/discount
| Parameter | Type | Description |
|---|---|---|
discountPercent | BigDecimal | Discount percentage (0-100) |
endDate | LocalDate | Discount expiration date |
Add Credits
Endpoint: POST /api/v1/billing/subscriptions/:subscriptionId/credits
| Parameter | Type | Description |
|---|---|---|
amount | BigDecimal | Credit amount in base currency |
reason | String | Reason for credit (optional) |
Billing Preview
Preview Current Period
Endpoint: GET /api/v1/billing/tenants/:tenantId/billing/preview
Shows what the current billing period invoice would look like based on usage so far.
Monthly Estimate
Endpoint: GET /api/v1/billing/tenants/:tenantId/billing/estimate
Projects the estimated monthly total based on current usage trends.
{
"estimatedMonthlyTotal": 2450.00
}