Billing & Subscription API Specification
========================================

1. Get Current Subscription
---------------------------
Endpoint:
GET /subscriptions/current?tenantId={tenantId}

Response (Trialing User)
{
  "success": true,
  "data": {
    "subscriptionId": "sub_trial_001",
    "planId": "plan_free",
    "planName": "Free Plan",
    "status": "trialing", 
    "trial": {
      "isTrial": true,
      "trialEndsAt": "2025-09-23T00:00:00Z",
      "daysLeft": 14
    },
    "willCancel": true,
    "message": "Your Plan will be cancelled after 14 days. You can upgrade to enjoy more features."
  }
}

Response (Active Paid User)
{
  "success": true,
  "data": {
    "subscriptionId": "sub_789",
    "planId": "plan_basic",
    "planName": "Basic Plan",
    "status": "active",
    "trial": {
      "isTrial": false
    },
    "nextBillingDate": "2025-10-09T00:00:00Z",
    "willCancel": false
  }
}

---------------------------------------------------

2. Upgrade Subscription
-----------------------
Endpoint:
POST /subscriptions/upgrade

Payload
{
  "tenantId": "org_12345",
  "newPlanId": "plan_advance",
  "billingCycle": "monthly", 
  "couponCode": "STARTUP50",   // optional
  "paymentMethodId": "pm_6008"
}

Response (Success)
{
  "success": true,
  "message": "Subscription upgraded successfully",
  "data": {
    "subscriptionId": "sub_789",
    "oldPlanId": "plan_free",
    "newPlanId": "plan_advance",
    "billingCycle": "monthly",
    "amount": 10,
    "discountAmount": 0,
    "tax": 1,
    "totalPaid": 11,
    "currency": "USD",
    "status": "active",
    "nextBillingDate": "2025-10-09T00:00:00Z"
  }
}

Response (Errors)
{
  "success": false,
  "message": "Invalid payment method",
  "errorCode": "PAYMENT_METHOD_INVALID"
}

{
  "success": false,
  "message": "Insufficient funds",
  "errorCode": "PAYMENT_FAILED"
}

{
  "success": false,
  "message": "Plan not found",
  "errorCode": "PLAN_NOT_FOUND"
}

{
  "success": false,
  "message": "Coupon not valid for this plan",
  "errorCode": "COUPON_INVALID"
}

---------------------------------------------------

3. Validate Coupon
------------------
Endpoint:
POST /coupons/validate

Payload
{
  "tenantId": "org_12345",
  "code": "STARTUP50",
  "planId": "plan_basic",
  "billingCycle": "monthly",
  "amount": 40
}

Response (Valid Coupon)
{
  "success": true,
  "message": "Coupon applied successfully",
  "data": {
    "code": "STARTUP50",
    "planId": "plan_basic",
    "billingCycle": "monthly",
    "discountType": "percentage",
    "discountValue": 50,
    "discountAmount": 20,
    "finalAmount": 20,
    "validUntil": "2025-12-31T23:59:59Z"
  }
}

Response (Invalid Coupon)
{
  "success": false,
  "message": "Coupon is expired or not applicable for this plan",
  "errorCode": "COUPON_INVALID"
}