Crear una suscripción en Treli

Esta guía explica todas las formas de crear una suscripción en Treli, qué pasa después de crearla, y cómo elegir la que corresponde a tu caso. Es una guía conceptual: el detalle campo por campo está en la referencia de la API (Crear suscripción, Crear sesión de checkout).

1. El modelo mental

Antes de escribir código, hay una idea que ahorra la mayoría de las dudas:

Una suscripción nunca se cobra a sí misma. La suscripción es el acuerdo (qué, cada cuánto, a quién). Cada ciclo de facturación, la suscripción genera un cobro, y el cobro es lo que se paga.

Objeto	Qué es
Producto (`prod_`)	El ítem de catálogo: "Plan Pro", "Caja mensual de café".
Precio (`price_`)	Un precio del producto: monto, moneda, y si es `recurring` (con `billing_period` + `billing_interval`) o `one_time`. Un producto puede tener varios precios (mensual, anual, USD, COP).
Cliente (`cus_`)	El comprador. Único por `(email, modo test/live)`.
Suscripción (`sub_`)	El acuerdo recurrente: ítems, descuentos, frecuencia, método de cobro, próxima renovación, prueba gratis.
Cobro (`col_`)	Un ciclo de facturación concreto: "la cuenta de este mes". Se crea al crear la suscripción y en cada renovación. Es el objeto al que se le atribuye el dinero.
Transacción (`tx_`)	Un intento de pago contra un cobro.
Charge (`ch_`)	El intento a nivel de pasarela (Wompi, PlaceToPay, Stripe…). Una transacción puede tener varios charges (reintentos).
Factura (`inv_`)	El documento fiscal (DIAN) generado en tu proveedor (Siigo, Alegra, Stripe). Opcional y configurable: antes o después del pago.
Medio de pago (`pm_`)	Tarjeta / Nequi / Daviplata / PSE tokenizado y guardado contra el cliente.

Consecuencia práctica: justo después de crear una suscripción con cobro automático, el estado no es active. Es incomplete, y pasa a active cuando el primer cobro queda pagado. Es el error de integración más común.

2. Antes de empezar

Autenticación

La API usa HTTP Basic con tu llave secreta como usuario y contraseña vacía:

Solo existe una clase de llave: la secreta (sk_live_… / sk_test_…). No hay llave publicable — el checkout alojado de Treli no la necesita, porque el objeto de sesión ya viene firmado.

El modo test se define por la llave. Con sk_test_ todos los objetos que crees quedan marcados is_test: true y viven separados de los reales: mismos endpoints, misma lógica, sin dinero.

Tener catálogo

Toda suscripción se arma sobre precios recurrentes. Si aún no los tienes:

billing_period: day · week · month · year. billing_interval: cada cuántos (3 + month = trimestral).

pricing_model: standard · graduated (escalonado) · volume (por volumen) · ntp (name the price, el cliente elige el monto).

La moneda del precio y la de la suscripción deben coincidir. COP es la moneda de liquidación; otras monedas se guardan con su valor convertido y la tasa de cambio del momento.

Tener una pasarela configurada

Al menos una pasarela activa en tu cuenta. Cada una soporta distintos métodos:

Pasarela	Métodos
`wompi`	`card`, `pse`, `nequi`, `daviplata`, `bancolombia_transfer`, `bancolombia_collect`, `pago_rapido`
`epayco`	`card`, `pse`, `efecty`
`payu` · `openpay` · `mercadopago` · `placetopay` · `payzen`	`card`, `pse`
`paymentsway`	`card`, `pse`, `efecty`
`stripe`	`card`
`dlocalgo`	`card`, `bank_transfer`, `cash`

Solo card, nequi y daviplata se pueden tokenizar y por lo tanto sirven para cobro automático recurrente. pse, efecty y afines requieren acción del cliente en cada ciclo.

3. La decisión que define tu integración: `collection_method`

Independiente de por dónde entre la suscripción, hay que responder cómo se cobra cada ciclo:

	`charge` — cobro automático	`collect` — cobro manual / enviado
