# 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[​](#pause-a-subscription "Direct link to Pause a subscription")

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

### Pause immediately[​](#pause-immediately "Direct link to 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[​](#pause-at-the-end-of-the-current-billing-period "Direct link to 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[​](#auto-resume-after-n-billing-cycles "Direct link to 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-subscription "Direct link to 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[​](#cancel-a-subscription "Direct link to Cancel a subscription")

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

### Cancel immediately[​](#cancel-immediately "Direct link to 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[​](#cancel-at-the-end-of-the-current-billing-period "Direct link to 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](#resume-a-subscription) to clear the cancel-at-period-end flag.

## Skip billing cycles[​](#skip-billing-cycles "Direct link to 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](https://docs.monei.com/apis/rest/subscriptions-update/.md) 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[​](#update-payment-method "Direct link to Update payment method")

To change the payment method on an active subscription, call the [activate](https://docs.monei.com/apis/rest/subscriptions-activate/.md) 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 [Hosted Payment Page](https://docs.monei.com/subscriptions/use-prebuilt-payment-page/.md#2-activate-the-subscription-server-side) or [custom checkout](https://docs.monei.com/subscriptions/build-custom-checkout/.md) approach. After the new payment method is verified, all future recurring charges will use it.

## Update subscription details[​](#update-subscription-details "Direct link to Update subscription details")

Modify subscription properties like amount, billing interval, description, metadata, or the next payment date using the [update subscription](https://docs.monei.com/apis/rest/subscriptions-update/.md) 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.