Skip to main content

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​

StatusDescription
PENDINGSubscription created, awaiting activation. The customer has not yet provided a payment method.
TRIALINGActive trial period. A €0 verification payment was made to validate the payment method. Billing begins when the trial ends.
ACTIVERecurring payments are being charged at each billing interval.
PAUSEDBilling is temporarily suspended. The subscription can be resumed at any time.
PAST_DUEA recurring payment failed. MONEI will retry according to the retry schedule.
CANCELEDThe subscription has been permanently stopped. No further payments will be charged.
EXPIREDThe 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:

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:

intervalintervalCountBilling frequency
day1Every day
week1Every week
week2Every 2 weeks
month1Every month
month3Every 3 months (quarterly)
year1Every 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.

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

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 failed payment retry. Read its status field to know the new 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 eventTriggered whenstatus sent to callbackUrl
subscription.pendingSubscription is createdNot sent
subscription.trialingTrial period startsTRIALING
subscription.activatedSubscription becomes activeACTIVE
subscription.pausedSubscription is pausedPAUSED
subscription.past_dueA recurring payment failsPAST_DUE
subscription.canceledSubscription is canceledCANCELED
subscription.updatedSubscription details are modifiedNot sent

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 return a 200 HTTP status code 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:

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.

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.