Sign in

v1

latestOpenAPI 3.0.02026-08-0631139237.5 KB
Subscriptions

Create Subscription

Creates a new subscription with the specified parameters.

Subscription Lifecycle:

  1. When first created, the subscription has a PENDING status
  2. To initiate billing, you must call the activate endpoint with payment details
  3. Once activated, the subscription will automatically bill according to the configured interval

Key Configuration Parameters:

  • Billing settings: Amount, currency, interval (daily, weekly, monthly, yearly)
  • Schedule customization: Interval count, trial period duration
  • Trial pricing: Offer a free trial with trialPeriodDays/trialPeriodEnd (no charge until the trial ends), or discounted introductory pricing with trialAmount + trialIntervalCount (the trialAmount is charged each billing cycle for that many cycles, then the regular amount applies). trialAmount can also be combined with trialPeriodDays/trialPeriodEnd to charge it once at activation for the whole trial period. trialIntervalCount requires trialAmount and cannot be combined with trialPeriodDays/trialPeriodEnd

Example — 5 EUR for the first 3 months, then 10 EUR/month:

{
  "amount": 1000,
  "currency": "EUR",
  "interval": "month",
  "intervalCount": 1,
  "trialAmount": 500,
  "trialIntervalCount": 3
}

The customer pays 5.00 EUR at activation and for the next two monthly cycles (3 discounted cycles in total), then 10.00 EUR every month.

  • Allowed payment methods: An array of strings specifying which payment methods are allowed for this subscription (e.g., card, bizum)
  • Customer information: Contact details, billing and shipping addresses
  • Communication: Callback URLs for webhook notifications about subscription events

Best Practices:

  • Set clear, descriptive names for subscriptions to help with identification
  • Configure appropriate webhook notifications to monitor subscription status changes
  • Consider offering trial periods to increase customer conversion rates
  • Use metadata to store additional information relevant to your business logic
post/subscriptions

Request body

amountinteger required

Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD).

currencystring required

Three-letter ISO currency code, in uppercase. Must be a supported currency.

interval'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' required

Subscription interval. The minute and hour intervals are only available in test mode.

intervalCountinteger

Number of intervals between subscription payments.

allowedPaymentMethodsstring[]

List of payment methods allowed for subscriptions.

descriptionstring

An arbitrary string attached to the subscription. Often useful for displaying to users.

trialPeriodEndnumber

The end date of the trial period. Measured in seconds since the Unix epoch.

trialPeriodDaysinteger

Number of days the trial period lasts.

trialAmountinteger

Amount charged on each billing cycle during the trial period, as a positive integer in the smallest currency unit (e.g., 100 cents to charge 1.00 USD). Once the trial ends, the subscription's regular amount is charged. Use this to offer discounted introductory pricing. Can be combined with trialIntervalCount (charged each cycle for that many cycles) or with trialPeriodDays/trialPeriodEnd (charged once at activation, covering the subscription until the trial period ends).

trialIntervalCountinteger

Number of billing cycles charged at trialAmount before the regular amount applies, using the subscription's interval (e.g., interval of month with a trialIntervalCount of 3 charges the trialAmount for the first 3 months). Requires trialAmount and cannot be combined with trialPeriodDays or trialPeriodEnd. In responses, the value decrements after each trial payment and is removed once the trial ends.

callbackUrlstring

The URL will be called each time subscription status changes. You will receive a subscription object in the body of the request.

paymentCallbackUrlstring

The URL will be called each time subscription creates a new payments. You will receive the payment object in the body of the request.

metadataMetadata

A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format.

Example request

{
  "amount": 110,
  "currency": "EUR",
  "interval": "month",
  "intervalCount": 1,
  "allowedPaymentMethods": [
    "card",
    "bizum"
  ],
  "description": "MoonMail Monthly Lite",
  "customer": {
    "email": "john.doe@example.com",
    "name": "John Doe"
  },
  "billingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "shippingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "trialPeriodEnd": 1636366897,
  "trialPeriodDays": 7,
  "trialAmount": 100,
  "trialIntervalCount": 3,
  "retrySchedule": [
    {
      "interval": "day",
      "intervalCount": 1
    },
    {
      "interval": "day",
      "intervalCount": 3
    },
    {
      "interval": "week",
      "intervalCount": 1
    }
  ],
  "callbackUrl": "https://example.com/subscriptions/callback",
  "paymentCallbackUrl": "https://example.com/payments/callback",
  "metadata": {
    "systemId": "12345"
  }
}

Response

A subscription object

idstring required

Unique identifier for the subscription.

amountinteger required

Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD).

currencystring

Three-letter ISO currency code, in uppercase. Must be a supported currency.

allowedPaymentMethodsstring[]

List of payment methods allowed for subscriptions.

descriptionstring

An arbitrary string attached to the subscription. Often useful for displaying to users.

accountIdstring required

MONEI Account identifier.

livemodeboolean required

Has the value true if the resource exists in live mode or the value false if the resource exists in test mode.

status'PENDING' | 'EXPIRED' | 'TRIALING' | 'ACTIVE' | 'PAST_DUE' | 'PAUSED' | 'CANCELED' required

The status of the subscription.

interval'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' required

Subscription interval. The minute and hour intervals are only available in test mode.

intervalCountinteger required

