Consulta mediante la API el MRR que incluye descuentos
La API de clientes ahora muestra el MRR actual y el pendiente con los descuentos de duración limitada incluidos. Los nuevos campos effectivemrrbycurrency y effectivependingmrrbycurrency corresponden a las columnas «MRR incl. descuentos» y «MRR pendiente incl. descuentos» de la exportación CSV.
La API de clientes ahora muestra el MRR actual y el pendiente con los descuentos de duración limitada incluidos. Los nuevos campos effective_mrr_by_currency y effective_pending_mrr_by_currency corresponden a las columnas «MRR incl. descuentos» y «MRR pendiente incl. descuentos» de la exportación CSV.
El MRR actual y el pendiente siguen siendo independientes: el MRR pendiente abarca las suscripciones con fecha de inicio futura, periodo de prueba activo o pausa activa. Los cuatro campos de la API se agrupan por divisa y usan la unidad monetaria más pequeña, como øre o céntimos.
Contexto histórico: agosto de 2024–septiembre de 2026
La API del MRR empezó con métricas actuales y más adelante incorporó valores pendientes, descuentos, intervalos y cambios programados. La respuesta de una suscripción concreta es más pertinente que el precio del catálogo de planes, porque la suscripción puede tener un precio, una divisa, un periodo de prueba o un descuento propios.
Cuando una integración modifique el periodo de prueba, el descuento o el intervalo de renovación, vuelve a consultar la suscripción actualizada y distingue los cambios que se aplican ahora de los programados. Usa UUID, paginación y la unidad del importe que documenta OpenAPI. Consulta la guía de API pública y webhooks (Markdown-fil, AI-agentvenlig).
Flujo de consulta, cambio y nueva consulta
Empieza con GET /api/v1/subscriptions/{uuid} y usa en el ejemplo de prueba el UUID ficticio e inexistente 00000000-0000-4000-8000-000000000003. Antes de enviar un cambio, guarda el precio actual, el tipo de precio, el intervalo, el periodo de prueba y available_price_change_dates. Envía únicamente la acción que pretendes realizar y vuelve a consultar la suscripción. La API devuelve la suscripción actualizada y puede indicar la fecha efectiva real en meta.effective_date.
Periodo de prueba
Usa PUT /api/v1/subscriptions/{uuid}/trial con { "end_date": "2026-10-15" } para un periodo de prueba existente y desbloqueado. La fecha de finalización debe ser posterior al inicio del periodo de prueba. Si la suscripción no tiene un periodo de prueba o la transacción correspondiente ya se ha facturado o cobrado, la llamada devuelve 422; esta llamada no crea un periodo de prueba.
Descuento
Usa POST /api/v1/subscriptions/{uuid}/discounts con un tipo de descuento documentado. Un porcentaje como 14.29 significa un 14,29 %, mientras que un descuento fijo usa la unidad monetaria más pequeña; por ejemplo, 5000 = 50,00. El periodo del descuento debe comenzar en un periodo desbloqueado y no puede solaparse con otro descuento pendiente. Las suscripciones basadas en el consumo admiten descuentos porcentuales, pero rechazan los descuentos fijos.
Intervalo y precio
PUT /api/v1/subscriptions/{uuid}/interval, por ejemplo con { "interval": 3 }, usa los intervalos configurados en el plan y se aplica a partir del próximo periodo futuro. PUT /api/v1/subscriptions/{uuid}/price recibe price para las suscripciones de tarifa fija o unit_price para las basadas en licencias; no mezcles los campos. Por defecto, los cambios de precio se aplican al siguiente periodo, aunque también pueden aplicarse en una effective_date válida. Los precios basados en el consumo y por tramos siguen sus propias reglas.
Un cambio programado aún no está activo. Si un periodo ya se ha facturado o bloqueado, el cambio se traslada a una fecha futura permitida y se vuelven a generar las transacciones futuras. Usa la respuesta de la suscripción y el endpoint de cambios programados para mostrar lo previsto. Cuando el contrato lo permita, usa DELETE /api/v1/subscriptions/{uuid}/scheduled-changes/{scheduledChangeUuid} para eliminar un cambio pendiente concreto.
Preguntas frecuentes
¿Por qué el MRR de la API no coincide con el precio del plan? El MRR refleja la suscripción concreta, incluidos el descuento, el periodo de prueba, la divisa y el estado; el precio del catálogo del plan es solo el valor predeterminado.
¿Por qué no se aplicó el nuevo precio inmediatamente? Si el periodo ya está bloqueado o facturado, el cambio se traslada a una fecha futura permitida.
¿Por qué se ha rechazado un descuento? Comprueba el tipo, el porcentaje o la unidad monetaria, que la fecha de inicio corresponda a un periodo desbloqueado y que no se solape con otros descuentos.
¿Puedo cambiar el intervalo de una suscripción por tramos? Usa el contrato que tiene en cuenta los tramos y el precio del tramo seleccionado para la suscripción; no lo sustituyas por una fila de intervalo de renovación sin procesar.
Las personas y asistentes de IA detrás de las novedades
Bo Møller y Emil Højbjerg son los principales desarrolladores de Alunta. Como dedican la mayor parte del tiempo a programar, han delegado en nuestros asistentes de IA la redacción de estas explicaciones.
Los asistentes de IA escriben a partir de las actualizaciones que hemos publicado. Bo y Emil están detrás de los cambios y se responsabilizan de que la información refleje lo que realmente se ha lanzado.
