# Planes de suscripción

La API Subscription Plans administra los planes definidos por el tenant: límite de anuncios de una cuenta, periodo de vencimiento y tarifas o comisiones por pedido. Es independiente de Memberships (`/v1/memberships`), basada en anuncios y destinada a programas propios de clientes o miembros.

Todos los ejemplos usan autenticación Bearer. El gateway obtiene tenant y usuario de la solicitud autenticada; no envíes encabezados de identidad adicionales.

```bash
export API="https://api.tradly.app"
export TOKEN="<bearer-token>"
```

## Administrar planes

- `GET /v1/subscription_products` lista los planes visibles para el tenant. Los parámetros opcionales incluyen `currency_id`, `account_id` e `include_stats=true`. Los usuarios no administradores solo reciben planes activos y deben proporcionar el contexto de divisa.
- `GET /v1/subscription_products/{id}` devuelve un plan. Los usuarios no administradores solo pueden obtener planes activos y deben proporcionar el contexto de divisa requerido.
- `POST /v1/subscription_products` crea un plan dentro del objeto `subscription_product`. Requiere `title`, `allowed_listings` (entero positivo), `currency_id`, `expiry_days` (entero positivo) y `type`. Valores permitidos: `free_subscription`, `stripe`, `android`, `ios`, `mangopay`.

```bash
curl -X POST "$API/v1/subscription_products" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  --data-raw '{"subscription_product":{"title":"Starter","description":"Starter plan","amount":49.00,"currency_id":13,"expiry_days":30,"allowed_listings":25,"type":"stripe","sku":"starter-monthly","active":true,"fee_fixed_per_order":0,"commission_percent_per_order":0,"metadata":{}}}'
```

La respuesta incluye el nuevo `subscription_product.id`.

- `PUT /v1/subscription_products/{id}` actualiza el plan con el mismo objeto y campos obligatorios. Acepta `stripe`, `android`, `ios`, `mangopay`; este validador no acepta `free_subscription`.
- `DELETE /v1/subscription_products/{id}` archiva el plan y lo marca como inactivo, sin borrar el historial.

## Analítica de planes

Las rutas de analítica están limitadas al tenant autenticado.

| Método | Punto de conexión | Descripción |
|---|---|---|
| `GET` | `/v1/subscription_products/stats` | Estadísticas agregadas de los planes del tenant. |
| `GET` | `/v1/subscription_products/{id}/stats` | Estadísticas de un plan. |
| `GET` | `/v1/subscription_products/{id}/subscribers` | Suscriptores paginados; filtros `page`, `per_page` (máx. 100) y `status` (`active`, `trial`, `expired`, `cancelled`). |
| `GET` | `/v1/subscription_products/{id}/invoices` | Historial de facturación paginado con los mismos filtros, derivado de suscripciones; no hay tabla de facturas independiente. |
| `GET` | `/v1/subscription_products/{id}/revenue` | Series mensuales de ingresos y cantidad de suscriptores. |

Las estadísticas agregadas incluyen recuentos de estados activos, cancelados, vencidos y de prueba, MRR/ARR, tasa de cancelación, altas y bajas del mes, duración media de suscripciones canceladas e ingresos totales registrados. Son métricas operativas y no sustituyen las facturas contables ni el libro mayor.

## Ciclo de vida de la suscripción de clientes

| Método | Punto de conexión | Función |
|---|---|---|
| `GET` | `/v1/subscriptions/subscribe/products?account_id={account_id}` | Lista planes disponibles de una cuenta; filtro opcional `type`. |
| `POST` | `/v1/subscriptions/subscribe` | Confirma una compra móvil con `account_id`, `subscription_product_id` y el recibo `token`; el handler verifica recibos iOS/Android. |
| `POST` | `/v1/subscriptions/subscribe/confirm` | Confirma una compra móvil con los mismos campos obligatorios. |
| `POST` | `/v1/subscriptions/email_trigger` | Envía el correo de invitación a suscribirse a una cuenta apta (`account_id`). |
| `DELETE` | `/v1/subscriptions/unsubscribe` | Cancela la suscripción de una cuenta (`account_id`). |
| `GET` | `/v1/subscriptions/subscribe/manage?account_id={account_unique_id}&tenant_id={tenant_unique_id}` | Abre la página o portal de administración compatible (actualmente Stripe). |

La confirmación de compra actualmente verifica recibos iOS y Android. Los planes `stripe` no se confirman con esos puntos de conexión; usa el flujo de checkout/portal de Stripe configurado. Los puntos de transferencia web usan un contrato heredado distinto y no se muestran aquí como ejemplos de cliente con solo Bearer.

## API relacionadas

- [Membresías](memberships) — membresías basadas en anuncios, aportes y registros de precios.
- [Anuncios](listings) — planes/productos y checkout.