Skip to main content
POST

Headers

string
required
Token único para garantizar la idempotencia de la petición

Body

Esta página describe un cuerpo que el endpoint ya no acepta. Hoy POST /subscriptions crea la suscripción a partir de un plan existente y exige plan_id (o price_id), customer_id, payment_method_type y payment_method_id. Los campos de importe y periodicidad — amount_in_cents, reference_price_in_cents, cicle_frequency, cicles, currency, name — se definen ahora al crear el plan, no aquí; enviarlos a este endpoint devuelve un 422 pidiendo plan_id.Estamos reescribiendo esta página. Mientras tanto, toma como referencia crear planes y confirma el cuerpo con soporte antes de integrar.
string
required
ID del cliente que asumirá los cobros. Crea primero el cliente.
string
required
Nombre público de la suscripción.
string
Descripción rica que se mostrará en correos y facturas.
string
default:"COP"
required
Moneda en formato ISO-4217. Actualmente soportamos COP.
number
required
Valor a cobrar en cada ciclo expresado en centavos.
string
Precio de referencia que se mostrará en UI. Puede diferir del amount_in_cents cuando usas pagos complejos.
string
required
Frecuencia: daily, weekly, monthly, annual.
number
Número máximo de ciclos. Usa null para renovaciones indefinidas.
date
Fecha en la que deseas iniciar los cobros. Si se omite se usa la fecha actual.
string
Identificador que usas en tus sistemas.
string
ID del plan preconfigurado que deseas usar. Ver cómo crear planes.
string
default:"request"
Define si se cobrará automáticamente (auto_debit) o vía solicitudes (request).
boolean
default:false
Si es true, el checkout sugerirá activar débito automático.
number
Días de anticipación para recordatorios de pago.
number
Número de ciclos consecutivos fallidos antes de cancelar la suscripción.
object
Pares clave/valor para enriquecer la suscripción.
object
Configuración del periodo de prueba.
array
Pagos con valores especiales por ciclo (ej. matrículas o cargos iniciales).
Métodos de pago permitidosEl método de pago disponible depende de la configuración de tu cuenta. Comunícate con el equipo de soporte para habilitar métodos adicionales.Solo uno de los dos (account_id o card_id) debe estar presente en la petición.

Response

string
Identificador único de la suscripción (UUID).
string
Nombre comercial de la suscripción.
string
Estado actual (active, unpaid, pass_due, canceled, finished, frozen).
string
Descripción enriquecida (puede contener HTML).
string
Identificador interno que usas en tu sistema.
string
ID del plan asociado, si aplica.
string
ID del cupón aplicado.
string
Precio de referencia en centavos como string.
string
Moneda en formato ISO-4217 (ej. COP).
number
Valor base cobrado en cada ciclo.
string
Frecuencia de cobro: weekly, monthly, annual, etc.
number
Cantidad máxima de ciclos; null para indefinido.
number
Ciclo actual procesado.
object
Configuración de métodos de pago permitidos para la suscripción.
boolean
Indica si se sugiere activar débito automático durante el onboarding del cliente.
date
Fecha programada de inicio.
date
Fecha de finalización si aplica.
object
Información de periodo de prueba (has_trial, trial_days, start_trial_date).
string
Modo de cobro (request, auto_debit, etc.).
number
Días de anticipación para recordatorios de pago.
number
Número de ciclos fallidos antes de cancelar automáticamente.
array
Pagos con valores diferenciados por ciclo.
object
Atributos personalizados que acompañan la suscripción.
object
Resumen del cliente asociado.
object
Información del plan enlazado, cuando existe.
date
Fecha de creación de la suscripción.
date
Fecha de última actualización.