Subscription System API Testing Guide

Development: http://localhost:3000
Staging: https://api-stg.kulcare.com

Authorization: Bearer <your_jwt_token>

curl -X GET "http://localhost:3000/billing/subscription_plans?region=IN"

{
  "data": [
    {
      "id": "plan-uuid-1",
      "name": "Essential",
      "tier": "starter",
      "billing_cycle": "monthly",
      "region": "IN",
      "currency": "INR",
      "price": "575.84",
      "price_inr": "575.84",
      "price_usd": "7.0",
      "price_aed": "25.0",
      "features": {
        "patients_per_day": 10,
        "queue_appointments": true,
        "billing": true,
        "video_consultations": true,
        "digital_prescriptions": true,
        "mobile_apps": true,
        "clinic_website": false
      },
      "limits": {
        "monthly_appointments": 300,
        "locations": 1,
        "doctors": 3,
        "staff": 2
      },
      "trial_days": 14,
      "is_active": true
    }
  ]
}

curl -X GET "http://localhost:3000/billing/subscription_plans/plan-uuid-1"

curl -X POST "http://localhost:3000/billing/subscriptions/initiate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan-uuid-1",
    "facility_id": "facility-uuid"
  }'

{
  "data": {
    "gateway": "razorpay",
    "gateway_subscription_id": "sub_XXXXXXXXXX",
    "gateway_key": "rzp_test_XXXXXXXXXX",
    "amount": 575.84,
    "currency": "INR",
    "plan_id": "plan-uuid-1",
    "plan_name": "Essential",
    "billing_cycle": "monthly",
    "trial_days": 14,
    "customer_id": "billing-customer-uuid",
    "promo_code": null
  }
}

curl -X POST "http://localhost:3000/billing/subscriptions/verify" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_XXXXXXXXXX",
    "subscription_id": "sub_XXXXXXXXXX",
    "signature": "hmac_sha256_signature_here",
    "plan_id": "plan-uuid-1",
    "facility_id": "facility-uuid",
    "customer_id": "billing-customer-uuid"
  }'

{
  "data": {
    "id": "sub-uuid-new",
    "status": "trial",
    "amount": "575.84",
    "currency": "INR",
    "billing_cycle": "monthly",
    "start_date": "2026-04-07",
    "end_date": "2026-05-07",
    "trial_end_date": "2026-04-21",
    "next_billing_date": "2026-04-21",
    "gateway_subscription_id": "sub_XXXXXXXXXX",
    "gateway": "razorpay",
    "plan": { ... }
  }
}

curl -X GET "http://localhost:3000/billing/subscriptions/current" \
  -H "Authorization: Bearer <token>"

{
  "data": {
    "id": "sub-uuid-1",
    "plan_id": "plan-uuid-1",
    "status": "active",
    "billing_cycle": "monthly",
    "currency": "INR",
    "amount": "575.84",
    "start_date": "2026-04-07",
    "end_date": "2026-05-07",
    "trial_end_date": null,
    "next_billing_date": "2026-05-07",
    "gateway_subscription_id": "sub_XXXXXXXXXX",
    "plan": {
      "id": "plan-uuid-1",
      "name": "Essential",
      "tier": "starter",
      "region": "IN",
      "currency": "INR",
      "price": "575.84"
    }
  }
}

curl -X POST "http://localhost:3000/billing/subscriptions/change_plan" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "new-plan-uuid"
  }'

curl -X POST "http://localhost:3000/billing/subscriptions/sub-uuid/cancel" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"at_cycle_end": true, "reason": "Switching to a different solution"}'

curl -X GET "http://localhost:3000/billing/payment_methods?facility_id=facility-uuid" \
  -H "Authorization: Bearer <token>"

curl -X POST "http://localhost:3000/billing/payment_methods" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "facility_id": "facility-uuid",
    "method_type": "card",
    "gateway_token": "tok_razorpay_xxx",
    "last_four": "4242",
    "card_brand": "Visa"
  }'

curl -X DELETE "http://localhost:3000/billing/payment_methods/pm-uuid" \
  -H "Authorization: Bearer <token>"

curl -X PUT "http://localhost:3000/billing/payment_methods/pm-uuid/set_default" \
  -H "Authorization: Bearer <token>"

curl -X POST "http://localhost:3000/billing/promo_codes/validate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "WELCOME20", "plan_id": "plan-uuid-1"}'

{
  "data": {
    "valid": true,
    "code": "WELCOME20",
    "discount_type": "percentage",
    "discount_amount": null,
    "discount_percentage": 20.0
  }
}

# 1. List plans for India
curl -X GET "http://localhost:3000/billing/subscription_plans?region=IN"

# 2. Check no existing subscription
curl -X GET "http://localhost:3000/billing/subscriptions/current" \
  -H "Authorization: Bearer TOKEN"

# 3. Initiate checkout
curl -X POST "http://localhost:3000/billing/subscriptions/initiate" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "PLAN_ID", "facility_id": "FACILITY_ID"}'
# Save gateway_subscription_id from response

# 4. (In browser) Open Razorpay checkout with the subscription_id
# Or skip to step 5 if testing verify directly with known payment data

# 5. Verify payment (after Razorpay callback)
curl -X POST "http://localhost:3000/billing/subscriptions/verify" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_XXXXX",
    "subscription_id": "sub_XXXXX",
    "signature": "HMAC_SIGNATURE",
    "plan_id": "PLAN_ID",
    "facility_id": "FACILITY_ID"
  }'

# India plans only
curl "http://localhost:3000/billing/subscription_plans?region=IN"
# Should return 8 plans (Essential + Premium x 4 billing cycles)

# US plans only
curl "http://localhost:3000/billing/subscription_plans?region=US"
# Should return 8 plans with USD pricing

# All plans (no region filter)
curl "http://localhost:3000/billing/subscription_plans"
# Should return 24 active plans (8 per region)

# Region mismatch (IN facility subscribing to US plan)
curl -X POST "http://localhost:3000/billing/subscriptions/initiate" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"plan_id": "US_PLAN_ID", "facility_id": "IN_FACILITY_ID"}'
# Expected: 422 "This plan is not available for your facility's region"

# Duplicate subscription
curl -X POST "http://localhost:3000/billing/subscriptions/initiate" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"plan_id": "PLAN_ID", "facility_id": "ANY_FACILITY_OF_A_SUBSCRIBED_TENANT"}'
# Expected: 422 "This tenant already has an active subscription"
# Any facility of that tenant trips it — the subscription covers the tenant.

# Cross-region plan change
# (subscribe to IN plan, then try changing to US plan)
# Expected: 422 "Cannot change to a plan from a different region"

cd backend
bundle exec rake billing:seed_go_forward_plans
# Seeds Essential and Premium (IN, monthly), their price rows and their
# Cashfree plan IDs. Safe to re-run. On a development database, db:seed
# does the same.