# API · Crear plan recurrente

> Creación de planes recurrentes: frecuencias, prueba gratis, modalidades y webhooks.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/planes/create-plan

```http
POST /api/v1/createPlanRepeat
```

## Qué hace [#que-hace]

Crea un plan de suscripción: frecuencia de cobro, moneda, periodo de prueba, modalidades y webhooks.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="create-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="create-plan-parametro-title" name="title" type="string" required>
Título del plan recurrente.
</Param>

<Param id="create-plan-parametro-description" name="description" type="string">
Descripción del plan.
</Param>

<Param id="create-plan-parametro-frecuency" name="frecuency" type="integer">
Frecuencia de cobro.

| Código | Valor |
| --- | --- |
| 1 | Diario |
| 2 | Semanal |
| 3 | Mensual |
| 4 | Anual |
| 5 | Quincenal |
| 6 | Bimestral |
| 7 | Trimestral |
| 8 | Cuatrimestral |
| 9 | Semestral |
</Param>

<Param id="create-plan-parametro-currency" name="currency" type="string" required>
Código de moneda en formato ISO 4217.
</Param>

<Param id="create-plan-parametro-first-amount" name="first_amount" type="integer" required>
Monto por pago inicial.
</Param>

<Param id="create-plan-parametro-trial" name="trial" type="integer" required>
Activa el periodo de prueba gratis: 0 no, 1 sí.
</Param>

<Param id="create-plan-parametro-trial-days" name="trial_days" type="integer" required>
Días del periodo de prueba gratis.
</Param>

<Param id="create-plan-parametro-attempts" name="attempts" type="integer" required>
Cantidad de reintentos para cobros fallidos.
</Param>

<Param id="create-plan-parametro-modality" name="modality" type="array" required>
Array de modalidades del plan.
</Param>

<Param id="create-plan-parametro-thanks-url" name="thanks_url" type="string">
Campo opcional. URL de agradecimiento propia del comercio; debe soportar el método **GET**.
</Param>

<Param id="create-plan-parametro-webhook-subscribe" name="webhook_subscribe" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un cliente adquiere una suscripción de forma exitosa. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'modality' : 'ModalityName', 'amount' : 25, 'frequency' : '', 'coupon' : '5HT5W8YT', 'free_trial' : 1, 'next_payment_date' : '2023-02-25'}`
</Param>

<Param id="create-plan-parametro-webhook-payment" name="webhook_payment" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando el cargo al cliente se realiza con éxito. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25, 'auth' : '123456', 'orderNumber' : 'PRE123456'}`
</Param>

<Param id="create-plan-parametro-webhook-rejected" name="webhook_rejected" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un pago falla. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25}`
</Param>

<Param id="create-plan-parametro-webhook-unsubscribe" name="webhook_unsubscribe" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un cliente cancela la suscripción a uno de sus planes. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'expire' : '2023-02-25'}`
</Param>

<Param id="create-plan-parametro-webhook-reactive" name="webhook_reactive" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un cliente reactiva la suscripción a uno de sus planes. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'next_payment_date' : '2023-02-25'}`
</Param>

<Param id="create-plan-parametro-end-at" name="end_at" type="string">
Fecha de finalización del plan recurrente, formato `d-m-Y` (por ejemplo 25-09-2022). Si el plan no tiene fecha de fin, se envía vacío.
</Param>

<Param id="create-plan-parametro-notify" name="notify" type="integer">
En 1 agrega al correo de notificación el texto de `notify_detail` y `notify_note`. En 0 no agrega ninguno de los dos.
</Param>

<Param id="create-plan-parametro-notify-detail-es" name="notify_detail_es" type="string">
Texto del detalle en español. Opcional si `notify` es 0.
</Param>

<Param id="create-plan-parametro-notify-detail-en" name="notify_detail_en" type="string">
Texto del detalle en inglés. Opcional si `notify` es 0.
</Param>

<Param id="create-plan-parametro-notify-note-es" name="notify_note_es" type="string">
Texto de las notas en español. Opcional si `notify` es 0.
</Param>

<Param id="create-plan-parametro-notify-note-en" name="notify_note_en" type="string">
Texto de las notas en inglés. Opcional si `notify` es 0.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "title": "Plan title",
  "description": "Plan description",
  "frecuency": 1,
  "currency": "USD",
  "first_amount": 0,
  "trial": 0,
  "trial_days": 0,
  "attempts": 1,
  "modality": [
    {
      "title": "Basic",
      "amount": 10
    },
    {
      "title": "Premium",
      "amount": 30
    }
  ],
  "thanks_url": "",
  "webhook_subscribe": "",
  "webhook_payment": "",
  "webhook_rejected": "",
  "webhook_unsubscribe": "",
  "webhook_reactive": "",
  "end_at": "25-10-2023",
  "notify": 0,
  "notify_detail_es": "",
  "notify_detail_en": "",
  "notify_note_es": "",
  "notify_note_en": ""
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "status": 1,
  "message": "Success",
  "id": 624,
  "url": "https://app.tilopay.com/link/TmpJMHwx"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).