---
title: "Price a shopping list for delivery across online storefronts"
method: POST
path: "/v1/delivery/optimize"
tags: ["delivery"]
---

# Price a shopping list for delivery across online storefronts

`POST /v1/delivery/optimize`

## Request

- Base URL: `https://supermcp.co.il`
- URL: `https://supermcp.co.il/v1/delivery/optimize`
- Auth: none required

Prices a whole basket at every Israeli online supermarket that delivers to an address and ranks them on what the ORDER costs, not what the goods cost. Online prices are not shelf prices: a chain's website runs its own price book (measured: Rami Levy's online store shares 22% of its prices with its own branches; Carrefour's runs ~8% below its shelves), so every figure comes from the storefront's own regulated feed rows. Storefronts that do not serve the address, sit below the minimum order, or have published no fresh prices for over a week, are returned in unavailableStores with a reason rather than dropped.

## Request body

- object: Either an initial request (items, with or without a destination) or a resume: {continuation, answers}, plus a destination when answering a needs_destination reply.
  - `items` object[]
    - `product_id` string, uuid
    - `gtin` string
    - `query` string
    - `unit` string: Required with amount: kg, g, L, ml, unit, יח, etc. Do not pair mass/volume units with pack_qty.
  - `address` string: Delivery address in Israel, free text, e.g. 'מנדלסון 1, תל אביב'. Preferred: a storefront whose service area is a polygon or a depot radius can only be tested against a located point.
  - `city` string: Hebrew or English city (or CBS locality code). Enough for a chain that publishes a settlement list; not enough for a polygon or radius service area.
  - `near` string: 'lat,lng', e.g. '32.078,34.774'. Do not combine with address.
  - `preference` 'cheapest' | 'balanced': cheapest takes the lowest delivered figure outright; balanced (default) prefers a storefront whose terms we verified when the money is close.
  - `slot_type` 'standard' | 'pickup': standard (default) is delivery to the door; pickup is click-and-collect, cheaper where offered but the shopper travels. These are the only two slots any storefront publishes.
  - `memberships` string[]: Cards or subscriptions the shopper holds that unlock a cheaper rate.
  - `max_split_stores` integer: How many storefronts the returned splitOrder may spread the list over. Default 2. A third adds a third delivery fee, so it only wins when it reaches items the other two do not stock.
  - `include_club` boolean
  - `include_coupon` boolean
  - `resolution_mode` 'fast' | 'strict' | 'preview'
  - `response_detail` 'summary' | 'standard' | 'debug': How much per-line detail to return. summary gives every storefront's totals, fees and coverage but the lines[] breakdown only for the storefronts the recommendations name; standard returns lines for every storefront; debug adds resolution internals.
  - `intent` string: The shopper's own framing of this shop, in their own words, e.g. 'ברביקיו ל-12 אנשים'. Not a summary of the item list. Shown on the handoff page beside what was priced, so a shopper opening the link sees why they asked. Optional; omit rather than inventing one. Longer text is truncated rather than rejected.
  - `continuation` string: Opaque token from a needs_confirmation, preview or needs_destination reply. Send it with answers, or with a destination, and nothing else: the list travels inside it.
  - `answers` object[]
    - `item_index` integer, required
    - `product_id` string, uuid, required

## Response `200`

## 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)