> 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-suscripcion.md).

# Generar Suscripción

Crea una nueva suscripción asociada a un plan existente. Al crearla, Trazo genera un enlace seguro para que el cliente complete la vinculación de su medio de pago. Envía la información del suscriptor para reducir los datos que el cliente debe completar durante la vinculación.

## Endpoint

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

## **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><thead><tr><th width="254.38671875">Campo</th><th width="110.2734375">Tipo</th><th width="124.75390625">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td><code>plan_id</code></td><td>String</td><td>Sí</td><td>Identificador visible del plan al que se asociará la suscripción.</td></tr><tr><td><code>customer</code></td><td>Object</td><td>No</td><td><p>Objeto con la información del cliente. </p><p></p><p><em>⚠️ Debe enviarse si no se utiliza</em> <code>form_values</code>.</p></td></tr><tr><td><code>customer.name</code></td><td>String</td><td>Condicional</td><td><p>Nombre del cliente, el cual se usa para la validación del número de documento.</p><p></p><p><em>⚠️ Sujeto a la regla de interdependencia.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: Andrés</code></mark></em></p></td></tr><tr><td><code>customer.id_type</code></td><td>String</td><td>Condicional</td><td><p>Tipo de documento de identificación del cliente.</p><p></p><p><em>⚠️ Sujeto a la regla de interdependencia.</em><br><br><mark style="color:green;"><code>CC | CE | NIT | PASAPORTE | DNI | EIN</code></mark></p></td></tr><tr><td><code>customer.id_number</code></td><td>String</td><td>Condicional</td><td><p>Número del documento de identificación del cliente.</p><p></p><p><em>⚠️ Sujeto a la regla de interdependencia.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 11119999</code></mark></em></p></td></tr><tr><td><code>customer.email</code></td><td>String</td><td>No</td><td>Correo del cliente al que se enviarán las notificaciones.<br><br><em><mark style="color:blue;"><code>Ejemplo: cliente@minegocio.com</code></mark></em></td></tr><tr><td><code>customer.phone</code></td><td>String</td><td>No</td><td>Número de teléfono celular del cliente pagador (debe incluir el código de área internacional).<br><br><em><mark style="color:blue;"><code>Ejemplo: 573112223333</code></mark></em></td></tr><tr><td><code>form_values</code></td><td>Object</td><td>No</td><td><p>Objeto de valores de los campos configurados en el plan. </p><p></p><p><em>⚠️ Debe enviarse si no se utiliza <code>customer</code>.</em></p></td></tr><tr><td><code>form_values.field_*</code></td><td>String</td><td>No</td><td>Valor de un campo configurado en el plan.</td></tr></tbody></table>

{% hint style="warning" %}
Los campos: *`customer.id_type`*, *`customer.id_number`* y *`customer.name`* operan bajo una lógica de **obligatoriedad conjunta**. Si decides enviar cualquiera de estos tres campos en el JSON, **los otros dos se vuelven obligatorios de inmediato** para asegurar la consistencia y el correcto procesamiento del fraude/recaudo en Trazo.
{% endhint %}

***

## **Response**

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

```json
{
  "subscription_id": "B1B2B3B4",
  "plan_id": "A1A2A3A4",
  "subscription_url": "https://{host}/s/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}}/subscription" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: YOUR_SECRET_TOKEN" \
  -d '{
    "plan_id": "A1A2A3A4",
    "customer": {
      "name": "Juan Pérez",
      "id_type": "CC",
      "id_number": "1020304050",
      "email": "cliente@correo.com",
      "phone": "573001234567"
    },
    "form_values": {
      "field_one": "Juan Pérez",
      "field_two": "cliente@correo.com",
      "field_three": "3001234567",
      "field_four": "1020304050"
    }
  }'
```

{% endtab %}
{% endtabs %}