API Documentation

Welcome to the Melibel API. This documentation will help you integrate our services into your applications.

Authentication

All API endpoints require authentication using a Personal Access Token.

Header Format: Authorization: <Access-Token <TOKEN>>

Replace TOKEN with your personal access token from the tokens page

Endpoints

GET Recent Offers

Returns a list of recent offers with optional filtering.

Endpoint Details

URL: /api/products/recent-offers/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 0)
category String No Filter by category (can be repeated for multiple)
lower_price Integer No Minimum price filter
higher_price Integer No Maximum price filter
percentage Integer No Discount percentage filter (default: 100)
store String No Filter by store (can be repeated for multiple)
q String No Search query

Example Request

curl -X GET "/api/products/recent-offers/?page=1" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 123,
  "next": "http://localhost:8000/api/products/recent-offers/?page=2",
  "previous": null,
  "results": [
    {
      "id": 123,
      "name": "Product Name",
      "last_price_found": 99.99,
      "second_last_price_found": 129.99,
      "origin": "MLM",
      "url": "https://...",
      "thumbnail": "https://...",
      "created_at": "2026-04-11T12:00:00Z",
      "last_price": {
        "extra_prices": [],
        "created": "2026-04-11",
        "amount": 1356.0,
        "currency": "MXN"
      },
      "average_price": 2224.67,
      "price_difference": -868.67
    },
    ...
  ]
}

GET Stock One

Returns a list of products with stock information from Mercado Libre.

Endpoint Details

URL: /api/products/stock-one/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)

Example Request

curl -X GET "/api/products/stock-one/" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 48,
  "next": "http://localhost:8000/api/products/stock-one/?page=2",
  "previous": null,
  "results": [
    {
      "id": 4570082,
      "product": {
        "id": 152,
        "product": "Apple Pencil Pro",
        "origin": "ML",
        "url": "https://www.mercadolibre.com.mx/apple-pencil-pro/up/MLMU399490896",
        "image": "https://http2.mlstatic.com/D_Q_NP_2X_771749-MLM76442010789_052024-E.webp",
        "location": "MEX",
        "alternative_id": "MLMU399490896",
        "category": [
          "computación",
          "tablets y accesorios",
          "accesorios",
          "lápiz óptico"
        ]
      },
      "created": "2026-04-11T00:55:51.733012Z",
      "modified": "2026-04-11T00:55:51.732998Z",
      "products_available": 0,
      "products_sold": 0,
      "seller": null
    },
    ...
  ]
}

GET Stock Levels

Returns stock levels for products with filtering options.

Endpoint Details

URL: /api/products/stock-levels/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)
alternative_id String No Mercado Libre product ID (e.g., 'MLM12345678' or 'MLM-123456789'). Use instead of product_url
product_url String No Product URL (partial match, e.g., 'iphone-15' or full URL)
stock_status String No Filter by: in_stock, low_stock, out_of_stock
category String No Filter by category name
days Integer No Lookback days (default: 15)

Example Request

curl -X GET "/api/products/stock-levels/?stock_status=low_stock" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Stock Status Definitions

  • in_stock: More than 2 units available
  • low_stock: 1-2 units available (about to run out)
  • out_of_stock: 0 units available

Example Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "product_id": 1250,
      "product_name": "Xiaomi Poco X7 Pro 5g Dual Slm 256 Gb Negro 8 Gb Ram",
      "product_url": "https://www.mercadolibre.com.mx/xiaomi-poco-x7-pro-5g-dual-slm-256-gb-negro-8-gb-ram/p/MLM45824212",
      "product_alternative_id": "MLM45824212",
      "current_stock": 50,
      "products_sold": 10000,
      "stock_status": "in_stock",
      "last_stock_update": "2026-04-13T00:06:47.988229Z",
      "seller_url": "https://www.mercadolibre.com.mx/tienda/poco",
      "price": "5964.48"
    }
  ]
}

GET Competitor Pricing

Search for a product by URL to see pricing from all sellers. Compare your price against competitors.

Endpoint Details

