# Get preference

Check all the payment information for a product or service with the ID of the preference of your choice.

**GET** `/checkout/preferences/{id}`

## Request parameters

### Path

- `id` (string, required)
  Preference ID.

## Response parameters

- `additional_info` (string, optional)
  Additional information.

- `auto_return` (String, optional)
  If specified, the buyer will be automatically redirected to the seller's site after the purchase is approved with a credit card.
Possible enum values:

  - `approved`
  The redirection takes place only for approved payments with a credit card.

  - `all`
  The redirection takes place only for approved payments with a credit card, forward compatibility only if we change the default behavior.

- `back_urls` (object, optional)
  Return URLs to the seller's site, either automatically ("auto_return") or through the 'Return to site' button, depending on the payment status.

  - `back_urls.failure` (string, optional)
  Canceled payment URL.

  - `back_urls.pending` (string, optional)
  Pending or in process payment URL.

  - `back_urls.success` (string, optional)
  Approved payment URL.

- `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.

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

- `date_created` (string, optional)
  Registration date.

- `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.

- `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.

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

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

- `id` (string, optional)
  Autogenerated unique ID that identifies the preference. For example 036151801-2484cd71-7140-4c51-985a-d4cfcf133baf.

- `init_point` (string, optional)
  Automatically generated URL to open the Checkout.

- `items` (array, optional)
  Items information.

  - `items[].id` (string, optional)
  Item id.

  - `items[].currency_id` (string, optional)
  Unique ID to identify the currency. ISO_4217 code. Some sites allow local currency and USD, but it is important to note that the amount is converted to local currency when the preference is created, as the checkout always processes transactions using local currency. If you use USD please take into consideration that this value is not automatically updated if the value of local currency changes in relation to USD.

  - `items[].title` (string, optional)
  This is the item`s title, which will display during the payment process, at checkout, activities, and emails.

  - `items[].picture_url` (string, optional)
  Item image URL.

  - `items[].description` (string, optional)
  Item description. This is a free text field.

  - `items[].category_id` (string, optional)
  This is a free string where the item category can be added.

  - `items[].quantity` (number, optional)
  Item quantity. This property is used to calculate the total cost.

  - `items[].unit_price` (number, optional)
  Unit price of the item. This property is used together with the property quantity to determine the order cost.

  - `items[].fiscal_data` (enum, optional)
  Presents the tax data of the item.
Possible enum values:

  - `sat`
  Provides the SAT (Authenticator and Transmitter System for Electronic Tax Receipts) category of the item.

  - `sat_measurement_id`
  Indicates whether the item is dangerous or not.

  - `measurement_unit`
  If the item is considered dangerous, specifies the type of the dangerous material.

  - `package_id`
  Identification of the package key.

  - `dangerous_material_idOP`
  Identification of the hazardous material key.

  - `items[].dimensions` (enum, optional)
  Presents the dimensions of the item to be shipped.
Possible enum values:

  - `unit`
  Unit of measure for the item.

  - `height`
  Height of the item.

  - `width`
  Ancho del artículo.

  - `length`
  Item length.

  - `weight`
  Item weight.

- `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.

- `marketplace_fee` (number, optional)
  Marketplace`s fee charged by application owner. It is a fixed amount and its default value is 0 in local currency. This property can only be sent if a valid marketplace has been defined as well, otherwise the request will fail.

- `notification_url` (string, optional)
  Notifications URL available to receive notifications of events related to Payment. The maximum number of characters allowed for submission in this parameter is 248 characters. The use of the protocol ("https") in the URL is mandatory.

- `statement_descriptor` (string, optional)
  The statement descriptor is a long text (up to 13 characters) that will be visualized in the payer´s credit card statement to easily identify the purchase.

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

  - `regular_payment`
  Normal payment.

  - `money_transfer`
  Money request.

- `payer` (object, optional)
  Buyer information, such as name, last name, e-mail, phone, personal identification, address, and registration date.

  - `payer.phone` (object, optional)
  Buyer’s phone number.

  - `payer.phone.area_code` (string, optional)
  Area code.

  - `payer.phone.number` (string, optional)
  Phone number.

  - `payer.address` (object, optional)
  Buyer’s address.

  - `payer.address.zip_code` (string, optional)
  Zip code.

  - `payer.address.street_name` (string, optional)
  Street name.

  - `payer.address.street_number` (string, optional)
  Street number.

  - `payer.email` (string, optional)
  Payer’s email address.

  - `payer.identification` (object, optional)
  Payer ID.

  - `payer.identification.number` (string, optional)
  Identification number.

  - `payer.identification.type` (string, optional)
  Identification Type.

  - `payer.name` (string, optional)
  Buyer’s name.

  - `payer.surname` (string, optional)
  Buyer's last name.

  - `payer.date_created` (string, optional)
  Registration date.

- `payment_methods` (object, optional)
  All configuration related to payments methods, such as excluded payment methods, excluded payment types, default payment method, and installments.

  - `payment_methods.excluded_payment_methods` (array, optional)
  Payment methods excluded from the payment process (except account_money, which is always allowed). The payment methods included here will not be available at checkout.

  - `payment_methods.excluded_payment_methods[].id` (string, optional)
  Payment method identifier.

  - `payment_methods.default_installments` (string, optional)
  Prefered number of credit card installments.

  - `payment_methods.default_payment_method_id` (string, optional)
  Suggested payment method. The user will initiate the checkout this this payment method already selected. It is considered suggested because Checkouts follow different logics in order to select the best payment method for a specific transaction, and this property is the option with the least relevance.

  - `payment_methods.excluded_payment_types` (array, optional)
  Payment types excluded from the payment process. The payment types included here will not be available at checkout.

  - `payment_methods.excluded_payment_types[].id` (string, optional)
  Payment type identifier.

  - `payment_methods.installments` (string, optional)
  Maximum number of credit card installments to be accepted.

