# Search preferences

Find all the information related to generated preferences using specific filters or a specific date range. Only data from the last 90 days (3 months) will be brought. If you want to search for older data, use the GET for "Get preference".

**GET** `/checkout/preferences/search`

## Request parameters

### Query

- `sponsor_id` (string, optional)
  Unique numeric ID to identify the sponsor. It is used to identify what platform the checkout flow was initiated in.

- `external_reference` (string, optional)
  Reference you can synchronize with your payment system.

- `site_id` (string, optional)
  The site id.

- `marketplace` (string, optional)
  Marketplace ID.

- `limit` (integer, optional)
  Maximum number of records to return in the response. Must be a numeric value greater than or equal to 1. The default value is 30.

- `offset` (integer, optional)
  Starting point from which records should be returned. Must be a numeric value greater than or equal to 0. The default value is 0.

## Response parameters

- `elements` (array, optional)
  Elements

  - `elements[].id` (string, optional)
  Preference ID.

  - `elements[].client_id` (string, optional)
  Unique ID used to identify the client. It is obtained from the credentials used to create the preference. It´s the application ID.

  - `elements[].collector_id` (number, optional)
  Unique ID used to identify the collector. It is the same as the Cust ID.

  - `elements[].concept_id` (string, optional)
  Unique ID used to identify the concept.

  - `elements[].corporation_id` (string, optional)
  Corporation identifier.

  - `elements[].date_created` (string, optional)
  Registration date.

  - `elements[].expiration_date_from` (string, optional)
  Date in "yyyy-MM-dd'T'HH:mm:ssz" format which indicates the start of the preference`s validity period. This can be used, for instance, for limited sales, where sellers make an offer between certain dates. For example - 2022-11-17T09:37:52.000-04:00.

  - `elements[].expiration_date_to` (string, optional)
  Date in "yyyy-MM-dd'T'HH:mm:ssz" format which indicates the end of the preference`s validity period. This can be used, for instance, for limited sales, where sellers make an offer between certain dates. For example - 2022-11-17T09:37:52.000-04:00.

  - `elements[].expires` (boolean, optional)
  Boolean value that determines if a preference expires.

  - `elements[].external_reference` (string, optional)
  Reference you can synchronize with your payment system.

  - `elements[].integrator_id` (string, optional)
  Integrator identifier.

  - `elements[].items` (array, optional)
  items

  - `elements[].last_updated` (string, optional)
  Last updated date.

  - `elements[].live_mode` (boolean, optional)
  Indicates whether the Payment was made in a production environment or in a Test environment. If TRUE, then the chargeback will be processed in production mode. If FALSE, then the chargeback will be processed in sandbox mode.

  - `elements[].marketplace` (string, optional)
  Origin of the payment. This is an alphanumeric field whose default value is NONE. If the collector has their own marketplace, this is where the credentials to identify it are sent. As the marketplace is associated to the Application ID, the marketplace credentials must correspond to the credentials used to create the preference. Using the wrong credentials will result in an error.

  - `elements[].operation_type` (String, optional)
  Operation data_type.
Possible enum values:

  - `regular_payment`
  Normal payment.

  - `money_transfer`
  Money request.

  - `elements[].payer_email` (string, optional)
  Payer’s email address.

  - `elements[].platform_id` (string, optional)
  Platform identifier.

  - `elements[].processing_modes` (string, optional)
  Processing mode.

  - `elements[].product_id` (string, optional)
  Unique ID used to identify the product.

  - `elements[].purpose` (string, optional)
  This field has two possible values, empty and wallet_purchase.

  - `elements[].site_id` (string, optional)
  Unique ID used to identify the site.

  - `elements[].sponsor_id` (number, optional)
  Unique numeric ID to identify the sponsor. It is used to identify what platform the checkout flow was initiated in.

- `next_offset` (number, optional)
  Numeric field used to paginate the response.

- `total` (number, optional)
  total

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | ds_search_query | invalid query. |
| 401 | invalid_token | invalid_token. |
| 401 | invalid_caller_id | invalid caller_id |

## Request example

### cURL

```bash
curl -X GET \
  'https://api.mercadopago.com/checkout/preferences/search?sponsor_id=<SPONSOR_ID>&external_reference=<EXTERNAL_REFERENCE>&site_id=<SITE_ID>&marketplace=<MARKETPLACE>&limit=<LIMIT>&offset=<OFFSET>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

### Node.js

```javascript
const client = new MercadoPago({ accessToken: config.access_token });
const preference = new Preference(client);

const options = {
	 offset: 0,
	 limit: 2
};
const searched = await preference.search({ options });

```

### PHP

```php
<?php
MercadoPagoConfig::setAccessToken("ACCESS_TOKEN");

$client = new PreferenceClient();
$search_request = new MPSearchRequest(2, 0);
$search_result = $client->search($search_request);

echo implode($preference);
?>

```

### Java

```java
MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

PreferenceClient client = new PreferenceClient();

MPSearchRequest searchRequest =
MPSearchRequest.builder().limit(2).offset(0).build();

MPElementsResourcesPage<PreferenceSearch> result =
client.search(searchRequest);

```

## Response example

```json
{
  "elements": [
  {
  "id": "202809963-a2201f8d-11cb-443f-adf6-de5a42eed67d",
  "client_id": "6295877106812064",
  "collector_id": 202809963,
  "concept_id": "string",
  "corporation_id": "string",
  "date_created": "2018-02-02T19:18:51.150Z",
  "expiration_date_from": "2022-11-17T09:37:52.000-04:00",
  "expiration_date_to": "2022-11-17T10:37:52.000-05:00",
  "expires": false,
  "external_reference": "string",
  "integrator_id": "string",
  "items": [
  "Test Item"
  ],
  "last_updated": "string",
  "live_mode": false,
  "marketplace": "NONE",
  "operation_type": "regular_payment",
  "payer_email": "string",
  "platform_id": "string",
  "processing_modes": "string",
  "product_id": "string",
  "purpose": "string",
  "site_id": "MCO",
  "sponsor_id": 0
  }
  ],
  "next_offset": 1,
  "total": 1
}
```