Create preference
POST
Products that use it:
Request's parameters
BODY
items
Items information.array
REQUIRED
payer
Buyer´s information, such as name, last name, e-mail, phone, personal identification, address, and registration date.object
payment_methods
All configuration related to payments methods, such as excluded payment methods, excluded payment types, default payment method, and installments.object
shipments
Shipments information.object
Response parameters
collector_id
Unique ID used to identify the collector. It is the same as the Cust ID.number
operation_type
Operation data_type.String
regular_payment: Normal payment.
money_transfer: Money request.
items
Items information.array
payer
Buyer information, such as name, last name, e-mail, phone, personal identification, address, and registration date.object
Errors
400Error
collector_does_not_comply_with_current_regulation
identity validation required.
invalid_collector_id
collector_id invalid.
invalid_sponsor_id
sponsor_id is not an active user.
invalid_collector_email
collector is not collector_email owner.
invalid_operation_type
operation_type invalid.
invalid_expiration_date_to
expiration_date_to invalid.
invalid_date
invalid date of expiration.
invalid_expiration_date_from
expiration_date_from invalid.
invalid_items
unit_price invalid.
invalid_back_urls
back_urls invalid. Wrong format.
invalid_payment_methods
installments invalid. Should be a number between 1 and 36.
invalid_marketplace_fee
marketplace_fee must not be greater than total amount.
invalid_id
preference_id not found.
invalid_access_token
access denied.
invalid_shipments
invalid type (<type>) for field shipments.cost.
invalid_binary_mode
binary_mode must be boolean.
sponsor_id site must be the same as collector_id
The sponsor_id site must be the same as the collector_id site.
Request
curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer TEST-2151*********762-03031*********750b665b7*********4dac477-1*********' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "BRL",
"unit_price": 10
}
],
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"phone": {
"area_code": "11",
"number": 988888888
},
"identification": {
"type": "CPF",
"number": "19119119100"
},
"address": {
"zip_code": "06233200",
"street_name": "Example Street",
"street_number": 123
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "amex",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"default_shipping_method": null,
"free_methods": [
{
"id": null
}
],
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "72549555",
"street_name": "Street address test",
"city_name": "São Paulo",
"state_name": "São Paulo",
"street_number": 100,
"country_name": "Brazil"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
],
"metadata": {}
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer TEST-2151*********762-03031*********750b665b7*********4dac477-1*********' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "BRL",
"unit_price": 10
}
],
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"phone": {
"area_code": "11",
"number": 988888888
},
"identification": {
"type": "CPF",
"number": "19119119100"
},
"address": {
"zip_code": "06233200",
"street_name": "Example Street",
"street_number": 123
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "amex",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"default_shipping_method": null,
"free_methods": [
{
"id": null
}
],
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "72549555",
"street_name": "Street address test",
"city_name": "São Paulo",
"state_name": "São Paulo",
"street_number": 100,
"country_name": "Brazil"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
],
"metadata": {}
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer TEST-2151*********762-03031*********750b665b7*********4dac477-1*********' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "BRL",
"unit_price": 10
}
],
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"phone": {
"area_code": "11",
"number": 988888888
},
"identification": {
"type": "CPF",
"number": "19119119100"
},
"address": {
"zip_code": "06233200",
"street_name": "Example Street",
"street_number": 123
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "amex",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"default_shipping_method": null,
"free_methods": [
{
"id": null
}
],
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "72549555",
"street_name": "Street address test",
"city_name": "São Paulo",
"state_name": "São Paulo",
"street_number": 100,
"country_name": "Brazil"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
],
"metadata": {}
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer TEST-2151*********762-03031*********750b665b7*********4dac477-1*********' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "BRL",
"unit_price": 10
}
],
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"phone": {
"area_code": "11",
"number": 988888888
},
"identification": {
"type": "CPF",
"number": "19119119100"
},
"address": {
"zip_code": "06233200",
"street_name": "Example Street",
"street_number": 123
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "amex",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"default_shipping_method": null,
"free_methods": [
{
"id": null
}
],
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "72549555",
"street_name": "Street address test",
"city_name": "São Paulo",
"state_name": "São Paulo",
"street_number": 100,
"country_name": "Brazil"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
],
"metadata": {}
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer TEST-2151*********762-03031*********750b665b7*********4dac477-1*********' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "BRL",
"unit_price": 10
}
],
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"phone": {
"area_code": "11",
"number": 988888888
},
"identification": {
"type": "CPF",
"number": "19119119100"
},
"address": {
"zip_code": "06233200",
"street_name": "Example Street",
"street_number": 123
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "amex",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"default_shipping_method": null,
"free_methods": [
{
"id": null
}
],
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "72549555",
"street_name": "Street address test",
"city_name": "São Paulo",
"state_name": "São Paulo",
"street_number": 100,
"country_name": "Brazil"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
],
"metadata": {}
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer TEST-2151*********762-03031*********750b665b7*********4dac477-1*********' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "BRL",
"unit_price": 10
}
],
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"phone": {
"area_code": "11",
"number": 988888888
},
"identification": {
"type": "CPF",
"number": "19119119100"
},
"address": {
"zip_code": "06233200",
"street_name": "Example Street",
"street_number": 123
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "amex",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"default_shipping_method": null,
"free_methods": [
{
"id": null
}
],
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "72549555",
"street_name": "Street address test",
"city_name": "São Paulo",
"state_name": "São Paulo",
"street_number": 100,
"country_name": "Brazil"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
],
"metadata": {}
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer TEST-2151*********762-03031*********750b665b7*********4dac477-1*********' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "BRL",
"unit_price": 10
}
],
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"phone": {
"area_code": "11",
"number": 988888888
},
"identification": {
"type": "CPF",
"number": "19119119100"
},
"address": {
"zip_code": "06233200",
"street_name": "Example Street",
"street_number": 123
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "amex",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"default_shipping_method": null,
"free_methods": [
{
"id": null
}
],
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "72549555",
"street_name": "Street address test",
"city_name": "São Paulo",
"state_name": "São Paulo",
"street_number": 100,
"country_name": "Brazil"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
],
"metadata": {}
}'Sample answer
{
"collector_id": 202809963,
"items": [
{
"title": "Dummy Item",
"description": "Multicolor Item",
"currency_id": "$",
"quantity": 1,
"unit_price": 10
}
],
"payer": {
"phone": {},
"identification": {},
"address": {}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"auto_return": "approved",
"payment_methods": {
"excluded_payment_methods": [
{}
],
"excluded_payment_types": [
{}
]
},
"client_id": 6295877106812064,
"marketplace": "MP-MKT-6295877106812064",
"marketplace_fee": 0,
"shipments": {
"receiver_address": {}
},
"notification_url": "https://notificationurl.com",
"statement_descriptor": "MERCADOPAGO",
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"date_created": "2022-11-17T10:37:52.000-05:00",
"id": "202809963-920c288b-4ebb-40be-966f-700250fa5370",
"init_point": "https://www.mercadopago.com/mla/checkout/start?pref_id=202809963-920c288b-4ebb-40be-966f-700250fa5370",
"sandbox_init_point": "https://sandbox.mercadopago.com/mla/checkout/pay?pref_id=202809963-920c288b-4ebb-40be-966f-700250fa5370",
"metadata": {}
}