{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/buyrecord-app/json-schema/buyrecord-app-product-details-schema.json",
  "title": "ProductDetails",
  "description": "REST only: product outcomes plus price history, variants and policy details.",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/buyrecord-app-openapi.json#/components/schemas/ProductDetails",
  "properties": {
    "product_id": {
      "type": "string",
      "format": "uuid",
      "title": "Product Id"
    },
    "title": {
      "type": "string",
      "title": "Title",
      "description": "Product name as published by the merchant, cleaned and capped at 200 characters."
    },
    "url": {
      "type": "string",
      "title": "Url"
    },
    "price": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Price"
    },
    "available": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Available"
    },
    "source": {
      "type": "string",
      "enum": [
        "merchant_sync",
        "email_receipt",
        "public_web",
        "merchant_reported"
      ],
      "title": "Source"
    },
    "merchant_published_rating": {
      "anyOf": [
        {
          "$ref": "#/$defs/MerchantPublishedRating"
        },
        {
          "type": "null"
        }
      ]
    },
    "store_policy": {
      "anyOf": [
        {
          "$ref": "#/$defs/StorePolicy"
        },
        {
          "type": "null"
        }
      ]
    },
    "recalls": {
      "items": {
        "$ref": "#/$defs/Recall"
      },
      "type": "array",
      "title": "Recalls",
      "description": "US CPSC recalls linked to this product."
    },
    "retailer_offers": {
      "items": {
        "$ref": "#/$defs/RetailerOffer"
      },
      "type": "array",
      "title": "Retailer Offers",
      "description": "Same GTIN at big retailers (official APIs). Not verified."
    },
    "score": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Score",
      "description": "0 to 100. Null when sample_size is below min_sample."
    },
    "sample_size": {
      "type": "integer",
      "title": "Sample Size"
    },
    "min_sample": {
      "type": "integer",
      "title": "Min Sample"
    },
    "confidence": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Confidence",
      "description": "low under 10 verified outcomes, medium under 30, high from 30. Null when no score is shown."
    },
    "breakdown": {
      "additionalProperties": {
        "type": "integer"
      },
      "propertyNames": {
        "enum": [
          "kept_silent",
          "kept_positive",
          "complained",
          "returned"
        ]
      },
      "type": "object",
      "title": "Breakdown"
    },
    "top_reasons": {
      "items": {
        "type": "string",
        "enum": [
          "size",
          "quality",
          "not_as_described",
          "late_delivery",
          "damaged",
          "other"
        ]
      },
      "type": "array",
      "title": "Top Reasons"
    },
    "computed_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Computed At"
    },
    "compare_at_price": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Compare At Price"
    },
    "price_history": {
      "anyOf": [
        {
          "$ref": "#/$defs/PriceHistory"
        },
        {
          "type": "null"
        }
      ]
    },
    "variants": {
      "items": {
        "$ref": "#/$defs/Variant"
      },
      "type": "array",
      "title": "Variants"
    },
    "policy_details": {
      "anyOf": [
        {
          "$ref": "#/$defs/PolicyDetails"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "type": "object",
  "required": [
    "product_id",
    "title",
    "url",
    "price",
    "available",
    "source",
    "merchant_published_rating",
    "store_policy",
    "score",
    "sample_size",
    "min_sample",
    "confidence",
    "breakdown",
    "top_reasons",
    "computed_at",
    "compare_at_price",
    "price_history",
    "variants",
    "policy_details"
  ],
  "$defs": {
    "MerchantPublishedRating": {
      "properties": {
        "average": {
          "type": "number",
          "title": "Average",
          "description": "Out of 5."
        },
        "count": {
          "type": "integer",
          "title": "Count"
        },
        "label": {
          "type": "string",
          "const": "published on the merchant's site, not verified",
          "title": "Label",
          "default": "published on the merchant's site, not verified"
        }
      },
      "type": "object",
      "required": [
        "average",
        "count"
      ],
      "title": "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."
    },
    "PolicyDetails": {
      "properties": {
        "return_shipping": {
          "type": "string",
          "enum": [
            "free",
            "paid",
            "not_stated"
          ],
          "title": "Return Shipping"
        },
        "restocking_fee": {
          "type": "string",
          "enum": [
            "none",
            "yes",
            "not_stated"
          ],
          "title": "Restocking Fee"
        },
        "restocking_fee_percent": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Restocking Fee Percent"
        },
        "restocking_fee_amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Restocking Fee Amount"
        },
        "warranty_mentioned": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Warranty Mentioned"
        },
        "warranty_months": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Warranty Months"
        },
        "warranty_lifetime": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Warranty Lifetime"
        },
        "ships_from_country": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Ships From Country",
          "description": "ISO 3166 country code."
        },
        "final_sale_items": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Final Sale Items",
          "description": "True when the policy excludes some items as final sale."
        },
        "label": {
          "type": "string",
          "const": "published on the merchant's site, not verified",
          "title": "Label",
          "default": "published on the merchant's site, not verified"
        }
      },
      "type": "object",
      "required": [
        "return_shipping",
        "restocking_fee",
        "restocking_fee_percent",
        "restocking_fee_amount",
        "warranty_mentioned",
        "warranty_months",
        "warranty_lifetime",
        "ships_from_country",
        "final_sale_items"
      ],
      "title": "PolicyDetails",
      "description": "Facts read from the store's public refund and shipping policy pages. Not verified by BuyRecord."
    },
    "PriceHistory": {
      "properties": {
        "lowest": {
          "$ref": "#/$defs/PricePoint"
        },
        "highest": {
          "$ref": "#/$defs/PricePoint"
        },
        "tracked_since": {
          "type": "string",
          "format": "date-time",
          "title": "Tracked Since"
        },
        "price_changes": {
          "type": "integer",
          "title": "Price Changes"
        },
        "label": {
          "type": "string",
          "const": "published on the merchant's site, not verified",
          "title": "Label",
          "default": "published on the merchant's site, not verified"
        }
      },
      "type": "object",
      "required": [
        "lowest",
        "highest",
        "tracked_since",
        "price_changes"
      ],
      "title": "PriceHistory",
      "description": "Lowest and highest price seen at the merchant's own site since BuyRecord started tracking it (one snapshot a\nweek, kept when something changed). Not verified; no price alerts."
    },
    "PricePoint": {
      "properties": {
        "price": {
          "type": "number",
          "title": "Price"
        },
        "since": {
          "type": "string",
          "format": "date-time",
          "title": "Since"
        }
      },
      "type": "object",
      "required": [
        "price",
        "since"
      ],
      "title": "PricePoint"
    },
    "Recall": {
      "properties": {
        "recall_number": {
          "type": "string",
          "title": "Recall Number"
        },
        "recall_date": {
          "type": "string",
          "format": "date",
          "title": "Recall Date"
        },
        "url": {
          "type": "string",
          "title": "Url",
          "description": "Official CPSC recall notice."
        },
        "match": {
          "type": "string",
          "enum": [
            "upc",
            "brand_and_name"
          ],
          "title": "Match"
        }
      },
      "type": "object",
      "required": [
        "recall_number",
        "recall_date",
        "url",
        "match"
      ],
      "title": "Recall",
      "description": "A US CPSC recall linked to this product. match: 'upc' (exact barcode) or 'brand_and_name'."
    },
    "RetailerOffer": {
      "properties": {
        "retailer": {
          "type": "string",
          "enum": [
            "bestbuy",
            "walmart"
          ],
          "title": "Retailer"
        },
        "retailer_name": {
          "type": "string",
          "enum": [
            "Best Buy",
            "Walmart"
          ],
          "title": "Retailer Name"
        },
        "url": {
          "type": "string",
          "title": "Url",
          "description": "Product page at the retailer."
        },
        "affiliate_link": {
          "type": "boolean",
          "title": "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."
        },
        "price": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Price",
          "description": "USD, as returned by the retailer's API at fetched_at."
        },
        "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": {
          "type": "string",
          "const": "gtin",
          "title": "Match",
          "default": "gtin"
        },
        "fetched_at": {
          "type": "string",
          "format": "date-time",
          "title": "Fetched At"
        },
        "source": {
          "type": "string",
          "const": "retailer_api",
          "title": "Source",
          "default": "retailer_api"
        },
        "attribution": {
          "type": "string",
          "title": "Attribution",
          "description": "Data source, as the retailer's terms require."
        },
        "logo_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Logo Url",
          "description": "Retailer logo to show next to this data, when its terms require one."
        },
        "label": {
          "type": "string",
          "const": "published by the retailer, not verified",
          "title": "Label",
          "default": "published by the retailer, not verified"
        }
      },
      "type": "object",
      "required": [
        "retailer",
        "retailer_name",
        "url",
        "affiliate_link",
        "price",
        "available",
        "rating",
        "fetched_at",
        "attribution",
        "logo_url"
      ],
      "title": "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."
    },
    "RetailerRating": {
      "properties": {
        "average": {
          "type": "number",
          "title": "Average",
          "description": "Out of 5."
        },
        "count": {
          "type": "integer",
          "title": "Count"
        }
      },
      "type": "object",
      "required": [
        "average",
        "count"
      ],
      "title": "RetailerRating"
    },
    "StorePolicy": {
      "properties": {
        "return_window_days": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Return Window Days"
        },
        "free_returns": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Free Returns"
        },
        "label": {
          "type": "string",
          "const": "published on the merchant's site, not verified",
          "title": "Label",
          "default": "published on the merchant's site, not verified"
        }
      },
      "type": "object",
      "required": [
        "return_window_days",
        "free_returns"
      ],
      "title": "StorePolicy",
      "description": "Return policy facts read from the store's public refund policy. Not verified by BuyRecord."
    },
    "Variant": {
      "properties": {
        "variant_id": {
          "type": "integer",
          "title": "Variant Id"
        },
        "sku": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sku"
        },
        "gtin": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Gtin"
        },
        "options": {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object",
          "title": "Options",
          "description": "e.g. {\"Color\": \"Black\"}"
        },
        "condition": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "new",
                "refurbished",
                "used"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Condition",
          "description": "Null when the merchant does not say."
        },
        "price": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Price"
        },
        "compare_at_price": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Compare At Price"
        },
        "available": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Available"
        },
        "price_history": {
          "anyOf": [
            {
              "$ref": "#/$defs/PriceHistory"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object",
      "required": [
        "variant_id",
        "sku",
        "gtin",
        "options",
        "condition",
        "price",
        "compare_at_price",
        "available",
        "price_history"
      ],
      "title": "Variant"
    }
  }
}