Create subscription
Subscriptions API

POST
https://api.mollie.nl/v1/customers/customerId/subscriptions
Authentication: API keys OAuth 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 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=5 interval="2 weeks"
    Your consumer will be charged €5 once every two weeks.
  • amount=20 interval="1 day" times=5
    Your consumer will be charged €20 every day, for five consecutive days.
  • amount=10 interval="1 month" startDate="2017-11-30"
    Your consumer will be charged €10 on the last day of each month, starting next month.

Parameters

amount
decimal

The constant amount in EURO that you want to charge with each subscription payment, e.g. 100.00 if you would want to charge €100.00.

times
int | null

Optional – Total number of charges for the subscription to complete. Leave empty for an ongoing subscription.

interval
string

Interval to wait between charges like 1 month(s) or 14 days.

Possible values: … months … weeks … days

startDate
string

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

A description unique per customer. This will be included in the payment description along with the charge date in yyyy-mm-dd format.

method
string | null

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

Optional – Use this parameter to set a webhook URL for all subscription payments.

Includes

Some endpoints allow you to indicate if you want more information to be included in the API response via the include querystring parameter.

  • No includes supported for this endpoint.

Response

201
application/json; charset=utf-8

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

Example

Request code

$mollie = new Mollie_API_Client;
$mollie->setApiKey('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');

$subscription = $mollie->customers_subscriptions->withParentId("cst_stTC2WHAuS")->create([
    "amount"      => 25.00,
    "times"       => 4,
    "interval"    => "3 months",
    "description" => "Quarterly payment",
    "webhookUrl"  => "https://webshop.example.org/payments/webhook/",
]);

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "resource": "subscription",
    "id": "sub_rVKGtNd6s3",
    "customerId": "cst_stTC2WHAuS",
    "mode": "live",
    "createdDatetime": "2016-06-01T12:23:34.0Z",
    "status": "active",
    "amount": "25.00",
    "times": 4,
    "interval": "3 months",
    "description": "Quarterly payment",
    "method": null,
    "cancelledDatetime": null,
    "links": {
        "webhookUrl": "https://webshop.example.org/payments/webhook/"
    }
}