> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mercado Livre as a data source
> Bring data from Mercado Livre Marketplace and Advertising to Nekt.
Mercado Livre is Latin America's largest e-commerce and fintech platform, operating across Brazil, Argentina, Mexico, and other countries in the region. This connector provides access to your seller account data including orders (with shipment details, fiscal invoices, and buyer billing profiles where available), catalog listings via a scan-based item list plus full item payloads, advertising campaigns (Product Ads and Brand Ads), and item-level performance metrics such as visits, quality scores, and buyer experience ratings.
## Configuring Mercado Livre as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Mercado Livre option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need to create a Mercado Livre application and generate OAuth credentials to connect your seller account to Nekt.
The following configurations are required:
* **Client ID**: The application ID from your Mercado Livre OAuth app.
* **Client Secret**: The secret key from your Mercado Livre OAuth app.
* **Refresh Token**: A refresh token obtained through the Mercado Livre OAuth flow, from a seller account with enough permissions to access the data.
* **Metrics Granularity**: The time granularity for item-level metrics (visits, ad performance, etc.). Available options:
* `day` - Daily metrics (most granular, but slower extraction)
* `week` - Weekly metrics
* `month` - Monthly metrics (default, fastest extraction)
* **Start Date**: The earliest date from which records will be synced.
The more granular the metrics setting, the longer the extraction will take, as more API calls are required.
Follow these steps to create an OAuth application in Mercado Livre and obtain the credentials needed for Nekt:
1. Go to [Mercado Livre Developer Center](https://developers.mercadolivre.com.br/devcenter) (use the appropriate country link for your account)
2. Log in with your Mercado Livre seller account
3. Click **Create new application**
4. Fill in the application details:
* **Application name**: e.g., "Nekt Data Integration"
* **Short description**: e.g., "Data extraction for analytics"
* **Redirect URI**: `https://developers.google.com/oauthplayground`
5. Under **Scopes**, select:
* `read` — Read access to your account data
* `offline_access` — Required to generate a refresh token
6. Click **Create application**
7. Copy your **App ID** (this is your Client ID) and **Secret Key** (this is your Client Secret)
Keep your Client Secret secure. Never expose it in frontend code or public repositories.
Click the link below to open Google OAuth Playground pre-configured for Mercado Livre:
[**Open Mercado Livre OAuth Playground →**](https://developers.google.com/oauthplayground/#step1\&url=https%3A%2F%2F\&content_type=application%2Fjson\&http_method=GET\&useDefaultOauthCred=unchecked\&oauthEndpointSelect=Custom\&oauthAuthEndpointValue=https%3A%2F%2Fauth.mercadolivre.com.br%2Fauthorization\&oauthTokenEndpointValue=https%3A%2F%2Fapi.mercadolibre.com%2Foauth%2Ftoken\&oauthClientId=ML_CLIENT_ID\&oauthClientSecret=ML_CLIENT_SECRET\&includeCredentials=checked\&accessTokenType=bearer\&autoRefreshToken=unchecked\&accessType=offline\&prompt=consent\&response_type=code\&wrapLines=on)
In the OAuth Playground, click the **gear icon (⚙️)** on the right side to open "OAuth 2.0 configuration" and update these values:
1. Replace `ML_CLIENT_ID` with your **App ID** (Client ID)
2. Replace `ML_CLIENT_SECRET` with your **Secret Key** (Client Secret)
3. Verify the endpoints:
* **OAuth authorization endpoint**: `https://auth.mercadolivre.com.br/authorization`
* **OAuth token endpoint**: `https://api.mercadolibre.com/oauth/token`
If your account is from **Argentina**, use `https://auth.mercadolibre.com.ar/authorization`. For **Mexico**, use `https://auth.mercadolibre.com.mx/authorization`. The token endpoint is always `https://api.mercadolibre.com/oauth/token` regardless of region.
4. Click **Close**
1. In Step 1 of the playground, click **Authorize APIs**
2. You'll be redirected to Mercado Livre — log in and grant permissions
3. After returning to the playground, click **Exchange authorization code for tokens** (Step 2)
4. Your **refresh token** will appear in the response on the right side
```json theme={null}
{
"access_token": "APP_USR-...",
"token_type": "Bearer",
"expires_in": 21600,
"scope": "offline_access read",
"user_id": 123456789,
"refresh_token": "TG-..."
}
```
You now have everything needed to configure Mercado Livre in Nekt:
* **Client ID**: Your App ID from the Developer Center
* **Client Secret**: Your Secret Key from the Developer Center
* **Refresh Token**: The `refresh_token` from the OAuth response (starts with `TG-`)
The refresh token will be automatically renewed by Nekt on each extraction. You don't need to manually refresh it.
Once you're done, click **Next**.
### 2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can pick individual streams or combine marketplace, fiscal, and advertising tables as needed.
**Important:** Advertising streams (Product Ads Campaigns, Product Ads Campaign Metrics, Brand Ads Campaigns, Brand Ads Campaign Metrics) are only available if your account has an Advertiser ID registered with Mercado Livre Advertising.
**Order-related child streams** (**Shipments**, **Invoices**, **Billing Info**) run one API request per qualifying order and can materially increase runtime for high-volume sellers.
**Items List** is not selected by default; it holds scan batches of item IDs used to drive the **Items** stream. Enable it only if you want the intermediate ID batches as their own table in the catalog.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
* Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
Optionally, you can define some additional settings:
* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from Mercado Livre and their corresponding fields:
Stream for all orders from your seller account, including payment details, items, and buyer/seller information.
**Key Fields:**
* `id` - Unique identifier for the order
* `status` - Order status
* `status_detail` - Detailed status information
* `date_created` - When the order was created
* `date_closed` - When the order was closed
* `date_last_updated` - Last update timestamp (replication key)
* `last_updated` - Last modification timestamp
* `expiration_date` - Order expiration date
**Financial:**
* `total_amount` - Total order amount
* `paid_amount` - Amount paid
* `shipping_cost` - Shipping cost
* `currency_id` - Currency code (e.g., BRL, ARS, MXN)
* `coupon` - Coupon information
* `amount` - Coupon discount amount
* `id` - Coupon ID
* `taxes` - Tax information
* `amount` - Tax amount
* `currency_id` - Tax currency
* `id` - Tax ID
**Payments:**
* `payments` - Array of payment details
* `id` - Payment ID
* `status` - Payment status
* `status_code` - Payment status code
* `status_detail` - Payment status detail
* `total_paid_amount` - Total amount paid
* `transaction_amount` - Transaction amount
* `transaction_amount_refunded` - Refunded amount
* `payment_method_id` - Payment method identifier
* `payment_type` - Payment type
* `installments` - Number of installments
* `installment_amount` - Amount per installment
* `date_created` - Payment creation date
* `date_approved` - Payment approval date
* `date_last_modified` - Last modification date
* `authorization_code` - Authorization code
* `operation_type` - Operation type
* `taxes_amount` - Taxes on payment
* `shipping_cost` - Shipping cost in payment
* `coupon_id` - Applied coupon ID
* `coupon_amount` - Coupon discount amount
* `overpaid_amount` - Overpaid amount
* `currency_id` - Currency ID
* `site_id` - Site ID
* `payer_id` - Payer ID
* `order_id` - Associated order ID
* `card_id` - Card ID (if applicable)
* `issuer_id` - Card issuer ID
* `collector` - Collector information (id)
* `available_actions` - Available actions array
* `activation_uri` - Activation URI
* `deferred_period` - Deferred period
* `atm_transfer_reference` - ATM transfer reference (transaction\_id, company\_id)
* `transaction_order_id` - Transaction order ID
* `reason` - Payment reason
**Order Items:**
* `order_items` - Array of purchased items
* `item` - Item details
* `id` - Item ID (MLB...)
* `title` - Item title
* `category_id` - Category ID
* `variation_id` - Variation ID
* `seller_custom_field` - Seller custom field
* `seller_sku` - Seller SKU
* `global_price` - Global price
* `net_weight` - Net weight
* `variation_attributes` - Variation attributes array
* `warranty` - Warranty info
* `condition` - Item condition
* `quantity` - Quantity purchased
* `unit_price` - Unit price
* `full_unit_price` - Full unit price (before discounts)
* `currency_id` - Currency ID
* `sale_fee` - Mercado Livre sale fee
* `listing_type_id` - Listing type
* `manufacturing_days` - Manufacturing days
* `picked_quantity` - Picked quantity
* `requested_quantity` - Requested quantity (measure, value)
* `base_exchange_rate` - Base exchange rate
* `base_currency_id` - Base currency ID
* `bundle` - Bundle info
* `element_id` - Element ID
**Buyer & Seller:**
* `buyer` - Buyer information (id, nickname)
* `seller` - Seller information (id, nickname)
**Shipping & Fulfillment:**
* `shipping` - Shipping information (id)
* `fulfilled` - Whether the order is fulfilled
* `pack_id` - Pack ID for grouped shipments
* `pickup_id` - Pickup ID
**Additional:**
* `tags` - Array of order tags
* `comment` - Order comment
* `manufacturing_ending_date` - Manufacturing ending date
* `feedback` - Feedback info (buyer, seller)
* `order_request` - Order request info (change, return)
* `context` - Context information
* `application` - Application
* `product_id` - Product ID
* `channel` - Channel
* `site` - Site
* `flows` - Flows array
Shipment details for each order that has a shipping ID. This stream is a child of **Orders** and calls `GET /shipments/{shipping_id}` so you get fields such as `logistic_type` (for example fulfillment vs. self-service) that are not on the order payload alone.
**Key Fields:**
* `id` - Shipment ID (primary key)
* `order_id` - Associated order ID (injected from the parent order)
* `order_last_updated` - Parent order `date_last_updated` (replication key)
* `status` - Shipment status
* `substatus` - Shipment substatus
* `date_created` - When the shipment was created
* `last_updated` - When the shipment was last updated
* `logistic_type` - Shipping / fulfillment type (for example `fulfillment`, `self_service`, `drop_off`, `xd_drop_off`, `cross_docking`)
* `mode` - Shipment mode (for example `me2`)
* `sender_id` - Sender (seller) ID
* `receiver_id` - Receiver (buyer) ID
* `tracking_number` - Carrier tracking number
* `tracking_method` - Tracking method used
**Shipping option:**
* `shipping_option` - Selected option including:
* `id`, `name`, `currency_id`, `cost`
* `speed` - `handling`, `shipping`
* `estimated_delivery_time` - `date`, `pay_before`, `type`
**Contents:**
* `shipping_items` - Items in the shipment (`id`, `quantity`, `description`, `dimensions`)
Brazilian electronic invoice (NF-e style) data for orders, when Mercado Livre exposes an invoice for that order. This stream is a child of **Orders**; orders without an invoice may be skipped with a warning.
**Key Fields:**
* `id` - Invoice record ID
* `order_id` - Marketplace order ID
* `order_last_updated` - Parent order last update (replication key)
* `status` - Invoice workflow status
* `transaction_status` - Fiscal transaction processing status
* `issued_date` - Official issuance timestamp
* `invoice_series` - Fiscal series
* `invoice_number` - Sequential number within the series
* `site_id` - Mercado Livre site code
* `pack_id` - Associated fulfillment pack ID
* `amount` - Total monetary amount
* `items_amount` - Sum of line amounts before global adjustments
* `items_quantity` - Number of line items
* `errors` - Validation or emission errors
**Issuer & recipient:**
* `issuer` - Legal issuer including `user_id`, `brand_name`, `name`, `phone` (`area_code`, `number`), `address` (street, city, zip, state, country), `identifications` (`cnpj`, `crt`, `ie`, `ie_type`)
* `recipient` - Buyer/recipient including `external_recipient_id`, `name`, `phone`, `address`, `identifications` (`cpf`, `cnpj`, `crt`, `ie`, `ie_type`)
**Shipment block on the invoice:**
* `shipment` - `id`, `site_id`, `mode`, `logistic_type`, `buyer_cost`, `paid_by`, `carrier` (name, phone, address, identifications), `volumes` (`net_weight`, `gross_weight`), `fiscal_model_id`, `shipping_locations`, `destination`
**Line items (`items` array):**
* Identifiers: `id`, `invoice_id`, `seller_id`, `pack_id`, `external_order_id`, `external_product_id`
* `attributes` - `ean`, `sku`, `type`, `bundle_quantity`
* `product_name`, `quantity`, `total_amount`, `shipping_buyer_cost`, `discount_amount` (`unconditional`, `conditional`)
* `fiscal_data` - Brazilian tax payload per line (NCM, CEST, CFOP, CSOSN, tax rules with ICMS/PIS/COFINS bases and amounts, and nested `messages`)
* `payments` - Payments linked to the line (`payment_method_id`, `installments`, `transaction_amount`, `charges_details`, etc.)
* `additional_info`, `other_amount`
**Header attributes (`attributes`):**
* Fiscal metadata such as `invoice_key`, `environment_type`, `xml_version`, Sefaz `status_code` / `status_description`, `receipt`, `receipt_date`, `protocol`, `authorization_date`, cancellation fields, `danfe`, `xml_location`, `document_type`, `tags`, and related NF-e fields
**Invoice-level fiscal totals (`fiscal_data`):**
* `customer_type`, `transaction_type`, `transaction_type_description`, `messages`
* `fiscal_amounts` - Named totalizers with consolidated tax amounts (`vbc`, `vicms`, `vst`, `vpis`, `vcofins`, etc.)
* `state_calculation_type` - State-specific ICMS calculation method
**Other:**
* `payments` - Serialized payment summary on the invoice header (string)
* `additional_info`, `custom_issuer_address`, `other_amount`
Buyer billing profile for each order (name, document, address, and tax metadata). This stream is a child of **Orders** and calls `/orders/{order_id}/billing_info` with API version `2`. Some orders return **403** if the authenticated account cannot read billing data; those orders are skipped with a warning.
**Key Fields:**
* `cust_id` - Buyer customer ID (primary key in the stream schema)
* `date_last_updated` - Parent order last update timestamp carried into the row
* `name` - Buyer first name for invoicing
* `last_name` - Buyer last name for invoicing
**Identification:**
* `identification` - `type`, `number` (tax or personal ID)
**Taxes:**
* `taxes` - Wrapper for buyer tax metadata including `taxpayer_type` (`id`, `description`)
**Address:**
* `address` - `street_name`, `street_number`, `city_name`, `comment`, `neighborhood`, `state` (`code`, `name`), `zip_code`, `country_id`
**Attributes:**
* `attributes` - `vat_discriminated_billing`, `new_billing_info`, `normalized`, `cust_type`
Scan-based discovery of all item IDs for the seller (`/users/{seller_id}/items/search?search_type=scan`). Each row is one batch of IDs returned from the search API. This stream is the **parent** of the **Items** stream: full item records are loaded per batch. By default this stream is **not** selected; enable it if you want the batched ID lists as a separate table in addition to item details.
**Key Fields:**
* `id_list` - Comma-separated list of item IDs in one batch (primary key)
Stream for all product listings from your seller account. Rows are loaded in batches discovered by the **Items List** parent stream (each batch of IDs becomes one or more full item payloads).
**Key Fields:**
* `id` - Unique item identifier (e.g., MLB12345678)
* `title` - Item title
* `permalink` - Direct link to the listing
* `condition` - Item condition (new, used)
* `status` - Item status (active, paused, closed, etc.)
* `site_id` - Site identifier
* `seller_id` - Seller ID
* `category_id` - Category ID
* `domain_id` - Domain ID
* `catalog_product_id` - Catalog product ID (if linked to catalog)
* `catalog_listing` - Whether item is a catalog listing
* `listing_type_id` - Listing type (gold\_special, gold\_pro, etc.)
* `buying_mode` - Buying mode (buy\_it\_now, auction)
* `start_time` - Listing start time
* `stop_time` - Listing end time
* `end_time` - Listing end time
* `expiration_time` - Listing expiration time
* `date_created` - Item creation date
* `last_updated` - Last update timestamp
* `health` - Item health score
* `family_name` - Family name
* `family_id` - Family ID
* `user_product_id` - User product ID
* `parent_item_id` - Parent item ID (for variations)
* `seller_custom_field` - Custom seller field
**Pricing:**
* `price` - Current price
* `base_price` - Base price
* `original_price` - Original price (before discount)
* `currency_id` - Currency code
**Inventory:**
* `available_quantity` - Available stock quantity
* `initial_quantity` - Initial quantity
* `sold_quantity` - Total units sold
* `inventory_id` - Inventory ID
**Media:**
* `thumbnail` - Thumbnail URL
* `thumbnail_id` - Thumbnail ID
* `video_id` - Video ID
* `pictures` - Array of item pictures
* `id` - Picture ID
* `url` - Picture URL
* `secure_url` - Secure picture URL
* `size` - Picture size
* `max_size` - Max picture size
* `quality` - Picture quality
**Seller & Store:**
* `official_store_id` - Official store ID
**Shipping:**
* `shipping` - Shipping configuration
* `store_pick_up` - Store pickup available
* `local_pick_up` - Local pickup available
* `free_shipping` - Free shipping enabled
* `logistic_type` - Logistic type (fulfillment, xd\_drop\_off, etc.)
* `mode` - Shipping mode
* `tags` - Shipping tags
* `methods` - Available shipping methods
* `dimensions` - Package dimensions
* `international_delivery_mode` - International delivery mode
**Location:**
* `seller_address` - Seller's address
* `address_line` - Address line
* `zip_code` - ZIP code
* `city` - City (id, name)
* `state` - State (id, name)
* `country` - Country (id, name)
* `latitude` - Latitude
* `longitude` - Longitude
* `search_location` - Search location (neighborhood, city, state)
* `geolocation` - Geolocation coordinates (latitude, longitude)
**Attributes:**
* `attributes` - Array of item attributes
* `id` - Attribute ID
* `name` - Attribute name
* `value_id` - Value ID
* `value_name` - Value name
* `attribute_group_id` - Attribute group ID
* `attribute_group_name` - Attribute group name
* `value_struct` - Structured value (number, unit)
* `values` - Values array
* `source` - Attribute source
* `value_type` - Value type
**Sale Terms:**
* `sale_terms` - Array of sale terms
* `id` - Term ID
* `name` - Term name
* `value_id` - Value ID
* `value_name` - Value name
* `value_type` - Value type
* `values` - Values array (id, name)
**Variations:**
* `variations` - Array of product variations
* `id` - Variation ID
* `price` - Variation price
* `available_quantity` - Available quantity for this variation
* `sold_quantity` - Sold quantity for this variation
* `inventory_id` - Inventory ID
* `user_product_id` - User product ID
* `catalog_product_id` - Catalog product ID
* `seller_custom_field` - Seller custom field
* `picture_ids` - Picture IDs array
* `attribute_combinations` - Attribute combinations array (id, name, value\_id, value\_name, value\_type, values)
* `sale_terms` - Sale terms for this variation
* `item_relations` - Related items (id, variation\_id, stock\_relation)
**Additional:**
* `accepts_mercadopago` - Accepts MercadoPago
* `sub_status` - Sub-status array
* `tags` - Item tags array
* `warranty` - Warranty information
* `deal_ids` - Active deal IDs
* `automatic_relist` - Whether item is auto-relisted
* `item_relations` - Related items array (id, variation\_id, stock\_relation)
* `channels` - Sales channels array
* `listing_source` - Listing source
* `descriptions` - Item descriptions
* `non_mercado_pago_payment_methods` - Non-MercadoPago payment methods
* `coverage_areas` - Coverage areas
* `warnings` - Item warnings
* `differential_pricing` - Differential pricing info
Customer experience and reputation metrics for each item. This stream is a child of the Items stream.
**Key Fields:**
* `item_id` - The item identifier
**Status:**
* `status` - Current status (id)
* `freeze` - Freeze information (text)
* `title` - Title information (text)
**Reputation:**
* `reputation` - Overall reputation
* `color` - Reputation color indicator
* `text` - Reputation text
* `value` - Reputation score
**Subtitles:**
* `subtitles` - Array of subtitle information
* `order` - Display order
* `text` - Subtitle text
* `placeholders` - Placeholder values
**Actions:**
* `actions` - Available actions array
* `order` - Action order
* `text` - Action text
**Metrics Details:**
* `metrics_details` - Detailed metrics breakdown
* `problems` - Array of problems
* `order` - Problem order
* `key` - Problem key
* `color` - Problem severity color
* `quantity` - Quantity string
* `cancellations` - Number of cancellations
* `claims` - Number of claims
* `tag` - Problem tag
* `level_two` - Level two details (key, title)
* `level_three` - Level three details (key, title, remedy)
* `distribution` - Rating distribution
* `from` - Period start
* `to` - Period end
* `level_one` - Level one breakdown array
* `key` - Key
* `title` - Title (order, text)
* `color` - Color
* `percentage` - Percentage
* `quantities_level_two` - Level two quantities
Visit statistics for each item over time. This stream is a child of the Items stream.
**Key Fields:**
* `item_id` - The item identifier
* `date_from` - Period start date (replication key)
* `date_to` - Period end date
**Metrics:**
* `total_visits` - Total number of visits in the period
**Visit Details:**
* `visits_detail` - Breakdown by source
* `company` - Source/company name
* `quantity` - Number of visits from this source
Quality score and performance metrics for each item. This stream is a child of the Items stream.
Quality score is only available for non-catalog items. Items linked to the Mercado Livre catalog will be skipped.
**Key Fields:**
* `entity_type` - Entity type
* `entity_id` - Entity identifier (item ID)
* `score` - Overall quality score
* `level` - Quality level
* `level_wording` - Quality level description
* `calculated_at` - Calculation timestamp (replication key)
**Buckets:**
* `buckets` - Quality score buckets array
* `key` - Bucket key
* `type` - Bucket type
* `status` - Bucket status
* `score` - Bucket score
* `title` - Bucket title
* `calculated_at` - Calculation timestamp
* `variables` - Variables array
* `key` - Variable key
* `status` - Variable status
* `score` - Variable score
* `calculated_at` - Calculation timestamp
* `title` - Variable title
* `rules` - Rules array
* `key` - Rule key
* `status` - Rule status
* `progress` - Progress value
* `mode` - Rule mode
* `calculated_at` - Calculation timestamp
* `wordings` - Rule wordings (title, label, link)
Product Ads campaign configurations and settings. Only available for accounts with an Advertiser ID.
**Key Fields:**
* `id` - Campaign ID
* `name` - Campaign name
* `status` - Campaign status (active, paused, etc.)
* `date_created` - Creation timestamp
* `last_updated` - Last update timestamp
**Budget & Bidding:**
* `budget` - Daily budget amount
* `currency_id` - Budget currency
* `acos_target` - Target ACoS (Advertising Cost of Sale)
* `acos_top_search_target` - Target ACoS for top search positions
* `strategy` - Bidding strategy
**Channel:**
* `channel` - Campaign channel
Daily performance metrics for Product Ads campaigns. This stream is a child of Product Ads Campaigns.
**Key Fields:**
* `campaign_id` - Campaign identifier
* `date` - Metrics date (replication key)
**Traffic Metrics:**
* `prints` - Number of impressions
* `clicks` - Number of clicks
* `ctr` - Click-through rate
* `cpc` - Cost per click
* `cost` - Total advertising cost
**Conversion Metrics:**
* `direct_units_quantity` - Units sold from direct clicks
* `indirect_units_quantity` - Units sold from indirect attribution
* `units_quantity` - Total units sold
* `direct_amount` - Revenue from direct conversions
* `indirect_amount` - Revenue from indirect conversions
* `total_amount` - Total attributed revenue
* `direct_items_quantity` - Items sold from direct clicks
* `indirect_items_quantity` - Items sold from indirect attribution
* `advertising_items_quantity` - Total items from advertising
**Organic Metrics:**
* `organic_units_quantity` - Organic units sold
* `organic_units_amount` - Organic revenue
* `organic_items_quantity` - Organic items sold
**Efficiency Metrics:**
* `acos` - Advertising Cost of Sale (cost/revenue)
* `cvr` - Conversion rate
* `roas` - Return on Ad Spend
**Share of Voice:**
* `sov` - Share of Voice
* `impression_share` - Impression share
* `top_impression_share` - Top position impression share
* `lost_impression_share_by_budget` - Lost impressions due to budget
* `lost_impression_share_by_ad_rank` - Lost impressions due to ad rank
**Benchmark:**
* `acos_benchmark` - ACoS benchmark for comparison
Brand Ads campaign configurations and settings. Only available for accounts with an Advertiser ID.
**Key Fields:**
* `campaign_id` - Campaign ID
* `name` - Campaign name
* `status` - Campaign status
* `moderation_status` - Content moderation status
* `campaign_type` - Campaign type
* `start_date` - Campaign start date
* `end_date` - Campaign end date
**Account:**
* `advertiser_id` - Advertiser ID
* `site_id` - Site ID
* `eshop_id` - E-shop ID
* `official_store_id` - Official store ID
* `destination_id` - Destination ID
**Creative:**
* `headline` - Campaign headline
**Budget & Bidding:**
* `budget` - Budget information
* `amount` - Budget amount
* `currency` - Currency code
* `cpc` - Cost per click bid
**Items:**
* `items` - Array of campaign items
* `campaign_id` - Campaign ID
* `status` - Item status
* `item_id` - Item ID
**Keywords:**
* `keywords` - Array of campaign keywords
* `campaign_id` - Campaign ID
* `type` - Keyword type
* `term` - Keyword term
* `match_type` - Match type (exact, phrase, broad)
* `is_negative` - Is negative keyword
* `cpc` - Keyword CPC bid
Daily performance metrics for Brand Ads campaigns. This stream is a child of Brand Ads Campaigns.
**Key Fields:**
* `campaign_id` - Campaign identifier
* `date` - Metrics date (replication key)
**Traffic Metrics:**
* `prints` - Number of impressions
* `clicks` - Number of clicks
* `ctr` - Click-through rate
* `cost_per_clicks` - Cost per click (CPC)
* `consumed_budget` - Budget consumed
**Efficiency Metrics:**
* `cvr` - Conversion rate
* `acos` - Advertising Cost of Sale
* `roas` - Return on Ad Spend
**Attribution Metrics:**
* `attribution_order_conversions` - Number of orders attributed to the campaign
* `attribution_order_amount` - Revenue attributed to the campaign
* `leads` - Number of leads generated
# Data Model
The following diagram illustrates the relationships between the core data streams in Mercado Livre. The arrows indicate the join keys that link the different entities.
```mermaid theme={null}
graph TD;
subgraph "Seller Data"
Orders("Orders");
Shipments("Shipments");
Invoices("Invoices");
BillingInfo("Billing Info");
ItemsList("Items List");
Items("Items");
end
subgraph "Item Metrics"
VisitsPerItem("Visits Per Item");
QualityScore("Quality Score Per Item");
BuyerExperience("Buyer Experience Per Item");
end
subgraph "Product Ads"
ProductAdsCampaigns("Product Ads Campaigns");
ProductAdsMetrics("Product Ads Campaign Metrics");
end
subgraph "Brand Ads"
BrandAdsCampaigns("Brand Ads Campaigns");
BrandAdsMetrics("Brand Ads Campaign Metrics");
end
Orders -- "shipping_id" --> Shipments;
Orders -- "order_id" --> Invoices;
Orders -- "per order" --> BillingInfo;
ItemsList -- "id_list batches" --> Items;
Items -- "item_id" --> VisitsPerItem;
Items -- "item_id" --> QualityScore;
Items -- "item_id" --> BuyerExperience;
Items -- "item.id" --> Orders;
ProductAdsCampaigns -- "campaign_id" --> ProductAdsMetrics;
BrandAdsCampaigns -- "campaign_id" --> BrandAdsMetrics;
BrandAdsCampaigns -- "item_id" --> Items;
```
# Use Cases for Data Analysis
This guide outlines valuable business intelligence use cases when consolidating Mercado Livre data, along with ready-to-use SQL queries that you can run on [Explorer](https://app.nekt.ai/explorer).
### 1. Product Ads Campaign Performance Overview
Analyze the performance of your Product Ads campaigns to understand ROI and optimize budget allocation.
**Business Value:**
* Identify top-performing campaigns by ROAS and ACoS
* Understand which campaigns drive the most conversions
* Optimize budget distribution across campaigns
```sql theme={null}
WITH campaign_summary AS (
SELECT
c.id AS campaign_id,
c.name AS campaign_name,
c.status AS campaign_status,
c.strategy,
c.acos_target,
SUM(m.prints) AS total_impressions,
SUM(m.clicks) AS total_clicks,
SUM(m.cost) AS total_cost,
SUM(m.total_amount) AS total_revenue,
SUM(m.units_quantity) AS total_units_sold,
AVG(m.ctr) AS avg_ctr,
AVG(m.cvr) AS avg_cvr
FROM
nekt_raw.mercadolivre_product_ads_campaigns c
LEFT JOIN nekt_raw.mercadolivre_product_ads_campaign_metrics m
ON c.id = m.campaign_id
WHERE
m.date >= CURRENT_DATE - INTERVAL '30' DAY
GROUP BY
c.id, c.name, c.status, c.strategy, c.acos_target
)
SELECT
campaign_name,
campaign_status,
strategy,
total_impressions,
total_clicks,
ROUND(total_cost, 2) AS total_cost,
ROUND(total_revenue, 2) AS total_revenue,
total_units_sold,
ROUND(avg_ctr * 100, 2) AS ctr_percent,
ROUND(avg_cvr * 100, 2) AS cvr_percent,
ROUND(CASE WHEN total_revenue > 0 THEN total_cost / total_revenue * 100 ELSE 0 END, 2) AS acos_percent,
ROUND(acos_target * 100, 2) AS target_acos_percent,
ROUND(CASE WHEN total_cost > 0 THEN total_revenue / total_cost ELSE 0 END, 2) AS roas
FROM
campaign_summary
ORDER BY
total_revenue DESC
```
```sql theme={null}
WITH campaign_summary AS (
SELECT
c.id AS campaign_id,
c.name AS campaign_name,
c.status AS campaign_status,
c.strategy,
c.acos_target,
SUM(m.prints) AS total_impressions,
SUM(m.clicks) AS total_clicks,
SUM(m.cost) AS total_cost,
SUM(m.total_amount) AS total_revenue,
SUM(m.units_quantity) AS total_units_sold,
AVG(m.ctr) AS avg_ctr,
AVG(m.cvr) AS avg_cvr
FROM
`nekt_raw.mercadolivre_product_ads_campaigns` c
LEFT JOIN `nekt_raw.mercadolivre_product_ads_campaign_metrics` m
ON c.id = m.campaign_id
WHERE
DATE(m.date) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY
c.id, c.name, c.status, c.strategy, c.acos_target
)
SELECT
campaign_name,
campaign_status,
strategy,
total_impressions,
total_clicks,
ROUND(total_cost, 2) AS total_cost,
ROUND(total_revenue, 2) AS total_revenue,
total_units_sold,
ROUND(avg_ctr * 100, 2) AS ctr_percent,
ROUND(avg_cvr * 100, 2) AS cvr_percent,
ROUND(SAFE_DIVIDE(total_cost, total_revenue) * 100, 2) AS acos_percent,
ROUND(acos_target * 100, 2) AS target_acos_percent,
ROUND(SAFE_DIVIDE(total_revenue, total_cost), 2) AS roas
FROM
campaign_summary
ORDER BY
total_revenue DESC
```
| campaign\_name | campaign\_status | strategy | total\_impressions | total\_clicks | total\_cost | total\_revenue | total\_units\_sold | ctr\_percent | cvr\_percent | acos\_percent | target\_acos\_percent | roas |
| --------------------- | ---------------- | --------- | ------------------ | ------------- | ----------- | -------------- | ------------------ | ------------ | ------------ | ------------- | --------------------- | ---- |
| Top Products Campaign | active | automatic | 1,245,890 | 42,156 | 8,542.30 | 42,800.00 | 856 | 3.38 | 2.03 | 19.96 | 20.00 | 5.01 |
| Electronics Promo | active | manual | 892,340 | 31,245 | 4,998.50 | 21,150.00 | 423 | 3.50 | 1.35 | 23.64 | 25.00 | 4.23 |
| Seasonal Sale | paused | automatic | 567,230 | 18,456 | 3,691.20 | 12,670.00 | 289 | 3.25 | 1.57 | 29.13 | 30.00 | 3.43 |
### 2. Item Quality Score Analysis
Monitor the quality scores of your listings to improve visibility and sales performance.
**Business Value:**
* Identify items with low quality scores that need improvement
* Track quality metrics over time
* Prioritize optimization efforts
```sql theme={null}
SELECT
i.id AS item_id,
i.title AS item_title,
i.price,
i.available_quantity,
q.score AS quality_score,
q.level AS quality_level,
q.level_wording AS quality_description,
q.calculated_at AS last_calculated
FROM
nekt_raw.mercadolivre_items i
LEFT JOIN nekt_raw.mercadolivre_quality_score_per_item q
ON i.id = q.entity_id
WHERE
q.score IS NOT NULL
ORDER BY
q.score ASC
LIMIT 50
```
```sql theme={null}
SELECT
i.id AS item_id,
i.title AS item_title,
i.price,
i.available_quantity,
q.score AS quality_score,
q.level AS quality_level,
q.level_wording AS quality_description,
q.calculated_at AS last_calculated
FROM
`nekt_raw.mercadolivre_items` i
LEFT JOIN `nekt_raw.mercadolivre_quality_score_per_item` q
ON i.id = q.entity_id
WHERE
q.score IS NOT NULL
ORDER BY
q.score ASC
LIMIT 50
```
| item\_id | item\_title | price | available\_quantity | quality\_score | quality\_level | quality\_description | last\_calculated |
| ----------- | ------------------------- | ------- | ------------------- | -------------- | -------------- | -------------------- | -------------------- |
| MLB12345678 | Smartphone Samsung Galaxy | 1299.00 | 45 | 72 | medium | Bom | 2024-11-27T10:30:00Z |
| MLB23456789 | Notebook Dell Inspiron | 3499.00 | 12 | 85 | high | Muito bom | 2024-11-27T10:25:00Z |
| MLB34567890 | Fone de Ouvido Bluetooth | 89.90 | 230 | 58 | low | Regular | 2024-11-27T10:20:00Z |
### 3. Sales and Revenue Analysis
Analyze order data to understand sales performance and payment methods.
**Business Value:**
* Track revenue trends over time
* Understand payment method preferences
* Identify top-selling items
```sql theme={null}
WITH order_items_exploded AS (
SELECT
o.id AS order_id,
o.date_created,
o.status AS order_status,
o.total_amount,
o.paid_amount,
o.currency_id,
oi.item.id AS item_id,
oi.item.title AS item_title,
oi.quantity,
oi.unit_price,
oi.sale_fee
FROM
nekt_raw.mercadolivre_orders o
CROSS JOIN UNNEST(o.order_items) AS oi
WHERE
o.date_created >= CURRENT_DATE - INTERVAL '30' DAY
)
SELECT
DATE(date_created) AS order_date,
COUNT(DISTINCT order_id) AS total_orders,
SUM(quantity) AS total_units_sold,
ROUND(SUM(total_amount), 2) AS total_revenue,
ROUND(SUM(sale_fee), 2) AS total_fees,
ROUND(AVG(total_amount), 2) AS avg_order_value
FROM
order_items_exploded
WHERE
order_status = 'paid'
GROUP BY
DATE(date_created)
ORDER BY
order_date DESC
```
```sql theme={null}
WITH order_items_exploded AS (
SELECT
o.id AS order_id,
o.date_created,
o.status AS order_status,
o.total_amount,
o.paid_amount,
o.currency_id,
oi.item.id AS item_id,
oi.item.title AS item_title,
oi.quantity,
oi.unit_price,
oi.sale_fee
FROM
`nekt_raw.mercadolivre_orders` o
CROSS JOIN UNNEST(o.order_items) AS oi
WHERE
DATE(o.date_created) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
)
SELECT
DATE(date_created) AS order_date,
COUNT(DISTINCT order_id) AS total_orders,
SUM(quantity) AS total_units_sold,
ROUND(SUM(total_amount), 2) AS total_revenue,
ROUND(SUM(sale_fee), 2) AS total_fees,
ROUND(AVG(total_amount), 2) AS avg_order_value
FROM
order_items_exploded
WHERE
order_status = 'paid'
GROUP BY
DATE(date_created)
ORDER BY
order_date DESC
```
| order\_date | total\_orders | total\_units\_sold | total\_revenue | total\_fees | avg\_order\_value |
| ----------- | ------------- | ------------------ | -------------- | ----------- | ----------------- |
| 2024-11-27 | 156 | 234 | 45,678.90 | 5,481.47 | 292.81 |
| 2024-11-26 | 142 | 198 | 38,456.20 | 4,614.74 | 270.82 |
| 2024-11-25 | 128 | 176 | 32,890.50 | 3,946.86 | 256.96 |
## Implementation Notes
### Data Quality Considerations
* **Advertising Streams**: Product Ads and Brand Ads streams are only available if your Mercado Livre account has an advertiser ID. Accounts without advertising access still get marketplace streams (orders, items, metrics, fiscal helpers, etc.) but not the advertising campaign tables.
* **Invoices**: Emitted per order when Mercado Livre returns invoice data; orders without an invoice (HTTP 404) are skipped with a log warning. Invoice payloads are Brazil-centric (NF-e style fields and Sefaz metadata).
* **Billing Info**: One request per order; HTTP 403 when the credential cannot read billing data for that order (skipped with a warning). Join child rows back to orders using your pipeline’s parent/child lineage fields if the raw table does not repeat `order_id`.
* **Shipments**: Only orders with a `shipping.id` produce shipment rows; the stream supplies `logistic_type` and tracking fields from the Shipments API.
* **Items List**: Optional catalog table of scan batches; the **Items** stream depends on it for ID discovery—leave **Items List** off unless you need the intermediate batches as data.
* **Quality Score Availability**: Quality scores are only available for non-catalog items. Items linked to the Mercado Livre product catalog will be skipped during extraction.
* **Metrics Time Window**: Campaign metrics are available for the last 90 days only.
### API Limits & Performance
* **Metrics Granularity Impact**: The more granular the metrics setting (day vs. month), the longer extractions will take due to increased API calls.
* **Order Child Streams**: **Shipments**, **Invoices**, and **Billing Info** each add per-order API calls on top of the base Orders extraction. Disable any you do not need to reduce duration and rate-limit pressure.
* **Visit Data Limit**: Visit statistics are limited to the last 2 years of data.
* **Pagination**: Large seller accounts with many items may experience longer extraction times.
### Regional Considerations
* **Currency**: All financial values are in the local currency of the site (BRL for MLB, ARS for MLA, MXN for MLM).
* **Timestamps**: All timestamps are in UTC.
## Skills for agents
Mercado Livre connector documentation as plain markdown, for use in AI agent contexts.