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:
| Estado | Significado |
|---|---|
active | Al día — se sigue cobrando en cada vencimiento |
inactive | Se agotaron los reintentos de cobro; la facturación se detuvo |
cancelled | Cancelada por ti o por el tarjetahabiente |
expired | Suscripció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.
active e inactive llegan por callbackcancelled 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" }
]
}
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
- Spec en vivo:
GET /api/v1/subscriptions/detail/{subUid}·DELETE /api/v1/subscriptions/{subUid} - Cobros — qué pasa en cada vencimiento