PreapprovalClient and PreApprovalPlanClient Reference

Mercado Pago’s recurring billing system is built around two complementary clients. PreApprovalPlanClient manages subscription plan templates — reusable billing configurations (frequency, currency, amount) that multiple subscribers can share. PreapprovalClient manages individual subscriptions (preapprovals) — the authorisation from a specific payer to be charged on a recurring schedule, either via a plan or configured directly. Together, these two clients cover the full lifecycle of subscription billing: create a plan, link subscribers to it, and manage each subscription’s status independently.

PreApprovalPlanClient

Package: com.mercadopago.client.preapprovalplan PreApprovalPlanClient provides CRUD operations for subscription plan templates. Each plan defines the billing frequency, currency, and amount that all subscriptions attached to it will inherit. Creating a plan returns an initPoint URL that subscribers visit to sign up.

Constructors

`PreApprovalPlanClient()`

Creates a client using the default HTTP client from MercadoPagoConfig.

PreApprovalPlanClient planClient = new PreApprovalPlanClient();

`PreApprovalPlanClient(MPHttpClient httpClient)`

Creates a client with a custom HTTP client.

httpClient

MPHttpClient

required

The HTTP client implementation used to execute all requests.

Methods

`get` — Retrieve a plan

public PreApprovalPlan get(String id) throws MPException, MPApiException
public PreApprovalPlan get(String id, MPRequestOptions requestOptions) throws MPException, MPApiException

Retrieves a subscription plan by its unique identifier.

String

required

The unique identifier of the subscription plan.

requestOptions

MPRequestOptions

Optional per-request overrides for access token, custom headers, or timeouts. Pass null to use global defaults.

Returns: PreApprovalPlan — the requested plan. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`create` — Create a plan

