Subscriptions

Overview

Available Operations

create - Create subscription
list - List customer subscriptions
get - Get subscription
update - Update subscription
cancel - Cancel subscription
all - List all subscriptions
listPayments - 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

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.*;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.CreateSubscriptionResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        CreateSubscriptionResponse res = sdk.subscriptions().create()
                .customerId("cst_5B8cwPMGnU")
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .subscriptionRequest(SubscriptionRequest.builder()
                    .amount(Amount.builder()
                        .currency("EUR")
                        .value("10.00")
                        .build())
                    .times(6L)
                    .interval("2 days")
                    .startDate("2025-01-01")
                    .description("Subscription of streaming channel")
                    .method(SubscriptionMethod.PAYPAL)
                    .applicationFee(SubscriptionRequestApplicationFee.builder()
                        .amount(Amount.builder()
                            .currency("EUR")
                            .value("10.00")
                            .build())
                        .description("Platform fee")
                        .build())
                    .webhookUrl("https://example.com/webhook")
                    .mandateId("mdt_5B8cwPMGnU")
                    .profileId("pfl_5B8cwPMGnU")
                    .testmode(false)
                    .build())
                .call();

        if (res.subscriptionResponse().isPresent()) {
            System.out.println(res.subscriptionResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description	Example
`customerId`	String	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`idempotencyKey`	Optional<String>	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`subscriptionRequest`	Optional<SubscriptionRequest>	➖	N/A

Response

CreateSubscriptionResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorResponse	404	application/hal+json
models/errors/APIException	4XX, 5XX	/

list

Retrieve all subscriptions of a customer.

The results are paginated.

Example Usage

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.components.Sorting;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.ListSubscriptionsRequest;
import com.mollie.mollie.models.operations.ListSubscriptionsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .testmode(false)
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        ListSubscriptionsRequest req = ListSubscriptionsRequest.builder()
                .customerId("cst_5B8cwPMGnU")
                .from("sub_5B8cwPMGnU")
                .limit(50L)
                .sort(Sorting.DESC)
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .build();


        sdk.subscriptions().list()
                .callAsStream()
                .forEach((ListSubscriptionsResponse item) -> {
                   // handle page
                });

    }
}

Parameters

Parameter	Type	Required	Description
`request`	ListSubscriptionsRequest	✔️	The request object to use for the request.

Response

ListSubscriptionsResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorResponse	400, 404	application/hal+json
models/errors/APIException	4XX, 5XX	/

get

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

Example Usage

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.GetSubscriptionResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .testmode(false)
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        GetSubscriptionResponse res = sdk.subscriptions().get()
                .customerId("cst_5B8cwPMGnU")
                .subscriptionId("sub_5B8cwPMGnU")
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .call();

        if (res.subscriptionResponse().isPresent()) {
            System.out.println(res.subscriptionResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description	Example
`customerId`	String	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`subscriptionId`	String	✔️	Provide the ID of the related subscription.	sub_5B8cwPMGnU
`testmode`	Optional<Boolean>	➖	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.
`idempotencyKey`	Optional<String>	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426

Response

GetSubscriptionResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorResponse	404	application/hal+json
models/errors/APIException	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

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Amount;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.UpdateSubscriptionRequestBody;
import com.mollie.mollie.models.operations.UpdateSubscriptionResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        UpdateSubscriptionResponse res = sdk.subscriptions().update()
                .customerId("cst_5B8cwPMGnU")
                .subscriptionId("sub_5B8cwPMGnU")
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .requestBody(UpdateSubscriptionRequestBody.builder()
                    .amount(Amount.builder()
                        .currency("EUR")
                        .value("10.00")
                        .build())
                    .description("Subscription of streaming channel")
                    .interval("1 months")
                    .startDate("2025-01-01")
                    .times(6L)
                    .webhookUrl("https://example.com/webhook")
                    .mandateId("mdt_5B8cwPMGnU")
                    .testmode(false)
                    .build())
                .call();

        if (res.subscriptionResponse().isPresent()) {
            System.out.println(res.subscriptionResponse().get());
        }
    }
}

