# 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.                                                                            |

In [MONEI Dashboard → Subscriptions](https://dashboard.monei.com/subscriptions), each status is a tab above the table, so you can list every active, trialing, paused, canceled, or past-due subscription:

![Subscriptions list in the MONEI Dashboard, with the status tabs, the amount charged each interval and the next payment date](/img/dashboard/en/subscriptions-list.png)

Subscriptions list in the MONEI Dashboard, with the status tabs, the amount charged each interval and the next payment date

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

Configure how often the customer is charged using `interval` and `intervalCount`. The table below shows common examples — it is not a complete list of every valid billing interval:

| 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\_EXPIRED   | Subscription expired (not activated in time) |
| 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

## Activating subscriptions[​](#activating-subscriptions "Direct link to Activating subscriptions")

Choose how customers activate subscriptions:

* **[Hosted Payment Page](https://docs.monei.com/subscriptions/use-prebuilt-payment-page/.md)** — Redirect customers to the MONEI Hosted Payment 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.
* **[Send subscription link](https://docs.monei.com/subscriptions/send-subscription-link/.md)** — Send an activation link by email or SMS for manual or back-office subscription creation.

## Manage subscriptions[​](#manage-subscriptions "Direct link to Manage subscriptions")

After subscriptions are active, use these guides to manage them:

* **[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.

## Common questions[​](#common-questions "Direct link to Common questions")

### What is the Subscriptions API?[​](#subscriptions-api "Direct link to What is the Subscriptions API?")

The [Subscriptions API](https://docs.monei.com/apis/rest/subscriptions-create/.md) is built to help you process subscription payments. For example, use [MONEI Subscriptions](https://monei.com/features/subscriptions/) to set up automatic charges to your customer's account for a fixed amount on a weekly, monthly, or annual basis.

You can create subscriptions based on a range of parameters including ID, subscription name/description, starting date, amount, currency, payment method, interval, length (period-end), and customer information including shipping and billing details.

Simplify your billing, improve the customer experience, and earn recurring revenue with MONEI Subscriptions. All you have to do is integrate the Subscriptions API with your e-commerce website using the [Hosted Payment Page](https://docs.monei.com/integrations/use-prebuilt-payment-page/.md). If your website is built on WooCommerce you can use our WooCommerce subscriptions plugin (see below).

Possible use cases include subscription boxes, subscription services (streaming, online courses, gym memberships), and recurring payments for rentals or leases.

### Automatic retries for subscription payments[​](#automatic-retries "Direct link to Automatic retries for subscription payments")

If your customer's payment method fails during a subscription payment because the card expired (or for another reason), two things happen to recover the transaction:

1. We send an automated email to the customer asking them to update their subscription payment information. This email gets sent up to three times by default — at 1, 6, and 15 days after the failed payment for a monthly subscription (frequency depends on the subscription plan). This email comes from your business and includes [your logo](https://dashboard.monei.com/settings/branding) and contact information.
2. If the subscription payment is not recovered, it gets canceled and you will receive a notification.

You can also set up custom retries (see below).

### Custom retries for subscription payments[​](#custom-retries "Direct link to Custom retries for subscription payments")

Yes, you can determine when automatic retries for subscription payments get sent. You can schedule daily, weekly, monthly, or yearly retries, but the sum of all intervals in the retry schedule cannot exceed the subscription interval.

**Examples**

1. If your subscription renews weekly, and you want to send up to two retries, they both need to be sent within seven days, before the new subscription interval begins.
2. If your subscription renews monthly, and you want to send up to five retries, all five retries must occur before the next monthly subscription interval begins.

### Subscriptions on WooCommerce[​](#woocommerce "Direct link to Subscriptions on WooCommerce")

MONEI's WooCommerce plugin has subscription support. To configure subscriptions in your WooCommerce account, you need to first [install and configure the MONEI WooCommerce plugin](https://docs.monei.com/e-commerce/woocommerce/.md), then [buy the WooCommerce Subscriptions extension](https://woocommerce.com/es/products/woocommerce-subscriptions/).