URL: /api/products/competitor-pricing/

Query Parameters

Parameter Type Required Description
alternative_id String No Mercado Libre product ID (e.g., 'MLM12345678' or 'MLM-123456789'). Use instead of product_url
product_url String Yes Product URL (partial match, e.g., 'iphone-15' or full URL)
seller_url String No Your seller URL to find your position in the ranking
days Integer No Lookback days (default: 15)

Example Request

# Search for a product by URL to see competitor prices
curl -X GET "/api/products/competitor-pricing/?product_url=iphone-15-pro" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

# Search using Mercado Libre ID (alternative_id)
curl -X GET "/api/products/competitor-pricing/?alternative_id=MLM123456789" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

# Also see where you rank among competitors
curl -X GET "/api/products/competitor-pricing/?product_url=iphone-15-pro&seller_url=mystore" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "product_id": 7412,
  "product_name": "iPhone 15 Pro 256GB",
  "product_url": "https://www.mercadolibre.com.mx/iphone-15-pro...",
  "category": "iphone",
  "total_sellers": 12,
  "your_position": {
    "seller_id": 5,
    "seller_url": "https://www.mercadolibre.com.mx/tienda/mystore",
    "price": 15499.00,
    "last_updated": "2026-04-12T10:30:00Z"
  },
  "your_rank": 3,
  "your_price_vs_competitors": 200.00,
  "lowest_price": 14990.00,
  "highest_price": 17990.00,
  "average_price": 16200.00,
  "all_sellers": [
    {
      "seller_id": 8,
      "seller_url": "https://www.mercadolibre.com.mx/tienda/cheapseller",
      "price": 14990.00,
      "last_updated": "2026-04-12T08:00:00Z"
    },
    {
      "seller_id": 3,
      "seller_url": "https://www.mercadolibre.com.mx/tienda/competitor2",
      "price": 15299.00,
      "last_updated": "2026-04-12T09:15:00Z"
    },
    {
      "seller_id": 5,
      "seller_url": "https://www.mercadolibre.com.mx/tienda/mystore",
      "price": 15499.00,
      "last_updated": "2026-04-12T10:30:00Z"
    },
    ...
  ]
}

Response Fields

  • total_sellers: Number of sellers with prices for this product
  • your_position: Your seller info (if seller_url matches)
  • your_rank: Your position in price ranking (1 = cheapest)
  • your_price_vs_competitors: Your price minus the lowest price. Positive = you're more expensive
  • all_sellers: All sellers sorted by price (lowest first)

GET Price Trends

Shows price trends for products with significant price changes (drops or increases). Use this to find deals or identify pricing opportunities.

Endpoint Details

URL: /api/products/price-trends/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)
trend String No Filter by: price_drop, price_increase, all (default: all)
days Integer No Lookback days (default: 30)
min_percentage Integer No Minimum price change percentage (default: 1)

Example Request

# Get products with price drops
curl -X GET "/api/products/price-trends/?trend=price_drop&min_percentage=5" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 892,
  "next": "http://localhost:8000/api/products/price-trends/?page=2",
  "previous": null,
  "results": [
    {
      "product_id": 7412,
      "product_name": "Samsung Galaxy S24 Ultra",
      "product_url": "https://...",
      "category": "samsung",
      "current_price": 18990.00,
      "previous_price": 21999.00,
      "price_change": -3009.00,
      "percentage": -13.68,
      "trend": "price_drop",
      "last_updated": "2026-04-12T10:30:00Z"
    },
    ...
  ]
}

GET Category Insights

Returns market insights for leaf categories (most specific category level). Products are only registered to leaf categories.

Endpoint Details

URL: /api/categories/category-insights/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)
category String No Filter by category name (partial match)
parent String No Filter by parent category name
days Integer No Lookback days (default: 30)

Example Request

