## Subscription API Documentation

This API allows users to interact with subscription plans, view purchased subscriptions, buy new ones, and check the
status of existing subscriptions. Authentication is required for all the endpoints, and the requests should use the
appropriate token.

### List of Contents

- [List Subscription Plans](#1-list-subscription-plans)
- [List Purchased Subscriptions](#2-list-purchased-subscriptions)
- [Purchase Subscription](#3-purchase-subscription)
- [Check Subscription Status](#4-check-subscription-status)

### Authentication

- Authentication is handled using [Sanctum](https://laravel.com/docs/sanctum) tokens. Ensure that you include a valid
  token in the `Authorization` header of your requests to access protected endpoints.

### Content Type

- All API endpoints operate with `application/json` for both requests and responses.

---

#### 1. List Subscription Plans

- **Endpoint**: `POST /api/v1/subscription/plans`
- **Description**: Retrieves a list of all available subscription plans.
- **Authentication**: Yes
- **Permissions**: User or Team

##### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": [
        {
            "id": 1,
            "name": "Basic Plan",
            "status": "active",
            "type": "monthly",
            "base_price": 99.99,
            "additional_user_price": 9.99
        },
        {
            "id": 2,
            "name": "Premium Plan",
            "status": "active",
            "type": "yearly",
            "base_price": 499.99,
            "additional_user_price": 19.99
        }
    ]
}
```

---

#### 2. List Purchased Subscriptions

- **Endpoint**: `POST /api/v1/subscription/purchased`
- **Description**: Retrieves a list of subscriptions purchased by the user or a specified team.
- **Authentication**: Yes
- **Permissions**: User or Team

##### Request Parameters:

| Parameter | Required/Optional | Type    | Description                                                                                                             |
|-----------|-------------------|---------|-------------------------------------------------------------------------------------------------------------------------|
| `team_id` | Optional          | Integer | The ID of the team if the subscription is for a team. (if not provided, current authenticated user's ID would be used). |

##### Request Example:

```json
{
    "team_id": 5
}
```

##### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": [
        {
            "id": 3,
            "plan": {
                "id": 1,
                "name": "Basic Plan",
                "type": "team"
            },
            "additional_user_const": 3000,
            "status": "active",
            "start_date": "2024-09-01",
            "end_date": "2025-09-01",
            "purchased_at": "2024-09-01T10:00:00.000000Z"
        },
        {
            "id": 4,
            "plan": {
                "id": 2,
                "name": "Premium Plan",
                "type": "team"
            },
            "additional_user_const": 15000,
            "status": "expired",
            "start_date": "2023-09-01",
            "end_date": "2024-09-01",
            "purchased_at": "2023-09-01T10:00:00.000000Z"
        }
    ]
}
```

---

#### 3. Purchase Subscription

- **Endpoint**: `POST /api/v1/subscription/purchase`
- **Description**: Allows the user or a team to purchase a subscription plan.
- **Authentication**: Yes
- **Permissions**: User or Team

##### Request Parameters:

| Parameter          | Required/Optional | Type    | Description                                           |
|--------------------|-------------------|---------|-------------------------------------------------------|
| `plan_id`          | Required          | Integer | The ID of the subscription plan to purchase.          |
| `team_id`          | Optional          | Integer | The ID of the team if the subscription is for a team. |

##### Request Example:

```json
{
    "plan_id": 1,
    "team_id": 5
}
```

##### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": {
        "order_id": 1,
        "amount": 450000,
        "tracking_code": "2024091841369",
        "uuid": "49a92585-83a8-47f0-8468-675b303fb7bc",
        "payment_type": "payment"
    }
}
```

---

#### 4. Check Subscription Status

- **Endpoint**: `POST /api/v1/subscription/status`
- **Description**: Retrieves the status of a specific subscription.
- **Authentication**: Yes
- **Permissions**: User or Team

##### Request Parameters:

| Parameter         | Required/Optional | Type    | Description                                     |
|-------------------|-------------------|---------|-------------------------------------------------|
| `subscription_id` | Required          | Integer | The ID of the subscription to check the status. |

##### Request Example:

```json
{
    "subscription_id": 3
}
```

##### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": {
        "id": 3,
        "purchaser": {
            "id": 1,
            "name": "John Doe",
            "email": "john.doe@example.com"
        },
        "plan": {
            "id": 1,
            "name": "Basic Plan",
            "type": "user"
        },
        "additional_user_const": 3,
        "status": "active",
        "start_date": "2024-09-01",
        "end_date": "2025-09-01",
        "purchased_at": "2024-09-01T10:00:00.000000Z"
    }
}
```

---