> For the complete documentation index, see [llms.txt](https://docs.qentaz.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qentaz.com/documentation/planes-y-suscripciones/generar-plan.md).

# Generar Plan

Crea un nuevo plan de cobro recurrente. A través de este endpoint defines las condiciones económicas (monto, moneda, frecuencia, número de cobros) y de comportamiento (reintentos, campos personalizados del formulario de vinculación) que aplicarán a todos los clientes que se suscriban a este plan.

## Endpoint

<mark style="color:green;">`POST`</mark> `{{base_url}}/plan`

## **Headers**

| Name                                                   | Value            |
| ------------------------------------------------------ | ---------------- |
| `Content-Type`*<mark style="color:red;">**\***</mark>* | application/json |
| `x-auth-token`*<mark style="color:red;">**\***</mark>* | {token}          |
| `child-id`                                             | {business\_id}   |

{% hint style="info" %}
El child-id es opcional y se usa para las cuentas administradas para conocer más puedes ingresa a este [enlace](/documentation/cobros/terminos-de-relevancia.md#cuentas-administradas).
{% endhint %}

## **Body**

### **Información general**

Campos base para la identificación del plan y del comercio que lo crea.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th width="120.39453125">Tipo</th><th width="119.5">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td><code>merchant_id_number</code></td><td>String</td><td>Sí</td><td>Número de documento del cobrador o responsable del plan.<br><br><em><mark style="color:blue;"><code>Ejemplo: 12345678</code></mark></em></td></tr><tr><td><code>name</code></td><td>String</td><td>Sí</td><td>Nombre visible del plan.<br><br><em><mark style="color:blue;"><code>Ejemplo: Servicio mensual</code></mark></em></td></tr><tr><td><code>plan_details.currency</code></td><td>String</td><td>Sí</td><td>Código de la divisa del cobro bajo el estándar ISO 4217.<br><br><mark style="color:green;"><code>COP | USD</code></mark></td></tr><tr><td><code>plan_details.amount</code></td><td>Number</td><td>Sí</td><td>Monto fijo de cada cobro. El cliente no puede modificarlo.<br><br><em><mark style="color:blue;"><code>Ejemplo: 54000.85</code></mark></em></td></tr><tr><td><code>plan_details.description</code></td><td>String</td><td>No</td><td>Texto visible durante la vinculación y en el comprobante. Admite variables dinámicas, como <code>{{charge_number}}</code> y <code>{{month}}</code>. Consulte <a data-mention href="/pages/enH5tAq4lFl6Xyip68zk">/pages/enH5tAq4lFl6Xyip68zk</a>.<br><br><em><mark style="color:blue;"><code>Ejemplo: Cuota {{charge_number}} - Servicio</code></mark></em></td></tr><tr><td><code>plan_details.frequency</code></td><td>String</td><td>Sí</td><td><p>Frecuencia en la que se ejecutará el cobro.</p><p><mark style="color:green;"><code>monthly | biweekly | weekly</code></mark></p></td></tr><tr><td><code>plan_details.trial_days</code></td><td>Integer</td><td>No</td><td><p>Número de días de gracia antes del primer cobro.<br><br>Si <code>trial_days > 0</code>, no se realiza un cobro inmediato. El primer cobro se programa para la fecha actual más el número de días indicado.</p><p></p><p>ℹ️ <em>Predeterminado: <code>0</code>.</em></p><p></p><p><em>⚠️ <code>trial_days</code> tiene prioridad sobre <code>billing_day</code>.</em></p></td></tr><tr><td><code>plan_details.billing_day</code></td><td>Integer</td><td>No</td><td><p>Día del mes en que debe realizarse el primer cobro.</p><p></p><p>Si <code>billing_day = 0</code> o no se envía, el cobro se realiza inmediatamente. Si <code>billing_day</code> tiene un valor entre <code>1</code> y <code>30</code>, el primer cobro se programa para ese día del mes. </p><p></p><p>ℹ️ <em>Predeterminado: <code>0</code>.</em></p><p><br><em><mark style="color:blue;"><code>Ejemplo: 4</code></mark></em></p></td></tr><tr><td><code>plan_details.total_charges</code></td><td>Integer</td><td>No</td><td>Número máximo de cobros del plan. Admite valores entre 1 y 12.<br><br>ℹ️ <em>Predeterminado: <code>12</code>.</em></td></tr><tr><td><code>plan_details.expires_at</code></td><td>Date</td><td>No</td><td><p>Fecha límite para aceptar nuevas suscripciones a este plan.</p><p><br><br>ℹ️ <em>Si se omite, el plan acepta nuevas suscripciones sin límite de tiempo.</em></p></td></tr><tr><td><code>plan_details.retry.max_attempts</code></td><td>Integer</td><td>No</td><td>Número de reintentos antes de aplicar <code>status_after_retry</code>. El máximo es 3.<br><br>ℹ️ <em>Predeterminado: <code>1</code>.</em></td></tr><tr><td><code>plan_details.retry.interval_days</code></td><td>Integer</td><td>No</td><td>Número de días entre cada reintento.<br><br>ℹ️ <em>Predeterminado: <code>1</code>.</em></td></tr><tr><td><code>plan_details.retry.final_status</code></td><td>String</td><td>No</td><td>Estado de la suscripción después de agotar los reintentos.<br><br>ℹ️ <em>Predeterminado: <code>OVERDUE</code>.</em><br><br><mark style="color:green;"><code>ACTIVE | OVERDUE | CANCELED</code></mark></td></tr></tbody></table>

### Configuración adicional

Define la redirección posterior a la vinculación y los campos que se muestran en el formulario.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="246.94921875">Campo</th><th width="103.5234375">Tipo</th><th width="119.8515625">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td><code>return_url</code></td><td>String</td><td>No</td><td>Enlace al que se redirige automáticamente al cliente después de vincular su medio de pago.<br><br><em><mark style="color:blue;"><code>Ejemplo: https://comercio.com/exito</code></mark></em></td></tr><tr><td><code>custom_webhook</code></td><td>String</td><td>No</td><td><p>Si necesitas que los eventos de esta transacción en específico (como el éxito o fallo del pago) se notifiquen a una URL distinta a la que configuraste globalmente, envía aquí tu enlace personalizado.</p><p><br><em><mark style="color:blue;"><code>Ejemplo: https://miwebhook.com/status</code></mark></em></p></td></tr><tr><td><code>form_fields.image_url</code></td><td>String</td><td>No</td><td>URL de la imagen visible para el plan, cuando aplique.<br><br><em><mark style="color:blue;"><code>Ejemplo: https://comercio.com/plan.png</code></mark></em></td></tr><tr><td><code>form_fields.field_one</code> a <code>form_fields.field_six</code></td><td>Object</td><td>No</td><td>Campos adicionales del formulario. Puede definir hasta seis campos con la misma estructura que se guardaran en la referencia del cobro respectivamente.<br><br><mark style="color:green;"><code>field_one | field_two | field_three | field_four | field_five | field_six</code></mark></td></tr><tr><td><code>form_fields.field_*.type</code></td><td>String</td><td>Sí</td><td>Tipo de campo que se muestra en el formulario.<br><br><mark style="color:green;"><code>text | number | list</code></mark></td></tr><tr><td><code>form_fields.field_*.label</code></td><td>String</td><td>Sí</td><td>Nombre que identifica el campo para el cliente.<br><br><em><mark style="color:blue;"><code>Ejemplo: Tipo de servicio</code></mark></em></td></tr><tr><td><code>form_fields.field_*.is_visible</code></td><td>Boolean</td><td>Sí</td><td>Define si el campo se muestra en el formulario.<br><br><mark style="color:green;"><code>true | false</code></mark></td></tr><tr><td><code>form_fields.field_*.is_required</code></td><td>Boolean</td><td>Sí</td><td>Define si el campo es obligatorio para el cliente.<br><br><mark style="color:green;"><code>true | false</code></mark></td></tr><tr><td><code>form_fields.field_*.options</code></td><td>Array</td><td>Condicional</td><td>Opciones disponibles para el cliente.<br><br><em>⚠️ Requerido cuando <code>type</code> es <code>list</code>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: ["Básico", "Premium"]</code></mark></em></td></tr><tr><td><code>form_fields.field_*.default_value</code></td><td>String</td><td>No</td><td>Valor inicial del campo.<br><br><em><mark style="color:blue;"><code>Ejemplo: ""</code></mark></em></td></tr></tbody></table>

***

## **Response**

{% tabs %}
{% tab title="200" icon="octagon-check" %}

```json
{
  "plan_id": "A1A2A3A4",
  "name": "Plan de Suscripción de Ejemplo",
  "status": "active",
  "expires_at": "2027-12-31",
  "plan_url": "https://{host}/p/abc123",
  "created_at": "2026-06-28T15:30:00Z"
}
```

{% endtab %}

{% tab title="400" icon="octagon-xmark" %}

```json
{
  "error": {
    "type": "bad_request",
    "message": "The request contains invalid or incomplete data.",
    "details": [
      {
        "field": "payment_policy.total_charges",
        "message": "total_charges must be between 1 and 12."
      }
    ]
  }
}
```

{% endtab %}

{% tab title="401" icon="hexagon-exclamation" %}

```json
{
  "error": {
    "type": "unauthorized",
    "message": "Authentication failed."
  }
}
```

{% endtab %}
{% endtabs %}

***

## Ejemplo

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "{{base_url}}/plan" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: YOUR_SECRET_TOKEN" \
  -d '{
    "merchant_id_number": "12345678",
    "name": "Plan Premium",
    "plan_details": {
      "currency": "COP",
      "amount": 150000,
      "description": "Cobro {{charge_number}} - {{month}}",
      "frequency": "monthly",
      "billing_day": 5,
      "total_charges": 6,
      "initial_charge": true,
      "trial_days": 7,
      "expires_at": "2026-09-12",
      "retry": {
        "max_attempts": 3,
        "interval_days": 2,
        "final_status": "OVERDUE"
      }
    },
    "form_fields": {
      "field_one": {
        "type": "list",
        "label": "Tipo de servicio",
        "is_visible": true,
        "is_required": true,
        "options": ["Básico", "Premium"],
        "default_value": "Premium"
      },
      "field_two": {
        "type": "text",
        "label": "Documento de identidad",
        "is_visible": true,
        "is_required": true,
        "default_value": ""
      }
    },
    "return_url": "https://comercio.com/pagos/resultado",
    "custom_webhook": "https://comercio.com/pagos/webhook"
  }'
```

{% endtab %}
{% endtabs %}