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

POST {{base_url}}/subscription

Headers

Name	Value
Content-Type*	application/json
x-auth-token*	{token}
child-id	{business_id}

El child-id es opcional y se usa para las cuentas administradas para conocer más puedes ingresa a este enlace.

Body

Información general

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

Campo	Tipo	Obligatorio	Descripción
plan_id	String	Sí	Identificador visible del plan al que se asociará la suscripción.
customer	Object	No	Objeto con la información del cliente. ⚠️ Debe enviarse si no se utiliza form_values.
customer.name	String	Condicional	Nombre del cliente, el cual se usa para la validación del número de documento. ⚠️ Sujeto a la regla de interdependencia. Ejemplo: Andrés
customer.id_type	String	Condicional	Tipo de documento de identificación del cliente. ⚠️ Sujeto a la regla de interdependencia. CC | CE | NIT | PASAPORTE | DNI | EIN
customer.id_number	String	Condicional	Número del documento de identificación del cliente. ⚠️ Sujeto a la regla de interdependencia. Ejemplo: 11119999
customer.email	String	No	Correo del cliente al que se enviarán las notificaciones. Ejemplo: [e-mail]
customer.phone	String	No	Número de teléfono celular del cliente pagador (debe incluir el código de área internacional). Ejemplo: 573112223333
form_values	Object	No	Objeto de valores de los campos configurados en el plan. ⚠️ Debe enviarse si no se utiliza customer.
form_values.field_*	String	No	Valor de un campo configurado en el plan.

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.

---

Response

200

{
  "subscription_id": "B1B2B3B4",
  "plan_id": "A1A2A3A4",
  "subscription_url": "https://{host}/s/abc123",
  "created_at": "2026-06-28T15:30:00Z"
}

400

{
  "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."
      }
    ]
  }
}

401

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

---

Ejemplo

cURL

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": "[e-mail]",
      "phone": "573001234567"
    },
    "form_values": {
      "field_one": "Juan Pérez",
      "field_two": "[e-mail]",
      "field_three": "3001234567",
      "field_four": "1020304050"
    }
  }'