Mercado Libre Ads

Mercado Libre has a public advertising API for advertiser lookup, campaign management, and reporting. Its developer application flow includes an Advertising permission for Product Ads and Display Ads. See Create application.

The public Ads documentation checked does not publish a browser tag, app SDK, or server-side conversion-event ingestion API. Treat Mercado Libre as a reporting and campaign-management adapter. Do not create a /conversions, /events, or /pixel route from analogy. See Product Ads and Display Ads.

Use ad-conversion-hub for the canonical event envelope, consent gate, identity rules, retry policy, and adapter contract. Pair it with ad-experiments for one-audience tests, seed sizing, PII-export authorization, and payment-provider truth.

Account and access

Mercado Libre uses OAuth 2.0 for access to private user resources. Its server-side authorization flow redirects the user to Mercado Libre, receives a code, then exchanges that code for an access token. The same guide documents a refresh_token issued alongside the access token, used to renew access without repeating the redirect flow. Access tokens expire; do not assume the token exchanged once during onboarding stays valid indefinitely. Confirm the current refresh endpoint, parameters, and token lifetimes at the cited guide before relying on them in production. See Authentication and Authorization.

Create an application in the Mercado Libre DevCenter. The application form requires a registered redirect URI beginning with https://. The application permission groups include Advertising, with Product Ads and Display Ads as connected resources. See Create application.

Product Ads has a seller activation route. The current Product Ads guide says to activate it from My profile → Advertising. It also lists eligibility requirements: yellow reputation or higher, at least 15 days of account age, minimum sales, and no overdue invoices. See Product Ads eligibility.

Display Ads is not documented as self-serve. Mercado Libre says that Display is enabled by Commercial Advisors. Guaranteed Display campaigns are contracted directly with a Mercado Libre agent, and the operations team manages them. See Display Ads access and campaign types.

Use MERCADOLIBRE_ADS_CLIENT_ID, MERCADOLIBRE_ADS_CLIENT_SECRET, MERCADOLIBRE_ADS_ACCESS_TOKEN, and MERCADOLIBRE_ADS_REFRESH_TOKEN for local OAuth configuration. Use MERCADOLIBRE_ADVERTISER_ID, MERCADOLIBRE_SITE_ID, and MERCADOLIBRE_ADS_PRODUCT for adapter state. These are local conventions; the documented product values are PADS and DISPLAY. See Product Ads and Display Ads.

Client-side tag or pixel

Mercado Libre's public Ads guides do not document a browser pixel, tag ID, mobile SDK, or CTV event SDK for off-site conversion collection. Do not add a script, pixel ID, cookie, or app event call to this adapter. See Product Ads and Display Ads.

Rule setup and event mapping

There is no public Mercado Libre Ads event mapping to configure. Product Ads reports sales and advertising metrics for promoted marketplace listings. Display Ads reports attributed sales and actions such as product-page views, add-to-cart, bookmarks, checkout, and leads. These are reporting fields, not an endpoint for uploading the hub's events. See Product Ads metrics and Display Ads metrics.

Do not dispatch these events to a guessed Mercado Libre endpoint. Keep the adapter's result skipped when no contracted vendor integration exists. The hub must not fail a payment or signup flow because Ads reporting is absent. See ad-conversion-hub.

Server-side conversions API

No public Mercado Libre Ads conversions API is documented in the official Ads guides checked. Those guides document advertiser lookup, campaign resources, ad resources, and metrics. They do not document a conversion-event POST operation, event schema, event timestamp field, identity field, or server-side deduplication field. See Product Ads and Display Ads.

Therefore, this adapter has no CAPI request. Do not send hashed email, phone, IP address, payment data, event_id, or a browser cookie to the Marketplace Ads API. Do not infer a conversion contract from the existence of the public campaign metrics API.

For managed Display campaigns, ask the Commercial Advisor for any contracted measurement or reporting specification. The public guide defines the advisor access route, but it does not publish a partner postback contract. See Display Ads access.

OAuth and advertiser validation

Mercado Libre documents bearer tokens in the Authorization header. The following advertiser lookup is a documented read operation. It confirms that the token can see the requested Ads product and returns advertiser_id and site_id. See Product Ads advertiser lookup and Display Ads advertiser lookup.

curl -sS \
  'https://api.mercadolibre.com/advertising/advertisers?product_id=PADS' \
  -H 'Authorization: Bearer <MERCADOLIBRE_ADS_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Api-Version: 1'

Use product_id=DISPLAY for Display Ads. The Display guide documents the same resource and the DISPLAY value. See Display advertiser lookup.

Treat a missing advertiser permission as an access failure. The Product Ads guide documents a 404 response with “No permissions found for user_id” when the product is not enabled. The Display guide directs the user to a Commercial Advisor for access. See Product Ads access errors and Display Ads access errors.

Product Ads campaign reporting

Use the current Product Ads campaign search resource. The guide says the campaign path must end in /search and uses api-version: 2. See Product Ads campaign search.

GET https://api.mercadolibre.com/marketplace/advertising/<SITE_ID>/advertisers/<ADVERTISER_ID>/product_ads/campaigns/search
Authorization: Bearer <MERCADOLIBRE_ADS_ACCESS_TOKEN>
api-version: 2