Number of intervals between subscription payments.

pauseIntervalCountinteger

Number of intervals when subscription will be paused before it activates again.

skipIntervalCountinteger

The number of intervals during which the subscription billing cycle will be skipped without altering the subscription status. This is useful when payment for a specific period is received through different methods.

lastOrderIdstring

An order ID from your system. A unique identifier that can be used to reconcile the payment with your internal system.

currentPeriodStartnumber

The start date of the current subscription period. Measured in seconds since the Unix epoch.

currentPeriodEndnumber

The end date of the current subscription period. Measured in seconds since the Unix epoch.

trialPeriodEndnumber

The end date of the trial period. Measured in seconds since the Unix epoch.

trialAmountinteger

Amount charged on each billing cycle during the trial period, as a positive integer in the smallest currency unit (e.g., 100 cents to charge 1.00 USD). Once the trial ends, the subscription's regular amount is charged. Use this to offer discounted introductory pricing. Can be combined with trialIntervalCount (charged each cycle for that many cycles) or with trialPeriodDays/trialPeriodEnd (charged once at activation, covering the subscription until the trial period ends).

trialIntervalCountinteger

Number of billing cycles charged at trialAmount before the regular amount applies, using the subscription's interval (e.g., interval of month with a trialIntervalCount of 3 charges the trialAmount for the first 3 months). Requires trialAmount and cannot be combined with trialPeriodDays or trialPeriodEnd. In responses, the value decrements after each trial payment and is removed once the trial ends.

nextPaymentAtinteger

The date when the next payment will be made.

retryCountinteger

Number of retries left for the subscription.

cancelAtPeriodEndboolean

If true, the subscription will be canceled at the end of the current period.

pauseAtPeriodEndboolean

If true, the subscription will be paused at the end of the current period.

sequenceIdstring

A permanent identifier that refers to the initial payment of a sequence of payments. This value needs to be sent in the path for RECURRING payments.

callbackUrlstring

The URL will be called each time subscription status changes. You will receive a subscription object in the body of the request.

paymentCallbackUrlstring

The URL will be called each time subscription creates a new payments. You will receive the payment object in the body of the request.

metadataMetadata

A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format.

createdAtinteger

Time at which the resource was created. Measured in seconds since the Unix epoch.

updatedAtinteger

Time at which the resource updated last time. Measured in seconds since the Unix epoch.

Example response

{
  "id": "575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa",
  "amount": 110,
  "currency": "EUR",
  "allowedPaymentMethods": [
    "card",
    "bizum"
  ],
  "description": "MoonMail Monthly Lite",
  "accountId": "aa9333ba-82de-400c-9ae7-087b9f8d2242",
  "status": "PENDING",
  "customer": {
    "email": "john.doe@example.com",
    "name": "John Doe"
  },
  "billingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "shippingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "interval": "month",
  "intervalCount": 1,
  "pauseIntervalCount": 1,
  "skipIntervalCount": 1,
  "lastOrderId": "14379133960355",
  "lastPayment": {
    "id": "af6029f80f5fc73a8ad2753eea0b1be0",
    "status": "PENDING",
    "statusCode": "E000",
    "statusMessage": "Transaction approved"
  },
  "paymentMethod": {
    "method": "card",
    "card": {
      "country": "ES",
      "brand": "visa",
      "type": "credit",
      "threeDSecureVersion": "2.1.0",
      "threeDSecureFlow": "CHALLENGE",
      "expiration": 2048544000,
      "last4": "0004",
      "fingerprint": "7f2afde1566286c5fb126bb7e79bef549755cce6033dc429013c46d1365ff0e9",
      "tokenizationMethod": "applePay",
      "cardholderName": "John Doe",
      "cardholderEmail": "email@example.com"
    }
  },
  "currentPeriodStart": 1636366897,
  "currentPeriodEnd": 1636366897,
  "trialPeriodEnd": 1636366897,
  "trialAmount": 100,
  "trialIntervalCount": 3,
  "nextPaymentAt": 1636366897,
  "retryCount": 1,
  "retrySchedule": [
    {
      "interval": "day",
      "intervalCount": 1
    },
    {
      "interval": "day",
      "intervalCount": 3
    },
    {
      "interval": "week",
      "intervalCount": 1
    }
  ],
  "traceDetails": {
    "ip": "100.100.200.100",
    "countryCode": "ES",
    "lang": "es",
    "deviceType": "desktop",
    "browser": "Chrome",
    "browserVersion": "83.0.4103.116",
    "os": "Mac OS",
    "osVersion": "10.15.4",
    "source": "MONEI/PHP",
    "sourceVersion": "0.1.2",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
    "browserAccept": "text/html,application/xhtml+xml,application/json",
    "browserColorDepth": "24",
    "browserScreenHeight": "1152",
    "browserScreenWidth": "2048",
    "browserTimezoneOffset": "-120",
    "userEmail": "user@example.com"
  },
  "sequenceId": "62b23b9f3627cc38b08ff471ccd313ad",
  "callbackUrl": "https://example.com/subscriptions/callback",
  "paymentCallbackUrl": "https://example.com/payments/callback",
  "metadata": {
    "systemId": "12345"
  },
  "createdAt": 1636366897,
  "updatedAt": 1636366897
}