Subscription plans let customers buy products on a recurring schedule at a discount. A plan's billing frequency is `cadence` (`month` or `week`) multiplied by `interval` (e.g. cadence `month` × interval `3` = every quarter). `discountPercent` is the discount applied versus a one-time purchase. Each plan can be assigned to a set of products that customers may subscribe to.

## List Subscription Plans

```
GET /api/v1/subscription-plans
```

Returns subscription plans ordered by position. Each plan includes the IDs of products it's assigned to.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 50 | Plans per page (1-100) |
| `offset` | `number` | 0 | Plans to skip |
| `query` | `string` | – | Search term for plan name |
| `active` | `boolean` | – | Filter by active status |

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/subscription-plans
```

### Response (200)

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "name": "Monthly delivery",
      "cadence": "month",
      "interval": 1,
      "discountPercent": 10,
      "description": "Delivered every month",
      "benefits": "Free shipping, cancel anytime",
      "position": 0,
      "active": true,
      "productIds": ["0191abc0-0000-7000-8000-000000000200"],
      "createdAt": "2024-06-15T10:30:00.000Z",
      "updatedAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 50
  }
}
```

---

## Get Subscription Plan

```
GET /api/v1/subscription-plans/{id}
```

Returns a single subscription plan by UUID, including assigned product IDs.

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/subscription-plans/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Monthly delivery",
  "cadence": "month",
  "interval": 1,
  "discountPercent": 10,
  "description": "Delivered every month",
  "benefits": "Free shipping, cancel anytime",
  "position": 0,
  "active": true,
  "productIds": ["0191abc0-0000-7000-8000-000000000200"],
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T10:30:00.000Z"
}
```

---

## Create Subscription Plan

```
POST /api/v1/subscription-plans
```

Creates a recurring purchase plan. Assign products by passing their UUIDs in `products`.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Plan display name, e.g. "Monthly delivery" |
| `cadence` | `string` | Yes | Billing cadence unit: `month` or `week` |
| `interval` | `number` | No | Number of cadence units between charges (default: 1) |
| `discountPercent` | `number` | No | Percentage discount vs. one-time purchase (0-100) |
| `description` | `string` | No | Optional plan description |
| `benefits` | `string` | No | Optional plan benefits text |
| `position` | `number` | No | Sort order (lower shows first) |
| `active` | `boolean` | No | Whether the plan is selectable (default: `true`) |
| `products` | `string[]` | No | Product UUIDs offered on this plan (replaces the existing set) |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly delivery",
    "cadence": "month",
    "interval": 1,
    "discountPercent": 10,
    "products": ["0191abc0-0000-7000-8000-000000000200"]
  }' \
  https://your-store.yns.store/api/v1/subscription-plans
```

### Response (201)

Returns the created subscription plan (same shape as Get Subscription Plan).

---

## Update Subscription Plan

```
PATCH /api/v1/subscription-plans/{id}
```

Partially updates a subscription plan. Only provided fields change. Passing `products` replaces the entire assigned product set.

### Request Body

All fields from Create Subscription Plan are accepted and optional.

```bash
curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"discountPercent": 15, "active": false}' \
  https://your-store.yns.store/api/v1/subscription-plans/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

Returns the updated subscription plan.

---

## Delete Subscription Plan

```
DELETE /api/v1/subscription-plans/{id}
```

Hard-deletes the subscription plan by UUID.

```bash
curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/subscription-plans/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "ok": true,
  "deleted": 1
}
```