The documented query fields include limit, offset, date_from, date_to, metrics, and aggregation_type. Metrics include clicks, impressions, cost, CPC, CTR, attributed amounts and units, CVR, ROAS, and other campaign metrics. See Product Ads campaign metrics.

The Product Ads metrics guide allows a date range of up to 90 days. It says metrics update at 10:00 AM GMT-3 and only one aggregation_type may be requested at a time. See Product Ads metric limits.

Display Ads campaign reporting

Display campaign listing uses GET /advertising/advertisers/<ADVERTISER_ID>/display/campaigns with bearer authentication and Api-Version: 1. The guide documents sort_by and sort_order as optional parameters. It returns campaign ID, dates, advertiser ID, status, site, type, and goal fields. See Display campaign listing.

Campaign metrics use date_from and date_to in YYYY-MM-DD format:

GET https://api.mercadolibre.com/advertising/advertisers/<ADVERTISER_ID>/display/campaigns/<CAMPAIGN_ID>/metrics?date_from=<YYYY-MM-DD>&date_to=<YYYY-MM-DD>
Authorization: Bearer <MERCADOLIBRE_ADS_ACCESS_TOKEN>
Content-Type: application/json
Api-Version: 1

The Display guide limits metric queries to 90 days. Its response documents impressions, clicks, views, reach, spend, CPM, CPC, frequency, and event-time and touch-point attribution metrics. See Display campaign metrics.

Identity and consent

The public Ads operations documented here authenticate the advertiser with an OAuth bearer token. They do not publish customer-identity fields for a conversion upload. Do not add identity fields to an Ads request. See Mercado Libre OAuth and Product Ads.

The hub owns consent and identity handling. Require the hub's measurement consent before first-party analytics. Require its ad-user-data consent before any ad-user identifier would be sent to a separately documented partner. See ad-conversion-hub.

Do not hash identifiers for Mercado Libre Ads. The official Ads guides checked do not specify a customer-list upload, hash algorithm, identity field, or matching rule. Adding SHA-256 here would invent a vendor contract. See Product Ads and Display Ads.

Click ID and first-party cookie

The official Product Ads and Display Ads guides checked do not document a Mercado Libre click-ID query parameter, cookie name, browser storage rule, or attribution lifetime. Do not create mercadolibre_click_id, meli_click_id, or a guessed cookie. See Product Ads and Display Ads.

If a Commercial Advisor supplies a campaign-link field in a written campaign specification, keep it as a partner-specific field. Capture it only with the hub consent gate. Do not treat that field as a public Mercado Libre API parameter. See Display Ads managed access and ad-conversion-hub.

Deduplication

Mercado Libre's public Ads guides do not document event-level deduplication. They publish campaign, ad, line-item, and metric identifiers instead. Do not send event_id, eventId, transaction IDs, or replay keys as guessed API fields. See Product Ads identifiers and Display Ads identifiers.

Deduplicate the advertiser's own first-party events in the hub and payment system. Keep the canonical event ID for internal reconciliation. Do not claim that Mercado Libre deduplicated an event unless a contracted integration gives that behavior in writing. See ad-conversion-hub.

Verification

Use three proofs:

1. Access proof: run the documented advertiser lookup for the intended product. Record the redacted response, advertiser_id, and site_id. See advertiser lookup.
2. Platform proof: query the documented campaign and metrics resource for the selected product. Check dates, campaign status, spend, clicks, and platform-attributed sales or actions. See Product Ads metrics and Display Ads metrics.
3. Business proof: reconcile platform-reported sales with succeeded orders, payment-provider truth, refunds, and campaign attribution rules. A metrics response does not prove that an off-site payment was uploaded.

For Display Ads, record the reporting date range and whether the report uses event-time or touch-point attribution. The Display guide documents both views. See Display attribution metrics.

Common pitfalls and security

• Do not invent /conversions, /events, /pixel, or a postback payload. Product Ads
• Do not call legacy Product Ads paths after the current guide's migration. Product Ads
• Do not confuse campaign metrics with an off-site conversions API. Display Ads
• Do not send customer identifiers or payment data to the documented Ads reads. Product Ads
• Do not treat a valid OAuth token as proof of advertiser permission. Product Ads
• Do not treat a 200 metrics response as payment reconciliation.
• Do not claim click attribution without a documented campaign field. Display Ads
• Do not claim Mercado Libre deduplicated a first-party event. Product Ads

Keep MERCADOLIBRE_ADS_CLIENT_SECRET, MERCADOLIBRE_ADS_ACCESS_TOKEN, and MERCADOLIBRE_ADS_REFRESH_TOKEN server-side. Never place them in browser bundles, URLs, logs, screenshots, or commits. Mercado Libre documents the client secret as secret and bearer authentication in the request header. See Create application and Authentication and Authorization.

Use HTTPS for the OAuth redirect URI. See Create application. Redact credentials from access logs. Apply the hub consent gate before first-party measurement. Keep the adapter a logged no-op when the Ads product or managed contract is unavailable.

Official sources checked (2026-08-30)

• Create application and Advertising permission
• Authentication and Authorization
• Product Ads
• Display Ads
• Create an application