Qué hace Treli en cada renovación	Genera el cobro y lo cobra al medio de pago guardado	Genera el cobro y se lo envía al cliente (email/WhatsApp) con un link de pago
Requiere medio de pago guardado	Sí (`pm_`, `payment_information`, o el medio por defecto del cliente)	No
Campos	`payment_method` o `payment_information` (nunca los dos)	`days_until_due` (obligatorio)
Estado inicial	`incomplete` → `active` cuando se paga el primer cobro	`active` de inmediato (o `trialing` / `scheduled`)
Si nunca se paga el primer cobro	La suscripción expira a las ~23 horas (`expired`)	El cobro queda `past_due` y entra en recordatorios
Típico para	B2C, SaaS, membresías, cajas de suscripción	B2B, facturación a crédito, transferencia, efectivo, clientes corporativos

Extra útil de collect: switch_to_charge: true — si el cliente paga un cobro con un método tokenizable, la suscripción se pasa sola a cobro automático a partir de ahí. Es la forma limpia de arrancar "envío la primera cuenta" y terminar en automático.

4. Las formas de crear una suscripción

#	Forma	Quién captura el pago	Código	Cuándo usarla
1	Sesión de checkout	Treli (página alojada)	Bajo	Default para casi todo
2	Enlace de pago	Treli	Ninguno	Una oferta fija, reutilizable, compartible
3	API directa, cobro automático	Tú	Alto	Ya tienes el medio de pago guardado
4	API directa, cobro manual	Treli	Medio	B2B / facturación a crédito
5	Migración / importación	—	Bajo	Traer suscripciones que ya existen en otra parte
6	Dashboard	Treli	Ninguno	Manual

Opción 1 — Sesión de checkout (recomendada)

El equivalente a Stripe Checkout. Tú describes qué se va a vender; Treli devuelve una URL alojada; el cliente paga ahí; Treli crea cliente + medio de pago + suscripción + cobro + transacción en un solo paso.

Respuesta:

{
  "session": { "id": "cs_xxx", "mode": "subscription", "status": "open", "total": "89900", "expires_at": "2026-09-09 10:00:00", "...": "..." },
  "url": "https://checkout.treli.co/c/pay/cs_xxx#<hash>"
}

Redirige al cliente a url. Cuando paga, Treli emite checkout_session.completed, subscription.created, collection.created y (si el pago se aprueba) collection.paid + subscription.activated.

Detalles que importan

Expiración: 24 horas por defecto. Puedes acortarla con expires_at. Al expirar, la sesión queda expired y el cobro asociado se anula.

