BestPrice Agent Commerce · Schema
Bestprice Get Shopping Decision Output
ShoppingPrice ComparisonE-CommerceRetailMCPWebMCPAgentic CommerceGreeceProduct RecommendationsShopping DecisionsDelivered Price
JSON Schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"anyOf": [
{
"type": "object",
"properties": {
"schema_version": {
"$ref": "#/$defs/__schema0"
},
"as_of": {
"$ref": "#/$defs/__schema1"
},
"currency": {
"$ref": "#/$defs/__schema2"
},
"locale": {
"$ref": "#/$defs/__schema3"
},
"warnings": {
"$ref": "#/$defs/__schema4"
},
"brain": {
"type": "object",
"properties": {
"projection_version": {
"type": "string",
"pattern": "^bestprice_mcp_decision_v[1-9][0-9]*$",
"description": "Version of this MCP projection of the decision. Currently bestprice_mcp_decision_v1; a later bestprice_mcp_decision_v<N> is returned without a tools/list change."
},
"decision_version": {
"type": "string",
"pattern": "^bestprice_decision_v[1-9][0-9]*$",
"description": "Shopping Brain decision contract version. Currently bestprice_decision_v1; a later bestprice_decision_v<N> is returned without a tools/list change."
},
"decision_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"evidence_fingerprint": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Fingerprint of the original, unmodified Brain evidence; the public evidence below is a returned-product subset."
}
},
"required": [
"projection_version",
"decision_version",
"decision_id",
"evidence_fingerprint"
]
},
"outcome": {
"type": "string",
"enum": [
"recommendation",
"no_match",
"clarification",
"answer",
"comparison",
"basket"
]
},
"status": {
"type": "string",
"enum": [
"ready",
"no_match",
"needs_input"
]
},
"answer": {
"type": "string",
"maxLength": 8000
},
"reason": {
"anyOf": [
{
"type": "string",
"maxLength": 160
},
{
"type": "null"
}
]
},
"message": {
"anyOf": [
{
"type": "string",
"maxLength": 8000
},
{
"type": "null"
}
]
},
"blocking_constraints": {
"maxItems": 24,
"type": "array",
"items": {
"$ref": "#/$defs/__schema6"
}
},
"near_miss": {
"type": "object",
"properties": {
"over_by_eur": {
"type": "number"
}
},
"required": [
"over_by_eur"
]
},
"recommended_product_id": {
"anyOf": [
{
"$ref": "#/$defs/__schema7"
},
{
"type": "null"
}
]
},
"alternatives": {
"maxItems": 2,
"type": "array",
"items": {
"$ref": "#/$defs/__schema8"
}
},
"products": {
"maxItems": 4,
"type": "array",
"items": {
"$ref": "#/$defs/__schema28"
}
},
"constraints": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/__schema36"
},
"additionalProperties": {
"$ref": "#/$defs/__schema37"
}
},
"reasons": {
"maxItems": 24,
"type": "array",
"items": {
"$ref": "#/$defs/__schema38"
}
},
"tradeoffs": {
"maxItems": 24,
"type": "array",
"items": {
"$ref": "#/$defs/__schema39"
}
},
"offer_summary": {
"$ref": "#/$defs/__schema9"
},
"comparison": {
"anyOf": [
{
"type": "object",
"properties": {
"comparison_type": {
"type": "string",
"enum": [
"specifications",
"delivered_cost"
]
},
"evaluation": {
"type": "string",
"enum": [
"selected",
"no_eligible_compared_product",
"not_evaluated_budget",
"unavailable"
]
},
"products": {
"minItems": 2,
"maxItems": 4,
"type": "array",
"items": {
"$ref": "#/$defs/__schema40"
}
},
"feature_rows": {
"maxItems": 12,
"type": "array",
"items": {
"$ref": "#/$defs/__schema42"
}
},
"price_spread_eur": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"$ref": "#/$defs/__schema10"
},
{
"type": "null"
}
]
},
"warnings": {
"$ref": "#/$defs/__schema4"
},
"as_of": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "null"
}
]
}
},
"required": [
"comparison_type",
"products",
"feature_rows",
"price_spread_eur",
"postal_code",
"warnings",
"as_of"
]
},
{
"type": "null"
}
]
},
"basket": {
"anyOf": [
{
"type": "object",
"properties": {
"schema_version": {
"$ref": "#/$defs/__schema0"
},
"as_of": {
"$ref": "#/$defs/__schema1"
},
"currency": {
"$ref": "#/$defs/__schema2"
},
"locale": {
"$ref": "#/$defs/__schema3"
},
"warnings": {
"$ref": "#/$defs/__schema4"
},
"preferred_plan": {
"anyOf": [
{
"type": "string",
"enum": [
"cheapest",
"fewer_merchants",
"balanced"
]
},
{
"type": "null"
}
]
},
"methodology_id": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*_v[1-9][0-9]*$",
"description": "Basket planning method. Currently bestprice_basket_bounded_v1; a revised method is returned as a new <name>_v<N> id without a tools/list change."
},
"plans": {
"maxItems": 3,
"type": "array",
"items": {
"$ref": "#/$defs/__schema44"
}
},
"unavailable_items": {
"maxItems": 20,
"type": "array",
"items": {
"$ref": "#/$defs/__schema7"
}
}
},
"required": [
"schema_version",
"as_of",
"currency",
"locale",
"warnings",
"preferred_plan",
"methodology_id",
"plans",
"unavailable_items"
]
},
{
"type": "null"
}
]
},
"basket_request": {
"anyOf": [
{
"type": "object",
"properties": {
"version": {
"type": "string",
"pattern": "^bestprice_basket_request_v[1-9][0-9]*$",
"description": "Basket request version. Currently bestprice_basket_request_v1; a later bestprice_basket_request_v<N> is returned without a tools/list change."
},
"requested_slots": {
"maxItems": 20,
"type": "array",
"items": {
"$ref": "#/$defs/__schema48"
}
},
"resolved_slots": {
"maxItems": 20,
"type": "array",
"items": {
"$ref": "#/$defs/__schema50"
}
},
"unresolved_slots": {
"maxItems": 20,
"type": "array",
"items": {
"$ref": "#/$defs/__schema52"
}
},
"total_budget_eur": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1000000
},
{
"type": "null"
}
]
}
},
"required": [
"version",
"requested_slots",
"resolved_slots",
"unresolved_slots",
"total_budget_eur"
]
},
{
"type": "null"
}
]
},
"clarifications": {
"maxItems": 3,
"type": "array",
"items": {
"$ref": "#/$defs/__schema53"
}
},
"price_verdict": {
"type": "object",
"properties": {
"verdict": {
"type": "string",
"enum": [
"good",
"typical",
"high",
"insufficient_evidence"
]
},
"reason": {
"type": "string",
"maxLength": 100
},
"source_ids": {
"maxItems": 32,
"type": "array",
"items": {
"$ref": "#/$defs/__schema54"
}
},
"predicts_future_price": {
"type": "boolean",
"const": false
}
},
"required": [
"verdict",
"reason",
"source_ids",
"predicts_future_price"
]
},
"next_action": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"compare",
"create_alert",
"provide_context"
],
"description": "Advisory step for the shopper, never an action for the agent. compare: review current offers at bestprice_url. create_alert: the current price is above its typical 180-day price; the shopper may set a price alert on the BestPrice page at bestprice_url (no tool creates alerts). provide_context: the request needs a change or more detail from the shopper."
},
"reason": {
"type": "string",
"maxLength": 100
},
"requires_user_action": {
"type": "boolean",
"const": true
},
"bestprice_url": {
"anyOf": [
{
"$ref": "#/$defs/__schema34"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"reason",
"requires_user_action",
"bestprice_url"
]
},
"ranking_policy": {
"type": "object",
"properties": {
"version": {
"type": "string",
"pattern": "^bestprice_shopping_policy_v[1-9][0-9]*$",
"description": "Ranking policy version. Currently bestprice_shopping_policy_v1; a later bestprice_shopping_policy_v<N> is returned without a tools/list change."
},
"product": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*$",
"description": "Product ranking rule. Known values: hard_constraints_then_fit_and_marginal_value. New values are added without a tools/list change."
},
"merchant": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*$",
"description": "Merchant ranking rule. Known values: lowest_known_comparable_cost, basket_objective. New values are added without a tools/list change."
},
"commercial_signals_used": {
"type": "boolean",
"const": false
}
},
"required": [
"version",
"product",
"merchant",
"commercial_signals_used"
]
},
"retrieval": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"enum": [
"returned_page",
"exact_products",
"not_searched"
]
},
"candidate_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"complete_catalog": {
"type": "boolean",
"const": false
},
"search_calls": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"receipt": {
"anyOf": [
{
"type": "object",
"properties": {
"version": {
"type": "string",
"pattern": "^bestprice_retrieval_v[1-9][0-9]*$",
"description": "Retrieval receipt version. Currently bestprice_retrieval_v1; a later bestprice_retrieval_v<N> is returned without a tools/list change."
},
"policy": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*_v[1-9][0-9]*$",
"description": "Catalog retrieval policy. Currently single_catalog_page_v1; a revised method is returned as a new <name>_v<N> id without a tools/list change."
},
"backend": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_-]*)*$",
"description": "Catalog search backend that served the page. Known values: n.products.search, bp.search. New values are added without a tools/list change."
},
"checked_at": {
"$ref": "#/$defs/__schema55"
},
"source_observed_at": {
"anyOf": [
{
"$ref": "#/$defs/__schema55"
},
{
"type": "null"
}
]
},
"search_calls": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Catalog searches the retrieval policy made; currently always 1."
},
"trinity_calls": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"page": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"page_size": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"catalog_total": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"candidate_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"eligible_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"returned_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"category_id": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"protected_term_mismatch": {
"type": "boolean"
},
"ranking_scope": {
"type": "string",
"const": "returned_page"
}
},
"required": [
"version",
"policy",
"backend",
"checked_at",
"source_observed_at",
"search_calls",
"trinity_calls",
"page",
"page_size",
"catalog_total",
"candidate_count",
"eligible_count",
"returned_count",
"category_id",
"protected_term_mismatch",
"ranking_scope"
]
},
{
"type": "null"
}
]
}
},
"required": [
"scope",
"candidate_count",
"complete_catalog",
"search_calls",
"receipt"
]
},
"shopping_context": {
"type": "object",
"properties": {
"version": {
"type": "string",
"pattern": "^bestprice_shopping_context_v[1-9][0-9]*$",
"description": "Shopping-context projection version. Currently bestprice_shopping_context_v29; a later bestprice_shopping_context_v<N> is returned without a tools/list change."
},
"products": {
"maxItems": 48,
"type": "array",
"items": {
"$ref": "#/$defs/__schema56"
}
},
"market": {
"maxItems": 48,
"type": "array",
"items": {
"$ref": "#/$defs/__schema61"
}
}
},
"required": [
"version",
"products",
"market"
]
},
"search_handoff": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"required": [
"url",
"label"
]
},
"catalog_candidates": {
"type": "object",
"properties": {
"basis": {
"$ref": "#/$defs/__schema67"
},
"note": {
"$ref": "#/$defs/__schema68"
},
"query": {
"$ref": "#/$defs/__schema69"
},
"price_min_eur": {
"$ref": "#/$defs/__schema70"
},
"price_max_eur": {
"$ref": "#/$defs/__schema71"
},
"products": {
"$ref": "#/$defs/__schema72"
}
},
"required": [
"basis",
"note",
"query",
"price_min_eur",
"price_max_eur",
"products"
],
"description": "Present only on a no_match that returns no product: one bounded BestPrice catalog search page for the request, with signed product links. Search results, not a recommendation; the Shopping Brain did not rank or verify them against the request."
},
"evidence": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"const": "returned_products"
},
"detail": {
"type": "string",
"const": "summary"
},
"note": {
"type": "string",
"maxLength": 400
},
"omitted_claim_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"omitted_source_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sources": {
"maxItems": 256,
"type": "array",
"items": {
"$ref": "#/$defs/__schema75"
}
},
"claims": {
"maxItems": 2048,
"type": "array",
"items": {
"$ref": "#/$defs/__schema76"
}
}
},
"required": [
"scope",
"sources",
"claims"
]
},
"uncertainty": {
"maxItems": 64,
"type": "array",
"items": {
"$ref": "#/$defs/__schema79"
}
}
},
"required": [
"schema_version",
"as_of",
"currency",
"locale",
"warnings",
"brain",
"outcome",
"status",
"answer",
"reason",
"message",
"blocking_constraints",
"recommended_product_id",
"alternatives",
"products",
"constraints",
"reasons",
"tradeoffs",
"offer_summary",
"comparison",
"basket",
"basket_request",
"clarifications",
"price_verdict",
"next_action",
"ranking_policy",
"retrieval",
"shopping_context",
"evidence",
"uncertainty"
]
},
{
"type": "object",
"properties": {
"schema_version": {
"$ref": "#/$defs/__schema0"
},
"as_of": {
"$ref": "#/$defs/__schema1"
},
"currency": {
"$ref": "#/$defs/__schema2"
},
"locale": {
"$ref": "#/$defs/__schema3"
},
"warnings": {
"$ref": "#/$defs/__schema4"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Z][A-Z0-9_]{2,63}$"
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message",
"retryable"
]
}
},
"required": [
"schema_version",
"as_of",
"currency",
"locale",
"warnings",
"error"
]
}
],
"$defs": {
"__schema0": {
"type": "string",
"pattern": "^[1-9][0-9]*\\.[0-9]+$",
"description": "Result schema version. Currently 2.0; a later <major>.<minor> is returned without a tools/list change."
},
"__schema1": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"__schema2": {
"type": "string",
"const": "EUR"
},
"__schema3": {
"type": "string",
"const": "el-GR"
},
"__schema4": {
"maxItems": 20,
"type": "array",
"items": {
"$ref": "#/$defs/__schema5"
}
},
"__schema5": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"__schema6": {
"type": "string",
"maxLength": 200
},
"__schema7": {
"type": "string",
"pattern": "^bp_[0-9]{10}$"
},
"__schema8": {
"type": "object",
"properties": {
"product_id": {
"$ref": "#/$defs/__schema7"
},
"label": {
"type": "string",
"maxLength": 240
},
"tradeoff": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
},
"requires_constraint_change": {
"type": "boolean"
},
"offer_summary": {
"$ref": "#/$defs/__schema9"
}
},
"required": [
"product_id",
"label",
"tradeoff",
"requires_constraint_change",
"offer_summary"
]
},
"__schema9": {
"anyOf": [
{
"type": "object",
"properties": {
"postal_code": {
"anyOf": [
{
"$ref": "#/$defs/__schema10"
},
{
"type": "null"
}
]
},
"price_basis": {
"type": "string",
"enum": [
"item_price",
"delivered_total"
]
},
"affordability": {
"type": "string",
"enum": [
"unknown",
"not_requested",
"over_budget",
"within_delivered_budget",
"within_item_budget_delivery_unknown"
]
},
"offer_scope": {
"type": "string",
"const": "returned_sample"
},
"delivery_affordability_proven": {
"type": "boolean"
},
"recommended": {
"anyOf": [
{
"$ref": "#/$defs/__schema11"
},
{
"type": "null"
}
]
},
"cheapest": {
"anyOf": [
{
"$ref": "#/$defs/__schema11"
},
{
"type": "null"
}
]
},
"same_offer": {
"type": "boolean"
},
"recommendation_reason": {
"anyOf": [
{
"type": "string",
"maxLength": 240
},
{
"type": "null"
}
]
},
"budget_eur": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
},
"recommended_within_budget": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cheapest_within_budget": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"compared_offer_count": {
"type": "integer",
"minimum": 0,
"maximum": 10
},
"unknown_shipping_count": {
"type": "integer",
"minimum": 0,
"maximum": 10
}
},
"required": [
"postal_code",
"price_basis",
"recommended",
"cheapest",
"same_offer",
"recommendation_reason",
"budget_eur",
"recommended_within_budget",
"cheapest_within_budget",
"compared_offer_count",
"unknown_shipping_count"
]
},
{
"type": "null"
}
]
},
"__schema10": {
"type": "string",
"pattern": "^(?:[1-7][0-9]{4}|8[0-5][0-9]{3})$"
},
"__schema11": {
"type": "object",
"properties": {
"offer_id": {
"type": "string",
"pattern": "^bp_offer_[0-9]+$"
},
"merchant_id": {
"anyOf": [
{
"type": "string",
"pattern": "^bp_merchant_[0-9]+$"
},
{
"type": "null"
}
]
},
"merchant_name": {
"$ref": "#/$defs/__schema12"
},
"merchant_logo_url": {
"description": "BestPrice CDN logo of the store; null when the store has none.",
"$ref": "#/$defs/__schema13"
},
"merchant_rating": {
"$ref": "#/$defs/__schema14"
},
"merchant_rating_count": {
"$ref": "#/$defs/__schema15"
},
"verified_merchant": {
"$ref": "#/$defs/__schema16"
},
"certification_level": {
"$ref": "#/$defs/__schema17"
},
"item_price": {
"$ref": "#/$defs/__schema19"
},
"shipping_price": {
"$ref": "#/$defs/__schema21"
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bestprice/refs/heads/main/json-schema/bestprice-get-shopping-decision-output.json
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/bestprice-get-shopping-decision-output"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.