curl -X GET "/api/categories/category-insights/?parent=Celulares" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 4293,
  "next": "http://localhost:8000/api/products/category-insights/?page=2",
  "previous": null,
  "results": [
    {
      "category_id": 123,
      "category_name": "iphone",
      "parent_category": "celulares y smartphones",
      "product_count": 892,
      "active_sellers": 45,
      "average_price": 12500.50,
      "min_price": 3500.00,
      "max_price": 45000.00,
      "avg_products_available": 0.5,
      "trending_score": 8.5
    },
    ...
  ]
}

GET Seller Performance

Returns performance metrics for sellers including product count, pricing, and competitiveness scores.

Endpoint Details

URL: /api/products/seller-performance/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)
days Integer No Lookback days (default: 30)
seller_url String No Search seller by URL (partial match, case-insensitive). Returns single seller if found.

Example Request

# Get all sellers
curl -X GET "/api/products/seller-performance/" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

# Search for a specific seller by URL
curl -X GET "/api/products/seller-performance/?seller_url=gadgettroops" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 309,
  "next": "http://localhost:8000/api/products/seller-performance/?page=2",
  "previous": null,
  "results": [
    {
      "seller_id": 698,
      "seller_url": "https://www.mercadolibre.com.mx/pagina/seller123",
      "product_count": 45,
      "average_price": 5200.00,
      "lowest_price": 450.00,
      "highest_price": 15000.00,
      "avg_products_available": 12.5,
      "price_competitiveness_score": -5.2,
      "last_updated": "2026-04-12T10:30:00Z"
    },
    ...
  ]
}

Response Fields

  • price_competitiveness_score: Percentage difference from market average. Negative = cheaper than average, Positive = more expensive than average
  • product_count: Number of unique products the seller has priced
  • average_price: Average price across all their products

GET Stock Velocity

Identifies fast-moving inventory by calculating products_sold over time. Compares products_sold between two points to get velocity per day. Products are ordered by velocity (fastest selling first).

Endpoint Details

URL: /api/products/stock-velocity/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)
days Integer No Lookback days to calculate velocity (default: 30)

Example Request

# Get products with highest velocity (fastest selling)
curl -X GET "/api/products/stock-velocity/?days=30" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 156,
  "next": "http://localhost:8000/api/products/stock-velocity/?page=2",
  "previous": null,
  "results": [
    {
      "product_id": 1234,
      "product_name": "iPhone 15 Pro 256GB",
      "product_url": "https://www.mercadolibre.com.mx/iphone-15-pro...",
      "category": "iphone",
      "velocity": 333.33,
      "total_products_sold": 10000,
      "products_available": 10,
      "average_price": 15499.00
    },
    {
      "product_id": 5678,
      "product_name": "Samsung Galaxy S24",
      "product_url": "https://www.mercadolibre.com.mx/samsung-galaxy-s24...",
      "category": "samsung",
      "velocity": 100.00,
      "total_products_sold": 3000,
      "products_available": 25,
      "average_price": 12999.00
    }
  ]
}

Response Fields

  • velocity: Products sold per day in the period
  • total_products_sold: Total products sold in the period (difference between start and end)
  • products_available: Current available stock
  • average_price: Average price across sellers

GET Seller Products

Track a seller's products and prices. Returns the latest products with price history from a specific seller.

Endpoint Details

URL: /api/products/seller-products/

Query Parameters

Parameter Type Required Description
seller_url String Yes Seller URL to track (partial match, case-insensitive)
page Integer No Page number (default: 1)
days Integer No Lookback days (default: 15)

Example Request

# Get products and prices from a specific seller
curl -X GET "/api/products/seller-products/?seller_url=mystore&days=7" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 50,
  "next": "http://localhost:8000/api/products/seller-products/?page=2&seller_url=mystore",
  "previous": null,
  "results": [
    {
      "product_id": 1234,
      "product_name": "iPhone 15 Pro 256GB",
      "product_url": "https://www.mercadolibre.com.mx/iphone-15-pro...",
      "category": "iphone",
      "price": 15499.00,
      "products_available": 10,
      "products_sold": 100,
      "last_updated": "2026-04-13T10:30:00Z",
      "prices": [
        {"amount": 15499.00, "currency": "MXN", "created": "2026-04-13T10:30:00Z"},
        {"amount": 15299.00, "currency": "MXN", "created": "2026-04-12T10:30:00Z"},
        {"amount": 15199.00, "currency": "MXN", "created": "2026-04-11T10:30:00Z"}
      ]
    }
  ]
}