El hash va en el fragmento (#…) de la URL. Redirige con la URL completa y textual; no la reconstruyas ni la recortes.

payment_methods (opcional) restringe qué métodos se ofrecen, con la forma {"wompi": ["card","pse"], "offline": ["transferencia"]}. La pasarela debe estar configurada en tu cuenta o la petición se rechaza.

customer (opcional) preasocia un cus_ existente. Si no lo mandas, el checkout identifica o crea al cliente solo (incluye reconocimiento por OTP al email).

discounts: [{ "code": "BIENVENIDO20", "duration_in_collections": 3 }].

Los otros mode, que resuelven problemas vecinos:

`mode`	Para qué
`subscription`	Crear una suscripción (esta sección)
`payment`	Un cobro único, sin suscripción
`setup`	Guardar un medio de pago sin cobrar. Total 0. Con `setup_subscription_id` reemplaza el medio de pago de una suscripción existente (recuperar una suscripción `past_due`, actualizar una tarjeta vencida). Sin él, deja un `pm_` guardado que puedes usar luego en la Opción 3

Por qué es la recomendada: la captura de la información de pago queda del lado de Treli, obtienes todos los métodos locales (tarjeta, PSE, Nequi, Daviplata, efectivo, transferencia) sin integrarlos uno por uno, y los flujos asíncronos (PSE redirige al banco, Nequi hace push al celular, efectivo genera un recaudo) ya están resueltos.

Opción 2 — Enlace de pago (`pl_`)

Una oferta fija y reutilizable. Se crea una vez y se comparte por WhatsApp, email, redes o un botón. Cada visitante genera su propia sesión de checkout por debajo.

URL pública: https://checkout.treli.co/pl/{pl_id}

Reglas

No existe una bandera "es recurrente": se deduce de los precios. Si algún ítem tiene un precio recurring, el enlace crea suscripciones; si todos son one_time, crea cobros únicos.

Si mandas subscription_settings sin ningún precio recurrente, la petición se rechaza.

Todos los precios recurrentes de un enlace deben tener la misma frecuencia. No puedes mezclar mensual y anual.

No se permiten precios duplicados en un mismo enlace.

Precios ntp (name the price): solo uno por enlace, y no admiten prueba gratis.

usage_limit limita cuántas veces se puede usar; cta_text acepta Pagar, Suscribirse, Donar, Reservar.

Opción 3 — API directa con cobro automático (`collection_method: "charge"`)

Para cuando ya tienes el medio de pago y quieres crear la suscripción sin pasar al cliente por una página de Treli.

Si omites payment_method y payment_information, Treli usa el medio de pago por defecto del cliente (y falla si no tiene uno).

¿De dónde sale un pm_?

Una sesión de checkout en mode: "setup" (Opción 1).

El portal del cliente, donde el propio cliente agrega o cambia su tarjeta.

GET /v1/customers/{id}/payment_methods para listar los que ya existen.

No hay un endpoint "crear medio de pago" con datos de tarjeta sueltos: los medios de pago nacen de un intento de pago o de un flujo de tokenización.

Reglas de validación de esta ruta

payment_method y payment_information son mutuamente excluyentes.

days_until_due no se permite con charge.

Si usas first_payment_invoicing, con charge solo puede ser "after" (no puedes emitir la factura fiscal antes de cobrar automáticamente).

Con schedule_date no se permite payment_information (se cobrará luego, con el medio guardado).

Qué devuelve

El objeto suscripción con status: "incomplete" y latest_collection: "col_xxx". El primer cobro se genera y se intenta pagar en el mismo request:

Aprobado (tarjeta) → llegan collection.paid + subscription.activated casi de inmediato.

Rechazado → la petición devuelve error de decline con el motivo.

Asíncrono (tarjeta via Wompi, PSE, Nequi, efectivo) → la transacción queda processing y su additional_data contiene la información de redirección/instrucción que debes mostrarle al cliente. Para métodos asíncronos, la sesión de checkout es bastante más simple, porque esa redirección ya viene resuelta.

Sin resolver en ~23 horas → la suscripción pasa a expired.

Opción 4 — API directa con cobro manual (`collection_method: "collect"`)

Sin medio de pago. Treli emite el cobro y se lo envía al cliente en cada ciclo.

days_until_due es obligatorio y define la fecha de vencimiento de cada cobro.

No se permiten payment_method ni payment_information.

La suscripción queda active de inmediato (o trialing si hay prueba, scheduled si hay schedule_date).

Cada cobro trae su propia URL de pago pública (https://checkout.treli.co/col/{col_id}), que Treli envía por email/WhatsApp y sobre la que corren recordatorios y reglas de vencimiento.

first_payment_invoicing: "create" emite la factura fiscal antes del pago — el caso clásico de facturación a crédito. Con "after" se emite al pagar.

switch_to_charge: true convierte la suscripción a cobro automático en cuanto el cliente pague con un método tokenizable.

Opción 5 — Migrar suscripciones que ya existen

Para traer una base viva desde otra plataforma sin cobrar nada y sin alterar el calendario:

La diferencia clave con POST /v1/subscriptions: no genera un primer cobro ni intenta pagar nada. Respeta el next_renewal_date que le des, así que el cliente no paga dos veces ni pierde días.

Opción 6 — Sin escribir código

Dashboard de Treli — crear la suscripción a mano contra un cliente. Usa exactamente los mismos motores, así que dispara los mismos webhooks.

Portal del cliente (https://p.treli.co/p/login/{url_id}) — no crea suscripciones nuevas, pero es donde el cliente cancela, pausa, reanuda y actualiza su medio de pago. Vale integrarlo desde el día uno: reduce mucho el churn involuntario por tarjeta vencida.

5. Modificadores comunes

Aplican en POST /v1/subscriptions y, cuando corresponde, vía subscription_settings en checkout / enlaces / tiendas.

Campo	Qué hace
`trial_days`	Prueba gratis. En el primer cobro, los ítems recurrentes quedan en 0 (los `one_time` sí se cobran), así que se valida el medio de pago sin cobrar la mensualidad. La suscripción queda `trialing` y se activa al primer cobro real. No se combina con `schedule_date`.
`schedule_date`	Inicio futuro: estado `scheduled`, sin cobro hasta la fecha.
`duration`	Número total de ciclos. Al alcanzarlo, la suscripción pasa a `ended` (y avisa un ciclo antes con `subscription.will_end`).
`commitment_periods`	Periodos de permanencia mínima; se usa para las reglas de cancelación.
`usage_based`	Suscripción por consumo: en cada renovación Treli emite `subscription.report_usage` y espera ~5 minutos antes de generar el cobro, para que reportes el consumo del periodo (actualizando ítems/cantidades vía API).
`discounts`	Cupones por código: `[{ "code": "X", "duration_in_collections": 3 }]`. Sin `duration_in_collections`, aplica a todos los ciclos.
`days_until_due`	Días de plazo de cada cobro. Obligatorio en `collect`, prohibido en `charge`.
`first_payment_invoicing`	`create` (factura fiscal antes del pago) · `after` (después del pago). Con `charge` solo `after`.
`renewal_invoicing`	Si cada renovación genera factura fiscal. Por defecto `true`.
`invoice_settings` / `invoice_retentions`	Parámetros del proveedor de facturación (Siigo/Alegra) y retenciones (`reteiva`, `reteica`, `retefte`).
`meta_data`	Tus propias llaves/valores (máx. 255 caracteres cada valor). Ideal para tu `user_id`. Viaja en los webhooks.

6. Qué pasa después de crear

Estados de la suscripción

Estado	Significado
`incomplete`	Creada con `charge`, esperando que se pague el primer cobro. Todavía no da acceso.
`trialing`	En prueba gratis.
`scheduled`	Programada, aún no arranca.
`active`	Al día.
`past_due`	Un cobro se venció sin pagarse; corren reintentos y recordatorios.
`unpaid`	Se agotó la política de reintentos/dunning.
`paused`	Pausada (opcionalmente con `resumes_at`).
`pending_cancel`	Cancelación agendada para el fin del periodo; no renueva.
`canceled`	Cancelada.
`ended`	Alcanzó su `duration`.
`expired`	Nació con `charge` y nunca completó el primer pago (~23 h).

El ciclo, en orden

Creación → subscription.created (o subscription.scheduled), y se genera el primer cobro (collection.created).

Primer pago. Con charge se intenta en el momento; con collect se envía la cuenta (collection.sent).

Cobro pagado → collection.paid + charge.paid → la suscripción se activa (subscription.activated).

Renovación. Treli agenda la próxima renovación (next_renewal_date); al llegar, genera un cobro nuevo y repite el paso 2. No hay que hacer nada.

Fallo. El cobro vence → collection.past_due + subscription.past_due → reintentos → si se agotan, subscription.unpaid / collection.uncollectible.

Fin. POST /v1/subscriptions/{id}/cancel (con cancel_at: "period_end" o "now"), /pause, /resume; o ended al cumplir duration.

7. Webhooks: en qué fijarse

Los dos que sostienen una integración de suscripciones:

subscription.activated → dale acceso al cliente.

collection.paid → entró el dinero de este ciclo. Se dispara en cada renovación pagada, no solo en la primera.

Y los que conviene manejar:

Evento	Para qué
`subscription.created`	Registrar la suscripción en tu sistema (aún sin acceso si vino con `charge`).
`subscription.past_due` / `unpaid`	Avisar, limitar o suspender el acceso.
`subscription.canceled` / `pending_canceled` / `ended` / `expired`	Revocar acceso (`pending_canceled` = revocar al final del periodo).
`subscription.paused` / `resumed`	Suspender y restaurar.
`subscription.will_end`	Un ciclo antes de agotar `duration`: momento de ofrecer renovación.
`subscription.report_usage`	Reportar consumo antes de que se genere el cobro (solo `usage_based`).
`collection.created` / `sent` / `reminder` / `payment_failed` / `voided` / `refunded`	Seguir la cobranza ciclo a ciclo.
`checkout_session.completed` / `expired`	Cerrar el flujo de checkout de tu lado.
`invoice.created` / `paid` / `voided`	Documentos fiscales, si facturas con Siigo/Alegra.

Idempotencia: un webhook puede llegar más de una vez. Deduplica por el id del evento (evt_…) y hazlo idempotente por objeto (sub_, col_).

8. Cómo elegir, en tres preguntas

¿Quieres capturar datos de pago en tu propio servidor?
No → sesión de checkout (Opción 1), enlace de pago (2) o tienda (3).
Sí → API directa (4).

¿Cada cliente ve una oferta distinta, calculada por ti?
Sí → sesión de checkout: se crea por cliente y muere en 24 h.
No, es la misma oferta siempre → enlace de pago: se crea una vez y se comparte.
El cliente elige entre varias → tienda.

¿Quieres realizar débitos automáticos, o cobrar por medio de notificaciones?
Paga solo, automático → collection_method: "charge".
Ingresa a pagar manualmente / paga por transferencia / facturas a crédito → collection_method: "collect" + days_until_due (+ switch_to_charge si quieres migrarlo a automático).

El camino más corto a producción: producto y precio → sesión de checkout en mode: "subscription" → escuchar subscription.activated y collection.paid → integrar el portal del cliente para que actualice su tarjeta.

9. Probar

Usa sk_test_. Todo lo que crees queda is_test: true, en paralelo a lo real.

Recorre el checkout completo con las tarjetas de prueba de tu pasarela.

Verifica el orden de estados: la suscripción debe verse incomplete antes de active — si tu código asume active al recibir la respuesta del POST, falla en producción con cualquier método asíncrono.

Prueba una renovación (un precio con billing_period: "day" hace el ciclo visible en minutos).

Prueba el camino de fallo: tarjeta rechazada → past_due → reintentos.

10. Errores comunes

Síntoma	Causa
"Creé la suscripción pero está `incomplete`"	Correcto y esperado con `charge`: se activa cuando se paga el primer cobro. Escucha `subscription.activated`.
`days_until_due is only allowed for collection_method charge`	`days_until_due` va solo con `collect`, donde además es obligatorio.
"No puedo mandar `payment_method` y `payment_information`"	Son excluyentes: uno u otro.
`Todos los precios deben tener la misma frecuencia`	En un mismo enlace/tienda/suscripción los precios recurrentes deben compartir `billing_period` + `billing_interval`.
`La pasarela de pago X no se encuentra configurada en tu cuenta`	`payment_methods` referencia una pasarela que no tienes activa.
La suscripción quedó `expired` sin explicación	Nació con `charge` y el primer pago nunca se completó dentro de ~23 h (típico de PSE abandonado).
Error al usar `first_payment_invoicing: "create"` con `charge`	Con cobro automático la primera factura solo puede ser `"after"`.
El monto no cuadra en monedas distintas a COP	COP es la moneda de liquidación; el resto se guarda convertido con la tasa del momento. Compara siempre en la moneda de la suscripción.
Los medios de pago no se guardan para renovar	Solo `card`, `nequi` y `daviplata` se tokenizan. Con `pse`/efectivo usa `collect` (+ `switch_to_charge`).

Referencia rápida de endpoints

Acción	Endpoint
Crear suscripción	`POST /v1/subscriptions`
Migrar suscripción existente	`POST /v1/subscriptions/migrate`
Ver / listar	`GET /v1/subscriptions/{id}` · `GET /v1/subscriptions`
Actualizar	`POST /v1/subscriptions/{id}/update`
Ítems	`POST /v1/subscription_items` · `POST
Cancelar / pausar / reanudar	`POST /v1/subscriptions/{id}/cancel` · `/pause` · `/resume`
Envío	`POST /v1/subscriptions/{id}/shipping` · `/shipping_item`
Sesión de checkout	`POST /v1/checkout_session` · `GET /v1/checkout_session/{id}`
Enlaces de pago	`POST /v1/payment_links` · `POST /v1/payment_links/{id}/update`
Tiendas	`POST /v1/storefronts` · `POST /v1/storefronts/{id}/update`
Catálogo	`POST /v1/products` · `POST /v1/prices`
Clientes	`POST /v1/customers` · `GET /v1/customers/{id}/payment_methods`
Cobros	`GET /v1/collections/{id}` · `POST /v1/collections/{id}/pay` · `/void` · `/refund`
Medios de pago	`POST /v1/payment_methods/{id}/update` · `/delete` · `POST /v1/payment_methods/migrate`

Crear una suscripción en Treli

1. El modelo mental#

2. Antes de empezar#

Autenticación#

Tener catálogo#

Tener una pasarela configurada#

3. La decisión que define tu integración: collection_method#

4. Las formas de crear una suscripción#

Opción 1 — Sesión de checkout (recomendada)#

Opción 2 — Enlace de pago (pl_)#

Opción 3 — API directa con cobro automático (collection_method: "charge")#

Opción 4 — API directa con cobro manual (collection_method: "collect")#

Opción 5 — Migrar suscripciones que ya existen#

Opción 6 — Sin escribir código#

5. Modificadores comunes#

6. Qué pasa después de crear#

Estados de la suscripción#

El ciclo, en orden#

7. Webhooks: en qué fijarse#

8. Cómo elegir, en tres preguntas#

9. Probar#

10. Errores comunes#

Referencia rápida de endpoints#