Gestionar suscripciones

Una vez que una suscripción está activada, puedes gestionar su ciclo de vida usando la API de MONEI — pausar, reanudar, cancelar, omitir pagos, actualizar el método de pago, modificar los detalles de la suscripción y prorratear cambios de plan.

Pausar una suscripción

Suspende temporalmente la facturación sin cancelar la suscripción. Hay varias formas de pausar:

Pausar inmediatamente

La suscripción pasa al estado PAUSED de inmediato. No se cobran más pagos hasta que la reanudes.

cURL

POST https://api.monei.com/v1/subscriptions/{id}/pause

curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/pause' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json'

Node.js

server.js

const subscription = await monei.subscriptions.pause('YOUR_SUBSCRIPTION_ID');

PHP

server.php

<?php
$subscription = $monei->subscriptions->pause('YOUR_SUBSCRIPTION_ID');
?>

Python

server.py

subscription = monei.subscriptions.pause("YOUR_SUBSCRIPTION_ID")

Pausar al final del periodo de facturación actual

La suscripción permanece ACTIVE hasta que finaliza el periodo de facturación actual y luego pasa a PAUSED.

cURL

POST https://api.monei.com/v1/subscriptions/{id}/pause

curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/pause' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "pauseAtPeriodEnd": true,
  "pauseIntervalCount": 3
}'

Node.js

server.js

const subscription = await monei.subscriptions.pause('YOUR_SUBSCRIPTION_ID', {
  pauseAtPeriodEnd: true,
  pauseIntervalCount: 3
});

PHP

server.php

<?php
use Monei\Model\PauseSubscriptionRequest;

$subscription = $monei->subscriptions->pause(
  'YOUR_SUBSCRIPTION_ID',
  new PauseSubscriptionRequest([
    'pause_at_period_end' => true,
    'pause_interval_count' => 3
  ])
);
?>

Python

server.py

from Monei import PauseSubscriptionRequest

subscription = monei.subscriptions.pause(
    "YOUR_SUBSCRIPTION_ID",
    pause_subscription_request=PauseSubscriptionRequest(
        pause_at_period_end=True,
        pause_interval_count=3
    )
)

Reanudación automática tras N ciclos de facturación

Establece pauseIntervalCount para reanudar automáticamente la suscripción después de un número específico de ciclos de facturación. Por ejemplo, si la suscripción se factura mensualmente y estableces pauseIntervalCount: 3, se pausará durante 3 meses y luego se reanudará automáticamente.

Cuando el contador llega a 0, la suscripción vuelve a ACTIVE y la facturación se reanuda.

Reanudar una suscripción

Reanuda una suscripción pausada para reiniciar la facturación. El siguiente pago se programa al final del periodo de facturación actual.

cURL

POST https://api.monei.com/v1/subscriptions/{id}/resume

curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/resume' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json'

Node.js

server.js

const subscription = await monei.subscriptions.resume('YOUR_SUBSCRIPTION_ID');

PHP

server.php

<?php
$subscription = $monei->subscriptions->resume('YOUR_SUBSCRIPTION_ID');
?>

Python

server.py

subscription = monei.subscriptions.resume("YOUR_SUBSCRIPTION_ID")

Al reanudar se eliminan cualquier indicador pendiente de pausa o cancelación al final del periodo.

Cancelar una suscripción

Detiene permanentemente una suscripción. Una vez cancelada, no se realizarán más cobros.

Cancelar inmediatamente

cURL

POST https://api.monei.com/v1/subscriptions/{id}/cancel

curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/cancel' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json'

Node.js

server.js

const subscription = await monei.subscriptions.cancel('YOUR_SUBSCRIPTION_ID');

PHP

server.php

<?php
$subscription = $monei->subscriptions->cancel('YOUR_SUBSCRIPTION_ID');
?>

Python

server.py

subscription = monei.subscriptions.cancel("YOUR_SUBSCRIPTION_ID")

Cancelar al final del periodo de facturación actual

La suscripción permanece activa hasta que finaliza el periodo actual y luego pasa a CANCELED. El cliente conserva el acceso hasta que vence su periodo pagado.

cURL

POST https://api.monei.com/v1/subscriptions/{id}/cancel

curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/cancel' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "cancelAtPeriodEnd": true
}'

Node.js

server.js