Response Fields

  • prices: Array with the last 30 prices for this product (amount, currency, created)

GET Category Price Elasticity

Calculates price elasticity for products in a category by comparing price changes to inventory depletion (products_sold). Shows how sensitive demand is to price changes.

Endpoint Details

URL: /api/categories/price-elasticity/

Query Parameters

Parameter Type Required Description
category String Yes Category name (partial match, case-insensitive). Includes all descendant categories.
days Integer No Lookback days (default: 60)

Example Request

# Calculate elasticity for "Phone Chargers" category
curl -X GET "/api/categories/price-elasticity/?category=Phone%20Chargers&days=60" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "category": "Phone Chargers",
  "elasticity_score": 2.4,
  "interpretation": "HIGHLY_ELASTIC",
  "meaning": "10% price drop → 24% sales increase"
}

Interpretation Levels

  • PERFECTLY_INELASTIC: Elasticity = 0 (demand doesn't change with price)
  • INELASTIC: 0 < Elasticity < 1 (demand changes less than price)
  • ELASTIC: 1 <= Elasticity < 3.5 (demand changes more than price)
  • HIGHLY_ELASTIC: Elasticity >= 3.5 (demand very sensitive to price)

GET Nested Categories

Returns categories in a tree structure, paginated by root categories. Each page includes the root categories and all their nested children.

Endpoint Details

URL: /api/categories/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)

Example Request

curl -X GET "/api/categories/" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 10,
  "next": "http://localhost:8000/api/products/categories/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Electronics",
      "children": [
        {"id": 2, "name": "Celphones", "children": []},
        {"id": 3, "name": "Tablets", "children": []}
      ]
    }
  ]
}

GET Seller State Registry

Returns seller state registries over time, including level, ratings, and transaction data.

Endpoint Details

URL: /api/sellers/state-registry/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)
seller_url String No Filter by seller URL (partial match, case-insensitive)
seller_name String No Filter by seller name (partial match, case-insensitive)
days Integer No Lookback days (default: 30, max: 180)

Example Request

curl -X GET "/api/sellers/state-registry/?seller_url=mystore&days=30" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "seller_id": 123,
      "seller_name": "My Store",
      "seller_url": "https://www.mercadolibre.com.mx/tienda/mystore",
      "level_id": 3,
      "power_seller_status": true,
      "transactions_total": 1500,
      "transactions_canceled": 50,
      "transactions_completed": 1450,
      "rating_negative": 100.0,
      "rating_positive": 5000.0,
      "rating_neutral": 200.0,
      "sales_period": 30,
      "sales_completed": 450,
      "created": "2026-04-15T10:30:00Z"
    }
  ]
}

GET Seller Opportunities

Returns sellers with higher negative ratings than positive ratings, ordered by descending sales. Useful for finding underperforming sellers to target.

Endpoint Details

URL: /api/sellers/opportunities/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)
days Integer No Lookback days (default: 30, max: 180)

Example Request

curl -X GET "/api/sellers/opportunities/?days=30" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 25,
  "next": "http://localhost:8000/api/products/sellers/opportunities/?page=2",
  "previous": null,
  "results": [
    {
      "seller_id": 456,
      "seller_name": "Underperforming Store",
      "seller_url": "https://www.mercadolibre.com.mx/tienda/badstore",
      "level_id": 2,
      "power_seller_status": false,
      "transactions_total": 800,
      "transactions_completed": 650,
      "rating_negative": 150.0,
      "rating_positive": 100.0,
      "rating_neutral": 50.0,
      "sales_completed": 300,
      "created": "2026-04-15T10:30:00Z"
    }
  ]
}

GET Churn Risk Predictor

ML-based churn risk prediction using declining sales, increasing cancellations, stagnant level, and inventory drops. Useful for proactive retention.