public PreApprovalPlan create(PreApprovalPlanCreateRequest request) throws MPException, MPApiException
public PreApprovalPlan create(PreApprovalPlanCreateRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Creates a new subscription plan template.

request

PreApprovalPlanCreateRequest

required

Plan configuration. Key fields:

Field	Type	Description
`reason`	`String`	Short descriptive title of the plan, shown to subscribers during checkout.
`backUrl`	`String`	URL to redirect the subscriber after completing the checkout flow.
`externalReference`	`String`	Your system’s reference identifier for reconciliation.
`autoRecurring`	`PreApprovalPlanAutoRecurringCreateRequest`	Recurring billing configuration (frequency type, frequency, currency, transaction amount, etc.).

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: PreApprovalPlan — the created plan, including id and initPoint. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`update` — Update a plan

public PreApprovalPlan update(String id, PreApprovalPlanUpdateRequest request) throws MPException, MPApiException
public PreApprovalPlan update(String id, PreApprovalPlanUpdateRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Updates an existing subscription plan.

String

required

The unique identifier of the plan to update.

request

PreApprovalPlanUpdateRequest

required

Updated plan fields. Available fields:

Field	Type	Description
`reason`	`String`	New title for the plan.
`backUrl`	`String`	New back URL for the plan.
`status`	`String`	New plan status (e.g. `"cancelled"`).
`autoRecurring`	`PreApprovalPlanAutoRecurringUpdateRequest`	Updated recurring billing configuration.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: PreApprovalPlan — the updated plan. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`search` — Search plans with pagination

public MPResultsResourcesPage<PreApprovalPlan> search(MPSearchRequest request) throws MPException, MPApiException
public MPResultsResourcesPage<PreApprovalPlan> search(MPSearchRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Searches for subscription plans matching the specified criteria.

request

MPSearchRequest

required

Search parameters. Build with MPSearchRequest.builder().filters(map).offset(0).limit(20).build().

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: MPResultsResourcesPage<PreApprovalPlan> — contains .getResults() and .getPaging(). Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`PreApprovalPlan` resource

String

Unique identifier of the subscription plan.

reason

String

Short title of the plan displayed to subscribers.

status

String

Current plan status: active or cancelled.

initPoint

String

Production checkout URL for subscribing to this plan. Share with users who want to subscribe.

sandboxInitPoint

String

Sandbox checkout URL for testing subscription sign-ups.

autoRecurring

PreApprovalPlanAutoRecurring

Recurring billing configuration: frequency type, frequency, currency, and transaction amount.

collectorId

Long

Mercado Pago user identifier of the seller who receives the charges.

externalReference

String

Your system’s reference identifier.

backUrl

String

URL subscribers are redirected to after completing the checkout flow.

dateCreated

OffsetDateTime

Timestamp when the plan was created.

lastModified

OffsetDateTime

Timestamp of the last modification.

Plan usage example

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.preapprovalplan.PreApprovalPlanClient;
import com.mercadopago.client.preapprovalplan.PreApprovalPlanCreateRequest;
import com.mercadopago.client.preapprovalplan.PreApprovalPlanAutoRecurringCreateRequest;
import com.mercadopago.client.preapprovalplan.PreApprovalPlanUpdateRequest;
import com.mercadopago.resources.preapprovalplan.PreApprovalPlan;
import com.mercadopago.net.MPSearchRequest;
import java.math.BigDecimal;
import java.util.Map;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

PreApprovalPlanClient planClient = new PreApprovalPlanClient();

// 1. Create a subscription plan (monthly, BRL 49.90)
PreApprovalPlanCreateRequest createRequest = PreApprovalPlanCreateRequest.builder()
    .reason("Premium Monthly Plan")
    .backUrl("https://your-site.com/subscription/result")
    .externalReference("plan-premium-monthly")
    .autoRecurring(
        PreApprovalPlanAutoRecurringCreateRequest.builder()
            .frequency(1)
            .frequencyType("months")
            .transactionAmount(new BigDecimal("49.90"))
            .currencyId("BRL")
            .build()
    )
    .build();

PreApprovalPlan plan = planClient.create(createRequest);
System.out.println("Plan ID: " + plan.getId());
System.out.println("Subscribe URL: " + plan.getInitPoint());

// 2. Retrieve the plan
PreApprovalPlan fetched = planClient.get(plan.getId());

// 3. Update the plan reason
PreApprovalPlanUpdateRequest updateRequest = PreApprovalPlanUpdateRequest.builder()
    .reason("Premium Monthly Plan (Updated)")
    .build();
PreApprovalPlan updated = planClient.update(plan.getId(), updateRequest);

// 4. Search plans
var page = planClient.search(
    MPSearchRequest.builder()
        .filters(Map.of("status", "active"))
        .offset(0)
        .limit(10)
        .build()
);
System.out.println("Active plans: " + page.getPaging().getTotal());

PreapprovalClient

Package: com.mercadopago.client.preapproval PreapprovalClient manages individual subscriptions (preapprovals). A preapproval authorises a specific seller to collect recurring payments from a payer’s payment method according to the billing schedule defined in the autoRecurring configuration. Each subscription has its own lifecycle: it begins as pending, becomes authorized after the payer completes the checkout flow, and can be paused or cancelled at any time.

Constructors

`PreapprovalClient()`

Creates a client using the default HTTP client from MercadoPagoConfig.

PreapprovalClient client = new PreapprovalClient();

`PreapprovalClient(MPHttpClient httpClient)`

Creates a client with a custom HTTP client.

httpClient

MPHttpClient

required

The HTTP client implementation used to execute all requests.

Methods

`get` — Retrieve a subscription

public Preapproval get(String id) throws MPException, MPApiException
public Preapproval get(String id, MPRequestOptions requestOptions) throws MPException, MPApiException

Retrieves a subscription by its unique identifier.

String

required

The unique identifier of the preapproval (subscription).

requestOptions

MPRequestOptions

Optional per-request overrides for access token, custom headers, or timeouts. Pass null to use global defaults.

Returns: Preapproval — the requested subscription. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`create` — Create a subscription

public Preapproval create(PreapprovalCreateRequest request) throws MPException, MPApiException
public Preapproval create(PreapprovalCreateRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Creates a new subscription. After creation, redirect the payer to preapproval.getInitPoint() so they can authorize recurring charges.

request

PreapprovalCreateRequest

required

Subscription creation request. Key fields:

Field	Type	Description
`payerEmail`	`String`	Email address of the subscriber (payer).
`backUrl`	`String`	URL to redirect the payer after completing the subscription flow.
`collectorId`	`String`	Unique identifier of the seller (collector).
`reason`	`String`	Title or reason describing the subscription.
`externalReference`	`String`	Your system’s reference identifier.
`status`	`String`	Initial status of the preapproval.
`autoRecurring`	`PreApprovalAutoRecurringCreateRequest`	Billing schedule: `frequency`, `frequencyType` (`"days"` or `"months"`), `transactionAmount`, `currencyId`, `startDate`, `endDate`.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: Preapproval — the created subscription, including id, status, initPoint, and sandboxInitPoint. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`update` — Update a subscription

public Preapproval update(String id, PreapprovalUpdateRequest request) throws MPException, MPApiException
public Preapproval update(String id, PreapprovalUpdateRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Updates an existing subscription. Use this to pause, reactivate, or cancel a subscription, or to update its billing amount or reason.

String

required

The unique identifier of the preapproval to update.

request

PreapprovalUpdateRequest

required

Updated subscription fields. Available fields:

Field	Type	Description
`backUrl`	`String`	Updated redirect URL.
`reason`	`String`	Updated title or description.
`externalReference`	`String`	Updated external reference.
`status`	`String`	New status: `authorized`, `paused`, or `cancelled`.
`autoRecurring`	`PreApprovalAutoRecurringUpdateRequest`	Updated billing configuration (amount, dates, frequency).

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: Preapproval — the updated subscription. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`search` — Search subscriptions with pagination

public MPResultsResourcesPage<Preapproval> search(MPSearchRequest request) throws MPException, MPApiException
public MPResultsResourcesPage<Preapproval> search(MPSearchRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Searches for subscriptions matching the specified criteria.

request

MPSearchRequest

required

Search parameters. Build with MPSearchRequest.builder().filters(map).offset(0).limit(20).build(). Common filters include status, payer_email, external_reference.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: MPResultsResourcesPage<Preapproval> — contains .getResults() and .getPaging(). Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`Preapproval` resource

String

Unique identifier of the subscription.

status

String

Current subscription status: pending, authorized, paused, cancelled.

reason

String

Title or description of the subscription.

initPoint

String

Production checkout URL where the payer authorizes recurring charges. Redirect the payer here after creating the subscription.

sandboxInitPoint

String

Sandbox checkout URL for testing subscription authorization.

payerId

Long

Identifier of the payer who authorized the recurring charges.

payerEmail

String

Email address of the payer.

collectorId

Long

Identifier of the seller who receives the recurring payments.

externalReference

String

Your system’s reference identifier.

nextPaymentDate

OffsetDateTime

Scheduled date of the next automatic payment debit.

autoRecurring

PreapprovalAutoRecurring

Active billing configuration: frequency, currency, and transaction amount.

paymentMethodId

String

Payment method used for recurring charges.

dateCreated

OffsetDateTime

Timestamp when the subscription was created.

lastModified

OffsetDateTime

Timestamp when the subscription was last modified.

Subscription usage example

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.preapproval.PreapprovalClient;
import com.mercadopago.client.preapproval.PreapprovalCreateRequest;
import com.mercadopago.client.preapproval.PreApprovalAutoRecurringCreateRequest;
import com.mercadopago.client.preapproval.PreapprovalUpdateRequest;
import com.mercadopago.resources.preapproval.Preapproval;
import com.mercadopago.net.MPSearchRequest;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.util.Map;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

PreapprovalClient client = new PreapprovalClient();

// 1. Create a subscription (payer pays BRL 29.90 every month)
PreapprovalCreateRequest createRequest = PreapprovalCreateRequest.builder()
    .reason("Monthly Newsletter Subscription")
    .payerEmail("subscriber@example.com")
    .backUrl("https://your-site.com/subscription/result")
    .externalReference("sub-user-42")
    .autoRecurring(
        PreApprovalAutoRecurringCreateRequest.builder()
            .frequency(1)
            .frequencyType("months")
            .transactionAmount(new BigDecimal("29.90"))
            .currencyId("BRL")
            .startDate(OffsetDateTime.now())
            .endDate(OffsetDateTime.now().plusYears(1))
            .build()
    )
    .build();

Preapproval subscription = client.create(createRequest);
System.out.println("Subscription ID: " + subscription.getId());
System.out.println("Auth URL: " + subscription.getInitPoint()); // redirect payer here

// 2. Retrieve a subscription
Preapproval fetched = client.get(subscription.getId());
System.out.println("Status: " + fetched.getStatus());
System.out.println("Next payment: " + fetched.getNextPaymentDate());

// 3. Pause the subscription
Preapproval paused = client.update(
    subscription.getId(),
    PreapprovalUpdateRequest.builder().status("paused").build()
);

// 4. Reactivate the subscription
Preapproval reactivated = client.update(
    subscription.getId(),
    PreapprovalUpdateRequest.builder().status("authorized").build()
);

// 5. Cancel the subscription
Preapproval cancelled = client.update(
    subscription.getId(),
    PreapprovalUpdateRequest.builder().status("cancelled").build()
);

// 6. Search subscriptions
var page = client.search(
    MPSearchRequest.builder()
        .filters(Map.of("payer_email", "subscriber@example.com", "status", "authorized"))
        .offset(0)
        .limit(10)
        .build()
);
System.out.println("Authorized subscriptions: " + page.getPaging().getTotal());

Core

Clients

Exceptions & HTTP

PreapprovalClient and PreApprovalPlanClient Reference

PreApprovalPlanClient

Constructors

`PreApprovalPlanClient()`

`PreApprovalPlanClient(MPHttpClient httpClient)`

Methods

`get` — Retrieve a plan

`create` — Create a plan

`update` — Update a plan

`PreApprovalPlan` resource

Plan usage example

PreapprovalClient

Constructors

`PreapprovalClient()`

`PreapprovalClient(MPHttpClient httpClient)`

Methods

`get` — Retrieve a subscription

`create` — Create a subscription

`update` — Update a subscription

`Preapproval` resource

Subscription usage example

Build docs developers (and LLMs) love

Core

Clients

Exceptions & HTTP

Documentation Index

​PreApprovalPlanClient

​Constructors

​PreApprovalPlanClient()

​PreApprovalPlanClient(MPHttpClient httpClient)

​Methods

​get — Retrieve a plan

​create — Create a plan

​update — Update a plan

​search — Search plans with pagination

​PreApprovalPlan resource

​Plan usage example

​PreapprovalClient

​Constructors

​PreapprovalClient()

​PreapprovalClient(MPHttpClient httpClient)

​Methods

​get — Retrieve a subscription

​create — Create a subscription

​update — Update a subscription

​search — Search subscriptions with pagination

​Preapproval resource

​Subscription usage example

Build docs developers (and LLMs) love

PreApprovalPlanClient

Constructors

`PreApprovalPlanClient()`

`PreApprovalPlanClient(MPHttpClient httpClient)`

Methods

`get` — Retrieve a plan

`create` — Create a plan

`update` — Update a plan

`search` — Search plans with pagination

`PreApprovalPlan` resource

Plan usage example

PreapprovalClient

Constructors

`PreapprovalClient()`

`PreapprovalClient(MPHttpClient httpClient)`

Methods

`get` — Retrieve a subscription

`create` — Create a subscription

`update` — Update a subscription

`search` — Search subscriptions with pagination

`Preapproval` resource

Subscription usage example