Subscriptions

Overview

Available Operations

create - Create subscription
list - List customer subscriptions
get - Get subscription
update - Update subscription
cancel - Cancel subscription
all - List all subscriptions
list_payments - List subscription payments

create

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 customer will be charged €5 once every two weeks.

amount[currency]="EUR" amount[value]="20.00" interval="1 day" times=5 Your customer 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 customer will be charged €10 on the last day of each month, starting in April 2018.

Example Usage

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.create(customer_id="cst_5B8cwPMGnU", idempotency_key="123e4567-e89b-12d3-a456-426", subscription_request=mollie.SubscriptionRequest(
        amount=mollie.Amount(
            currency="EUR",
            value="10.00",
        ),
        times=6,
        interval="2 days",
        start_date="2025-01-01",
        description="Subscription of streaming channel",
        method=mollie.SubscriptionMethod.PAYPAL,
        application_fee=mollie.SubscriptionRequestApplicationFee(
            amount=mollie.Amount(
                currency="EUR",
                value="10.00",
            ),
            description="Platform fee",
        ),
        webhook_url="https://example.com/webhook",
        mandate_id="mdt_5B8cwPMGnU",
        profile_id="pfl_5B8cwPMGnU",
        testmode=False,
    ))

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`customer_id`	str	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`idempotency_key`	Optional[str]	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`subscription_request`	Optional[models.SubscriptionRequest]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscriptionResponse

Errors

Error Type	Status Code	Content Type
models.ErrorResponse	404, 429	application/hal+json
models.APIError	4XX, 5XX	/

list

Retrieve all subscriptions of a customer.

The results are paginated.

Example Usage

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    testmode=True,
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.list(customer_id="cst_5B8cwPMGnU", from_="sub_5B8cwPMGnU", limit=50, sort=mollie.Sorting.DESC, idempotency_key="123e4567-e89b-12d3-a456-426")

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description	Example
`customer_id`	str	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`from_`	Optional[str]	➖	Provide an ID to start the result set from the item with the given ID and onwards. This allows you to paginate the result set.	sub_5B8cwPMGnU
`limit`	OptionalNullable[int]	➖	The maximum number of items to return. Defaults to 50 items.	50
`sort`	Optional[models.Sorting]	➖	Used for setting the direction of the result set. Defaults to descending order, meaning the results are ordered from newest to oldest.	desc
`testmode`	Optional[bool]	➖	Most API credentials are specifically created for either live mode or test mode. In those cases the `testmode` query parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting the `testmode` query parameter to `true`. Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
`idempotency_key`	Optional[str]	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.ListSubscriptionsResponse

Errors

Error Type	Status Code	Content Type
models.ErrorResponse	400, 404, 429	application/hal+json
models.APIError	4XX, 5XX	/

get

Retrieve a single subscription by its ID and the ID of its parent customer.

Example Usage

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    testmode=True,
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.get(customer_id="cst_5B8cwPMGnU", subscription_id="sub_5B8cwPMGnU", idempotency_key="123e4567-e89b-12d3-a456-426")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`customer_id`	str	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`subscription_id`	str	✔️	Provide the ID of the related subscription.	sub_5B8cwPMGnU
`testmode`	Optional[bool]	➖	Most API credentials are specifically created for either live mode or test mode. In those cases the `testmode` query parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting the `testmode` query parameter to `true`. Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
`idempotency_key`	Optional[str]	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscriptionResponse

Errors

Error Type	Status Code	Content Type
models.ErrorResponse	404, 429	application/hal+json
models.APIError	4XX, 5XX	/

update

Update an existing subscription.

Canceled subscriptions cannot be updated.

For an in-depth explanation of each parameter, refer to the Create subscription endpoint.

Example Usage: update-subscription-200-1

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.update(customer_id="cst_5B8cwPMGnU", subscription_id="sub_5B8cwPMGnU", idempotency_key="123e4567-e89b-12d3-a456-426", request_body={
        "amount": {
            "currency": "EUR",
            "value": "10.00",
        },
        "description": "Subscription of streaming channel",
        "interval": "1 months",
        "start_date": "2025-01-01",
        "times": 6,
        "webhook_url": "https://example.com/webhook",
        "mandate_id": "mdt_5B8cwPMGnU",
        "testmode": False,
    })

    # Handle response
    print(res)

