Manage subscriptions

After a subscription is activated, you can manage its lifecycle using the MONEI API — pause, resume, cancel, skip payments, update the payment method, and modify subscription details.

Pause a subscription

Temporarily suspend billing without canceling the subscription. There are several ways to pause:

Pause immediately

The subscription moves to PAUSED status right away. No further payments are charged until you resume it.

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

Pause at the end of the current billing period

The subscription stays ACTIVE until the current billing period ends, then transitions to 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
    )
)

Auto-resume after N billing cycles

Set pauseIntervalCount to automatically resume the subscription after a specific number of billing cycles. For example, if the subscription bills monthly and you set pauseIntervalCount: 3, it will pause for 3 months and then automatically resume.

When the count reaches 0, the subscription transitions back to ACTIVE and billing resumes.

Resume a subscription

Resume a paused subscription to restart billing. The next payment is scheduled at the end of the current billing period.

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

Resuming clears any pending pause or cancel-at-period-end flags.

Cancel a subscription

Permanently stop a subscription. Once canceled, no further payments will be charged.

Cancel immediately

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

Cancel at the end of the current billing period

The subscription stays active until the current period ends, then transitions to CANCELED. The customer continues to have access until their paid period expires.

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

If a customer changes their mind before the period ends, you can resume the subscription to clear the cancel-at-period-end flag.

Skip billing cycles

Skip one or more billing cycles without changing the subscription status. The subscription remains ACTIVE — the payment is simply not charged during the skipped cycles.

Use the update subscription endpoint with 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
    )
)

For example, setting skipIntervalCount: 2 on a monthly subscription skips the next 2 monthly payments. Billing resumes automatically after the skipped cycles.

note

Skip is only available for subscriptions in ACTIVE, TRIALING, or PAST_DUE status. It cannot be used on paused, canceled, or pending subscriptions.

Update payment method

To change the payment method on an active subscription, call the activate endpoint again. MONEI creates a €0 verification payment to validate the new payment method without charging the customer.

The activation flow is the same as the initial activation — use either the prebuilt payment page or custom checkout approach. After the new payment method is verified, all future recurring charges will use it.

Update subscription details

Modify subscription properties like amount, billing interval, description, metadata, or the next payment date using the update subscription endpoint.

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

Updatable fields:

amount — Change the recurring charge amount. The new amount applies from the next billing cycle.
interval / intervalCount — Change the billing frequency. The maximum period is 1 year.
nextPaymentAt — Reschedule the next payment to a specific date (must be in the future).
trialPeriodEnd — Extend the trial period on a TRIALING subscription (must be a future timestamp).
description / metadata — Update descriptive fields and custom metadata.

Bizum restriction

If the subscription uses Bizum as the payment method, the amount cannot be changed after activation.

Send subscription link

Send an activation link to the customer via email or SMS without writing any integration code. Useful for manually creating subscriptions from your 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"
    )
)

You can also send the link via SMS using customerPhone instead of customerEmail.

Pause a subscription​

Pause immediately​

Pause at the end of the current billing period​

Auto-resume after N billing cycles​

Resume a subscription​

Cancel a subscription​

Cancel immediately​

Cancel at the end of the current billing period​

Skip billing cycles​

Update payment method​

Update subscription details​

Send subscription link​