Endpoint Details

URL: /api/sellers/churn-risk/

Query Parameters

Parameter Type Required Description
seller_url String No Seller URL (partial match, case-insensitive). Use instead of seller_name
seller_name String No Seller name (partial match, case-insensitive). Use instead of seller_url
days Integer No Lookback days (default: 30, max: 180)

Example Request

curl -X GET "/api/sellers/churn-risk/?seller_url=mystore&days=30" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "seller_id": 123,
  "seller_name": "My Store",
  "seller_url": "https://www.mercadolibre.com.mx/tienda/mystore",
  "churn_risk_score": 75,
  "risk_level": "HIGH",
  "factors": {
    "sales_decline": 20.5,
    "cancel_rate": 15.0,
    "level_stagnant": 15.0,
    "inventory_drops": 24.5
  },
  "days_analyzed": 30
}

Risk Level Definitions

  • HIGH: Score >= 70 - Immediate intervention recommended
  • MEDIUM: Score >= 40 - Monitor closely
  • LOW: Score < 40 - Healthy status

GET Emerging Sellers

Discovers emerging/high-growth sellers based on sales acceleration, level promotion velocity, new seller traction, and rating improvement. Useful for finding potential partners.

Endpoint Details

URL: /api/sellers/emerging/

Query Parameters

Parameter Type Required Description
page Integer No Page number (default: 1)
days Integer No Lookback days (default: 30, max: 180)

Example Request

curl -X GET "/api/sellers/emerging/?days=30" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "count": 15,
  "next": "http://localhost:8000/api/products/sellers/emerging/?page=2",
  "previous": null,
  "results": [
    {
      "seller_id": 789,
      "seller_name": "Rising Star Store",
      "seller_url": "https://www.mercadolibre.com.mx/tienda/risingstar",
      "registration_date": "2026-01-15T00:00:00Z",
      "growth_score": 85,
      "growth_level": "HIGH",
      "transactions_completed": 1200,
      "sales_completed": 800,
      "level_id": 4,
      "factors": {
        "sales_acceleration": 25.0,
        "level_promotion": 25.0,
        "new_seller_traction": 15.0,
        "rating_improvement": 20.0
      }
    }
  ]
}

Growth Level Definitions

  • HIGH: Score >= 70 - High growth potential
  • MEDIUM: Score >= 40 - Moderate growth
  • LOW: Score < 40 - Low growth

GET Seller Vitality

Composite vitality score combining reputation momentum, inventory health, fulfillment reliability, and power seller trajectory. Use to monitor seller health daily.

Endpoint Details

URL: /api/sellers/vitality/

Query Parameters

Parameter Type Required Description
seller_url String No Seller URL (partial match, case-insensitive). Use instead of seller_name
seller_name String No Seller name (partial match, case-insensitive). Use instead of seller_url
days Integer No Lookback days (default: 30, max: 180)

Example Request

curl -X GET "/api/sellers/vitality/?seller_url=mystore&days=30" \
  -H "Authorization: <Access-Token YOUR_TOKEN_HERE>"

Example Response

{
  "seller_id": 123,
  "seller_name": "My Store",
  "seller_url": "https://www.mercadolibre.com.mx/tienda/mystore",
  "vitality_score": 75,
  "vitality_level": "HEALTHY",
  "factors": {
    "reputation_momentum": 8.5,
    "inventory_health": 20,
    "fulfillment_reliability": 18.0,
    "power_seller_trajectory": 10
  },
  "latest_registry": {
    "level_id": 3,
    "power_seller_status": true,
    "transactions_completed": 1500
  },
  "days_analyzed": 30
}

Vitality Level Definitions

  • HEALTHY: Score >= 70 - Seller is thriving
  • AT_RISK: Score >= 40 - Needs attention
  • CRITICAL: Score < 40 - Immediate intervention needed

Getting Started

  1. Create a personal access token from the Create Token page.
  2. Copy your token immediately as it will not be shown again.
  3. Use the token in the Authorization header for API requests.
  4. Refer to this documentation for available endpoints and parameters.