> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción

> Gestiona las suscripciones de tus clientes.

## ¿Qué es una Suscripción?

Una suscripción automatiza cobros recurrentes a un cliente. Se crea asociando un [cliente](/client/customers/index) a un [plan](/client/plans/index) con un método de pago autorizado (tarjeta o cuenta bancaria).

<Note>
  Antes de crear una suscripción, necesitas:

  1. Un [cliente](/client/customers/index) registrado
  2. Un [plan](/client/plans/index) configurado con monto y frecuencia
  3. Una [tarjeta](/client/cards/index) o [cuenta bancaria](/client/accounts/index) autorizada
</Note>

## Ejemplo Rápido

### Paso 1: Crear un plan

```bash theme={null}
curl https://api.onepay.la/v1/plans \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Premium Mensual",
    "amount": 50000,
    "currency": "COP",
    "cycle_frequency": 1,
    "cycle_type": "monthly"
  }'
```

**Respuesta:**

```json theme={null}
{
  "id": "9e5a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "name": "Plan Premium Mensual",
  "amount": 50000,
  "currency": "COP",
  "cycle_frequency": 1,
  "cycle_type": "monthly"
}
```

### Paso 2: Crear una suscripción

```bash theme={null}
curl https://api.onepay.la/v1/subscriptions \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: subscription-001" \
  -d '{
    "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
    "plan_id": "9e5a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "card_id": "9e01eeae-2868-4564-9d04-84d1d1d027d2"
  }'
```

**Respuesta:**

```json theme={null}
{
  "id": "9e5a2b3c-1234-5678-9abc-def012345678",
  "status": "ACTIVE",
  "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
  "plan_id": "9e5a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "card_id": "9e01eeae-2868-4564-9d04-84d1d1d027d2",
  "next_billing_date": "2025-03-08T00:00:00.000000Z",
  "created_at": "2025-02-08T15:45:00.000000Z"
}
```

OnePay cobrará automáticamente \$50.000 cada mes al método de pago autorizado.

## ¿Cuándo usar Suscripciones?

| Escenario                           | Solución                                                                  |
| ----------------------------------- | ------------------------------------------------------------------------- |
| Cobro único o esporádico            | Usa [Payments](/client/payments/index) o [Charges](/client/charges/index) |
| Cobro recurrente con monto fijo     | Crea un plan + suscripción                                                |
| Membresías mensuales/anuales        | Crea un plan + suscripción                                                |
| Cobro recurrente con monto variable | Usa [Charges](/client/charges/index) con tu propia lógica de recurrencia  |

## Relación Plan - Suscripción

Un **plan** es la plantilla (monto, frecuencia) y una **suscripción** es la instancia asociada a un cliente específico.

```
Plan "Premium $50.000/mes"
  ├── Suscripción de Cliente A (activa)
  ├── Suscripción de Cliente B (activa)
  └── Suscripción de Cliente C (cancelada)
```

## Estados de una suscripción

```mermaid theme={null}
stateDiagram-v2
    [*] --> CREATED
    CREATED --> ACTIVE: Pago aprobado
    ACTIVE --> UNPAID: Pago fallido
    UNPAID --> PASS_DUE: Intentos fallidos agotados
    PASS_DUE --> CANCELED: Cancelación
    ACTIVE --> CANCELED: Cancelada por la empresa
    ACTIVE --> FROZEN: Congelada a petición del cliente
    FROZEN --> ACTIVE: Reactivada
    ACTIVE --> FINISHED: Finaliza por vigencia del contrato
    CANCELED --> [*]
    FINISHED --> [*]
```

| Estado     | Descripción                                             |
| ---------- | ------------------------------------------------------- |
| `CREATED`  | Suscripción creada, pendiente del primer pago           |
| `ACTIVE`   | Pagos al día, cobros automáticos activos                |
| `UNPAID`   | Último pago fallido, se reintentará según configuración |
| `PASS_DUE` | Todos los reintentos fallaron                           |
| `FROZEN`   | Pausada temporalmente a petición del cliente            |
| `CANCELED` | Cancelada definitivamente                               |
| `FINISHED` | Completó su vigencia                                    |

## Endpoints

| Método   | Endpoint                      | Descripción                |
| -------- | ----------------------------- | -------------------------- |
| `POST`   | [/subscriptions](create)      | Crear suscripción          |
| `GET`    | [/subscriptions](list)        | Listar suscripciones       |
| `GET`    | [/subscriptions/{id}](detail) | Detalle de una suscripción |
| `DELETE` | [/subscriptions/{id}](delete) | Cancelar suscripción       |