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

# Crea un plan de suscripción

Localpayment te permite crear planes de suscripción fijos para escenarios de facturación recurrente estandarizados. Esta guía detalla cómo configurar planes de suscripción a través de la API de Localpayment, que luego se pueden asociar a las suscripciones de los clientes para una facturación automatizada y consistente.

## Antes de comenzar

Asegúrate de tener:

> [card] [Credenciales de API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md)
>
> Credenciales API válidas y token de acceso para la autenticación.

> [card] [Configuración de la cuenta](https://docs.localpayment.com/es/docs/make-your-first-test-payment.md)
>
> Configuración adecuada de la cuenta para el país de destino y verificación de la empresa.

> [card] [Lista blanca de IP](https://docs.localpayment.com/es/docs/dashboard-whitelist-your-ips.md)
>
> Incluye en la lista blanca las direcciones IP de tus servidores para el acceso a la API.

> [card] [Endpoint del webhook](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura una URL de webhook para recibir notificaciones de pago.

***

## Paso 1: Crea un plan de suscripción

Para crear un nuevo plan de suscripción, envía una solicitud `POST` al endpoint [Crear un plan de suscripción](https://docs.localpayment.com/es/reference/create-subscription-plan).

### Parámetros clave de la solicitud

La solicitud requiere varios objetos clave:

| Parámetro | Descripción | Requerido |
| - | - | - |
| `name` | Nombre descriptivo para el plan de suscripción | ✅ |
| `description` | Explicación detallada de las características y beneficios del plan. | ❌ |
| `country` | Código del país donde estará disponible el plan. | ✅ |
| `amount` | Importe de facturación fijo | ✅ |
| `currency` | Código de moneda para facturación | ✅ |
| `accountNumber` | Tu número de cuenta de comerciante | ✅ |
| `autoRecurring.repetitions` | Número de ciclos de facturación (usa `0` para recurrencia bajo demanda) | ✅ |
| `autoRecurring.type` | Unidad de frecuencia de facturación (usa `custom` para recurrencia bajo demanda) | |

### Frecuencias de facturación admitidas

> [card] A diario
>
> Factura a los clientes todos los días. Ideal para servicios con uso diario o suscripciones
> a corto plazo.
>
> Envía la propiedad `autoRecurring.type` con el valor: `day`

> [card] Mensual
>
> Facturación mensual recurrente para la mayoría de los productos SaaS, servicios de membresía y
> cajas de suscripción.
>
> Envía la propiedad `autoRecurring.type` con el valor: `month`

> [card] Personalizado (bajo demanda)
>
> Facturación bajo demanda para escenarios de uso variable. Ideal para servicios de pago por uso o
> basados en el uso.
>
> Envía la propiedad `autoRecurring.type` con el valor: `custom`

### Ejemplo de solicitud

A continuación se muestra un ejemplo que utiliza `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url https://api.stage.localpayment.com/api/subscriptions/plan \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Plan Básico Mensual",
    "description": "Acceso básico a contenido exclusivo",
    "country": "MEX",
    "amount": 50,
    "currency": "MXN",
    "accountNumber": "{{accountNumber}}",
    "autoRecurring": {
      "repetitions": 1,
      "type": "hour"
    }
  }'
```

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/es/reference/create-subscription-plan) en la solicitud.

***

## Paso 2: Gestionar la respuesta

### Respuesta exitosa

Un plan de suscripción creado correctamente devuelve todos los detalles del plan:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "internalId": "70af52e2-ea99-46a8-a931-65f15f6a3c20",
    "name": "Plan Básico Mensual",
    "description": "Acceso básico a contenido exclusivo",
    "amount": 50,
    "country": "MEX",
    "currency": "MXN",
    "accountNumber": "{{accountNumber}}",
    "autoRecurring": {
        "repetitions": 1,
        "type": "hour"
    },
    "status": {
        "code": "100",
        "description": "ACTIVE",
        "detail": "Subscription plan is active"
    }
}
```

### Campos de respuesta clave

| Parámetro | Descripción | Caso de uso |
| - | - | - |
| `internalId` | Identificador único del plan de Localpayment. | Úsalo como `planId` al crear suscripciones |
| `status.code` | Código de estado del plan actual. | Monitoreo del estado. |
| `autoRecurring.type` | Frecuencia de facturación confirmada. | Verificación del ciclo de facturación. |
| `autoRecurring.repetitions` | Número confirmado de ciclos de facturación. | Seguimiento de la duración del plan. |

### Respuesta de error

Cuando falle la creación del plan de suscripción, recibirás información detallada sobre el error:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "status": {
        "code": "400",
        "description": "REJECTED",
        "detail": "autoRecurring.type is required"
    }
}
```

***

## Paso 3: Seguimiento del estado de la transacción

Tras crear un plan de suscripción, supervisa su estado mediante estos métodos:

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando cambie el estado de la transacción. Más eficiente para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado de las transacciones.

### Códigos de estado comunes

| Código | Estado | Descripción |
| :- | :- | :- |
| `100` | `ACTIVE` | El plan está activo y disponible para asociaciones suscriptoras. |
| `400` | `REJECTED` | La creación del plan falló debido a errores de validación o parámetros no válidos. |

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Probando tu integración

### Escenarios de prueba

Verifica que tu integración gestione estos escenarios:

1. **Creación de plan exitosa**: Creación de plan estándar con parámetros válidos.
2. **Estructura de precios escalonada**: Creación de múltiples planes con diferentes precios.
3. **Diversas frecuencias de facturación**: Pruebas con planes diarios, mensuales y personalizados bajo demanda.
4. **Errores de validación**: Faltan campos obligatorios, importes no válidos, países no admitidos.
5. **Asociación de Suscripciones**: Probando que los planes se puedan vincular correctamente a las suscripciones.

***

## Próximos pasos

Tras crear un plan de suscripción, es posible que debas realizar acciones adicionales:

> [card] [Crear suscripción con plan](https://docs.localpayment.com/es/docs/create-a-subscription.md)
>
> Utiliza el internalId del plan como parámetro planId para crear suscripciones de clientes
> con tu nuevo plan.

> [card] [Actualizar plan de suscripción](https://docs.localpayment.com/es/docs/update-a-subscription-plan.md)
>
> Modifica los detalles de un plan existente manteniendo las asociaciones con las suscripciones
> activas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.