Example Usage: update-subscription-200-2

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Amount;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.UpdateSubscriptionRequestBody;
import com.mollie.mollie.models.operations.UpdateSubscriptionResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        UpdateSubscriptionResponse res = sdk.subscriptions().update()
                .customerId("cst_5B8cwPMGnU")
                .subscriptionId("sub_5B8cwPMGnU")
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .requestBody(UpdateSubscriptionRequestBody.builder()
                    .amount(Amount.builder()
                        .currency("EUR")
                        .value("10.00")
                        .build())
                    .description("Subscription of streaming channel")
                    .interval("1 months")
                    .startDate("2025-01-01")
                    .times(6L)
                    .webhookUrl("https://example.com/webhook")
                    .mandateId("mdt_5B8cwPMGnU")
                    .testmode(false)
                    .build())
                .call();

        if (res.subscriptionResponse().isPresent()) {
            System.out.println(res.subscriptionResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description	Example
`customerId`	String	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`subscriptionId`	String	✔️	Provide the ID of the related subscription.	sub_5B8cwPMGnU
`idempotencyKey`	Optional<String>	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`requestBody`	Optional<UpdateSubscriptionRequestBody>	➖	N/A

Response

UpdateSubscriptionResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorResponse	404	application/hal+json
models/errors/APIException	4XX, 5XX	/

cancel

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

Example Usage

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.CancelSubscriptionRequestBody;
import com.mollie.mollie.models.operations.CancelSubscriptionResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        CancelSubscriptionResponse res = sdk.subscriptions().cancel()
                .customerId("cst_5B8cwPMGnU")
                .subscriptionId("sub_5B8cwPMGnU")
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .requestBody(CancelSubscriptionRequestBody.builder()
                    .testmode(false)
                    .build())
                .call();

        if (res.subscriptionResponse().isPresent()) {
            System.out.println(res.subscriptionResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description	Example
`customerId`	String	✔️	Provide the ID of the related customer.	cst_5B8cwPMGnU
`subscriptionId`	String	✔️	Provide the ID of the related subscription.	sub_5B8cwPMGnU
`idempotencyKey`	Optional<String>	➖	A unique key to ensure idempotent requests. This key should be a UUID v4 string.	123e4567-e89b-12d3-a456-426
`requestBody`	Optional<CancelSubscriptionRequestBody>	➖	N/A

Response

CancelSubscriptionResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorResponse	404	application/hal+json
models/errors/APIException	4XX, 5XX	/

all

Retrieve all subscriptions initiated across all your customers.

The results are paginated.

Example Usage: list-payments-200-1

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.ListAllSubscriptionsRequest;
import com.mollie.mollie.models.operations.ListAllSubscriptionsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .profileId("pfl_5B8cwPMGnU")
                .testmode(false)
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        ListAllSubscriptionsRequest req = ListAllSubscriptionsRequest.builder()
                .from("tr_5B8cwPMGnU")
                .limit(50L)
                .build();


        sdk.subscriptions().all()
                .callAsStream()
                .forEach((ListAllSubscriptionsResponse item) -> {
                   // handle page
                });

    }
}

Example Usage: list-payments-200-2

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.ListAllSubscriptionsRequest;
import com.mollie.mollie.models.operations.ListAllSubscriptionsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .profileId("pfl_5B8cwPMGnU")
                .testmode(false)
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        ListAllSubscriptionsRequest req = ListAllSubscriptionsRequest.builder()
                .from("tr_5B8cwPMGnU")
                .limit(50L)
                .build();


        sdk.subscriptions().all()
                .callAsStream()
                .forEach((ListAllSubscriptionsResponse item) -> {
                   // handle page
                });

    }
}

Example Usage: list-payments-200-3

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.ListAllSubscriptionsRequest;
import com.mollie.mollie.models.operations.ListAllSubscriptionsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .profileId("pfl_5B8cwPMGnU")
                .testmode(false)
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        ListAllSubscriptionsRequest req = ListAllSubscriptionsRequest.builder()
                .from("tr_5B8cwPMGnU")
                .limit(50L)
                .build();


        sdk.subscriptions().all()
                .callAsStream()
                .forEach((ListAllSubscriptionsResponse item) -> {
                   // handle page
                });

    }
}

