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

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.

Note

Subscriptions in test mode will be canceled automatically after 10 charges.

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. Please note that this parameter can not set together with mandateId.

Possible values: creditcard directdebit null

mandateId

string
optional
The mandate used for this subscription. Please note that this parameter can not set together with method.

webhookUrl

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

metadata

mixed
optional
Provide any data you like, and we will save the data alongside the subscription. Whenever you fetch the subscription with our API, we’ll also include the metadata. You can use up to 1kB of JSON.

Access token parameters

If you are using organization access tokens or are creating an OAuth app, 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 website 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

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

Example

cURLPHPPythonRubyNode.js
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/"
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<?php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");

$customer = $mollie->customers->get("cst_stTC2WHAuS");
$customer->createSubscription([
   "amount" => [
         "currency" => "EUR",
         "value" => "25.00",
   ],
   "times" => 4,
   "interval" => "3 months",
   "description" => "Quarterly payment",
   "webhookUrl" => "https://webshop.example.org/subscriptions/webhook/",
]);
1
2
3
4
We don't have a Python code example for this API call yet.

If you have some time to spare, feel free to open a pull request at:
https://github.com/mollie/api-documentation
1
2
3
4
We don't have a Ruby code example for this API call yet.

If you have some time to spare, feel free to open a pull request at:
https://github.com/mollie/api-documentation
1
2
3
4
We don't have a Node.js code example for this API call yet.

If you have some time to spare, feel free to open a pull request at:
https://github.com/mollie/api-documentation

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
34
35
36
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,
    "timesRemaining": 4,
    "interval": "3 months",
    "description": "Quarterly payment",
    "startDate": "2016-06-01",
    "nextPaymentDate": "2016-09-01",
    "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"
        }
    }
}