Get subscription

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

Retrieve a subscription by its ID and its customer’s ID.

Parameters

Replace customerId in the endpoint URL by the customer’s ID, and replace id by the subscription’s ID. For example /v2/customers/cst_8wmqcHMN4U/subscriptions/sub_rVKGtNd6s3.

Access token parameters

If you are using organization access tokens or are creating an OAuth app, the testmode query string parameter is also available.

testmode

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

Response

200 application/hal+json

resource

string
Indicates the response contains a subscription object. Will always contain subscription for this endpoint.

id

string
The identifier uniquely referring to this subscription. Mollie assigns this identifier at subscription creation time. For example sub_rVKGtNd6s3.

mode

string

The mode used to create this subscription. Mode determines whether the subscription’s payments are real or test payments.

Possible values: live test

createdAt

datetime
The subscription’s date and time of creation, in ISO 8601 format.

status

string

The subscription’s current status, depends on whether the customer has a pending, valid or invalid mandate.

Possible values: pending active canceled suspended completed

amount

amount object

The constant amount that is charged with each subscription payment, e.g. {"currency":"EUR", "value":"10.00"} for a €10.00 subscription.

currency

string
The ISO 4217 currency code.

value

string
A string containing the exact amount of the payment in the given currency.

times

integer
Total number of charges for the subscription to complete.

timesRemaining

integer
Number of charges left for the subscription to complete.

interval

string

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

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

startDate

date
The start date of the subscription in YYYY-MM-DD format.

nextPaymentDate

date
optional
The date of the next scheduled payment in YYYY-MM-DD format. When there will be no next payment, for example when the subscription has ended, this parameter will not be returned.

description

string
The description specified during subscription creation. This will be included in the payment description along with the charge date in YYYY-MM-DD format.

method

string

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

mandateId

string
optional
The mandate used for this subscription. When there is no mandate specified, this parameter will not be returned.

canceledAt

datetime
The subscription’s date and time of cancellation, in ISO 8601 format. This parameter is omitted if the payment is not canceled (yet).

webhookUrl

string
The URL Mollie will call as soon a payment status change takes place.

metadata

mixed
The optional metadata you provided upon subscription creation. Metadata can for example be used to link a plan to a subscription.

_links

object

An object with several URL objects relevant to the subscription. Every URL object will contain an href and a type field.

self

URL object
The API resource URL of the subscription itself.

customer

URL object
The API resource URL of the customer the subscription is for.

documentation

URL object
The URL to the subscription retrieval endpoint documentation.

Example

cURLPHPPythonRubyNode.js
1
2
curl -X GET https://api.mollie.com/v2/customers/cst_stTC2WHAuS/subscriptions/sub_rVKGtNd6s3 \
   -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM"
1
2
3
4
5
6
<?php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");

$customer = $mollie->customers->get("cst_stTC2WHAuS");
$subscription = $customer->getSubscription("sub_rVKGtNd6s3");
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
37
38
39
40
HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "resource": "subscription",
    "id": "sub_rVKGtNd6s3",
    "mode": "live",
    "createdAt": "2016-06-01T12:23:34+00:00",
    "status": "active",
    "amount": {
        "value": "25.00",
        "currency": "EUR"
    },
    "times": 4,
    "timesRemaining": 4,
    "interval": "3 months",
    "startDate": "2016-06-01",
    "nextPaymentDate": "2016-09-01",
    "description": "Quarterly payment",
    "method": null,
    "mandateId": "mdt_38HS4fsS",
    "webhookUrl": "https://webshop.example.org/payments/webhook",
    "metadata": {
        "plan": "small"
    },
    "_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/get-subscription",
            "type": "text/html"
        }
    }
}