# Subscription Plan CRUD API Documentation

Base URL: `http://your-domain.com/api`

All endpoints require admin authentication. Include the admin bearer token in the Authorization header.

## Headers (Required for all endpoints)
```
Authorization: Bearer {admin_token}
Content-Type: application/json
Accept: application/json
```

---

## 1. List All Subscription Plans

**Endpoint:** `GET /admin/subscription-plans/list`

**Query Parameters (Optional):**
- `status` (integer): Filter by status (0=inactive, 1=active)
- `type` (integer): Filter by type (1=monthly, 2=yearly, 3=daily)

**Example Request:**
```bash
GET /admin/subscription-plans/list?status=1&type=1
```

**Response (200 OK):**
```json
{
  "status": 200,
  "message": "Subscription plans retrieved successfully",
  "data": {
    "plans": [
      {
        "_id": "657a1b2c3d4e5f6g7h8i9j0k",
        "title": "Essential",
        "active_jobs": 3,
        "ai_candidate_searching": true,
        "candidate_search": true,
        "talent_scoutting": 10,
        "ai_screening": true,
        "live_video_interviews": 5,
        "interview_recording": -1,
        "ai_interview": -1,
        "interview_scheduling": true,
        "recruitment_analytics": true,
        "employer_branding": true,
        "resume_parsing": 100,
        "ai_offer_letter": true,
        "support": "Priority Email",
        "price": 49,
        "type": 1,
        "paypal_plan_id": "P-37A33558MT819350ENE3IQ7Q",
        "description": "Ideal for small teams.",
        "status": 1,
        "created_at": "2024-12-23 10:30:00",
        "updated_at": "2024-12-23 10:30:00"
      }
    ],
    "total": 1
  }
}
```

---

## 2. Get Single Subscription Plan

**Endpoint:** `GET /admin/subscription-plans/get`

**Query Parameters (Required):**
- `plan_id` (string): MongoDB ObjectId of the plan

**Example Request:**
```bash
GET /admin/subscription-plans/get?plan_id=657a1b2c3d4e5f6g7h8i9j0k
```

**Response (200 OK):**
```json
{
  "status": 200,
  "message": "Subscription plan retrieved successfully",
  "data": {
    "plan": {
      "_id": "657a1b2c3d4e5f6g7h8i9j0k",
      "title": "Essential",
      "active_jobs": 3,
      "ai_candidate_searching": true,
      "candidate_search": true,
      "talent_scoutting": 10,
      "ai_screening": true,
      "live_video_interviews": 5,
      "interview_recording": -1,
      "ai_interview": -1,
      "interview_scheduling": true,
      "recruitment_analytics": true,
      "employer_branding": true,
      "resume_parsing": 100,
      "ai_offer_letter": true,
      "support": "Priority Email",
      "price": 49,
      "type": 1,
      "paypal_plan_id": "P-37A33558MT819350ENE3IQ7Q",
      "description": "Ideal for small teams.",
      "status": 1,
      "created_at": "2024-12-23 10:30:00",
      "updated_at": "2024-12-23 10:30:00"
    }
  }
}
```

**Error Response (404 Not Found):**
```json
{
  "status": 404,
  "message": "Subscription plan not found"
}
```

---

## 3. Create Subscription Plan

**Endpoint:** `POST /admin/subscription-plans/create`

**Request Body (All fields required except paypal_plan_id and description):**
```json
{
  "title": "Premium Plan",
  "active_jobs": 10,
  "ai_candidate_searching": true,
  "candidate_search": true,
  "talent_scoutting": 50,
  "ai_screening": true,
  "live_video_interviews": 20,
  "interview_recording": 10,
  "ai_interview": 15,
  "interview_scheduling": true,
  "recruitment_analytics": true,
  "employer_branding": true,
  "resume_parsing": 200,
  "ai_offer_letter": true,
  "support": "24/7 Priority Support",
  "price": 149.99,
  "type": 1,
  "paypal_plan_id": "P-1AB2CD3EF4GH5IJ6KL7MN8OP",
  "description": "Perfect for growing businesses with advanced recruitment needs.",
  "status": 1
}
```

**Field Descriptions:**
- `title` (string, required): Plan name
- `active_jobs` (integer, required): Number of active jobs allowed (-1 for not included, 0 for unlimited)
- `ai_candidate_searching` (boolean, required): Enable AI candidate searching
- `candidate_search` (boolean, required): Enable candidate search
- `talent_scoutting` (integer, required): Number of talent scouts (-1 for not included, 0 for unlimited)
- `ai_screening` (boolean, required): Enable AI screening
- `live_video_interviews` (integer, required): Number of live video interviews (-1 for not included, 0 for unlimited)
- `interview_recording` (integer, required): Number of interview recordings (-1 for not included, 0 for unlimited)
- `ai_interview` (integer, required): Number of AI interviews (-1 for not included, 0 for unlimited)
- `interview_scheduling` (boolean|integer, required): Interview scheduling (true/false or 1/0/-1)
- `recruitment_analytics` (boolean, required): Enable recruitment analytics
- `employer_branding` (boolean, required): Enable employer branding
- `resume_parsing` (integer, required): Number of resume parsing (-1 for not included, 0 for unlimited)
- `ai_offer_letter` (boolean, required): Enable AI offer letter
- `support` (string, required): Support level description
- `price` (numeric, required): Plan price (minimum 0)
- `type` (integer, required): Plan type (1=monthly, 2=yearly, 3=daily)
- `paypal_plan_id` (string, optional): PayPal subscription plan ID
- `description` (string, optional): Plan description
- `status` (integer, required): Plan status (0=inactive, 1=active)

