PreferenceClient: Checkout Preferences API Reference

PreferenceClient manages Mercado Pago Checkout Pro preferences. A preference is the configuration object that defines the entire payment experience presented to the buyer: which items are being purchased, which payment methods are accepted, shipping options, back-redirect URLs, expiration windows, and more. Once a preference is created, Mercado Pago returns an initPoint URL that you use to redirect your buyer into the hosted checkout flow. Package: com.mercadopago.client.preference

Constructors

`PreferenceClient()`

Creates a PreferenceClient using the default HTTP client configured via MercadoPagoConfig.

PreferenceClient client = new PreferenceClient();

`PreferenceClient(MPHttpClient httpClient)`

Creates a PreferenceClient with a custom HTTP client.

httpClient

MPHttpClient

required

The HTTP client implementation used to execute all requests.

PreferenceClient client = new PreferenceClient(customHttpClient);

Methods

`get` — Retrieve a preference

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

Retrieves a checkout preference by its unique identifier.

String

required

The unique identifier of the preference (e.g. "123456789-abc123de-...").

requestOptions

MPRequestOptions

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

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

`create` — Create a preference

public Preference create(PreferenceRequest request) throws MPException, MPApiException
public Preference create(PreferenceRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Creates a new checkout preference. The response includes initPoint — the production checkout URL — and sandboxInitPoint for testing.

request

PreferenceRequest

required

The preference configuration. Key fields:

Field	Type	Description
`items`	`List<PreferenceItemRequest>`	Required. List of items the buyer is purchasing.
`payer`	`PreferencePayerRequest`	Buyer information (email, name, identification).
`backUrls`	`PreferenceBackUrlsRequest`	Redirect URLs for success, pending, and failure outcomes.
`autoReturn`	`String`	Auto-redirect mode after payment: `"approved"` or `"all"`.
`paymentMethods`	`PreferencePaymentMethodsRequest`	Payment method exclusions and installment configuration.
`shipments`	`PreferenceShipmentsRequest`	Shipping mode, cost, and address details.
`notificationUrl`	`String`	Webhook URL for IPN payment status notifications.
`externalReference`	`String`	Your system’s reference identifier for this preference.
`expires`	`Boolean`	Whether the preference expires.
`expirationDateFrom`	`OffsetDateTime`	Start date for the active window.
`expirationDateTo`	`OffsetDateTime`	End date when the preference expires.
`binaryMode`	`Boolean`	When `true`, only `approved`/`rejected` statuses are used.
`marketplace`	`String`	Marketplace origin identifier. Defaults to `NONE`.
`marketplaceFee`	`BigDecimal`	Fee charged by the marketplace application.
`statementDescriptor`	`String`	Text shown on the buyer’s card statement.
`purpose`	`String`	Purpose of the preference (e.g. `"wallet_purchase"`).
`metadata`	`Map<String, Object>`	Arbitrary key-value metadata for merchant use.

requestOptions

MPRequestOptions

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

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

Redirecting buyers: After creating a preference, redirect your buyer to preference.getInitPoint() (production) or preference.getSandboxInitPoint() (sandbox/testing) to start the hosted checkout flow.

`update` — Update a preference

public Preference update(String id, PreferenceRequest request) throws MPException, MPApiException
public Preference update(String id, PreferenceRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Updates an existing preference. The same PreferenceRequest builder is used; only fields present in the request body are updated.

String

required

The unique identifier of the preference to update.

request

PreferenceRequest

required

The updated preference attributes. Build only the fields you want to change.

requestOptions

MPRequestOptions

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

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

`search` — Search preferences with pagination

public MPElementsResourcesPage<PreferenceSearch> search(MPSearchRequest request) throws MPException, MPApiException
public MPElementsResourcesPage<PreferenceSearch> search(MPSearchRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Searches for preferences matching the specified filters and returns a paginated result page containing PreferenceSearch summary objects.

request

MPSearchRequest

required

Search parameters. Build with MPSearchRequest.builder().filters(map).offset(0).limit(30).build(). Common filters include external_reference, site_id, sponsor_id.

requestOptions

MPRequestOptions

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

Returns: MPElementsResourcesPage<PreferenceSearch> — contains .getElements() (list of preference summaries) and .getPaging() for pagination metadata. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

Resource classes

`Preference` resource

Key fields returned on the Preference object:

String

Unique identifier of the preference.

initPoint

String

Production checkout URL. Redirect buyers here to start the payment flow. This is the most important field returned after creating a preference.

sandboxInitPoint

String

Sandbox checkout URL. Use this in testing environments to simulate the payment flow without real charges.

items

List<PreferenceItem>

The items configured for this checkout.

payer

PreferencePayer

Buyer information attached to this preference.

backUrls

PreferenceBackUrls

Redirect URLs for success, pending, and failure outcomes.

paymentMethods

PreferencePaymentMethods

Accepted and excluded payment method configuration.

externalReference

String

Your system’s reference ID passed at creation.

notificationUrl

String

Webhook URL for IPN notifications.

expires

Boolean

Whether this preference has an expiration window.

expirationDateFrom

OffsetDateTime

Start of the active window.

expirationDateTo

OffsetDateTime

End of the active window (preference expires after this time).

collectorId

Long

Identifier of the seller receiving the payment.

dateCreated

OffsetDateTime

Timestamp when the preference was created.

Usage example

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.preference.PreferenceClient;
import com.mercadopago.client.preference.PreferenceItemRequest;
import com.mercadopago.client.preference.PreferencePayerRequest;
import com.mercadopago.client.preference.PreferenceBackUrlsRequest;
import com.mercadopago.client.preference.PreferenceRequest;
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.resources.preference.Preference;
import java.math.BigDecimal;
import java.util.List;
import java.util.Map;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

PreferenceClient client = new PreferenceClient();

// 1. Create a preference
PreferenceRequest request = PreferenceRequest.builder()
    .items(List.of(
        PreferenceItemRequest.builder()
            .id("SKU-001")
            .title("Blue Running Shoes")
            .quantity(1)
            .unitPrice(new BigDecimal("99.90"))
            .currencyId("BRL")
            .build()
    ))
    .payer(PreferencePayerRequest.builder()
        .email("buyer@example.com")
        .build())
    .backUrls(PreferenceBackUrlsRequest.builder()
        .success("https://your-site.com/checkout/success")
        .pending("https://your-site.com/checkout/pending")
        .failure("https://your-site.com/checkout/failure")
        .build())
    .autoReturn("approved")
    .externalReference("order-5678")
    .notificationUrl("https://your-site.com/webhooks/mp")
    .build();

Preference preference = client.create(request);

// 2. Redirect the buyer
String checkoutUrl = preference.getInitPoint();      // production
String sandboxUrl  = preference.getSandboxInitPoint(); // testing
System.out.println("Redirect buyer to: " + checkoutUrl);

// 3. Retrieve the preference later
Preference fetched = client.get(preference.getId());

// 4. Update the preference (e.g. change expiration)
PreferenceRequest updateRequest = PreferenceRequest.builder()
    .notificationUrl("https://your-site.com/webhooks/mp-v2")
    .build();
Preference updated = client.update(preference.getId(), updateRequest);

// 5. Search preferences
var page = client.search(
    MPSearchRequest.builder()
        .filters(Map.of("external_reference", "order-5678"))
        .offset(0)
        .limit(10)
        .build()
);
System.out.println("Total matching preferences: " + page.getPaging().getTotal());
page.getElements().forEach(p -> System.out.println("  " + p.getId()));

Core

Clients

Exceptions & HTTP

PreferenceClient: Checkout Preferences API Reference

Constructors