Create subscription

Subscriptions API v2
POSThttps://api.mollie.com/v2/customers/*customerId*/subscriptions

With subscriptions, you can schedule recurring payments to take place at regular intervals.

For example, by simply specifying an amount and an interval, you can create an endless subscription to charge a monthly fee, until the consumer cancels their subscription.

Or, you could use the times parameter to only charge a limited number of times, for example to split a big transaction in multiple parts.

A few example usages:

  • amount[currency]="EUR" amount[value]="5.00" interval="2 weeks" Your consumer will be charged €5 once every two weeks.
  • amount[currency]="EUR" amount[value]="20.00" interval="1 day" times=5 Your consumer will be charged €20 every day, for five consecutive days.
  • amount[currency]="EUR" amount[value]="10.00" interval="1 month" startDate="2018-04-30" Your consumer will be charged €10 on the last day of each month, starting in April 2018.

Parameters

Replace customerId in the endpoint URL by the customer’s ID, for example /v2/customers/cst_8wmqcHMN4U/subscriptions.

amount

object
required

The amount that you want to charge, e.g. {"currency":"EUR", "value":"100.00"} if you would want to charge €100.00.

currency

string
required
An ISO 4217 currency code. The currencies supported depend on the payment methods that are enabled on your account.

value

string
required
A string containing the exact amount you want to charge in the given currency. Make sure to send the right amount of decimals. Non-string values are not accepted.

times

integer
optional
Total number of charges for the subscription to complete. Leave empty for an ongoing subscription.

interval

string
required

Interval to wait between charges, for example 1 month or 14 days.

Possible values: ... months ... weeks ... days

startDate

date
optional
The start date of the subscription in YYYY-MM-DD format. This is the first day on which your customer will be charged. When this parameter is not provided, the current date will be used instead.

description

string
required
A description unique per subscription . This will be included in the payment description along with the charge date.

method

string
optional

The payment method used for this subscription, either forced on creation or null if any of the customer’s valid mandates may be used.

Possible values: creditcard directdebit null

webhookUrl

string
optional
Use this parameter to set a webhook URL for all subscription payments.

Mollie Connect/OAuth parameters

If you’re creating an app with Mollie Connect/OAuth, the only mandatory extra parameter is the profileId parameter. With it, you can specify to which profile the subscription belongs. Organizations can have multiple profiles for each of their websites. See Profiles API for more information.

profileId

string
required
The payment profile’s unique identifier, for example pfl_3RkSN1zuPE. This field is mandatory.

testmode

boolean
optional
Set this to true to create a test mode subscription.

Response

201 application/hal+json; charset=utf-8

A subscription object is returned, as described in Get subscription.

Example

Request

1
2
3
4
5
6
7
8
curl -X POST https://api.mollie.com/v2/customers/cst_stTC2WHAuS/subscriptions \
    -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
    -d "amount[currency]=EUR" \
    -d "amount[value]=25.00" \
    -d "times=4" \
    -d "interval=3 months" \
    -d "description=Quarterly payment" \
    -d "webhookUrl=https://webshop.example.org/subscriptions/webhook/"

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
HTTP/1.1 201 Created
Content-Type: application/hal+json

{
    "resource": "subscription",
    "id": "sub_rVKGtNd6s3",
    "mode": "live",
    "createdAt": "2018-06-01T12:23:34+00:00",
    "status": "active",
    "amount": {
        "value": "25.00",
        "currency": "EUR"
    },
    "times": 4,
    "interval": "3 months",
    "description": "Quarterly payment",
    "method": null,
    "webhookUrl": "https://webshop.example.org/payments/webhook/",
    "_links": {
        "self": {
            "href": "https://api.mollie.com/v2/customers/cst_stTC2WHAuS/subscriptions/sub_rVKGtNd6s3",
            "type": "application/hal+json"
        },
        "customer": {
            "href": "https://api.mollie.com/v2/customers/cst_stTC2WHAuS",
            "type": "application/hal+json"
        },
        "documentation": {
            "href": "https://docs.mollie.com/reference/v2/subscriptions-api/create-subscription",
            "type": "text/html"
        }
    }
}