BuyRecord
US product return policies, recalls and, as stores join, verified purchase outcomes for AI agents.
我該用這個嗎
品質與安全性
B
發現項目（3）
- LOWTool 'get_product_outcomes' description lacks action verb在 get_product_outcomes 中
- LOWTool 'compare_products' description lacks action verb在 compare_products 中
- LOWTool 'get_merchant_profile' description lacks action verb在 get_merchant_profile 中
根據工具定義與協定合規性的自動化分析。
上下文成本
~6,107Token（工具定義）
~14.5 KB典型回應大小
顯著的注意力影響（128k 上下文的 4.77%）
這是每次將伺服器的工具載入模型上下文時所消耗的約略 token 數量。數量越高，可用於其他工作的注意力就越少。
安裝
一鍵安裝
將以下內容加入你的 `claude_desktop_config.json` 檔案：
{
"mcpServers": {
"buyrecord": {
"url": "https://api.buyrecord.app/mcp"
}
}
}遠端端點
https://api.buyrecord.app/mcpstreamable-http它能做什麼
工具清單
工具（5）
🟢 唯讀🟡 寫入🔴 刪除⚪ 未知
🟢search_products(query, category, limit)
Products matching a name, GTIN or SKU: verified outcome summary, plus price, availability, rating and return policy as published on the merchant's site (labelled not verified).
輸入結構描述
{
"type": "object",
"properties": {
"query": {
"description": "Name, GTIN or SKU.",
"maxLength": 100,
"minLength": 2,
"title": "Query",
"type": "string"
},
"category": {
"anyOf": [
{
"maxLength": 50,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "home_kitchen, apparel, beauty, health, jewelry, toys_baby, sports_outdoors, electronics, pets, food_drink, arts_crafts, garden, automotive, office, other",
"title": "Category"
},
"limit": {
"default": 10,
"maximum": 50,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"required": [
"query"
],
"title": "search_productsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"products": {
"items": {
"$ref": "#/$defs/Product"
},
"title": "Products",
"type": "array"
}
},
"required": [
"products"
],
"$defs": {
"MerchantPublishedRating": {
"description": "Average rating and review count the merchant publishes on its own product page (schema.org\nAggregateRating). Not verified by BuyRecord and never part of the verified score.",
"properties": {
"average": {
"description": "Out of 5.",
"title": "Average",
"type": "number"
},
"count": {
"title": "Count",
"type": "integer"
},
"label": {
"const": "published on the merchant's site, not verified",
"default": "published on the merchant's site, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"average",
"count"
],
"title": "MerchantPublishedRating",
"type": "object"
},
"OutcomeSummary": {
"properties": {
"score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "0 to 100. Null when sample_size is below min_sample.",
"title": "Score"
},
"sample_size": {
"title": "Sample Size",
"type": "integer"
},
"min_sample": {
"title": "Min Sample",
"type": "integer"
},
"confidence": {
"anyOf": [
{
"enum": [
"low",
"medium",
"high"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "low under 10 verified outcomes, medium under 30, high from 30. Null when no score is shown.",
"title": "Confidence"
},
"top_reasons": {
"items": {
"enum": [
"size",
"quality",
"not_as_described",
"late_delivery",
"damaged",
"other"
],
"type": "string"
},
"title": "Top Reasons",
"type": "array"
}
},
"required": [
"score",
"sample_size",
"min_sample",
"confidence",
"top_reasons"
],
"title": "OutcomeSummary",
"type": "object"
},
"Product": {
"properties": {
"id": {
"format": "uuid",
"title": "Id",
"type": "string"
},
"title": {
"description": "Product name as published by the merchant, cleaned and capped at 200 characters.",
"title": "Title",
"type": "string"
},
"gtin": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Gtin"
},
"url": {
"title": "Url",
"type": "string"
},
"category": {
"title": "Category",
"type": "string"
},
"price_band": {
"enum": [
"under_30",
"30_50",
"50_100",
"100_150",
"over_150",
"unknown"
],
"title": "Price Band",
"type": "string"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Lowest variant price in USD, as published by the merchant.",
"title": "Price"
},
"available": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Available"
},
"shop_domain": {
"title": "Shop Domain",
"type": "string"
},
"source": {
"description": "public_web: from the merchant's public site; no verified outcomes implied.",
"enum": [
"merchant_sync",
"email_receipt",
"public_web",
"merchant_reported"
],
"title": "Source",
"type": "string"
},
"outcomes": {
"$ref": "#/$defs/OutcomeSummary",
"description": "Verified purchase outcomes only."
},
"merchant_published_rating": {
"anyOf": [
{
"$ref": "#/$defs/MerchantPublishedRating"
},
{
"type": "null"
}
]
},
"store_policy": {
"anyOf": [
{
"$ref": "#/$defs/StorePolicy"
},
{
"type": "null"
}
]
},
"recalls": {
"description": "US CPSC recalls linked to this product.",
"items": {
"$ref": "#/$defs/Recall"
},
"title": "Recalls",
"type": "array"
},
"retailer_offers": {
"description": "Same GTIN at big retailers (official APIs). Not verified.",
"items": {
"$ref": "#/$defs/RetailerOffer"
},
"title": "Retailer Offers",
"type": "array"
}
},
"required": [
"id",
"title",
"gtin",
"url",
"category",
"price_band",
"price",
"available",
"shop_domain",
"source",
"outcomes",
"merchant_published_rating",
"store_policy"
],
"title": "Product",
"type": "object"
},
"Recall": {
"description": "A US CPSC recall linked to this product. match: 'upc' (exact barcode) or 'brand_and_name'.",
"properties": {
"recall_number": {
"title": "Recall Number",
"type": "string"
},
"recall_date": {
"format": "date",
"title": "Recall Date",
"type": "string"
},
"url": {
"description": "Official CPSC recall notice.",
"title": "Url",
"type": "string"
},
"match": {
"enum": [
"upc",
"brand_and_name"
],
"title": "Match",
"type": "string"
}
},
"required": [
"recall_number",
"recall_date",
"url",
"match"
],
"title": "Recall",
"type": "object"
},
"RetailerOffer": {
"description": "The same product (exact GTIN match) at a big retailer, from the retailer's official API. Not verified by\nBuyRecord, never part of the verified score, and never used to rank results.",
"properties": {
"retailer": {
"enum": [
"bestbuy",
"walmart"
],
"title": "Retailer",
"type": "string"
},
"retailer_name": {
"enum": [
"Best Buy",
"Walmart"
],
"title": "Retailer Name",
"type": "string"
},
"url": {
"description": "Product page at the retailer.",
"title": "Url",
"type": "string"
},
"affiliate_link": {
"description": "True when the url is an affiliate link: BuyRecord may earn a commission if a purchase follows. Commissions never affect which products are returned or their order.",
"title": "Affiliate Link",
"type": "boolean"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "USD, as returned by the retailer's API at fetched_at.",
"title": "Price"
},
"available": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Available"
},
"rating": {
"anyOf": [
{
"$ref": "#/$defs/RetailerRating"
},
{
"type": "null"
}
],
"description": "The retailer's customer rating (average and count only)."
},
"match": {
"const": "gtin",
"default": "gtin",
"title": "Match",
"type": "string"
},
"fetched_at": {
"format": "date-time",
"title": "Fetched At",
"type": "string"
},
"source": {
"const": "retailer_api",
"default": "retailer_api",
"title": "Source",
"type": "string"
},
"attribution": {
"description": "Data source, as the retailer's terms require.",
"title": "Attribution",
"type": "string"
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Retailer logo to show next to this data, when its terms require one.",
"title": "Logo Url"
},
"label": {
"const": "published by the retailer, not verified",
"default": "published by the retailer, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"retailer",
"retailer_name",
"url",
"affiliate_link",
"price",
"available",
"rating",
"fetched_at",
"attribution",
"logo_url"
],
"title": "RetailerOffer",
"type": "object"
},
"RetailerRating": {
"properties": {
"average": {
"description": "Out of 5.",
"title": "Average",
"type": "number"
},
"count": {
"title": "Count",
"type": "integer"
}
},
"required": [
"average",
"count"
],
"title": "RetailerRating",
"type": "object"
},
"StorePolicy": {
"description": "Return policy facts read from the store's public refund policy. Not verified by BuyRecord.",
"properties": {
"return_window_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Return Window Days"
},
"free_returns": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Free Returns"
},
"label": {
"const": "published on the merchant's site, not verified",
"default": "published on the merchant's site, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"return_window_days",
"free_returns"
],
"title": "StorePolicy",
"type": "object"
}
},
"title": "SearchResult"
}🟢get_product_outcomes(product_id)
Score, sample size, outcome breakdown and top return reasons for one product.
輸入結構描述
{
"type": "object",
"properties": {
"product_id": {
"format": "uuid",
"title": "Product Id",
"type": "string"
}
},
"required": [
"product_id"
],
"title": "get_product_outcomesArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"product_id": {
"format": "uuid",
"title": "Product Id",
"type": "string"
},
"title": {
"description": "Product name as published by the merchant, cleaned and capped at 200 characters.",
"title": "Title",
"type": "string"
},
"url": {
"title": "Url",
"type": "string"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Price"
},
"available": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Available"
},
"source": {
"enum": [
"merchant_sync",
"email_receipt",
"public_web",
"merchant_reported"
],
"title": "Source",
"type": "string"
},
"merchant_published_rating": {
"anyOf": [
{
"$ref": "#/$defs/MerchantPublishedRating"
},
{
"type": "null"
}
]
},
"store_policy": {
"anyOf": [
{
"$ref": "#/$defs/StorePolicy"
},
{
"type": "null"
}
]
},
"recalls": {
"description": "US CPSC recalls linked to this product.",
"items": {
"$ref": "#/$defs/Recall"
},
"title": "Recalls",
"type": "array"
},
"retailer_offers": {
"description": "Same GTIN at big retailers (official APIs). Not verified.",
"items": {
"$ref": "#/$defs/RetailerOffer"
},
"title": "Retailer Offers",
"type": "array"
},
"score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "0 to 100. Null when sample_size is below min_sample.",
"title": "Score"
},
"sample_size": {
"title": "Sample Size",
"type": "integer"
},
"min_sample": {
"title": "Min Sample",
"type": "integer"
},
"confidence": {
"anyOf": [
{
"enum": [
"low",
"medium",
"high"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "low under 10 verified outcomes, medium under 30, high from 30. Null when no score is shown.",
"title": "Confidence"
},
"breakdown": {
"additionalProperties": {
"type": "integer"
},
"propertyNames": {
"enum": [
"kept_silent",
"kept_positive",
"complained",
"returned"
]
},
"title": "Breakdown",
"type": "object"
},
"top_reasons": {
"items": {
"enum": [
"size",
"quality",
"not_as_described",
"late_delivery",
"damaged",
"other"
],
"type": "string"
},
"title": "Top Reasons",
"type": "array"
},
"computed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Computed At"
}
},
"required": [
"product_id",
"title",
"url",
"price",
"available",
"source",
"merchant_published_rating",
"store_policy",
"score",
"sample_size",
"min_sample",
"confidence",
"breakdown",
"top_reasons",
"computed_at"
],
"$defs": {
"MerchantPublishedRating": {
"description": "Average rating and review count the merchant publishes on its own product page (schema.org\nAggregateRating). Not verified by BuyRecord and never part of the verified score.",
"properties": {
"average": {
"description": "Out of 5.",
"title": "Average",
"type": "number"
},
"count": {
"title": "Count",
"type": "integer"
},
"label": {
"const": "published on the merchant's site, not verified",
"default": "published on the merchant's site, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"average",
"count"
],
"title": "MerchantPublishedRating",
"type": "object"
},
"Recall": {
"description": "A US CPSC recall linked to this product. match: 'upc' (exact barcode) or 'brand_and_name'.",
"properties": {
"recall_number": {
"title": "Recall Number",
"type": "string"
},
"recall_date": {
"format": "date",
"title": "Recall Date",
"type": "string"
},
"url": {
"description": "Official CPSC recall notice.",
"title": "Url",
"type": "string"
},
"match": {
"enum": [
"upc",
"brand_and_name"
],
"title": "Match",
"type": "string"
}
},
"required": [
"recall_number",
"recall_date",
"url",
"match"
],
"title": "Recall",
"type": "object"
},
"RetailerOffer": {
"description": "The same product (exact GTIN match) at a big retailer, from the retailer's official API. Not verified by\nBuyRecord, never part of the verified score, and never used to rank results.",
"properties": {
"retailer": {
"enum": [
"bestbuy",
"walmart"
],
"title": "Retailer",
"type": "string"
},
"retailer_name": {
"enum": [
"Best Buy",
"Walmart"
],
"title": "Retailer Name",
"type": "string"
},
"url": {
"description": "Product page at the retailer.",
"title": "Url",
"type": "string"
},
"affiliate_link": {
"description": "True when the url is an affiliate link: BuyRecord may earn a commission if a purchase follows. Commissions never affect which products are returned or their order.",
"title": "Affiliate Link",
"type": "boolean"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "USD, as returned by the retailer's API at fetched_at.",
"title": "Price"
},
"available": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Available"
},
"rating": {
"anyOf": [
{
"$ref": "#/$defs/RetailerRating"
},
{
"type": "null"
}
],
"description": "The retailer's customer rating (average and count only)."
},
"match": {
"const": "gtin",
"default": "gtin",
"title": "Match",
"type": "string"
},
"fetched_at": {
"format": "date-time",
"title": "Fetched At",
"type": "string"
},
"source": {
"const": "retailer_api",
"default": "retailer_api",
"title": "Source",
"type": "string"
},
"attribution": {
"description": "Data source, as the retailer's terms require.",
"title": "Attribution",
"type": "string"
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Retailer logo to show next to this data, when its terms require one.",
"title": "Logo Url"
},
"label": {
"const": "published by the retailer, not verified",
"default": "published by the retailer, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"retailer",
"retailer_name",
"url",
"affiliate_link",
"price",
"available",
"rating",
"fetched_at",
"attribution",
"logo_url"
],
"title": "RetailerOffer",
"type": "object"
},
"RetailerRating": {
"properties": {
"average": {
"description": "Out of 5.",
"title": "Average",
"type": "number"
},
"count": {
"title": "Count",
"type": "integer"
}
},
"required": [
"average",
"count"
],
"title": "RetailerRating",
"type": "object"
},
"StorePolicy": {
"description": "Return policy facts read from the store's public refund policy. Not verified by BuyRecord.",
"properties": {
"return_window_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Return Window Days"
},
"free_returns": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Free Returns"
},
"label": {
"const": "published on the merchant's site, not verified",
"default": "published on the merchant's site, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"return_window_days",
"free_returns"
],
"title": "StorePolicy",
"type": "object"
}
},
"title": "ProductOutcomes"
}🟢compare_products(product_ids)
Outcomes for 2 to 5 products, in the order given.
輸入結構描述
{
"type": "object",
"properties": {
"product_ids": {
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 5,
"minItems": 2,
"title": "Product Ids",
"type": "array"
}
},
"required": [
"product_ids"
],
"title": "compare_productsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"products": {
"items": {
"$ref": "#/$defs/ProductOutcomes"
},
"title": "Products",
"type": "array"
}
},
"required": [
"products"
],
"$defs": {
"MerchantPublishedRating": {
"description": "Average rating and review count the merchant publishes on its own product page (schema.org\nAggregateRating). Not verified by BuyRecord and never part of the verified score.",
"properties": {
"average": {
"description": "Out of 5.",
"title": "Average",
"type": "number"
},
"count": {
"title": "Count",
"type": "integer"
},
"label": {
"const": "published on the merchant's site, not verified",
"default": "published on the merchant's site, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"average",
"count"
],
"title": "MerchantPublishedRating",
"type": "object"
},
"ProductOutcomes": {
"properties": {
"product_id": {
"format": "uuid",
"title": "Product Id",
"type": "string"
},
"title": {
"description": "Product name as published by the merchant, cleaned and capped at 200 characters.",
"title": "Title",
"type": "string"
},
"url": {
"title": "Url",
"type": "string"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Price"
},
"available": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Available"
},
"source": {
"enum": [
"merchant_sync",
"email_receipt",
"public_web",
"merchant_reported"
],
"title": "Source",
"type": "string"
},
"merchant_published_rating": {
"anyOf": [
{
"$ref": "#/$defs/MerchantPublishedRating"
},
{
"type": "null"
}
]
},
"store_policy": {
"anyOf": [
{
"$ref": "#/$defs/StorePolicy"
},
{
"type": "null"
}
]
},
"recalls": {
"description": "US CPSC recalls linked to this product.",
"items": {
"$ref": "#/$defs/Recall"
},
"title": "Recalls",
"type": "array"
},
"retailer_offers": {
"description": "Same GTIN at big retailers (official APIs). Not verified.",
"items": {
"$ref": "#/$defs/RetailerOffer"
},
"title": "Retailer Offers",
"type": "array"
},
"score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "0 to 100. Null when sample_size is below min_sample.",
"title": "Score"
},
"sample_size": {
"title": "Sample Size",
"type": "integer"
},
"min_sample": {
"title": "Min Sample",
"type": "integer"
},
"confidence": {
"anyOf": [
{
"enum": [
"low",
"medium",
"high"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "low under 10 verified outcomes, medium under 30, high from 30. Null when no score is shown.",
"title": "Confidence"
},
"breakdown": {
"additionalProperties": {
"type": "integer"
},
"propertyNames": {
"enum": [
"kept_silent",
"kept_positive",
"complained",
"returned"
]
},
"title": "Breakdown",
"type": "object"
},
"top_reasons": {
"items": {
"enum": [
"size",
"quality",
"not_as_described",
"late_delivery",
"damaged",
"other"
],
"type": "string"
},
"title": "Top Reasons",
"type": "array"
},
"computed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Computed At"
}
},
"required": [
"product_id",
"title",
"url",
"price",
"available",
"source",
"merchant_published_rating",
"store_policy",
"score",
"sample_size",
"min_sample",
"confidence",
"breakdown",
"top_reasons",
"computed_at"
],
"title": "ProductOutcomes",
"type": "object"
},
"Recall": {
"description": "A US CPSC recall linked to this product. match: 'upc' (exact barcode) or 'brand_and_name'.",
"properties": {
"recall_number": {
"title": "Recall Number",
"type": "string"
},
"recall_date": {
"format": "date",
"title": "Recall Date",
"type": "string"
},
"url": {
"description": "Official CPSC recall notice.",
"title": "Url",
"type": "string"
},
"match": {
"enum": [
"upc",
"brand_and_name"
],
"title": "Match",
"type": "string"
}
},
"required": [
"recall_number",
"recall_date",
"url",
"match"
],
"title": "Recall",
"type": "object"
},
"RetailerOffer": {
"description": "The same product (exact GTIN match) at a big retailer, from the retailer's official API. Not verified by\nBuyRecord, never part of the verified score, and never used to rank results.",
"properties": {
"retailer": {
"enum": [
"bestbuy",
"walmart"
],
"title": "Retailer",
"type": "string"
},
"retailer_name": {
"enum": [
"Best Buy",
"Walmart"
],
"title": "Retailer Name",
"type": "string"
},
"url": {
"description": "Product page at the retailer.",
"title": "Url",
"type": "string"
},
"affiliate_link": {
"description": "True when the url is an affiliate link: BuyRecord may earn a commission if a purchase follows. Commissions never affect which products are returned or their order.",
"title": "Affiliate Link",
"type": "boolean"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "USD, as returned by the retailer's API at fetched_at.",
"title": "Price"
},
"available": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Available"
},
"rating": {
"anyOf": [
{
"$ref": "#/$defs/RetailerRating"
},
{
"type": "null"
}
],
"description": "The retailer's customer rating (average and count only)."
},
"match": {
"const": "gtin",
"default": "gtin",
"title": "Match",
"type": "string"
},
"fetched_at": {
"format": "date-time",
"title": "Fetched At",
"type": "string"
},
"source": {
"const": "retailer_api",
"default": "retailer_api",
"title": "Source",
"type": "string"
},
"attribution": {
"description": "Data source, as the retailer's terms require.",
"title": "Attribution",
"type": "string"
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Retailer logo to show next to this data, when its terms require one.",
"title": "Logo Url"
},
"label": {
"const": "published by the retailer, not verified",
"default": "published by the retailer, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"retailer",
"retailer_name",
"url",
"affiliate_link",
"price",
"available",
"rating",
"fetched_at",
"attribution",
"logo_url"
],
"title": "RetailerOffer",
"type": "object"
},
"RetailerRating": {
"properties": {
"average": {
"description": "Out of 5.",
"title": "Average",
"type": "number"
},
"count": {
"title": "Count",
"type": "integer"
}
},
"required": [
"average",
"count"
],
"title": "RetailerRating",
"type": "object"
},
"StorePolicy": {
"description": "Return policy facts read from the store's public refund policy. Not verified by BuyRecord.",
"properties": {
"return_window_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Return Window Days"
},
"free_returns": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Free Returns"
},
"label": {
"const": "published on the merchant's site, not verified",
"default": "published on the merchant's site, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"return_window_days",
"free_returns"
],
"title": "StorePolicy",
"type": "object"
}
},
"title": "Comparison"
}🟢get_merchant_profile(shop_domain)
Return rate, complaint rate and delivery issue rate across a merchant's products.
輸入結構描述
{
"type": "object",
"properties": {
"shop_domain": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9.-]{1,253}$",
"title": "Shop Domain",
"type": "string"
}
},
"required": [
"shop_domain"
],
"title": "get_merchant_profileArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"shop_domain": {
"title": "Shop Domain",
"type": "string"
},
"product_count": {
"title": "Product Count",
"type": "integer"
},
"sample_size": {
"title": "Sample Size",
"type": "integer"
},
"min_sample": {
"title": "Min Sample",
"type": "integer"
},
"return_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Return Rate"
},
"complaint_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Complaint Rate"
},
"delivery_issue_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Share of outcomes citing late_delivery or damaged.",
"title": "Delivery Issue Rate"
},
"top_reasons": {
"items": {
"enum": [
"size",
"quality",
"not_as_described",
"late_delivery",
"damaged",
"other"
],
"type": "string"
},
"title": "Top Reasons",
"type": "array"
},
"last_synced_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Synced At"
},
"store_policy": {
"anyOf": [
{
"$ref": "#/$defs/StorePolicy"
},
{
"type": "null"
}
]
}
},
"required": [
"shop_domain",
"product_count",
"sample_size",
"min_sample",
"return_rate",
"complaint_rate",
"delivery_issue_rate",
"top_reasons",
"last_synced_at",
"store_policy"
],
"$defs": {
"StorePolicy": {
"description": "Return policy facts read from the store's public refund policy. Not verified by BuyRecord.",
"properties": {
"return_window_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Return Window Days"
},
"free_returns": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Free Returns"
},
"label": {
"const": "published on the merchant's site, not verified",
"default": "published on the merchant's site, not verified",
"title": "Label",
"type": "string"
}
},
"required": [
"return_window_days",
"free_returns"
],
"title": "StorePolicy",
"type": "object"
}
},
"title": "MerchantProfile"
}🟡submit_outcome(outcome, proof, product_id, product_url, reasons)
Record a purchase outcome for a product (product_id or product_url). Requires an API key (Authorization: Bearer header). Proofs: shopify_order (shop domain, order number, confirmation number) is checked against the shop's order record; email_receipt (the merchant's original DKIM-signed confirmation email, order number, product name) is checked by its signature; both count when they match. payment_receipt is stored as quarantined.
輸入結構描述
{
"type": "object",
"properties": {
"outcome": {
"enum": [
"kept_silent",
"kept_positive",
"complained",
"returned"
],
"title": "Outcome",
"type": "string"
},
"proof": {
"discriminator": {
"mapping": {
"email_receipt": "#/$defs/EmailReceiptProof",
"payment_receipt": "#/$defs/PaymentReceiptProof",
"shopify_order": "#/$defs/ShopifyOrderProof"
},
"propertyName": "type"
},
"oneOf": [
{
"$ref": "#/$defs/PaymentReceiptProof"
},
{
"$ref": "#/$defs/ShopifyOrderProof"
},
{
"$ref": "#/$defs/EmailReceiptProof"
}
],
"title": "Proof"
},
"product_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Product Id"
},
"product_url": {
"anyOf": [
{
"maxLength": 500,
"pattern": "^https://",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Product Url"
},
"reasons": {
"default": [],
"items": {
"enum": [
"size",
"quality",
"not_as_described",
"late_delivery",
"damaged",
"other"
],
"type": "string"
},
"maxItems": 6,
"title": "Reasons",
"type": "array"
}
},
"required": [
"outcome",
"proof"
],
"$defs": {
"EmailReceiptProof": {
"properties": {
"type": {
"const": "email_receipt",
"title": "Type",
"type": "string"
},
"raw_email_base64": {
"description": "The merchant's original order confirmation email (.eml, RFC 5322), base64-encoded. Its DKIM signature is verified; the email is processed in memory and never stored.",
"maxLength": 2800000,
"title": "Raw Email Base64",
"type": "string"
},
"order_number": {
"description": "Order number as it appears in the email.",
"maxLength": 60,
"minLength": 1,
"title": "Order Number",
"type": "string"
},
"product_name": {
"description": "Product name exactly as it appears in the email.",
"maxLength": 200,
"minLength": 3,
"title": "Product Name",
"type": "string"
}
},
"required": [
"type",
"raw_email_base64",
"order_number",
"product_name"
],
"title": "EmailReceiptProof",
"type": "object"
},
"PaymentReceiptProof": {
"properties": {
"type": {
"const": "payment_receipt",
"title": "Type",
"type": "string"
},
"reference": {
"description": "Receipt or transaction reference. Hashed on arrival, never stored.",
"maxLength": 200,
"minLength": 4,
"title": "Reference",
"type": "string"
},
"purchased_on": {
"format": "date",
"title": "Purchased On",
"type": "string"
}
},
"required": [
"type",
"reference",
"purchased_on"
],
"title": "PaymentReceiptProof",
"type": "object"
},
"ShopifyOrderProof": {
"properties": {
"type": {
"const": "shopify_order",
"title": "Type",
"type": "string"
},
"shop_domain": {
"description": "The store's domain, e.g. brand.com or brand.myshopify.com.",
"pattern": "^[A-Za-z0-9][A-Za-z0-9.-]{1,253}$",
"title": "Shop Domain",
"type": "string"
},
"order_number": {
"description": "Order number as shown to the buyer, e.g. #1001. Never stored.",
"pattern": "^#?[A-Za-z0-9-]{1,40}$",
"title": "Order Number",
"type": "string"
},
"confirmation_number": {
"description": "Order confirmation number from the order confirmation, e.g. XPLZ3K9HG. Never stored.",
"pattern": "^[A-Za-z0-9]{6,20}$",
"title": "Confirmation Number",
"type": "string"
}
},
"required": [
"type",
"shop_domain",
"order_number",
"confirmation_number"
],
"title": "ShopifyOrderProof",
"type": "object"
}
},
"title": "submit_outcomeArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"id": {
"format": "uuid",
"title": "Id",
"type": "string"
},
"status": {
"enum": [
"accepted",
"quarantined"
],
"title": "Status",
"type": "string"
},
"status_reason": {
"enum": [
"verified",
"proof_not_verifiable",
"pending_merchant_verification"
],
"title": "Status Reason",
"type": "string"
}
},
"required": [
"id",
"status",
"status_reason"
],
"title": "SubmissionResult"
}社群
證據
近期觀測
已驗證未記錄版本5 個工具