BuyRecord Products API

openapi: 3.2.0
info:
  title: BuyRecord Products API
  description: 'BuyRecord publishes verified purchase outcomes (kept, kept and liked, complained, returned, with reasons) for products. Every outcome is tied to a proof of purchase: a connected Shopify store''s order record, or the merchant''s DKIM-signed order confirmation email. Scores run from 0 to 100, are shown from 5 verified outcomes and carry the number of outcomes and a confidence level. Scope: US online stores, 15 product categories, all prices; for products without a score, the price, availability, the store''s return policy and the rating the store publishes on its own site are returned, labelled apart from verified outcomes, with US CPSC recall flags. Verified stays (hotels and rentals) are scored the same way from DKIM-signed booking confirmations. Reading needs no key; submitting an outcome needs an API key or OAuth. No buyer personal data is stored. The same operations are available as an MCP server at https://api.buyrecord.app/mcp. Summary: https://buyrecord.app/llms.txt; methodology: https://buyrecord.app/methodology.html.'
  version: 0.1.0
tags:
- name: Products
paths:
  /v1/products/search:
    get:
      summary: Search Products
      description: 'Products matching a name, GTIN or SKU (of the product or one of its variants), each with its outcome summary.

        A barcode or SKU query also names the matching variant.'
      operationId: search_products
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 100
          title: Query
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 50
          - type: 'null'
          description: home_kitchen, apparel, beauty, health, jewelry, toys_baby, sports_outdoors, electronics, pets, food_drink, arts_crafts, garden, automotive, office, other
          title: Category
        description: home_kitchen, apparel, beauty, health, jewelry, toys_baby, sports_outdoors, electronics, pets, food_drink, arts_crafts, garden, automotive, office, other
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 10
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchHits'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Products
  /v1/products/compare:
    get:
      summary: Compare Products
      description: Outcomes for 2 to 5 products, in the order given.
      operationId: compare_products
      parameters:
      - name: ids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            format: uuid
          minItems: 2
          maxItems: 5
          title: Ids
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comparison'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Products
  /v1/products/{product_id}/outcomes:
    get:
      summary: Get Product Outcomes
      description: 'Score, sample size, outcome breakdown and top return reasons for one product, plus the price history,

        variants and return policy details published on the merchant''s site (not verified).'
      operationId: get_product_outcomes
      parameters:
      - name: product_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Product Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetails'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Products
components:
  schemas:
    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: '#/components/schemas/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

        BuyRecord, never part of the verified score, and never used to rank results.'
    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.
    RetailerRating:
      properties:
        average:
          type: number
          title: Average
          description: Out of 5.
        count:
          type: integer
          title: Count
      type: object
      required:
      - average
      - count
      title: RetailerRating
    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

        AggregateRating). Not verified by BuyRecord and never part of the verified score.'
    SearchHits:
      properties:
        products:
          items:
            $ref: '#/components/schemas/ProductHit'
          type: array
          title: Products
      type: object
      required:
      - products
      title: SearchHits
    Comparison:
      properties:
        products:
          items:
            $ref: '#/components/schemas/ProductOutcomes'
          type: array
          title: Products
      type: object
      required:
      - products
      title: Comparison
    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''.'
    ProductOutcomes:
      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: '#/components/schemas/MerchantPublishedRating'
          - type: 'null'
        store_policy:
          anyOf:
          - $ref: '#/components/schemas/StorePolicy'
          - type: 'null'
        recalls:
          items:
            $ref: '#/components/schemas/Recall'
          type: array
          title: Recalls
          description: US CPSC recalls linked to this product.
        retailer_offers:
          items:
            $ref: '#/components/schemas/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
      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
      title: ProductOutcomes
    ProductHit:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        title:
          type: string
          title: Title
          description: Product name as published by the merchant, cleaned and capped at 200 characters.
        gtin:
          anyOf:
          - type: string
          - type: 'null'
          title: Gtin
        url:
          type: string
          title: Url
        category:
          type: string
          title: Category
        price_band:
          type: string
          enum:
          - under_30
          - '30_50'
          - '50_100'
          - '100_150'
          - over_150
          - unknown
          title: Price Band
        price:
          anyOf:
          - type: number
          - type: 'null'
          title: Price
          description: Lowest variant price in USD, as published by the merchant.
        available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Available
        shop_domain:
          type: string
          title: Shop Domain
        source:
          type: string
          enum:
          - merchant_sync
          - email_receipt
          - public_web
          - merchant_reported
          title: Source
          description: 'public_web: from the merchant''s public site; no verified outcomes implied.'
        outcomes:
          $ref: '#/components/schemas/OutcomeSummary'
          description: Verified purchase outcomes only.
        merchant_published_rating:
          anyOf:
          - $ref: '#/components/schemas/MerchantPublishedRating'
          - type: 'null'
        store_policy:
          anyOf:
          - $ref: '#/components/schemas/StorePolicy'
          - type: 'null'
        recalls:
          items:
            $ref: '#/components/schemas/Recall'
          type: array
          title: Recalls
          description: US CPSC recalls linked to this product.
        retailer_offers:
          items:
            $ref: '#/components/schemas/RetailerOffer'
          type: array
          title: Retailer Offers
          description: Same GTIN at big retailers (official APIs). Not verified.
        matched_variant:
          anyOf:
          - $ref: '#/components/schemas/Variant'
          - type: 'null'
      type: object
      required:
      - id
      - title
      - gtin
      - url
      - category
      - price_band
      - price
      - available
      - shop_domain
      - source
      - outcomes
      - merchant_published_rating
      - store_policy
      title: ProductHit
      description: 'REST only: a search result that also names the variant matched by a barcode or SKU query.'
    PricePoint:
      properties:
        price:
          type: number
          title: Price
        since:
          type: string
          format: date-time
          title: Since
      type: object
      required:
      - price
      - since
      title: PricePoint
    OutcomeSummary:
      properties:
        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.
        top_reasons:
          items:
            type: string
            enum:
            - size
            - quality
            - not_as_described
            - late_delivery
            - damaged
            - other
          type: array
          title: Top Reasons
      type: object
      required:
      - score
      - sample_size
      - min_sample
      - confidence
      - top_reasons
      title: OutcomeSummary
    PriceHistory:
      properties:
        lowest:
          $ref: '#/components/schemas/PricePoint'
        highest:
          $ref: '#/components/schemas/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

        week, kept when something changed). Not verified; no price alerts.'
    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.
    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: '#/components/schemas/MerchantPublishedRating'
          - type: 'null'
        store_policy:
          anyOf:
          - $ref: '#/components/schemas/StorePolicy'
          - type: 'null'
        recalls:
          items:
            $ref: '#/components/schemas/Recall'
          type: array
          title: Recalls
          description: US CPSC recalls linked to this product.
        retailer_offers:
          items:
            $ref: '#/components/schemas/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: '#/components/schemas/PriceHistory'
          - type: 'null'
        variants:
          items:
            $ref: '#/components/schemas/Variant'
          type: array
          title: Variants
        policy_details:
          anyOf:
          - $ref: '#/components/schemas/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
      title: ProductDetails
      description: 'REST only: product outcomes plus price history, variants and policy details.'
    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: '#/components/schemas/PriceHistory'
          - type: 'null'
      type: object
      required:
      - variant_id
      - sku
      - gtin
      - options
      - condition
      - price
      - compare_at_price
      - available
      - price_history
      title: Variant
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      description: API key (br_live_...). Required for writing.
      scheme: bearer