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»:
| Valor | Qué hace | Cuándo usarlo |
|---|---|---|
"interval" | Cobra cada N días desde el alta | El más común — semanal, cada 30 días, cada 90 días |
"fixedDay" | Cobra un día fijo del mes | Facturación «el 1» o «el 15» de cada mes |
"anniversary" | Cobra el mismo día calendario en cada ciclo | Suscripciones anuales |
"automatic" | Delega el cálculo al procesador | Poco 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
}
}'
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
client | string | Sí | Tu slug de comercio |
plan.name | string | Sí | Se le muestra al tarjetahabiente |
plan.amount | number | Sí | Decimal, hasta 4 posiciones |
plan.currency | ISO 4217 | Sí | GTQ, USD, … |
plan.type | enum | No | Ver la tabla de cadencia |
plan.frequency.frequency | integer | Sí | Días entre cobros; 0 en fixedDay |
plan.frequency.day | 1–28 | No | Día del mes, solo para fixedDay |
plan.frequency.shortDescription | string | Sí | Etiqueta corta (p. ej. Mensual) |
plan.frequency.longDescription | string | Sí | Descripción completa de la cadencia |
plan.methods | string[] | Sí | Procesadores habilitados para cobrar |
plan.installments | number[] | Sí | Cuotas permitidas — [1] para pago simple |
plan.autoRenewal | boolean | Sí | Si Migo programa el siguiente cobro |
plan.dailyAttempts | integer | Sí | Reintentos ante un cobro fallido |
plan.daysNotifyExpiringCard | integer | Sí | 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
}
}'
- Los campos van anidados bajo
plan, y ese objeto debe incluirnameaunque no lo estés cambiando. Mandaramounten el nivel superior no hace nada — y no da error. - Cambiar el
amounto lafrequencyno 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
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
- Spec en vivo:
POST /api/v1/plans·GET /api/v1/plans/list·PUT /api/v1/plans - Link de pago de suscripción — el siguiente paso