<!-- https://pricto.dev/docs/api/compare-prices · Spanish version: https://pricto.dev/docs/api/compare-prices.md -->

# Compare a basket of products across retailers

`POST https://pricto.dev/v1/prices/compare`

Matrix of current prices for up to 50 products (by `product_id` or `gtin`) at each retailer, plus the basket total per retailer counting only retailers that have every item.

| Credits | MCP |
|---|---|
| 1 per price in the matrix (product × retailer with data) | [`compare_prices`](/docs/mcp#compare_prices) |

## Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `lang` | query | `string` | Response language as a BCP 47 tag (`es`, `es-CL`, `en`, `en-US`...). Supported today: es, en. An unsupported language falls back to English with a warning, never an error. Falls back to `Accept-Language`, then to the account default. The resolved value is in `meta.lang`. |
| `currency` | query | `string` | Add converted amounts in this ISO 4217 currency. `local` (default) returns source currency only. Default: `local`. |

## Body

| Field | Type | Description |
|---|---|---|
| `items` **required** | `ItemRef[]` |  |
| `items[].product_id` | `string` |  |
| `items[].gtin` | `string` |  |
| `items[].offer_id` | `string` |  |
| `items[].quantity` | `integer` | Compare only. |
| `retailers` | `string[]` |  |
| `location` | `string` |  |
| `max_credits` | `number` |  |
| `dry_run` | `boolean` |  |
| `min_confidence` | `number` |  |
| `match_kinds` | `string[]` |  |
| `price_type` | `string` | Which price to total. `card_price` falls back to `price` when there is no card price. Valores / values: `price`, `card_price`. |

## Response

`200` Price matrix and basket totals.

| Field | Type | Description |
|---|---|---|
| `data` **required** | `object` |  |
| `data.items` **required** | `object[]` |  |
| `data.items[].product` **required** | `ProductSummary` |  |
| `data.items[].product.id` **required** | `string` |  |
| `data.items[].product.name` **required** | `string` |  |
| `data.items[].product.brand` **required** | `BrandRef` |  |
| `data.items[].product.category` **required** | `CategoryRef` |  |
| `data.items[].product.size` | `object` |  |
| `data.items[].product.gtin` | `string[]` |  |
| `data.items[].product.image_url` | `string \| null` |  |
| `data.items[].product.price_summary` **required** | `PriceSummary` |  |
| `data.items[].product.score` | `number` | Relevance score, search only. |
| `data.items[].quantity` **required** | `integer` |  |
| `data.items[].prices` **required** | `object` | Map of retailer ID to price (null when the retailer does not carry it). |
| `data.retailers` **required** | `RetailerRef[]` |  |
| `data.retailers[].id` **required** | `string` |  |
| `data.retailers[].name` **required** | `string` |  |
| `data.totals` **required** | `object[]` | Basket total per retailer, cheapest first. |
| `data.totals[].retailer` **required** | `RetailerRef` |  |
| `data.totals[].retailer.id` **required** | `string` |  |
| `data.totals[].retailer.name` **required** | `string` |  |
| `data.totals[].total` **required** | `number` |  |
| `data.totals[].items_found` **required** | `integer` |  |
| `data.totals[].complete` **required** | `boolean` |  |
| `data.totals[].converted_total` | `number \| null` |  |
| `data.currency` | `string` |  |
| `data.not_found` | `ItemRef[]` |  |
| `data.not_found[].product_id` | `string` |  |
| `data.not_found[].gtin` | `string` |  |
| `data.not_found[].offer_id` | `string` |  |
| `data.not_found[].quantity` | `integer` | Compare only. |
| `meta` **required** | `Meta` |  |

`meta` carries the cost, the source line to quote, the language, the currency and notices (see [Conventions](/docs/convenciones)).

## Errors

- [`invalid_parameter`](/docs/errores#invalid_parameter)
- [`unauthorized`](/docs/errores#unauthorized)
- [`insufficient_credits`](/docs/errores#insufficient_credits)
- [`spend_cap_reached`](/docs/errores#spend_cap_reached)

## Example

```bash
curl -X POST "https://pricto.dev/v1/prices/compare" \
  -H "Authorization: Bearer sk_test_sandbox" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"product_id":"prd_01colu"},{"gtin":"2000070000373","quantity":2}]}'
```
```python
import requests

API_KEY = "sk_test_sandbox"

r = requests.post(
    "https://pricto.dev/v1/prices/compare",
    json={
        "items": [
            {
                "product_id": "prd_01colu",
            },
            {
                "gtin": "2000070000373",
                "quantity": 2,
            },
        ],
    },
    headers={"Authorization": f"Bearer {API_KEY}"},
)
print(r.status_code, r.json())
```
```js
const API_KEY = "sk_test_sandbox";

const res = await fetch("https://pricto.dev/v1/prices/compare", {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "items": [
      {
        "product_id": "prd_01colu"
      },
      {
        "gtin": "2000070000373",
        "quantity": 2
      }
    ]
  }),
});
console.log(res.status, await res.json());
```

```json
{
  "data": {
    "items": [
      {
        "product": {
          "id": "prd_01colu",
          "name": "Leche entera Colun 1 L",
          "brand": {
            "id": "colun",
            "name": "Colun"
          },
          "category": {
            "id": "food.dairy.milk",
            "label": "Leche",
            "path": [
              "Alimentos y bebidas",
              "Lácteos",
              "… 1 más / more"
            ]
          },
          "size": {
            "value": 1,
            "unit": "l",
            "pack_count": 1,
            "text": "1 L"
          },
          "gtin": [
            "2000070000007"
          ],
          "image_url": null,
          "price_summary": {
            "currency": "CLP",
            "min": 1090,
            "max": 1290,
            "median": 1190,
            "offers_count": 3,
            "retailers_count": 3,
            "best": {
              "retailer": {
                "id": "cl-unimarc",
                "name": "Unimarc"
              },
              "offer_id": "ofr_01nuni",
              "price": 1090
            },
            "observed_at": "2026-10-23T11:00:00Z"
          }
        },
        "quantity": 1,
        "prices": {
          "cl-unimarc": 1090,
          "cl-santaisabel": 1190,
          "cl-jumbo": 1290
        }
      },
      {
        "product": {
          "id": "prd_02sopr",
          "name": "Leche descremada Soprole 1 L",
          "brand": {
            "id": "soprole",
            "name": "Soprole"
          },
          "category": {
            "id": "food.dairy.milk",
            "label": "Leche",
            "path": [
              "Alimentos y bebidas",
              "Lácteos",
              "… 1 más / more"
            ]
          },
          "size": {
            "value": 1,
            "unit": "l",
            "pack_count": 1,
            "text": "1 L"
          },
          "gtin": [
            "2000070000373"
          ],
          "image_url": null,
          "price_summary": {
            "currency": "CLP",
            "min": 1190,
            "max": 1190,
            "median": 1190,
            "offers_count": 2,
            "retailers_count": 2,
            "best": {
              "retailer": {
                "id": "cl-jumbo",
                "name": "Jumbo"
              },
              "offer_id": "ofr_002jum",
              "price": 1190
            },
            "observed_at": "2026-10-23T11:00:00Z"
          }
        },
        "quantity": 2,
        "prices": {
          "cl-jumbo": 1190,
          "cl-santaisabel": 1190,
          "cl-unimarc": null
        }
      }
    ],
    "retailers": [
      {
        "id": "cl-jumbo",
        "name": "Jumbo"
      },
      {
        "id": "cl-santaisabel",
        "name": "Santa Isabel"
      },
      "… 1 más / more"
    ],
    "totals": [
      {
        "retailer": {
          "id": "cl-santaisabel",
          "name": "Santa Isabel"
        },
        "total": 3570,
        "items_found": 2,
        "complete": true,
        "converted_total": null
      },
      {
        "retailer": {
          "id": "cl-jumbo",
          "name": "Jumbo"
        },
        "total": 3670,
        "items_found": 2,
        "complete": true,
        "converted_total": null
      },
      "… 1 más / more"
    ],
    "currency": "CLP",
    "not_found": []
  },
  "meta": {
    "request_id": "req_5ba95ca646344b2c8f03",
    "attribution": {
      "text": "Fuente: Pricto · 23-10-2026 08:00 CLST",
      "source": "Pricto",
      "as_of": "2026-10-23T11:00:00Z",
      "resource_id": null,
      "url": null,
      "capture_method": null,
      "source_url": null
    },
    "credits_charged": 2,
    "credits_deduplicated": 3,
    "credits_remaining": 14989,
    "period_resets_at": "2026-11-01T00:00:00.000Z",
    "usage": {
      "credits_charged": 2,
      "credits_deduplicated": 3,
      "truncated": false,
      "truncated_reason": null,
      "dry_run": false,
      "units": {
        "offers": 5
      }
    },
    "lang": "es",
    "currency": "local",
    "data_as_of": "2026-10-23T11:00:00Z",
    "location": null,
    "warnings": [
      "synthetic_data: datos sintéticos de ejemplo / synthetic sample data"
    ]
  }
}
```