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

A subscription moves through several statuses during its lifetime:

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

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.

Bizum subscriptions

Bizum subscriptions support monthly and yearly intervals only. Daily and weekly intervals are not available for Bizum in live mode. See Payment methods.

You can change the interval of an active subscription. It applies from the next billing period, or from now if you prorate the change.

note

minute and hour intervals are available in test mode only — useful for quickly testing your integration without waiting for real billing cycles.

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

Not available with Bizum

Trial periods are not supported on Bizum subscriptions. To offer a trial, the customer must activate the subscription with a card.

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.

Webhook events

There are two ways to follow a subscription. Use either or both.

• Subscription callbacks. Set these two URLs when you create a subscription:
  • callbackUrl receives the Subscription object (not an event envelope) when the subscription's status changes, and again after each payment retry (see the last row of the table below). Read its status field to know the current state.
  • paymentCallbackUrl receives the Payment object of each recurring charge.
• Account webhooks. Select the subscription.* event types in Dashboard → Settings → Webhooks. Each delivery is an event envelope, and its type names what happened.

Subscription events

Account webhook event	Triggered when	status sent to callbackUrl
subscription.pending	Subscription is created	Not sent
subscription.trialing	Trial period starts	TRIALING
subscription.activated	Subscription becomes active	ACTIVE
subscription.paused	Subscription is paused	PAUSED
subscription.past_due	A recurring payment fails	PAST_DUE
subscription.canceled	Subscription is canceled	CANCELED
subscription.updated	Subscription details are modified	Not sent
No event	A failed payment is retried	Sent again with the current status

In the GraphQL API, the same event types are written in uppercase, for example SUBSCRIPTION_ACTIVATED.

Each request includes a MONEI-Signature header. Always verify the signature before processing it, and answer with a 2xx HTTP status code, such as 200 OK, to acknowledge receipt.

Payment methods

Subscriptions support the following payment methods:

• Card — Visa, Mastercard, and other supported . 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
  • Changes cannot be prorated

Activating subscriptions

Choose how customers activate subscriptions:

• Hosted Payment Page — Redirect customers to the MONEI Hosted Payment Page to activate their subscription. Simplest integration, no frontend code required.
• Build a custom checkout — Collect payment details on your own site using MONEI Components. Full control over the checkout experience.
• Send subscription link — Send an activation link by email or SMS for manual or back-office subscription creation.

Manage subscriptions

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

• Manage subscriptions — Pause, resume, cancel, skip payments, update payment method, prorate plan changes, and more.
• Handle failed payments — Understand retry logic, configure behavior, and recover past-due subscriptions.

Common questions

What is the Subscriptions API?

The Subscriptions API lets you charge a customer a fixed amount at a regular interval. You set the amount, currency, interval, trial period, and customer details when you create the subscription, and MONEI charges each billing period. Typical uses are subscription boxes, memberships, online courses, and for rentals.

What happens when a subscription payment fails?

The subscription becomes PAST_DUE and MONEI retries the charge on a schedule: by default 1, 6, and 15 days after the failure for a monthly subscription. If every retry fails, the subscription is canceled. See Handle failed payments.

Can I set my own retry schedule?

Yes, with the retrySchedule parameter. The retries must all take place within one billing interval. See Custom retry schedule.

Does a past-due subscription recover on its own?

Yes. If one of the retries succeeds, the subscription returns to ACTIVE and billing continues. You can also skip the failed cycle yourself — see Recover a past-due subscription.

How does a customer update their card after a failed payment?

Activate the subscription again with the new payment method. MONEI validates it with a €0 verification payment, and every future charge uses it. See Update payment method.

Is the customer told when a payment fails?

Only if you turn it on. With Email customer on subscription status changes, MONEI emails the customer when the subscription becomes past due and after each failed retry. See Email notifications.

Is a cancellation immediate?

You choose. Cancel immediately, or at the end of the current billing period so the customer keeps access until then. See Cancel a subscription.

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, then buy the WooCommerce Subscriptions extension.