const subscription = await monei.subscriptions.cancel('YOUR_SUBSCRIPTION_ID', {
  cancelAtPeriodEnd: true
});

PHP

server.php

<?php
use Monei\Model\CancelSubscriptionRequest;

$subscription = $monei->subscriptions->cancel(
  'YOUR_SUBSCRIPTION_ID',
  new CancelSubscriptionRequest([
    'cancel_at_period_end' => true
  ])
);
?>

Python

server.py

from Monei import CancelSubscriptionRequest

subscription = monei.subscriptions.cancel(
    "YOUR_SUBSCRIPTION_ID",
    cancel_subscription_request=CancelSubscriptionRequest(
        cancel_at_period_end=True
    )
)

tip

Si un cliente cambia de opinión antes de que finalice el periodo, puedes reanudar la suscripción para eliminar el indicador de cancelación al final del periodo.

Omitir ciclos de facturación

Omite uno o más ciclos de facturación sin cambiar el estado de la suscripción. La suscripción permanece ACTIVE — simplemente no se cobra el pago durante los ciclos omitidos.

Usa el endpoint actualizar suscripción con skipIntervalCount (1–31):

cURL

PUT https://api.monei.com/v1/subscriptions/{id}

curl --request PUT 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "skipIntervalCount": 2
}'

Node.js

server.js

const subscription = await monei.subscriptions.update('YOUR_SUBSCRIPTION_ID', {
  skipIntervalCount: 2
});

PHP

server.php

<?php
use Monei\Model\UpdateSubscriptionRequest;

$subscription = $monei->subscriptions->update(
  'YOUR_SUBSCRIPTION_ID',
  new UpdateSubscriptionRequest([
    'skip_interval_count' => 2
  ])
);
?>

Python

server.py

from Monei import UpdateSubscriptionRequest

subscription = monei.subscriptions.update(
    "YOUR_SUBSCRIPTION_ID",
    UpdateSubscriptionRequest(
        skip_interval_count=2
    )
)

Por ejemplo, establecer skipIntervalCount: 2 en una suscripción mensual omite los 2 próximos pagos mensuales. La facturación se reanuda automáticamente tras los ciclos omitidos.

nota

Omitir solo está disponible para suscripciones en estado ACTIVE, TRIALING o PAST_DUE. No se puede usar en suscripciones pausadas, canceladas o pendientes.

Actualizar el método de pago

Para cambiar el método de pago de una suscripción activa, llama de nuevo al endpoint activate. MONEI crea un pago de verificación de €0 para validar el nuevo método de pago sin cobrar al cliente.

El flujo de activación es el mismo que la activación inicial — usa el enfoque de página de pago alojada o de checkout personalizado. Una vez verificado el nuevo método de pago, todos los cobros recurrentes futuros lo utilizarán.

Actualizar los detalles de la suscripción

Modifica propiedades de la suscripción como el importe, el intervalo de facturación, la descripción, los metadatos o la fecha del próximo pago usando el endpoint actualizar suscripción.

cURL

PUT https://api.monei.com/v1/subscriptions/{id}

curl --request PUT 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 2500,
  "description": "Pro Plan Monthly (upgraded)"
}'

Node.js

server.js

const subscription = await monei.subscriptions.update('YOUR_SUBSCRIPTION_ID', {
  amount: 2500,
  description: 'Pro Plan Monthly (upgraded)'
});

PHP

server.php

<?php
use Monei\Model\UpdateSubscriptionRequest;

$subscription = $monei->subscriptions->update(
  'YOUR_SUBSCRIPTION_ID',
  new UpdateSubscriptionRequest([
    'amount' => 2500,
    'description' => 'Pro Plan Monthly (upgraded)'
  ])
);
?>

Python

server.py

from Monei import UpdateSubscriptionRequest

subscription = monei.subscriptions.update(
    "YOUR_SUBSCRIPTION_ID",
    UpdateSubscriptionRequest(
        amount=2500,
        description="Pro Plan Monthly (upgraded)"
    )
)

Campos actualizables:

