---
title: "Suggest cheaper similar products (by unit price)"
method: GET
path: "/v1/products/{id}/substitutes"
---

# Suggest cheaper similar products (by unit price)

`GET /v1/products/{id}/substitutes`

## Request

- Base URL: `https://supermcp.co.il`
- URL: `https://supermcp.co.il/v1/products/{id}/substitutes`
- Auth: none required

## Path parameters

- `id` string, uuid, required

## Query parameters

- `city` string
- `near` string
- `location` string
- `radius_km` number
- `limit` integer
- `cheaper_only` boolean

## Response `200`

OK

- object
  - `data` object
    - `product` object
      - `id` string, uuid
      - `gtin` string, nullable
      - `name` string
      - `brand` string, nullable
      - `categoryL1` string, nullable
      - `categoryL2` string, nullable
      - `sizeQty` number, nullable
      - `sizeUnit` string, nullable
      - `pieceCount` number, nullable
    - `baseline` object
      - `bestUnitPrice` number, nullable
      - `unitBasis` 'per_100g' | 'per_100ml' | 'per_unit' | 'unknown'
      - `currency` string
      - `storeId` string, uuid, nullable
      - `storeName` string, nullable
    - `substitutes` object[]
      - `product` object
        - `id` string, uuid
        - `gtin` string, nullable
        - `name` string
        - `brand` string, nullable
        - `categoryL1` string, nullable
        - `categoryL2` string, nullable
        - `sizeQty` number, nullable
        - `sizeUnit` string, nullable
        - `pieceCount` number, nullable
      - `bestUnitPrice` number
      - `unitBasis` 'per_100g' | 'per_100ml' | 'per_unit' | 'unknown'
      - `currency` string
      - `storeId` string, uuid
      - `storeName` string
      - `chainId` string
      - `chainName` string
      - `distanceKm` number, nullable
      - `unitPriceSaving` number, nullable
      - `matchReason` 'same_category' | 'similar_name' | 'same_category_and_name'

## Other responses

- `400`: Bad request. Query parameters are validated strictly: a parameter this document does not list is rejected, and `details[].keys` names it. A misspelled filter used to be dropped silently, which answered a question nobody asked with a plausible list of products.
- `401`: Unauthorized
- `404`: Not found
- `429`: Rate limited

---

[API](https://skmtc.dev/supermcp/apis/super-mcp-api.md) · [All operations](https://skmtc.dev/supermcp/apis/super-mcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/supermcp/apis/super-mcp-api/revisions/f0dea9415b1c?raw)