Submit one of your items to a promotion campaign with the offered deal price — this is a REAL write operation: if Meli approves, the item starts being sold at the promotional price for the campaign duration. Confirm the price with the user before calling. Flow: get_promotions (find a 'candidate' campaign) → add_item_to_promotion with the deal_price within the campaign's allowed range. Returns the submission result with item id and status.

Post a public answer to a buyer's pre-sale question. The answer is visible to everyone viewing the listing and CANNOT be edited or deleted afterwards — confirm the exact text with the user before sending. Get the question_id from get_questions (typically with status='UNANSWERED'). Returns the answer id, text, status and creation date.

Get the current Mercado Livre exchange rate between two currencies (e.g. USD → BRL). Useful for cross-border pricing or comparing prices across Meli sites. Returns the conversion ratio and both currency codes.

Opt one of your EXISTING listings into catalog competition by linking it to a catalog product — this is a real write operation. The listing keeps its identity but starts competing for the buy box under catalog rules: display and sales conditions change (e.g. free-shipping and price rules may differ from a standalone listing). Confirm with the user before calling. Flow: search_catalog → get_catalog_product (check the winner's price) → create_catalog_listing. The item must belong to the authenticated seller and match the catalog product. Returns the linked item id, status and permalink.

Create and PUBLISH a new listing on Mercado Livre — this is a real write operation: the item becomes public (immediately or per account settings) and selling fees apply once it sells. Confirm the details with the user before calling. Recommended flow: (1) predict_category with the title to get category_id; (2) get_category_attributes on that category and fill every attribute marked required via the attributes parameter; (3) optionally get_listing_types/get_listing_prices to choose the listing type and estimate fees; (4) call create_item. The title is limited to 60 characters. If Meli rejects the payload with a validation error, the full error body is returned — read it, fix the offending fields (usually missing required attributes) and retry. Returns the created item id, status and permalink.

Get performance metrics of a Mercado Ads campaign over a date range (defaults to the last 30 days): impressions, clicks, CTR, cost, attributed sales and ACOS when present. Use this to evaluate ad spend efficiency — a high ACOS means advertising costs eat a large share of the revenue it generates. Get campaign ids from get_ads_campaigns. Requires the advertising scope; scope errors are surfaced clearly. Date format: YYYY-MM-DD.

List the seller's Mercado Ads (Product Ads) campaigns. Use this for advertising questions: which campaigns exist, their status, daily budget and bidding strategy. Gotcha: this requires the advertising scope granted to the app and an active ads account — if either is missing, Meli answers with a scope/permission error, which is surfaced clearly so you know the feature isn't available. Get campaign ids here, then check performance with get_ads_campaign_metrics. Returns a compact list with campaign id, name, status, budget and strategy.

Get full details of a catalog product, including who is currently winning the buy box (buy_box_winner: price and seller id). Use this after search_catalog to study the competition before linking your listing with create_catalog_listing — the winner's price is the reference your listing must beat (along with reputation and shipping) to take the buy box. Returns name, attributes, picture URLs, main features and the buy box winner when present.

Get details of a category: its name, full path from the root, child categories (to keep drilling down the tree) and the listing settings that apply to it — including constraints relevant BEFORE create_item such as max pictures per item and max description length. A category with no children is a leaf and can be used as category_id in create_item; then call get_category_attributes for its mandatory attributes.

Get the attributes defined for a Mercado Livre category. Call this AFTER picking a category with predict_category and BEFORE create_item, to learn which attributes are mandatory (required=true) and what values are allowed. Every attribute flagged as required MUST be included in create_item's attributes parameter or the publication will be rejected with a validation error. Returns id, name, value_type (string/number/boolean/list/...), required flag, and allowed values (id + name) when the attribute is a closed list.

Get the full details of a single claim (reclamação), including its type, status, stage, reason, related order id, the parties involved (complainant = buyer, respondent = seller), the resolution when the claim is closed, and the recent messages in the claim thread. Use this after get_claims to understand a specific claim before replying with send_claim_message. If the messages endpoint is unavailable, messages are simply omitted — the rest of the detail is still returned.

Search the authenticated seller's claims (reclamações) — buyer complaints opened against sales. Open claims hurt seller reputation and have response deadlines, so use this to find claims needing attention (e.g. status 'opened'). Optional status filter and date range (ISO 8601); results are paginated with limit/offset. Returns a compact list with claim id, type (e.g. 'claim', 'return'), status, stage (e.g. 'claim', 'mediation'), resource_id (the related order id), reason id and creation date. Call get_claim_detail on a claim id for the full picture.

List the seller's stock stored at Mercado Livre fulfillment centers (Full), with available and non-sellable (e.g. damaged) quantities. Use this for inventory questions about Full — for regular (seller-shipped) stock use get_my_items/get_item instead. Gotcha: this only works for accounts enrolled in Full; otherwise Meli answers with an error, which is surfaced clearly.

Get full details of a single Mercado Livre listing by its item id. The id must be the complete id including the site prefix, e.g. 'MLB123456789' — bare numbers do not work. Use this to inspect a specific listing (yours or a competitor's) in depth: stock, sales count, pictures and attributes. For bulk listing of the seller's own items use get_my_items instead. Returns title, price, currency, available_quantity, sold_quantity, condition, status (active/paused/closed/...), permalink, picture URLs and attributes (id/name/value).

Get the number of page visits per listing in a date range (defaults to the last 30 days when no dates are given). Use this to measure listing traffic — a powerful combo is get_my_items + get_item_visits to find listings with many views but few or no sales (a sign the price, pictures or listing type may need work). Accepts up to 50 item ids at once; returns one entry per item id with the total visits in the range.

Estimate the selling fees for publishing an item at a given price, optionally for a specific category and listing type. Use this BEFORE create_item so the seller knows the commission cost of each exposure plan (Clássica vs Premium) before committing. Returns one entry per listing type with the sale fee percentage, fee amount and related flags for the given price.

List the listing types (exposure plans) available on the configured site, e.g. 'gold_special' (Clássica) and 'gold_pro' (Premium). Each type has different fees and exposure; higher tiers usually charge more commission but boost visibility. Call this (optionally together with get_listing_prices) before create_item to choose the listing_type_id. Returns ids and names.

Get the seller's Mercado Shop info (id, name, URL, status) if the account has one. Mercado Shops is an optional storefront feature — accounts without a shop get a graceful 'no shop' response instead of a hard error. Use this when the user asks about their store page or wants the shop URL.

List the authenticated seller's own listings, with optional status filter. Use this whenever the user asks about 'my listings/ads/products' — for marketplace-wide search use search_products instead. Status filter values: 'active' (published and visible), 'paused' (temporarily hidden), 'closed' (finished; items with sales usually end here). Results are paginated via limit/offset; each entry is hydrated with id, title, status, price, currency and permalink. Requires authentication.

Read the post-sale message conversation with the buyer of a specific order. Use this to see what the buyer asked after the purchase (delivery questions, invoice requests, etc.). The pack id in the messaging API equals the order id. Returns each message with sender/recipient (user id + role, e.g. 'buyer'/'seller'), text, date (ISO 8601) and whether it was read. To reply, use send_message with the same order id.

List the authenticated seller's orders (sales), newest first (sort=date_desc). Use this for questions about recent sales, revenue, or what a specific buyer purchased. The optional status filter accepts Mercado Livre order statuses such as 'confirmed', 'payment_required', 'payment_in_process', 'paid', 'shipped', 'delivered' and 'cancelled'. Each order includes id, creation date (ISO 8601), status, total amount, currency, buyer nickname, and line items with item id, title, quantity and unit price. Paginated via limit/offset. Requires authentication.

Get Mercado Livre's competitive price suggestion for one of your listings — the price Meli estimates would make the listing more competitive, based on comparable sales. Use it when the user asks whether a listing is priced right or wants to undercut the competition. Gotcha: not every listing has a suggestion (insufficient data); in that case the endpoint returns partial data and whatever comes back is surfaced as-is. Returns current price, suggested price and the basis of the suggestion when present.

List the items already participating in a specific promotion campaign, with their promotional price, original price and status. Use this to check which of your items are in a campaign (and at what price) after adding them with add_item_to_promotion, or to audit active discounts. Get the promotion_id from get_promotions. Paginated with limit/offset.

List the promotions/campaigns Mercado Livre offers to the authenticated seller (daily deals, lightning deals, etc.) — both campaigns you can join (status 'candidate') and ones already running ('started'). Use this to discover discount opportunities, then inspect participants with get_promotion_items or join with add_item_to_promotion. May legitimately return an empty list when there are no active campaigns for the account. Returns a compact list with id, type, status, title and start/finish dates, paginated with limit/offset.

List pre-sale questions buyers asked on the authenticated seller's listings, newest first. Use status='UNANSWERED' to find questions still waiting for a reply — that is the most common use case, since unanswered questions hurt conversion. Other status values: 'ANSWERED', 'DELETED', 'BANNED', 'DISABLED'. Use item_id to restrict to one listing. Each question comes back with its id (needed by answer_question), text, item id, status, creation date (ISO 8601), and the answer (text + date) when one exists. Requires authentication.

List the authenticated seller's product returns (devoluções) — items buyers sent back, usually linked to a claim. Use this to track return requests and their statuses; call get_claim_detail on the linked claim id for the full context and message thread. Returns a compact list with return id, claim id, order id, status and creation date, paginated with limit/offset. Accounts without returns may yield an API error — it is surfaced gracefully instead of crashing.

Get a seller's reputation profile on Mercado Livre — the authenticated account by default, or any seller by user_id (public data). Use this to check the seller's reputation thermometer and service metrics. The level_id is Meli's color scale: red (1_red) is worst, then orange/yellow/light_green, up to green (5_green) — plus Mercado Líder tiers in power_seller_status (e.g. 'silver', 'gold', 'platinum') for top sellers. Metrics include the rates of claims, delayed handling time and cancellations over the last period; keeping these low is what maintains a green reputation. Returns nickname, registration date, transaction totals (total/completed/canceled) and each metric with its rate and value.

Get the shipping details of a sale: status, substatus, tracking number, dates (ISO 8601), receiver address, shipped items and logistic type (e.g. 'me2', 'flex', 'self_service'). Shipment ids come from orders: each order returned by get_orders has a shipping id (order.shipping.id) — if you only have an order id, call get_orders first to find the shipment id. Status values include 'pending', 'ready_to_ship', 'shipped', 'delivered' and 'cancelled'. Use get_shipment_label to download the printable label for the shipment.

Download the Mercado Envios shipping label for a shipment and save it to a local file. Returns the absolute file path and size in bytes so the user can open/print it. The label comes back as PDF (default) or ZPL2 for thermal printers. Gotchas: the label only exists after the shipment is 'ready_to_ship', and some logistic types (e.g. flex / self-service) do not have a printable label — in those cases Meli returns an error, which is surfaced as-is. Shipment ids come from orders (order.shipping.id); call get_orders first if you only have an order id.

List the top-level categories of the configured site (MLB by default). This is the entry point for browsing the category tree: pick a category here, then drill down with get_category to reach a leaf category usable in create_item. For a title-driven shortcut to the right leaf category, predict_category is usually faster. Returns a list of {id, name}.

Get the trending search terms on the marketplace (top searches buyers are making right now). Great for product research and demand discovery; pass a category_id to see niche trends within a specific category (find ids with get_site_categories or predict_category). Returns keyword + URL for each trend, trimmed to the requested limit.

List the seller's registered warehouses (multi-origin stock locations / depósitos) with their ids, descriptions and addresses. Useful for accounts shipping from multiple addresses and for setting up shipping options per origin. Accounts without registered warehouses get an empty list or a clear API error.

Manage the seller's questions blacklist. 'list' shows the blocked users; 'block' prevents a user from asking questions on your listings; 'unblock' reverses it. Use 'block' only for abusive users — note this ONLY blocks new questions from that user; they can still buy from you, and blocking/unblocking is a real change to the account, so confirm with the user first. Get user ids from buyers' questions (get_questions) or orders.

Predict the best Mercado Livre category for a product title. ALWAYS call this BEFORE create_item: create_item requires a category_id, and publishing in the wrong category hurts visibility and can be rejected. Pass the product title you intend to publish and pick the top prediction. After choosing a category, call get_category_attributes to discover which attributes are mandatory for that category. Returns a list of predicted categories with id, name and full path (e.g. 'Celulares e Telefones > Celulares e Smartphones').

Search Mercado Livre's product catalog. Catalog products are shared listings where multiple sellers compete for the buy box on price and reputation — opt-ing into catalog can bring much more traffic than a standalone listing. Use this to find the catalog_product_id for a product you sell, then inspect it with get_catalog_product and link your listing with create_catalog_listing. Returns a compact list with product id, name, thumbnail and main attributes, paginated with limit/offset.

Search public listings on Mercado Livre for the configured site (ML_SITE_ID, default MLB = Brazil). Use this to research competitors, market prices, or find item/category ids by keyword — it searches the whole marketplace, NOT the seller's own listings (use get_my_items for that). Results are paginated: use limit (max 50) and offset to page through. Returns total count plus a compact list with id, title, price, currency, permalink, thumbnail, condition (new/used) and free-shipping flag.

Send a message inside a claim (reclamação) thread as the seller. This is a REAL message visible to the buyer AND to Mercado Livre's mediation team — it becomes part of the claim record, so confirm the exact text with the user before sending. The same moderation rules as buyer messaging apply: no contact information, links, phone numbers or e-mails, under risk of sanctions. Use get_claim_detail first to read the thread context. Returns the created message id and date.

Send a post-sale message to the buyer of a specific order — this is a REAL message delivered to the buyer, so confirm the exact text with the user before sending. Only for post-sale communication tied to an order. Important Mercado Livre moderation rules: messages are moderated and must NOT contain contact information — no links, phone numbers, e-mails or social media handles; violations can lead to sanctions on the seller's account, up to suspension. Text is limited to 350 characters. Use get_order_messages first to read the conversation context. Returns the sent message id, moderation status and date.

Update mutable fields of an existing listing owned by the authenticated seller: price, stock (available_quantity), title or video. Use this for price changes and stock adjustments; to change visibility (pause/activate/close) use update_item_status instead. Only the provided fields are sent. Gotcha: the title can only be changed while the item has no sales — once units are sold, Meli rejects title updates. Returns the updated item id, price, available_quantity and status.

Change the visibility status of a listing: 'pause' temporarily hides it (reversible), 'activate' re-publishes a paused item, and 'close' finishes the listing. WARNING: closing is effectively irreversible for items that had sales — a closed item cannot be reactivated; a new listing would have to be created. Because of that, action='close' is refused unless confirm=true is passed explicitly. Always confirm with the user before closing. Paused items keep their history and can be reactivated at any time with 'activate'. Returns the item id and its new status.

Upload a picture to the seller's Mercado Livre account and get back a picture id. Provide exactly ONE of: url (a public image URL that Meli will download) or file_path (a local image file, uploaded as multipart). Use the returned id in create_item's pictures when the images are local files; for images already hosted at a public URL, passing the URL directly to create_item also works. Returns the picture id, source URL and size variations.

Upload a product video from a local file to the seller's Mercado Livre account and get back a video_id. Pass that video_id to create_item or update_item to attach the video to a listing. Only local files are supported (mp4, mov, avi, mkv, webm). Meli enforces size/duration limits on product videos — very large or long files are rejected by the API, and in that case the API error is returned as-is so you can adjust the file and retry. Returns the video_id plus basic response info (id, max size/quality when present).