BuyRecord Merchants API

openapi: 3.2.0
info:
  title: BuyRecord Merchants 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: Merchants
paths:
  /v1/merchants/{shop_domain}:
    get:
      summary: Get Merchant Profile
      description: Return rate, complaint rate and delivery issue rate across a merchant's products.
      operationId: get_merchant_profile
      parameters:
      - name: shop_domain
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9.-]{1,253}$
          title: Shop Domain
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantProfile'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Merchants
components:
  schemas:
    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.
    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
    MerchantProfile:
      properties:
        shop_domain:
          type: string
          title: Shop Domain
        product_count:
          type: integer
          title: Product Count
        sample_size:
          type: integer
          title: Sample Size
        min_sample:
          type: integer
          title: Min Sample
        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'
          title: Delivery Issue Rate
          description: Share of outcomes citing late_delivery or damaged.
        top_reasons:
          items:
            type: string
            enum:
            - size
            - quality
            - not_as_described
            - late_delivery
            - damaged
            - other
          type: array
          title: Top Reasons
        last_synced_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Synced At
        store_policy:
          anyOf:
          - $ref: '#/components/schemas/StorePolicy'
          - type: 'null'
      type: object
      required:
      - shop_domain
      - product_count
      - sample_size
      - min_sample
      - return_rate
      - complaint_rate
      - delivery_issue_rate
      - top_reasons
      - last_synced_at
      - store_policy
      title: MerchantProfile
  securitySchemes:
    HTTPBearer:
      type: http
      description: API key (br_live_...). Required for writing.
      scheme: bearer