GET /product-related-products

Related Products

Get up to 10 products Mercadona suggests alongside a given product, with prices and availability for any Spanish postal code.

Mercadona API

Returns the products Mercadona suggests alongside a given product, up to 10, in Mercadona’s own order. These are cross-sell suggestions (for example olive oils shown next to a salt), not variants of the same product. Each item is a product row with price, unit price and availability for the resolved warehouse. To get more than 10, pass the ids you have already seen in exclude and the list is filled back up with the next suggestions.

HTTP Request

GET /product-related-products

Parameters

ParameterTypeRequiredDefaultDescription
product_idstringYes-Mercadona product id, passed verbatim. Unknown ids return an empty list
excludestringNo-Comma-separated product ids to leave out. The list is filled back up to 10 with the next suggestions. To page, pass every product_id received so far and repeat until fewer than 10 come back
postal_codestringNo-Spanish 5-digit postal code. Resolved to the warehouse that serves that address and takes precedence over warehouse
warehousestringNovlc1Hub or 4-digit store code from /warehouses . Ignored when postal_code is given
languagestringNoeses, en or ca. Translates product names and category names
freshbooleanNofalseBypass the 10-minute cache and fetch live data

Response

Request: GET /product-related-products?product_id=10381. The items array is trimmed to 2 of 10.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107

{
  "status": true,
  "request_id": "1d3eb054-ee9d-85a0-b9d5-7dc7af4f",
  "cached_at": null,
  "data": {
    "items": [
      {
        "product_id": "10382",
        "name": "Leche semidesnatada Hacendado",
        "slug": "leche-semidesnatada-hacendado-brick",
        "url": "https://tienda.mercadona.es/product/10382/leche-semidesnatada-hacendado-brick",
        "thumbnail": "https://prod-mercadona.imgix.net/images/5a14472b53ac7a848fc8220982694c4a.jpg?fit=crop&h=300&w=300",
        "packaging": "Brik",
        "main_feature": null,
        "is_water": false,
        "requires_age_check": false,
        "category": {
          "category_id": 6,
          "name": "Huevos, leche y mantequilla"
        },
        "availability": {
          "in_stock": true,
          "status": null,
          "unavailable_from": null,
          "unavailable_weekdays": [],
          "order_limit": 999
        },
        "price": "0.83",
        "price_value": 0.83,
        "previous_price": null,
        "previous_price_value": null,
        "is_price_drop": false,
        "unit_price": "0.830",
        "unit_price_value": 0.83,
        "unit_price_format": "L",
        "bulk_price_value": 0.83,
        "size_format": "l",
        "unit_size": 1.0,
        "is_pack": false,
        "pack_size": null,
        "total_units": null,
        "unit_name": null,
        "iva_percent": 4,
        "approx_size": false,
        "drained_weight": null,
        "currency": "EUR",
        "color_variants": null,
        "warehouse": "vlc1"
      },
      {
        "product_id": "10794",
        "name": "Leche semidesnatada Hacendado",
        "slug": "leche-semidesnatada-hacendado-pack-6",
        "url": "https://tienda.mercadona.es/product/10794/leche-semidesnatada-hacendado-pack-6",
        "thumbnail": "https://prod-mercadona.imgix.net/images/f16c6d550a0a4236222a7dfdea3017ca.jpg?fit=crop&h=300&w=300",
        "packaging": "Pack-6",
        "main_feature": null,
        "is_water": false,
        "requires_age_check": false,
        "category": {
          "category_id": 6,
          "name": "Huevos, leche y mantequilla"
        },
        "availability": {
          "in_stock": true,
          "status": null,
          "unavailable_from": null,
          "unavailable_weekdays": [],
          "order_limit": 999
        },
        "price": "1.64",
        "price_value": 1.64,
        "previous_price": null,
        "previous_price_value": null,
        "is_price_drop": false,
        "unit_price": "1.367",
        "unit_price_value": 1.37,
        "unit_price_format": "L",
        "bulk_price_value": 1.37,
        "size_format": "l",
        "unit_size": 1.2,
        "is_pack": true,
        "pack_size": 0.2,
        "total_units": 6,
        "unit_name": "mini briks",
        "iva_percent": 4,
        "approx_size": false,
        "drained_weight": null,
        "currency": "EUR",
        "color_variants": null,
        "warehouse": "vlc1"
      }
    ],
    "total": 10,
    "resolved_filters": {
      "warehouse": {
        "input": null,
        "resolved": "vlc1",
        "source": "default"
      }
    },
    "language": "es"
  },
  "request_params": {
    "product_id": "10381"
  }
}

Response Fields

