Saltar al contenido principal
Migo Docs

Suscripciones

Una suscripción une a un cliente final con un plan y con la tarjeta que quedó guardada al pagar. Migo la crea sola cuando se aprueba el pago del link de pago — no hay un POST /api/v1/subscriptions.

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

Estados​

Existen exactamente cuatro:

EstadoSignificado
activeAl día — se sigue cobrando en cada vencimiento
inactiveSe agotaron los reintentos de cobro; la facturación se detuvo
cancelledCancelada por ti o por el tarjetahabiente
expiredSuscripción de plazo fijo que llegó a su fin
┌──────────┐
│ active │
└────┬─────┘
┌─────────────┼─────────────┐
▼ ▼ ▼
┌───────────┐ ┌──────────┐ ┌──────────┐
│ cancelled │ │ inactive │ │ expired │
└───────────┘ └──────────┘ └──────────┘
la cancelas se agotaron venció el
los intentos plazo fijo

Los estados son terminales: no se puede reactivar una suscripción cancelled o inactive. Para retomar el cobro, genera un nuevo link de pago y que el cliente vuelva a pagar.

No existen trialing, past_due, unpaid ni paused: la API no soporta pruebas gratis, pausa, cambio de plan ni prorrateo.

Solo active e inactive llegan por callback

cancelled y expired no se notifican. Si te importan, consulta la suscripción periódicamente (ver Callback de suscripciones).

Consultar una suscripción​

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

Es la vía para conocer el estado real, incluidos los que el callback no notifica.

Listar suscripciones​

Requiere ambos parámetros, userId y clientId — si falta cualquiera devuelve 400:

curl "https://sb-mw.migopayments.com/api/v1/subscriptions?userId=<userId>&clientId=<clientId>" \
-H "Authorization: Bearer <token>"
{
"success": true,
"message": "subscriptions found",
"data": [
{ "planName": "Plan mensual", "uid": "sub_000001", "URL": "https://.../subscriptions/sub_000001" }
]
}
Es un listado por cliente final, no un listado general

No hay forma de traer «todas las suscripciones de mi comercio»: siempre tienes que saber el userId. Tampoco hay filtros por estado o plan, ni paginación. Mantén tu propio índice de clientes para poder recorrerlos.

Actualizar una suscripción​

PUT /api/v1/subscriptions cambia únicamente el email de notificación:

curl -X PUT https://sb-mw.migopayments.com/api/v1/subscriptions \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "subUid": "sub_000001", "email": "facturacion@ejemplo.com" }'

No cambia el plan, el importe, el estado ni la tarjeta. Para la tarjeta usa Métodos de pago.

Cancelar una suscripción​

curl -X DELETE https://sb-mw.migopayments.com/api/v1/subscriptions/<subUid> \
-H "Authorization: Bearer <token>"

La cancelación es inmediata: el estado pasa a cancelled y no se vuelve a cobrar. No hay cancelación diferida a fin de periodo ni reembolso automático del ciclo en curso; si quieres respetar el tiempo ya pagado, controlas tú la fecha de corte del acceso.

Alternativa: crear la suscripción desde tu propio checkout​

Si tienes alcance PCI y cobras con tu propio formulario de tarjeta, puedes crear la suscripción sin el webview: POST /api/v1/subscriptions/verify-card con shouldCreateSubscription: true y el planUid, ligado a una transacción existente. Tokeniza la tarjeta, la preautoriza, revierte esa autorización y crea la suscripción en el mismo paso.

Para la gran mayoría de integraciones no es el camino: exige certificación PCI y manejar datos de tarjeta. Ver Métodos de pago.

Relacionado​