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 y modificar los detalles de la suscripción.

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
Node.js
PHP
Python

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'

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

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

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
Node.js
PHP
Python

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
}'

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

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
  ])
);
?>

server.py
from Monei import PauseSubscriptionRequest

subscription = monei.subscriptions.pause(
    "YOUR_SUBSCRIPTION_ID",
    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
Node.js
PHP
Python

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'

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

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

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
Node.js
PHP
Python

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'

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

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

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
Node.js
PHP
Python

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
}'

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

server.php
<?php
use Monei\Model\CancelSubscriptionRequest;

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

server.py
from Monei import CancelSubscriptionRequest

subscription = monei.subscriptions.cancel(
    "YOUR_SUBSCRIPTION_ID",
    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
Node.js
PHP
Python

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
}'

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

server.php
<?php
use Monei\Model\UpdateSubscriptionRequest;

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

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 prediseñada 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
Node.js
PHP
Python

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)"
}'

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

server.php
<?php
use Monei\Model\UpdateSubscriptionRequest;

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

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.
interval / intervalCount — Cambia la frecuencia de facturación. El periodo máximo es de 1 año.
nextPaymentAt — Reprograma el próximo pago a una fecha específica (debe ser en el futuro).
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.

Enviar enlace de suscripción

Envía un enlace de activación al cliente por correo electrónico o SMS sin necesidad de escribir código de integración. Útil para crear suscripciones manualmente desde tu back office.

cURL
Node.js
PHP
Python

POST https://api.monei.com/v1/subscriptions/{id}/link
curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/link' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerEmail": "john.doe@example.com"
}'

server.js
const subscription = await monei.subscriptions.sendLink('YOUR_SUBSCRIPTION_ID', {
  customerEmail: 'john.doe@example.com'
});

server.php
<?php
use Monei\Model\SendSubscriptionLinkRequest;

$subscription = $monei->subscriptions->sendLink(
  'YOUR_SUBSCRIPTION_ID',
  new SendSubscriptionLinkRequest([
    'customer_email' => 'john.doe@example.com'
  ])
);
?>

server.py
from Monei import SendSubscriptionLinkRequest

subscription = monei.subscriptions.send_link(
    "YOUR_SUBSCRIPTION_ID",
    SendSubscriptionLinkRequest(
        customer_email="john.doe@example.com"
    )
)

También puedes enviar el enlace por SMS usando customerPhone en lugar de customerEmail.

Pausar una suscripción​

Pausar inmediatamente​

Pausar al final del periodo de facturación actual​

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

Reanudar una suscripción​

Cancelar una suscripción​

Cancelar inmediatamente​

Cancelar al final del periodo de facturación actual​

Omitir ciclos de facturación​

Actualizar el método de pago​

Actualizar los detalles de la suscripción​

Enviar enlace de suscripción​