> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Klarna Product Comparison

> Compares exactly two independently verified regional products using native specification tables. Product cards follow the requested order; category groups retain source ordering, units and per-product values, including empty and missing values without inference.

Compares exactly two distinct regional products. Supply `product_id` and `product_id_2`; both must exist in the requested region. A native product-information lookup independently verifies both identities before requesting the comparison. A source-confirmed missing product returns 404 rather than a partial one-product success.

`items` contains the two normalized product cards in **your requested order**, including native prices, ratings, categories and images when available. `source_product_order` separately records Klarna's returned order. Prices and ratings are source snapshots, not merchant checkout guarantees. UK, Swedish and Danish cards retain legacy source paths with null absolute URLs.

`categories` holds native category-specific specification tables. Each category lists its member `product_ids`, source-ordered `groups`, and `attributes`. Attribute `values` remain keyed by native product ID, with string arrays exactly as supplied. Empty arrays mean that the source supplied no values; absent keys stay absent. Units and descriptions remain native, and no unit conversion, missing-value inference or best-product recommendation is added. `attribute_count` counts returned attribute rows.

Cross-category comparisons retain separate tables. For example, headphones and a console have different category-specific attributes; a value for one category is not copied onto the other product. Duplicate identities, unexpected product-value keys, mismatched category IDs and invalid fields fail explicitly.

All 13 catalog regions are supported. Source access is anonymous and does not use customer accounts or follow advertising or checkout links. Each call uses two native source requests, shares the Klarna 20-request/minute ceiling, and has a 25-second total timeout and 2 MiB limit per response. Tables are bounded to 2,000 attribute rows; oversized results fail rather than silently truncate.

A fresh successful comparison costs **5 credits**. Failures, cached responses and successful idempotent replays have no net charge. Use `X-Max-Credits: 5` to cap the hold.


## OpenAPI

````yaml GET /klarna/product/compare
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /klarna/product/compare:
    get:
      tags:
        - Klarna
      summary: Klarna Product Compare
      description: >-
        Compares exactly two independently verified regional products using
        native specification tables. Product cards follow the requested order;
        category groups retain source ordering, units and per-product values,
        including empty and missing values without inference.
      operationId: get_klarna_product_compare
      parameters:
        - name: product_id
          in: query
          required: true
          example: '3331931731'
          schema:
            type: string
            pattern: ^[1-9][0-9]{0,17}$
          description: >-
            A native positive product ID in the requested region. The two
            product IDs must be distinct and must both exist.
        - name: product_id_2
          in: query
          required: true
          example: '3216399795'
          schema:
            type: string
            pattern: ^[1-9][0-9]{0,17}$
          description: >-
            A native positive product ID in the requested region. The two
            product IDs must be distinct and must both exist.
        - name: region
          in: query
          required: false
          schema:
            type: string
            enum:
              - usa
              - uk
              - germany
              - sweden
              - france
              - italy
              - spain
              - netherlands
              - austria
              - ireland
              - norway
              - finland
              - denmark
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            Compares exactly two independently verified regional products using
            native specification tables. Product cards follow the requested
            order; category groups retain source ordering, units and per-product
            values, including empty and missing values without inference.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                product:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    title:
                                      type: string
                                    source_path:
                                      type:
                                        - string
                                        - 'null'
                                    url:
                                      type:
                                        - string
                                        - 'null'
                                    description:
                                      type:
                                        - string
                                        - 'null'
                                    category:
                                      anyOf:
                                        - type: object
                                          properties:
                                            id:
                                              type:
                                                - string
                                                - 'null'
                                            name:
                                              type: string
                                            source_path:
                                              type:
                                                - string
                                                - 'null'
                                            url:
                                              type:
                                                - string
                                                - 'null'
                                          required:
                                            - id
                                            - name
                                            - source_path
                                            - url
                                        - type: 'null'
                                    price:
                                      type: object
                                      properties:
                                        current:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        currency:
                                          type: string
                                      required:
                                        - current
                                        - currency
                                    rating:
                                      type: object
                                      properties:
                                        average:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        count:
                                          type:
                                            - integer
                                            - 'null'
                                          minimum: 0
                                      required:
                                        - average
                                        - count
                                    image_urls:
                                      type: array
                                      items:
                                        type: string
                                    availability:
                                      type:
                                        - string
                                        - 'null'
                                      enum:
                                        - in_stock
                                        - out_of_stock
                                        - null
                                    condition:
                                      type:
                                        - string
                                        - 'null'
                                  required:
                                    - id
                                    - title
                                    - source_path
                                    - url
                                    - description
                                    - category
                                    - price
                                    - rating
                                    - image_urls
                                    - availability
                                    - condition
                              required:
                                - product
                            minItems: 2
                            maxItems: 2
                          returned_count:
                            type: integer
                            const: 2
                          product_ids:
                            type: array
                            items:
                              type: string
                          source_product_order:
                            type: array
                            items:
                              type: string
                          categories:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                product_ids:
                                  type: array
                                  items:
                                    type: string
                                groups:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                      name:
                                        type: string
                                      attributes:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            id:
                                              type: string
                                            name:
                                              type: string
                                            description:
                                              type:
                                                - string
                                                - 'null'
                                            unit:
                                              type:
                                                - string
                                                - 'null'
                                            values:
                                              type: object
                                              additionalProperties:
                                                type: array
                                                items:
                                                  type: string
                                          required:
                                            - id
                                            - name
                                            - description
                                            - unit
                                            - values
                                    required:
                                      - id
                                      - name
                                      - attributes
                              required:
                                - id
                                - name
                                - product_ids
                                - groups
                          attribute_count:
                            type: integer
                            minimum: 0
                          region:
                            type: string
                          country_code:
                            type: string
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - returned_count
                          - product_ids
                          - source_product_order
                          - categories
                          - attribute_count
                          - region
                          - country_code
                          - source
                          - coverage_note
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.