Example Usage: list-subscriptions-200-1

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.ListAllSubscriptionsRequest;
import com.mollie.mollie.models.operations.ListAllSubscriptionsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .profileId("pfl_5B8cwPMGnU")
                .testmode(false)
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        ListAllSubscriptionsRequest req = ListAllSubscriptionsRequest.builder()
                .from("sub_rVKGtNd6s3")
                .limit(50L)
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .build();


        sdk.subscriptions().all()
                .callAsStream()
                .forEach((ListAllSubscriptionsResponse item) -> {
                   // handle page
                });

    }
}

Parameters

Parameter	Type	Required	Description
`request`	ListAllSubscriptionsRequest	✔️	The request object to use for the request.

Response

ListAllSubscriptionsResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorResponse	400, 404	application/hal+json
models/errors/APIException	4XX, 5XX	/

listPayments

Retrieve all payments of a specific subscription.

The results are paginated.

Example Usage: list-payments-200-1

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.components.Sorting;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.ListSubscriptionPaymentsRequest;
import com.mollie.mollie.models.operations.ListSubscriptionPaymentsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .profileId("pfl_5B8cwPMGnU")
                .testmode(false)
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        ListSubscriptionPaymentsRequest req = ListSubscriptionPaymentsRequest.builder()
                .customerId("cst_5B8cwPMGnU")
                .subscriptionId("sub_5B8cwPMGnU")
                .from("tr_5B8cwPMGnU")
                .limit(50L)
                .sort(Sorting.DESC)
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .build();


        sdk.subscriptions().listPayments()
                .callAsStream()
                .forEach((ListSubscriptionPaymentsResponse item) -> {
                   // handle page
                });

    }
}

Example Usage: list-payments-200-2

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.components.Sorting;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.ListSubscriptionPaymentsRequest;
import com.mollie.mollie.models.operations.ListSubscriptionPaymentsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .profileId("pfl_5B8cwPMGnU")
                .testmode(false)
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        ListSubscriptionPaymentsRequest req = ListSubscriptionPaymentsRequest.builder()
                .customerId("cst_5B8cwPMGnU")
                .subscriptionId("sub_5B8cwPMGnU")
                .from("tr_5B8cwPMGnU")
                .limit(50L)
                .sort(Sorting.DESC)
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .build();


        sdk.subscriptions().listPayments()
                .callAsStream()
                .forEach((ListSubscriptionPaymentsResponse item) -> {
                   // handle page
                });

    }
}

Example Usage: list-payments-200-3

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.Security;
import com.mollie.mollie.models.components.Sorting;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.ListSubscriptionPaymentsRequest;
import com.mollie.mollie.models.operations.ListSubscriptionPaymentsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .profileId("pfl_5B8cwPMGnU")
                .testmode(false)
                .security(Security.builder()
                    .apiKey(System.getenv().getOrDefault("API_KEY", ""))
                    .build())
            .build();

        ListSubscriptionPaymentsRequest req = ListSubscriptionPaymentsRequest.builder()
                .customerId("cst_5B8cwPMGnU")
                .subscriptionId("sub_5B8cwPMGnU")
                .from("tr_5B8cwPMGnU")
                .limit(50L)
                .sort(Sorting.DESC)
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .build();


        sdk.subscriptions().listPayments()
                .callAsStream()
                .forEach((ListSubscriptionPaymentsResponse item) -> {
                   // handle page
                });

    }
}

Parameters

Parameter	Type	Required	Description
`request`	ListSubscriptionPaymentsRequest	✔️	The request object to use for the request.

Response

ListSubscriptionPaymentsResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorResponse	400	application/hal+json
models/errors/APIException	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: list-payments-200-1

Example Usage: list-payments-200-2

Example Usage: list-payments-200-3

Example Usage: list-subscriptions-200-1

Parameters

Response

Errors

listPayments

Example Usage: list-payments-200-1

Example Usage: list-payments-200-2

Example Usage: list-payments-200-3

Parameters

Response

Errors