Create subscription

Subscriptions API v2
POSThttps://api.mollie.com/v2/customers/*customerId*/subscriptions
Authentication:API keysOrganization access tokensApp access tokens

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.

amountamount objectrequired

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

Show child parameters

currencystringrequired
An ISO 4217 currency code. The currencies supported depend on the payment methods that are enabled on your account.
valuestringrequired
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.
timesintegeroptional

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.

intervalstringrequired

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).

startDatedateoptional
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.
descriptionstringrequired
A description unique per subscription. This will be included in the payment description.
methodstringoptional

The payment method used for this subscription, either forced on creation or null if any of the customer’s valid mandates may be used. This parameter can not set together with mandateId.

Possible values: creditcard directdebit paypal null

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

mandateIdstringoptional
The mandate used for this subscription. This parameter can not set together with method.
webhookUrlstringoptional
Use this parameter to set a webhook URL for all subscription payments.
metadatamixedoptional
Provide any data you like, and we will save the data alongside the subscription. Whenever you fetch the subscription with our API, we will 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, you have to specify which profile you are creating a subscription for using the profileId parameter. Organizations can have multiple profiles for each of their websites. See Profiles API for more information.

For these authentication methods the optional testmode parameter is available as well to enable test mode.

profileIdstringrequired for access tokens
testmodebooleanoptional
applicationFeeobjectoptional

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
15
16
from mollie.api.client import Client

mollie_client = Client()
mollie_client.set_api_key("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM")

customer = mollie_client.customers.get("cst_stTC2WHAuS")
subscription = customer.subscriptions.create({
    "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
const { createMollieClient } = require('@mollie/api-client');
const mollieClient = createMollieClient({ apiKey: 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

const subscription = await mollieClient.customerSubscriptions.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/'
});

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"
        }
    }
}