- `preference_expired` (boolean, optional)
  Boolean value that determines whether a preference has already expired or is still active. If true, the preference has expired. If false, the preference is still active.

- `sandbox_init_point` (string, optional)
  Do not use this parameter. For integration testing, use init_point.

- `shipments` (object, optional)
  Shipments information.

  - `shipments.receiver_address` (object, optional)
  Shipping address.

  - `shipments.receiver_address.zip_code` (string, optional)
  Zip code.

  - `shipments.receiver_address.street_name` (string, optional)
  Street name.

  - `shipments.receiver_address.city_name` (string, optional)
  City name.

  - `shipments.receiver_address.state_name` (string, optional)
  State name.

  - `shipments.receiver_address.street_number` (number, optional)
  Street number.

  - `shipments.receiver_address.floor` (string, optional)
  Floor.

  - `shipments.receiver_address.apartment` (string, optional)
  Apartment.

  - `shipments.receiver_address.country_name` (string, optional)
  Country name.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | invalid_collector_id | collector_id invalid. |
| 400 | invalid_sponsor_id | sponsor_id is not an active user. |
| 400 | invalid_collector_email | collector is not collector_email owner. |
| 400 | invalid_operation_type | operation_type invalid. |
| 400 | invalid_expiration_date_to | expiration_date_to invalid. |
| 400 | invalid_expiration_date_from | expiration_date_from invalid. |
| 400 | invalid_items | unit_price invalid. |
| 400 | invalid_payer | payer email invalid. Max length 150. |
| 400 | invalid_back_urls | back_urls invalid. Wrong format. |
| 400 | invalid_payment_methods | installments invalid. Should be a number between 1 and 36. |
| 400 | invalid_marketplace_fee | marketplace_fee must not be greater than total amount. |
| 400 | invalid_id | preference_id not found. |
| 400 | invalid_access_token | access denied. |
| 400 | invalid_shipments | Invalid total amount, with me2 it cannot be lesser than <limit>. |

## Request example

### cURL

```bash
curl -X GET \
  'https://api.mercadopago.com/checkout/preferences/{id}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

### Node.js

```javascript
const client = new MercadoPago({ accessToken: "access_token" });
const preference = new Preference(client);
const response = await preference.get({ preferenceId: "id" });
```

### PHP

```php
<?php
MercadoPagoConfig::setAccessToken("ACCESS_TOKEN");
$client = new PreferenceClient();
$preference = $client->get("id");
echo implode($preference);
?>

```

### Python

```python
import mercadopago

sdk = mercadopago.SDK("PROD_ACCESS_TOKEN")

preference_response = sdk.preference().get("id")
preference = preference_response["response"]
```

### Java

```java
MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");
PreferenceClient client = new PreferenceClient();

Preference preference = client.get("id");
```

### .Net

```csharp
MercadoPagoConfig.AccessToken = "PROD_ACCESS_TOKEN";
PreferenceClient client = new PreferenceClient();
Preference preference = await client.GetAsync("id");
```

### Ruby

```text
sdk = MercadoPago::Client.new('ACCES_TOKEN');
preference_response = sdk.preference.get('id');
preference = preference_response[:response];
```

## Response example

```json
{
  "additional_info": "string",
  "auto_return": "approved",
  "back_urls": {
  "failure": "string",
  "pending": "string",
  "success": "string"
  },
  "client_id": 6295877106812064,
  "collector_id": 202809963,
  "date_created": "2022-11-17T09:37:52.000-04:00",
  "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",
  "id": "202809963-a2201f8d-11cb-443f-adf6-de5a42eed67d",
  "init_point": "https://www.mercadopago.com/mla/checkout/start?pref_id=202809963-a2201f8d-11cb-443f-adf6-de5a42eed67d",
  "items": [
  {
  "id": "item-ID-1234",
  "currency_id": "ARS",
  "title": "Practical Granite Shirt",
  "picture_url": "https://placehold.it/350x150",
  "description": "This is my description",
  "category_id": "string",
  "quantity": 2,
  "unit_price": "24.50",
  "fiscal_data": "sat",
  "dimensions": "unit"
  }
  ],
  "marketplace": "MP-MKT-6295877106812064",
  "marketplace_fee": 0,
  "notification_url": "string",
  "statement_descriptor": "MERCADOPAGO",
  "operation_type": "regular_payment",
  "payer": {
  "phone": {
  "area_code": "string",
  "number": "2323-5555"
  },
  "address": {
  "zip_code": "C1264AAK",
  "street_name": "Marjory Stream",
  "street_number": 941
  },
  "email": "test@testuser.com",
  "identification": {
  "number": "12345678",
  "type": "DNI"
  },
  "name": "string",
  "surname": "string",
  "date_created": "string"
  },
  "payment_methods": {
  "excluded_payment_methods": [
  {
  "id": "string"
  }
  ],
  "default_installments": "string",
  "default_payment_method_id": "string",
  "excluded_payment_types": [
  {
  "id": "string"
  }
  ],
  "installments": "string"
  },
  "preference_expired": true,
  "sandbox_init_point": "https://sandbox.mercadopago.com/mla/checkout/pay?pref_id=202809963-a2201f8d-11cb-443f-adf6-de5a42eed67d",
  "shipments": {
  "receiver_address": {
  "zip_code": "string",
  "street_name": "string",
  "city_name": "string",
  "state_name": "string",
  "street_number": 0,
  "floor": "string",
  "apartment": "string",
  "country_name": "string"
  }
  }
}
```