# Subscriptions overview

Subscriptions allow you to charge a customer on a recurring basis. MONEI handles the billing cycle automatically — you create and activate a subscription, and MONEI charges the customer at each billing interval.

## Subscription lifecycle[​](#subscription-lifecycle "Direct link to Subscription lifecycle")

A subscription moves through several statuses during its lifetime:

<!-- -->

### Statuses[​](#statuses "Direct link to Statuses")

| Status    | Description                                                                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| PENDING   | Subscription created, awaiting activation. The customer has not yet provided a payment method.                                                   |
| TRIALING  | Active trial period. A €0 verification payment was made to validate the payment method. Billing begins when the trial ends.                      |
| ACTIVE    | Recurring payments are being charged at each billing interval.                                                                                   |
| PAUSED    | Billing is temporarily suspended. The subscription can be resumed at any time.                                                                   |
| PAST\_DUE | A recurring payment failed. MONEI will retry according to the [retry schedule](https://docs.monei.com/subscriptions/handle-failed-payments/.md). |
| CANCELED  | The subscription has been permanently stopped. No further payments will be charged.                                                              |
| EXPIRED   | The subscription was not activated in time and can no longer be used.                                                                            |

## Billing intervals[​](#billing-intervals "Direct link to Billing intervals")

Configure how often the customer is charged using `interval` and `intervalCount`:

| interval | intervalCount | Billing frequency          |
| -------- | ------------- | -------------------------- |
| day      | 1             | Every day                  |
| week     | 1             | Every week                 |
| week     | 2             | Every 2 weeks              |
| month    | 1             | Every month                |
| month    | 3             | Every 3 months (quarterly) |
| year     | 1             | Every year                 |

The maximum billing period is 1 year. For example, `intervalCount` cannot exceed 365 for `day`, 52 for `week`, 12 for `month`, or 1 for `year`.

note

`minute` and `hour` intervals are available in [test mode](https://docs.monei.com/testing/.md) only — useful for quickly testing your integration without waiting for real billing cycles.

## Trial periods[​](#trial-periods "Direct link to Trial periods")

You can offer a free trial before the first charge. Configure it with one of:

* **trialPeriodDays** — number of free days (e.g., `14` for a 14-day trial)
* **trialPeriodEnd** — Unix timestamp when the trial ends

During activation, MONEI creates a €0 verification payment to validate the customer's payment method without charging them. The first real charge occurs when the trial period ends.

You can extend an active trial by updating `trialPeriodEnd` on a TRIALING subscription — see [Update subscription details](https://docs.monei.com/subscriptions/manage-subscriptions/.md#update-subscription-details).

## Webhook events[​](#webhook-events "Direct link to Webhook events")

MONEI sends webhook notifications for subscription status changes and recurring payments. You configure two separate callback URLs when creating a subscription:

* **callbackUrl** — receives subscription status change events
* **paymentCallbackUrl** — receives payment events for each recurring charge

### Subscription events[​](#subscription-events "Direct link to Subscription events")

| Event type              | Triggered when                    |
| ----------------------- | --------------------------------- |
| SUBSCRIPTION\_PENDING   | Subscription is created           |
| SUBSCRIPTION\_ACTIVATED | Subscription becomes active       |
| SUBSCRIPTION\_TRIALING  | Trial period starts               |
| SUBSCRIPTION\_PAUSED    | Subscription is paused            |
| SUBSCRIPTION\_PAST\_DUE | A recurring payment fails         |
| SUBSCRIPTION\_CANCELED  | Subscription is canceled          |
| SUBSCRIPTION\_UPDATED   | Subscription details are modified |

Each webhook request includes a `MONEI-Signature` header. Always [verify the signature](https://docs.monei.com/guides/verify-signature/.md) before processing the event, and return a `200` HTTP status code to acknowledge receipt.

## Payment methods[​](#payment-methods "Direct link to Payment methods")

Subscriptions support the following payment methods:

* **Card** — Visa, Mastercard, and other supported card networks. Default payment method for all subscriptions.

* **Bizum** — Available with the following restrictions:

  <!-- -->

  * Monthly and yearly billing intervals only (daily and weekly not supported in production)
  * Trial periods are not supported
  * Subscription amount cannot be changed after activation

## Send subscription link[​](#send-subscription-link "Direct link to Send subscription link")

You can send an activation link to the customer via email or SMS using the [send subscription link](https://docs.monei.com/apis/rest/subscriptions-send-link/.md) endpoint. This allows the customer to activate the subscription without any custom integration — useful for manual or back-office subscription creation.

See [Send subscription link](https://docs.monei.com/subscriptions/manage-subscriptions/.md#send-subscription-link) for details.

## Next steps[​](#next-steps "Direct link to Next steps")

Choose how to integrate subscriptions based on your needs:

* **[Use prebuilt payment page](https://docs.monei.com/subscriptions/use-prebuilt-payment-page/.md)** — Redirect customers to a MONEI-hosted page to activate their subscription. Simplest integration, no frontend code required.
* **[Build a custom checkout](https://docs.monei.com/subscriptions/build-custom-checkout/.md)** — Collect payment details on your own site using MONEI Components. Full control over the checkout experience.
* **[Manage subscriptions](https://docs.monei.com/subscriptions/manage-subscriptions/.md)** — Pause, resume, cancel, skip payments, update payment method, and more.
* **[Handle failed payments](https://docs.monei.com/subscriptions/handle-failed-payments/.md)** — Understand retry logic, configure dunning behavior, and recover past-due subscriptions.