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 you cancel the 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

Note

The maximum interval is 1 year (12 months, 52 weeks or 365 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.

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 paypal null

Warning

Using PayPal Recurring is only possible if PayPal has activated this feature on your merchant-account.

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 on which profile the payments for the subscription should be created. 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.

testmode

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

applicationFee

object
optional

Adding an application fee allows you to charge the merchant for each payment in the subscription and transfer these amounts to your own account.

amount

amount object
required

The amount in that the app wants to charge, e.g. {"currency":"EUR", "value":"10.00"} if the app would want to charge €10.00.

currency

string
required
An ISO 4217 currency code.

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.

description

string
required

The description of the application fee. This will appear on settlement reports to the merchant and to you.

The maximum length is 255 characters.

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
 5
 6
 7
 8
 9
10
11
12
13
14
require 'mollie-api-ruby'

Mollie::Client.configure do |config|
  config.api_key = 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM'
end

subscription = Mollie::Customer::Subscription.create(
  customer_id: 'cst_stTC2WHAuS',
  amount:      { value: '25.00', currency: 'EUR' },
  times:       4,
  interval:    '3 months',
  description: 'Quarterly payment',
  webhook_url: 'https://webshop.example.org/subscriptions/webhook/'
)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const { createMollieClient } = require('@mollie/api-client');
const mollieClient = createMollieClient({ apiKey: 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

(async () => {
  const subscription = await mollieClient.customers_subscriptions.create({
    customerId: 'cst_stTC2WHAuS',
    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

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
37
38
39
40
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": "2018-06-01",
    "nextPaymentDate": "2018-09-01",
    "method": null,
    "webhookUrl": "https://webshop.example.org/subscriptions/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"
        },
        "profile": {
            "href": "https://api.mollie.com/v2/profiles/pfl_URR55HPMGx",
            "type": "application/hal+json"
        },
        "documentation": {
            "href": "https://docs.mollie.com/reference/v2/subscriptions-api/create-subscription",
            "type": "text/html"
        }
    }
}