Saltar a contenido

Gestión de actualizaciones y cambios a niveles inferiores de suscripción con prorrateo en 4Geeks Payments

🤖 Explicar con IA

La gestión de los ciclos de vida de las suscripciones es una parte crítica de la gestión de un negocio de SaaS o de membresías. Cuando un cliente actualiza (upgrade) o cambia a un nivel inferior (downgrade) su plan en medio de un ciclo de facturación, 4Geeks Payments gestiona automáticamente los cálculos de prorrateo. Esto garantiza que a sus clientes se les cobre de manera justa —pagando solo por el tiempo que usaron en cada plan— sin que usted necesite realizar cálculos manuales o emitir reembolsos por separado.

Esta guía explica cómo actualizar o cambiar a un nivel inferior una suscripción de forma programática utilizando la API de 4Geeks Payments y cómo el sistema calcula los cargos o créditos prorrateados resultantes.

Requisitos previos

Antes de comenzar, asegúrese de tener lo siguiente:

  • Una cuenta de 4Geeks Payments: Debe tener una cuenta de comercio activa.
  • Claves de API: Sus claves sk_test_ (para modo de prueba) o sk_live_ (para producción).
  • ID de suscripción: El identificador único (UUID) de la suscripción que desea modificar.
  • ID del plan: El identificador único del nuevo plan al que se está moviendo el cliente.
  • Acceso a 4Geeks Console: Inicie sesión para gestionar y verificar los cambios.

Cómo actualizar una suscripción

4Geeks Payments simplifica los cambios al tratar las actualizaciones y los cambios a niveles inferiores como una actualización del objeto de suscripción existente. El sistema detecta automáticamente la diferencia de precio y aplica el prorrateo necesario.

Paso 1: Recuperar la suscripción actual

  1. Inicie sesión en la 4Geeks Console.
  2. Navegue al módulo Payments.
  3. Seleccione Subscriptions en la barra lateral.
  4. Busque al cliente por correo electrónico o ID para listar sus suscripciones activas.
  5. Anote el subscription_id de la que desea actualizar.

Alternativamente, use la API para obtener suscripciones de forma programática:

  • Endpoint: GET https://api.4geeks.io/v1/subscriptions/?customer={customer_id}

Paso 2: Actualizar el plan de suscripción

Envíe una solicitud PUT al endpoint de suscripción con el nuevo plan_id. Esto activa la lógica de prorrateo.

  1. Prepare su solicitud de API con la clave adecuada.
  2. Incluya los detalles del nuevo plan en el cuerpo de la solicitud.

Ejemplo de solicitud (usando cURL):

curl -X PUT "https://api.4geeks.io/v1/subscriptions/sub_123456789" \
  -u "sk_test_YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_new_tier_id"
  }'
  1. Envíe la solicitud. El sistema calcula el prorrateo inmediatamente para el ciclo de facturación actual.

Consejo: Para las actualizaciones, espere una factura inmediata. Para los cambios a niveles inferiores, se aplica un crédito a futuras facturas. Evite mezclar IDs de modo de prueba y de producción para prevenir errores.

Paso 3: Verificar la factura de prorrateo

  1. Verifique la respuesta de la API para obtener los detalles de la suscripción actualizada, incluyendo la latest_invoice.
  2. En la 4Geeks Console, vaya a Invoices para ver la nueva factura prorrateada.
  3. Confirme el estado (por ejemplo, “paid” o “open”) y el importe adeudado.

Ejemplo de respuesta (JSON simplificado):

{
  "id": "sub_123456789",
  "status": "active",
  "plan": {
    "id": "plan_new_tier_id",
    "name": "Pro Plan",
    "amount": 50.00
  },
  "current_period_end": "2023-12-01T00:00:00Z",
  "latest_invoice": {
    "id": "inv_987654321",
    "amount_due": 15.50,
    "status": "paid"
  }
}

Mejor práctica: Supervise los webhooks para eventos como invoice.created o invoice.payment_succeeded para automatizar las notificaciones o actualizaciones en su sistema.

Casos de uso comunes

Escenario 1: Actualización a mitad de ciclo (cargo inmediato)

Un cliente con un Plan Básico de $10/mes se actualiza al Plan Pro de $30/mes a mitad del mes.

  • El sistema acredita ~\(5 por el tiempo no utilizado del Plan Básico y cobra ~\)15 por el tiempo restante del Plan Pro.
  • Resultado: Factura inmediata de $10. Sin interrupción del servicio, y el ciclo de facturación sigue siendo el mismo.

Esto mantiene satisfechos a los clientes al proporcionar acceso instantáneo a nuevas funciones y garantizar una facturación justa.

Escenario 2: Cambio a nivel inferior a mitad de ciclo (crédito aplicado)

Un cliente cambia de nivel inferior de Plan Pro de $30/mes a Plan Básico de $10/mes a mitad de ciclo.

  • Acredita ~\(15 por el tiempo no utilizado del Plan Pro y cobra ~\)5 por el tiempo restante del Plan Básico.
  • Resultado: Crédito de $10 almacenado en el saldo del cliente, aplicado a la siguiente factura.

Ideal para retener a los clientes que necesitan flexibilidad sin pagar de más.

Solución de problemas

Problema 1: La API devuelve 404 No encontrado

  • Causa: subscription_id o plan_id incorrectos.
  • Solución: Verifique dos veces los IDs en la 4Geeks Console. Asegúrese de la coherencia entre el modo de prueba y de producción.

Problema 2: La factura de actualización falla (402 Pago requerido)

  • Causa: La tarjeta del cliente rechaza el cargo prorrateado.
  • Solución: Verifique el estado de latest_invoice. Solicite al cliente que actualice su método de pago a través del enlace del portal del cliente.

Problema 3: No hay cargos visibles para el cambio a nivel inferior

  • Causa: Los cambios a niveles inferiores crean créditos, no reembolsos inmediatos.
  • Solución: Verifique el saldo del cliente en la API o en la 4Geeks Console. Los créditos se aplican automáticamente a facturas futuras.

Conclusión

Con 4Geeks Payments, la gestión de los cambios de suscripción es fluida y automatizada, lo que reduce la carga administrativa y mejora la satisfacción del cliente. Implemente estos pasos para gestionar las actualizaciones y los cambios a niveles inferiores de manera eficiente. Para una automatización más avanzada, explore la integración con los Agentes de IA de 4Geeks.

Recursos adicionales