FieldTypeDescription
statusbooleantrue when the request succeeded
request_idstringUnique request identifier
cached_atstring | nullISO timestamp when the answer came from cache, null when fetched for this request
dataobjectResponse payload
data.items[]arrayUp to 10 suggested products, in Mercadona’s order
data.items[].product_idstringMercadona product id. Pass it verbatim: decimal ids like 81241.3 exist
data.items[].namestringProduct name, translated with language
data.items[].slugstringURL slug of the product page
data.items[].urlstringProduct URL on tienda.mercadona.es
data.items[].thumbnailstringProduct image URL (300x300)
data.items[].packagingstring | nullPackaging label, e.g. "Pack-6" or "Brik"
data.items[].main_featurestring | nullHighlighted feature, when Mercadona sets one
data.items[].is_waterbooleanWater product flag
data.items[].requires_age_checkbooleanAlcohol or other age-restricted product
data.items[].categoryobjectLevel-0 category of the product
data.items[].category.category_idintegerLevel-0 category id
data.items[].category.namestringLevel-0 category name, translated with language
data.items[].availabilityobjectAvailability at the resolved warehouse
data.items[].availability.in_stockbooleanIn stock at the resolved warehouse
data.items[].availability.statusstring | nullRestriction status, null when unrestricted
data.items[].availability.unavailable_fromstring | nullDate the product stops being available
data.items[].availability.unavailable_weekdaysarrayWeekdays the product can’t be delivered
data.items[].availability.order_limitintegerMaximum units per order, e.g. 999
data.items[].pricestringDisplay price in euros, e.g. "4.98"
data.items[].price_valuefloatNumeric price in euros
data.items[].previous_pricestring | nullPrevious display price, null when there is none
data.items[].previous_price_valuefloat | nullPrevious numeric price
data.items[].is_price_dropbooleantrue when the current price is below the previous price (computed by the API, not a Mercadona flag)
data.items[].unit_pricestringDisplay unit price, e.g. "0.830"
data.items[].unit_price_valuefloatNumeric unit price
data.items[].unit_price_formatstringUnit the unit price refers to, e.g. "L" or "kg"
data.items[].bulk_price_valuefloatBulk price
data.items[].size_formatstringSize unit, e.g. "l"
data.items[].unit_sizefloatSize expressed in size_format units
data.items[].is_packbooleanProduct is sold as a pack
data.items[].pack_sizefloat | nullSize of each unit in the pack
data.items[].total_unitsinteger | nullNumber of units in the pack
data.items[].unit_namestring | nullName of each unit, e.g. "briks"
data.items[].iva_percentintegerVAT percentage
data.items[].approx_sizebooleanSize is approximate
data.items[].drained_weightfloat | nullDrained weight, for canned or preserved products
data.items[].currencystringAlways "EUR"
data.items[].color_variantsarray | nullColour variants, null when the product has none
data.items[].warehousestringWarehouse that answered for this row
data.totalintegerNumber of items returned
data.resolved_filtersobjectWhat your filters resolved to
data.resolved_filters.warehouseobjectWarehouse resolution
data.resolved_filters.warehouse.inputstring | nullThe postal_code or warehouse you sent, null when neither was sent
data.resolved_filters.warehouse.resolvedstringWarehouse that answered, e.g. vlc1
data.resolved_filters.warehouse.sourcestringpostal_code, param or default
data.languagestringLanguage used
request_paramsobjectQuery parameters you sent, echoed back as strings

Fields not included. Related product rows have no ean, brand, category_path or popularity_score. Call /product-details with the product_id when you need them.

Error Responses

An unknown product_id is not an error: you get status: true with an empty data.items list, not a not-found envelope.

Invalid input returns HTTP 400 with error as a plain string, not an object, naming the parameter that failed validation.

Status CodeCauseDescription
400Missing product_idproduct_id is required
400Invalid warehouseMust be a hub code (3 letters + 1 digit) or a 4-digit store code
200 with 0 itemsUnknown product_idCheck the id. Decimal ids like 81241.3 must be passed verbatim

Code Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import requests

url = "https://mercadona-api.p.rapidapi.com/product-related-products"

params = {
    "product_id": "10381",
    "postal_code": "08001"
}

headers = {
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "mercadona-api.p.rapidapi.com"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()["data"]

print(f"{data['total']} related products")
for item in data["items"]:
    print(f"{item['product_id']} {item['name']}: {item['price']} EUR, in stock: {item['availability']['in_stock']}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

const url = "https://mercadona-api.p.rapidapi.com/product-related-products";

const params = new URLSearchParams({
  product_id: "10381",
  postal_code: "08001"
});

const response = await fetch(`${url}?${params}`, {
  headers: {
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "mercadona-api.p.rapidapi.com"
  }
});

const { data } = await response.json();
for (const item of data.items) {
  console.log(`${item.product_id} ${item.name}: ${item.price} EUR (${item.packaging})`);
}

1
2
3
4
5

curl -G "https://mercadona-api.p.rapidapi.com/product-related-products" \
  --data-urlencode "product_id=10381" \
  --data-urlencode "postal_code=08001" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "X-RapidAPI-Host: mercadona-api.p.rapidapi.com"
Previous Category Tree
Next Product Details
Start building today

Get your API key and make your first request in under a minute.

Get Your API Key on RapidAPI