BuyRecord Outcomes API

openapi: 3.2.0
info:
  title: BuyRecord Outcomes 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: Outcomes
paths:
  /v1/outcomes:
    post:
      summary: Submit Outcome
      description: 'Record a purchase outcome for a product (product_id or product_url). Requires an API key.


        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.'
      operationId: submit_outcome
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutcomeSubmission'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Outcomes
components:
  schemas:
    ShopifyOrderProof:
      properties:
        type:
          type: string
          const: shopify_order
          title: Type
        shop_domain:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9.-]{1,253}$
          title: Shop Domain
          description: The store's domain, e.g. brand.com or brand.myshopify.com.
        order_number:
          type: string
          pattern: ^#?[A-Za-z0-9-]{1,40}$
          title: Order Number
          description: 'Order number as shown to the buyer, e.g. #1001. Never stored.'
        confirmation_number:
          type: string
          pattern: ^[A-Za-z0-9]{6,20}$
          title: Confirmation Number
          description: Order confirmation number from the order confirmation, e.g. XPLZ3K9HG. Never stored.
      type: object
      required:
      - type
      - shop_domain
      - order_number
      - confirmation_number
      title: ShopifyOrderProof
    OutcomeSubmission:
      properties:
        product_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Product Id
          description: BuyRecord product id. Either this or product_url.
        product_url:
          anyOf:
          - type: string
            maxLength: 500
            pattern: ^https://
          - type: 'null'
          title: Product Url
          description: The product page URL at the store. Either this or product_id.
        outcome:
          type: string
          enum:
          - kept_silent
          - kept_positive
          - complained
          - returned
          title: Outcome
        reasons:
          items:
            type: string
            enum:
            - size
            - quality
            - not_as_described
            - late_delivery
            - damaged
            - other
          type: array
          maxItems: 6
          title: Reasons
        proof:
          oneOf:
          - $ref: '#/components/schemas/PaymentReceiptProof'
          - $ref: '#/components/schemas/ShopifyOrderProof'
          - $ref: '#/components/schemas/EmailReceiptProof'
          title: Proof
          discriminator:
            propertyName: type
            mapping:
              email_receipt: '#/components/schemas/EmailReceiptProof'
              payment_receipt: '#/components/schemas/PaymentReceiptProof'
              shopify_order: '#/components/schemas/ShopifyOrderProof'
      type: object
      required:
      - outcome
      - proof
      title: OutcomeSubmission
    SubmissionResult:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        status:
          type: string
          enum:
          - accepted
          - quarantined
          title: Status
        status_reason:
          type: string
          enum:
          - verified
          - proof_not_verifiable
          - pending_merchant_verification
          title: Status Reason
      type: object
      required:
      - id
      - status
      - status_reason
      title: SubmissionResult
    PaymentReceiptProof:
      properties:
        type:
          type: string
          const: payment_receipt
          title: Type
        reference:
          type: string
          maxLength: 200
          minLength: 4
          title: Reference
          description: Receipt or transaction reference. Hashed on arrival, never stored.
        purchased_on:
          type: string
          format: date
          title: Purchased On
      type: object
      required:
      - type
      - reference
      - purchased_on
      title: PaymentReceiptProof
    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
    EmailReceiptProof:
      properties:
        type:
          type: string
          const: email_receipt
          title: Type
        raw_email_base64:
          type: string
          maxLength: 2800000
          title: 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.
        order_number:
          type: string
          maxLength: 60
          minLength: 1
          title: Order Number
          description: Order number as it appears in the email.
        product_name:
          type: string
          maxLength: 200
          minLength: 3
          title: Product Name
          description: Product name exactly as it appears in the email.
      type: object
      required:
      - type
      - raw_email_base64
      - order_number
      - product_name
      title: EmailReceiptProof
  securitySchemes:
    HTTPBearer:
      type: http
      description: API key (br_live_...). Required for writing.
      scheme: bearer