• amount — Cambia el importe del cobro recurrente. El nuevo importe se aplica desde el siguiente ciclo de facturación. Para cobrar o reembolsar la diferencia ahora, prorratea el cambio.
• interval / intervalCount — Cambia la frecuencia de facturación. El periodo máximo es de 1 año. El periodo actual llega a su fin y el nuevo intervalo se aplica desde el siguiente.
• nextPaymentAt — Mueve el próximo cobro a otra fecha, sin cambiar el precio. Consulta Mover la fecha del próximo cobro.
• trialPeriodEnd — Amplía el periodo de prueba de una suscripción en estado TRIALING (debe ser una marca de tiempo futura).
• description / metadata — Actualiza los campos descriptivos y los metadatos personalizados.

Restricción de Bizum

Si la suscripción usa Bizum como método de pago, el importe no puede modificarse tras la activación y los cobros no se pueden prorratear.

Mover la fecha del próximo cobro

Envía nextPaymentAt (una marca de tiempo Unix en segundos) para mover el próximo cobro. Los cobros siguientes parten de la nueva fecha. Por sí solo, el cambio no cobra ni reembolsa nada.

• La fecha debe ser futura y no más de cinco años en adelante.
• La suscripción debe estar en ACTIVE o PAST_DUE. Para mover una prueba, actualiza trialPeriodEnd. Para mover una suscripción pausada, reanúdala primero.
• Una omisión, pausa o cancelación pendiente bloquea el cambio, porque el cobro en la nueva fecha no se produciría. Elimínala en la misma solicitud: envía skipIntervalCount: 0, pauseIntervalCount: null, pauseAtPeriodEnd: false o cancelAtPeriodEnd: false.
• En una suscripción PAST_DUE, el cambio detiene los reintentos y programa el cobro en la nueva fecha.

Para cobrar o reembolsar el tiempo que el cambio añade o quita, envía también prorate: true.

Prorratear un cambio

Por defecto, un nuevo precio o intervalo se aplica en el siguiente ciclo de facturación. Envía prorate: true con la actualización para liquidar la diferencia ahora: MONEI abona el tiempo no usado al precio actual, cobra el nuevo precio y cobra o reembolsa la diferencia.

Lo que MONEI cobra depende de lo que cambies:

Cambio	Abono	Cobro	Periodo de facturación
amount	Tiempo no usado al precio actual	Tiempo restante al nuevo precio	Sin cambios
interval / intervalCount	Tiempo no usado al precio actual	El nuevo precio completo	Se reinicia ahora
nextPaymentAt	Tiempo no usado al precio actual	Tiempo desde ahora hasta la nueva fecha, al precio actual	Termina en la nueva fecha

Una fecha posterior cobra el tiempo que añade. Una fecha anterior reembolsa el tiempo que quita.

Por ejemplo, un cliente con un plan mensual de 10 € sube a 20 € a mitad de mes. MONEI abona 5 € por la mitad no usada a 10 €, cobra 10 € por esa misma mitad a 20 € y cobra la diferencia de 5 € al método de pago guardado. El siguiente cobro de 20 € se hace en la fecha original.

1. Previsualiza el cambio

Llama a previsualizar la actualización de la suscripción con los mismos campos que vas a enviar. Devuelve lo que liquidaría el cambio y no modifica nada. Muéstralo al cliente antes de que confirme.

cURL

POST https://api.monei.com/v1/subscriptions/{id}/preview

curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/preview' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 2000
}'

Node.js

server.js

const preview = await monei.subscriptions.preview('YOUR_SUBSCRIPTION_ID', {
  amount: 2000
});

PHP

server.php

<?php
use Monei\Model\PreviewSubscriptionUpdateRequest;

$preview = $monei->subscriptions->preview(
  'YOUR_SUBSCRIPTION_ID',
  new PreviewSubscriptionUpdateRequest([
    'amount' => 2000
  ])
);
?>

Python

server.py

from Monei import PreviewSubscriptionUpdateRequest

preview = monei.subscriptions.preview(
    "YOUR_SUBSCRIPTION_ID",
    PreviewSubscriptionUpdateRequest(
        amount=2000
    )
)

Response

{
  "credit": 500,
  "charge": 1000,
  "net": 500,
  "direction": "charge",
  "refundCapped": false,
  "effectiveAt": 1790000000,
  "currentPeriodEnd": 1791296000
}

• credit — Tiempo no usado al precio actual, en la unidad monetaria más pequeña.
• charge — Tiempo al nuevo precio. Un cambio de intervalo cobra el nuevo precio completo.
• net — charge menos credit: el importe que se mueve.
• direction — charge, refund o none. none significa que la diferencia se redondea a cero.
• newPeriodEnd / nextPaymentAt — Solo cuando el cambio reinicia o mueve el periodo de facturación.

