Saltar al contenido principal
Migo Docs

Planes

Un plan define cuánto se cobra y cada cuánto. Lo creas una vez y lo reutilizas en todas las suscripciones que quieras.

Todas las rutas de esta página usan Authorization: Bearer <tu-token-de-comercio>.

Cadencia — los cuatro tipos​

El campo type decide cómo Migo calcula la siguiente fecha de cobro. Envía el valor en minúsculas/camelCase tal como aparece en la columna «Valor»:

ValorQué haceCuándo usarlo
"interval"Cobra cada N días desde el altaEl más común — semanal, cada 30 días, cada 90 días
"fixedDay"Cobra un día fijo del mesFacturación «el 1» o «el 15» de cada mes
"anniversary"Cobra el mismo día calendario en cada cicloSuscripciones anuales
"automatic"Delega el cálculo al procesadorPoco habitual

Crear un plan​

curl -X POST https://sb-mw.migopayments.com/api/v1/plans \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"client": "<tu-client-slug>",
"plan": {
"name": "Plan mensual",
"amount": 99.00,
"currency": "GTQ",
"type": "interval",
"frequency": {
"frequency": 30,
"day": 1,
"shortDescription": "Mensual",
"longDescription": "Se cobra cada 30 días"
},
"methods": ["<processor-slug>"],
"installments": [1],
"autoRenewal": true,
"dailyAttempts": 3,
"daysNotifyExpiringCard": 7
}
}'
CampoTipoRequeridoNotas
clientstringSíTu slug de comercio
plan.namestringSíSe le muestra al tarjetahabiente
plan.amountnumberSíDecimal, hasta 4 posiciones
plan.currencyISO 4217SíGTQ, USD, …
plan.typeenumNoVer la tabla de cadencia
plan.frequency.frequencyintegerSíDías entre cobros; 0 en fixedDay
plan.frequency.day1–28NoDía del mes, solo para fixedDay
plan.frequency.shortDescriptionstringSíEtiqueta corta (p. ej. Mensual)
plan.frequency.longDescriptionstringSíDescripción completa de la cadencia
plan.methodsstring[]SíProcesadores habilitados para cobrar
plan.installmentsnumber[]SíCuotas permitidas — [1] para pago simple
plan.autoRenewalbooleanSíSi Migo programa el siguiente cobro
plan.dailyAttemptsintegerSíReintentos ante un cobro fallido
plan.daysNotifyExpiringCardintegerSíDías de aviso previo al vencimiento de la tarjeta

Guarda el uid del plan que devuelve la respuesta: es lo que después va en customKeys.plan.uid al generar el link de pago.

Listar planes​

curl "https://sb-mw.migopayments.com/api/v1/plans/list?client=<tu-client-slug>" \
-H "Authorization: Bearer <token>"

Consultar un plan​

curl "https://sb-mw.migopayments.com/api/v1/plans/<planId>/client/<client>/detail" \
-H "Authorization: Bearer <token>"

Devuelve el plan más los ajustes específicos de ese comercio (conversión de moneda, nombre localizado) y la próxima fecha de cobro calculada en su zona horaria.

Actualizar un plan​

curl -X PUT https://sb-mw.migopayments.com/api/v1/plans \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"client": "<tu-client-slug>",
"planId": "<plan-id>",
"plan": {
"name": "Plan mensual",
"amount": 119.00
}
}'
Dos reglas que sorprenden
  1. Los campos van anidados bajo plan, y ese objeto debe incluir name aunque no lo estés cambiando. Mandar amount en el nivel superior no hace nada — y no da error.
  2. Cambiar el amount o la frequency no afecta a las suscripciones ya existentes: siguen con su precio y cadencia originales.

Para subir el precio a los clientes actuales tienes que crear un plan nuevo y volver a suscribirlos: la API no permite mover una suscripción de plan.

Eliminar un plan​

No existe borrado de planes

La API expone crear, listar, consultar y actualizar — no hay DELETE /api/v1/plans ni un campo de archivado. Un plan que ya no ofreces queda en tu listado.

Mientras tanto, la práctica recomendada es marcarlo en el name (p. ej. anteponer [Discontinuado]) y filtrarlo del lado de tu aplicación. Borrarlo tampoco sería deseable: rompería la trazabilidad histórica de las suscripciones que se crearon con él.

Relacionado​