Create preference with the Mercado Pago API
Creates a payment preference and returns it with id and init_point, the Checkout Pro link where the buyer pays by Pix, card, boleto or Mercado Pago balance. Each item needs id, title, quantity and unit_price. Share init_point with the buyer.
- Identifier
- mercado_pago_create_preference
The request
POST https://connect.reportei.com/api/tools/mercado_pago_create_preference/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json
{
"customer_toolkit": "<connection UUID>",
"arguments": {
"items": []
}
}Your system sends your customer's connection id and the tool arguments. The headers are the same as the rest of the Connect API: your product's token and your customer's token.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| items | array | Yes | Products or services of the payment. The total is the sum of quantity times unit_price. |
| payer | object | No | Buyer data that fills in the checkout. |
| payment_methods | object | No | Payment options of the checkout. |
| back_urls | object | No | Pages of the seller's site the buyer returns to after the checkout. |
| auto_return | string | No | approved sends the buyer to back_urls.success right after an approved card payment. Needs back_urls.success.Values: approved, all |
| statement_descriptor | string | No | Text on the buyer's card statement, up to 13 characters. |
| external_reference | string | No | Your own code for this sale. Its payments carry it, so Search payments finds them by it. |
| expires | boolean | No | true makes the link valid only between expiration_date_from and expiration_date_to. |
| expiration_date_from | string | No | Start of the validity, like 2026-11-01T00:00:00.000-03:00. |
| expiration_date_to | string | No | End of the validity, in the same format as expiration_date_from. |
| metadata | object | No | Free key-value data saved with the preference. |
Supported connections
Your customer connects their Mercado Pago account once, with one of the modes below. The same connection serves every tool of the toolkit.
API key
Your customer pastes the app's key on a Connect screen, or your system sends the key with POST /api/customer-toolkits, with no screen.
The response
On success, Connect preserves the app's response status and body. HTTP errors returned by the app use the {error, api_error} envelope; authentication or validation can fail before execution. The X-Toolkit-Execution-Id header identifies the recorded execution, available at GET /api/tools/executions/{uuid}.
Ready for AI agents
This tool's input is a JSON Schema, available at GET /api/tools/mercado_pago_create_preference. It becomes your agent's tool definition with no conversion.
Other Mercado Pago tools
- Search paymentsGETSearches the payments the account received in the last 12 months; without dates, the ones created in the last 3 months. The response has results and paging with total, limit and offset: raise offset by limit to read the next page.
- Get paymentGETReturns one payment: status and status_detail, transaction_amount, transaction_details with the net amount received, payment method and type, installments, payer and dates.
- Update paymentPUTCancels a payment that is still pending, in_process or authorized, like an unpaid boleto or Pix, or changes the expiration date of a pending one. An approved payment is not cancelled here: it is refunded in Mercado Pago.
- Search preferencesGETLists the payment preferences, the checkout links, created in the last 90 days. The response has elements, next_offset and total. The link itself, init_point, comes from Get preference.
- Get preferenceGETReturns a payment preference with its items, payer, payment settings, validity and init_point, the checkout link to send to the buyer. Works for preferences of any age.
- Update preferencePUTChanges the fields sent on a payment preference, like items, prices, buyer data or validity. The id and the init_point link stay the same.
- Search subscription plansGETSearches the subscription plans of the account. Each plan in results has id, reason, auto_recurring, status, subscribed (how many subscribers) and init_point, the link where a buyer subscribes. Page with offset and limit; paging has the total.
- Create subscription planPOSTCreates a subscription plan and returns it with id and init_point, the link where buyers subscribe with their card. Needs reason, back_url and auto_recurring with frequency, frequency_type and currency_id.
Toolkits in the same category
See all 100 toolkitsSee Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.

Conta Azul