Las cifras son una estimación: la actualización las recalcula al aplicarla. La previsualización hace las mismas comprobaciones que la actualización, así que un cambio que la previsualización rechaza también se rechaza al actualizar.

2. Aplica el cambio

Envía los mismos campos a actualizar la suscripción con prorate: true:

cURL

PUT https://api.monei.com/v1/subscriptions/{id}

curl --request PUT 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 2000,
  "prorate": true
}'

Node.js

server.js

const subscription = await monei.subscriptions.update('YOUR_SUBSCRIPTION_ID', {
  amount: 2000,
  prorate: true
});

PHP

server.php

<?php
use Monei\Model\UpdateSubscriptionRequest;

$subscription = $monei->subscriptions->update(
  'YOUR_SUBSCRIPTION_ID',
  new UpdateSubscriptionRequest([
    'amount' => 2000,
    'prorate' => true
  ])
);
?>

Python

server.py

from Monei import UpdateSubscriptionRequest

subscription = monei.subscriptions.update(
    "YOUR_SUBSCRIPTION_ID",
    UpdateSubscriptionRequest(
        amount=2000,
        prorate=True
    )
)

La respuesta es la suscripción actualizada. lastProration registra lo que liquidó el cambio (credit, charge, net y el paymentId del cobro, si lo hay) y lastProrationAt registra cuándo. MONEI también envía un webhook subscription.updated.

Cómo funcionan los reembolsos

Cuando la diferencia es negativa, MONEI la reembolsa de los pagos que financiaron el periodo de facturación actual, empezando por el más reciente: el cobro del último cambio prorrateado del periodo y después el pago de renovación. Si entre los dos no cubren el reembolso, MONEI rechaza el cambio y no mueve dinero. Un cambio se liquida completo o no se liquida.

Para reembolsar, tu cuenta debe tener los reembolsos habilitados.

Límites

• Estado — Solo suscripciones ACTIVE y TRIALING. En una suscripción TRIALING los campos cambian y no se mueve dinero, porque no hay tiempo pagado que abonar.
• Cambios repetidos — Puedes prorratear un periodo de facturación más de una vez. Espera al menos un segundo entre cambios: MONEI rechaza un cambio mientras el anterior se está liquidando.
• Periodos redimensionados — Después de un cambio que mueve el fin del periodo actual (un cambio de nextPaymentAt, o un cambio de intervalo sin prorate), no puedes volver a prorratear hasta la siguiente renovación.
• Fecha del próximo cobro — Un cambio prorrateado de nextPaymentAt solo funciona en suscripciones ACTIVE, no se puede combinar con un cambio de intervalo y no puede cobrar más de 24 periodos de facturación.
• Cambios programados — prorate no se puede combinar con trialPeriodEnd, cancelAtPeriodEnd, pauseAtPeriodEnd, pauseIntervalCount ni skipIntervalCount. Un cambio de intervalo prorrateado se rechaza mientras haya una cancelación, pausa u omisión programada. La única excepción es un cambio de nextPaymentAt, que acepta los valores de eliminación de Mover la fecha del próximo cobro.
• Algo que liquidar — prorate necesita un cambio en amount, interval, intervalCount o nextPaymentAt.
• Bizum — Las suscripciones que pagan con Bizum no se pueden prorratear.

Prorratear en el Dashboard

1. En el MONEI Dashboard, abre la suscripción y haz clic en Actualizar.
2. Cambia el Importe, el Periodo de facturación o la Próxima fecha de cobro.
3. Activa Aplica el cambio ahora. El formulario muestra lo que se cobrará o reembolsará al cliente.
4. Haz clic en Actualizar la suscripción.

Formulario Actualizar la suscripción en el panel de MONEI: el importe sube a 49 € con Aplica el cambio ahora activado, y el formulario indica que al cliente se le cobrarán 10,26 € ahora

El interruptor Aplica el cambio ahora aparece en las suscripciones activas que no pagan con Bizum. Cada liquidación aparece después en la cronología de la suscripción como Cobro prorrateado o Reembolso prorrateado.

Cronología de la suscripción en el panel de MONEI: tras cambiar el importe a 49,00 €, se cobraron 10,26 € prorrateados por el resto del periodo de facturación