**Response (201 Created):**
```json
{
  "status": 201,
  "message": "Subscription plan created successfully",
  "data": {
    "plan": {
      "_id": "657a1b2c3d4e5f6g7h8i9j0k",
      "title": "Premium Plan",
      "active_jobs": 10,
      "ai_candidate_searching": true,
      "candidate_search": true,
      "talent_scoutting": 50,
      "ai_screening": true,
      "live_video_interviews": 20,
      "interview_recording": 10,
      "ai_interview": 15,
      "interview_scheduling": true,
      "recruitment_analytics": true,
      "employer_branding": true,
      "resume_parsing": 200,
      "ai_offer_letter": true,
      "support": "24/7 Priority Support",
      "price": 149.99,
      "type": 1,
      "paypal_plan_id": "P-1AB2CD3EF4GH5IJ6KL7MN8OP",
      "description": "Perfect for growing businesses with advanced recruitment needs.",
      "status": 1,
      "created_at": "2024-12-23 10:30:00",
      "updated_at": "2024-12-23 10:30:00"
    }
  }
}
```

**Error Response (422 Validation Failed):**
```json
{
  "status": 422,
  "message": "Validation failed",
  "data": {
    "errors": {
      "title": ["The title field is required."],
      "price": ["The price must be at least 0."],
      "type": ["The selected type is invalid."]
    }
  }
}
```

---

## 4. Update Subscription Plan

**Endpoint:** `POST /admin/subscription-plans/update`

**Request Body (Only plan_id is required, all other fields are optional):**
```json
{
  "plan_id": "657a1b2c3d4e5f6g7h8i9j0k",
  "title": "Premium Plan Updated",
  "price": 159.99,
  "status": 1,
  "description": "Updated description for premium plan"
}
```

**Notes:**
- Only include fields you want to update
- All fields from create are supported (except they're optional)
- `plan_id` is always required

**Response (200 OK):**
```json
{
  "status": 200,
  "message": "Subscription plan updated successfully",
  "data": {
    "plan": {
      "_id": "657a1b2c3d4e5f6g7h8i9j0k",
      "title": "Premium Plan Updated",
      "active_jobs": 10,
      "ai_candidate_searching": true,
      "candidate_search": true,
      "talent_scoutting": 50,
      "ai_screening": true,
      "live_video_interviews": 20,
      "interview_recording": 10,
      "ai_interview": 15,
      "interview_scheduling": true,
      "recruitment_analytics": true,
      "employer_branding": true,
      "resume_parsing": 200,
      "ai_offer_letter": true,
      "support": "24/7 Priority Support",
      "price": 159.99,
      "type": 1,
      "paypal_plan_id": "P-1AB2CD3EF4GH5IJ6KL7MN8OP",
      "description": "Updated description for premium plan",
      "status": 1,
      "created_at": "2024-12-23 10:30:00",
      "updated_at": "2024-12-23 12:45:00"
    }
  }
}
```

**Error Response (404 Not Found):**
```json
{
  "status": 404,
  "message": "Subscription plan not found"
}
```

---

## 5. Delete Subscription Plan

**Endpoint:** `POST /admin/subscription-plans/delete`

**Request Body:**
```json
{
  "plan_id": "657a1b2c3d4e5f6g7h8i9j0k"
}
```

**Response (200 OK):**
```json
{
  "status": 200,
  "message": "Subscription plan deleted successfully",
  "data": {
    "plan": {
      "_id": "657a1b2c3d4e5f6g7h8i9j0k",
      "title": "Premium Plan",
      "active_jobs": 10,
      "price": 149.99,
      "type": 1,
      "status": 1
    }
  }
}
```

**Error Response (404 Not Found):**
```json
{
  "status": 404,
  "message": "Subscription plan not found"
}
```

---

## Common Error Responses

### 401 Unauthorized
```json
{
  "status": 401,
  "message": "Unauthorized"
}
```

### 403 Forbidden
```json
{
  "status": 403,
  "message": "Access denied. Admin privileges required."
}
```

### 500 Internal Server Error
```json
{
  "status": 500,
  "message": "Failed to [action] subscription plan",
  "data": {
    "error": "Error details"
  }
}
```

---

## Plan Type Reference

- **1** = Monthly subscription
- **2** = Yearly subscription
- **3** = Daily subscription

## Status Reference

- **0** = Inactive (plan not available for purchase)
- **1** = Active (plan available for purchase)

## Feature Value Reference

For integer fields like `active_jobs`, `talent_scoutting`, etc.:
- **-1** = Feature not included
- **0** = Unlimited
- **Positive number** = Specific limit

For boolean fields:
- **true** = Feature enabled
- **false** = Feature disabled

**Note:** The `interview_scheduling` field accepts both boolean (true/false) and integer (1, 0, -1) values. The value will be stored as provided without type conversion.

---

## Postman Import

To import these APIs into Postman:

1. Create a new collection named "Subscription Plan CRUD"
2. Add an environment variable for `base_url` and `admin_token`
3. Create requests for each endpoint above
4. Set Authorization to "Bearer Token" and use `{{admin_token}}`
5. Set the base URL to `{{base_url}}/api`

### Example Environment Variables:
```json
{
  "base_url": "http://your-domain.com",
  "admin_token": "your-admin-bearer-token-here"
}
```