Example Usage: update-subscription-200-2

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.update(customer_id="cst_5B8cwPMGnU", subscription_id="sub_5B8cwPMGnU", idempotency_key="123e4567-e89b-12d3-a456-426", request_body={
        "amount": {
            "currency": "EUR",
            "value": "10.00",
        },
        "description": "Subscription of streaming channel",
        "interval": "1 months",
        "start_date": "2025-01-01",
        "times": 6,
        "webhook_url": "https://example.com/webhook",
        "mandate_id": "mdt_5B8cwPMGnU",
        "testmode": False,
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`customer_id`	str	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`subscription_id`	str	✔️	Provide the ID of the related subscription.	sub_5B8cwPMGnU
`idempotency_key`	Optional[str]	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`request_body`	Optional[models.UpdateSubscriptionRequestBody]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscriptionResponse

Errors

Error Type	Status Code	Content Type
models.ErrorResponse	404, 429	application/hal+json
models.APIError	4XX, 5XX	/

cancel

Cancel an existing subscription. Canceling a subscription has no effect on the mandates of the customer.

Example Usage

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.cancel(customer_id="cst_5B8cwPMGnU", subscription_id="sub_5B8cwPMGnU", idempotency_key="123e4567-e89b-12d3-a456-426", request_body={
        "testmode": False,
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`customer_id`	str	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`subscription_id`	str	✔️	Provide the ID of the related subscription.	sub_5B8cwPMGnU
`idempotency_key`	Optional[str]	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`request_body`	Optional[models.CancelSubscriptionRequestBody]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscriptionResponse

Errors

Error Type	Status Code	Content Type
models.ErrorResponse	404, 429	application/hal+json
models.APIError	4XX, 5XX	/

all

Retrieve all subscriptions initiated across all your customers.

The results are paginated.

Example Usage

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    profile_id="<id>",
    testmode=True,
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.all(limit=50, idempotency_key="123e4567-e89b-12d3-a456-426")

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description	Example
`from_`	OptionalNullable[str]	➖	Provide an ID to start the result set from the item with the given ID and onwards. This allows you to paginate the result set.
`limit`	OptionalNullable[int]	➖	The maximum number of items to return. Defaults to 50 items.	50
`profile_id`	OptionalNullable[str]	➖	The identifier referring to the profile you wish to retrieve subscriptions for. Most API credentials are linked to a single profile. In these cases the `profileId` is already implied. To retrieve all subscriptions across the organization, use an organization-level API credential and omit the `profileId` parameter.
`testmode`	Optional[bool]	➖	Most API credentials are specifically created for either live mode or test mode. In those cases the `testmode` query parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting the `testmode` query parameter to `true`. Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
`idempotency_key`	Optional[str]	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.ListAllSubscriptionsResponse

Errors

Error Type	Status Code	Content Type
models.ErrorResponse	400, 404, 429	application/hal+json
models.APIError	4XX, 5XX	/

list_payments

Retrieve all payments of a specific subscription.

The results are paginated.

Example Usage: list-payments-200-1

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    profile_id="<id>",
    testmode=False,
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.list_payments(customer_id="cst_5B8cwPMGnU", subscription_id="sub_5B8cwPMGnU", from_="tr_5B8cwPMGnU", limit=50, sort=mollie.Sorting.DESC, idempotency_key="123e4567-e89b-12d3-a456-426")

    while res is not None:
        # Handle items

        res = res.next()

Example Usage: list-payments-200-2

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    profile_id="<id>",
    testmode=True,
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.list_payments(customer_id="cst_5B8cwPMGnU", subscription_id="sub_5B8cwPMGnU", from_="tr_5B8cwPMGnU", limit=50, sort=mollie.Sorting.DESC, idempotency_key="123e4567-e89b-12d3-a456-426")

    while res is not None:
        # Handle items

        res = res.next()

Example Usage: list-payments-200-3

import mollie
from mollie import ClientSDK
import os


with ClientSDK(
    profile_id="<id>",
    testmode=False,
    security=mollie.Security(
        api_key=os.getenv("CLIENT_API_KEY", ""),
    ),
) as client_sdk:

    res = client_sdk.subscriptions.list_payments(customer_id="cst_5B8cwPMGnU", subscription_id="sub_5B8cwPMGnU", from_="tr_5B8cwPMGnU", limit=50, sort=mollie.Sorting.DESC, idempotency_key="123e4567-e89b-12d3-a456-426")

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description	Example
`customer_id`	str	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`subscription_id`	str	✔️	Provide the ID of the related subscription.	sub_5B8cwPMGnU
`from_`	Optional[str]	➖	Provide an ID to start the result set from the item with the given ID and onwards. This allows you to paginate the result set.	tr_5B8cwPMGnU
`limit`	OptionalNullable[int]	➖	The maximum number of items to return. Defaults to 50 items.	50
`sort`	Optional[models.Sorting]	➖	Used for setting the direction of the result set. Defaults to descending order, meaning the results are ordered from newest to oldest.	desc
`profile_id`	Optional[str]	➖	The identifier referring to the profile you wish to retrieve the resources for. Most API credentials are linked to a single profile. In these cases the `profileId` must not be sent. For organization-level credentials such as OAuth access tokens however, the `profileId` parameter is required.
`testmode`	Optional[bool]	➖	Most API credentials are specifically created for either live mode or test mode. In those cases the `testmode` query parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting the `testmode` query parameter to `true`. Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
`idempotency_key`	Optional[str]	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.ListSubscriptionPaymentsResponse

Errors

Error Type	Status Code	Content Type
models.ErrorResponse	400, 429	application/hal+json
models.APIError	4XX, 5XX	/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Subscriptions

Overview

Available Operations

create

Example Usage

Parameters

Response

Errors

list

Example Usage

Parameters

Response

Errors

get

Example Usage

Parameters

Response

Errors

update

Example Usage: update-subscription-200-1

Example Usage: update-subscription-200-2

Parameters

Response

Errors

cancel

Example Usage

Parameters

Response

Errors

all

Example Usage

Parameters

Response

Errors

list_payments

Example Usage: list-payments-200-1

Example Usage: list-payments-200-2

Example Usage: list-payments-200-3

Parameters

Response

Errors