compsniper-com TC Gplayer API

openapi: 3.2.0
info:
  title: CompSniper Marketplace and Shipping TC Gplayer API
  version: 2.3.0
  description: Public eBay (including up to 3 years of sold history), Poshmark, Mercari, TCGplayer, Grailed, Depop and PSA graded card (prices by grade, population) data plus a separate quote-only US shipping-rates product. Shipping quotes separate applicable services from carrier-packaging and content-restricted options, use an independent subscription and quota, and do not consume sold-comps requests or purchased credits.
  contact:
    name: CompSniper
    url: https://compsniper.com
servers:
- url: https://api.compsniper.com
security:
- bearerAuth: []
tags:
- name: TCGplayer
paths:
  /v1/tcgplayer/sold:
    get:
      tags:
      - TCGplayer
      summary: TCGplayer completed sales and price history
      description: Full TCGplayer completed-sale history for a product, with optional market price history. One successful call uses one request; repeat calls can return instantly from a short-lived saved copy; send fresh=true for a live fetch.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: keyword
        in: query
        required: false
        schema:
          type: string
          maxLength: 300
          example: charizard ex obsidian flames 223
          description: Card or product name (required unless productId is sent)
      - name: productId
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Exact TCGplayer product ID
      - name: count
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 100
          description: Number of sales
      - name: condition
        in: query
        required: false
        schema:
          type: string
          example: Near Mint
          description: Condition filter
      - name: variant
        in: query
        required: false
        schema:
          type: string
          example: Holofoil
          description: Variant filter
      - name: language
        in: query
        required: false
        schema:
          type: string
          example: English
          description: Language filter
      - name: history
        in: query
        required: false
        schema:
          type: string
          enum:
          - none
          - month
          - quarter
          - annual
          default: none
          description: Market price history range
      - name: soldAfter
        in: query
        required: false
        schema:
          type: string
          format: date
          example: '2026-10-14'
          description: Only sales on or after this date (UTC, YYYY-MM-DD). Filters the newest sales returned for the product; count applies first.
      - name: soldBefore
        in: query
        required: false
        schema:
          type: string
          format: date
          example: '2026-10-15'
          description: Only sales on or before this date (UTC, YYYY-MM-DD).
      - name: fresh
        in: query
        required: false
        schema:
          type: boolean
          default: false
          description: When true, fetches the latest sales live from TCGplayer instead of a recently saved copy. Costs one request, like any call.
      responses:
        '200':
          description: Sales
          content:
            application/json:
              schema:
                type: object
                properties:
                  keyword:
                    type: string
                  marketplace:
                    type: string
                    example: tcgplayer
                  product:
                    type:
                    - object
                    - 'null'
                    properties:
                      productId:
                        type:
                        - integer
                        - 'null'
                      name:
                        type:
                        - string
                        - 'null'
                      productLine:
                        type:
                        - string
                        - 'null'
                      setName:
                        type:
                        - string
                        - 'null'
                      number:
                        type:
                        - string
                        - 'null'
                      rarity:
                        type:
                        - string
                        - 'null'
                      sealed:
                        type:
                        - boolean
                        - 'null'
                      marketPrice:
                        type:
                        - number
                        - 'null'
                      lowestPrice:
                        type:
                        - number
                        - 'null'
                      lowestPriceWithShipping:
                        type:
                        - number
                        - 'null'
                      totalListings:
                        type:
                        - integer
                        - 'null'
                      url:
                        type:
                        - string
                        - 'null'
                  otherMatches:
                    type: array
                    items:
                      type:
                      - object
                      - 'null'
                      properties:
                        productId:
                          type:
                          - integer
                          - 'null'
                        name:
                          type:
                          - string
                          - 'null'
                        productLine:
                          type:
                          - string
                          - 'null'
                        setName:
                          type:
                          - string
                          - 'null'
                        number:
                          type:
                          - string
                          - 'null'
                        rarity:
                          type:
                          - string
                          - 'null'
                        sealed:
                          type:
                          - boolean
                          - 'null'
                        marketPrice:
                          type:
                          - number
                          - 'null'
                        lowestPrice:
                          type:
                          - number
                          - 'null'
                        lowestPriceWithShipping:
                          type:
                          - number
                          - 'null'
                        totalListings:
                          type:
                          - integer
                          - 'null'
                        url:
                          type:
                          - string
                          - 'null'
                  salesHistory:
                    type: string
                    enum:
                    - full
                    - limited
                  totalSales:
                    type:
                    - integer
                    - 'null'
                  totalItems:
                    type: integer
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type:
                          - string
                          - 'null'
                        condition:
                          type:
                          - string
                          - 'null'
                        variant:
                          type:
                          - string
                          - 'null'
                        language:
                          type:
                          - string
                          - 'null'
                        quantity:
                          type:
                          - integer
                          - 'null'
                        price:
                          type:
                          - number
                          - 'null'
                        shipping:
                          type:
                          - number
                          - 'null'
                        totalPrice:
                          type:
                          - number
                          - 'null'
                        soldAt:
                          type:
                          - string
                          - 'null'
                        listingType:
                          type:
                          - string
                          - 'null'
                  priceHistory:
                    type:
                    - array
                    - 'null'
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        variant:
                          type: string
                        condition:
                          type: string
                        language:
                          type: string
                        marketPrice:
                          type: number
                        quantitySold:
                          type: integer
                        transactionCount:
                          type: integer
                        lowSalePrice:
                          type: number
                        highSalePrice:
                          type: number
                  summary:
                    type:
                    - object
                    - 'null'
                  scrapedAt:
                    type: string
        '400':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '429':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '502':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '503':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
      operationId: getV1TcgplayerSold
      x-operation-id-source: derived
  /v1/tcgplayer/listings:
    get:
      tags:
      - TCGplayer
      summary: TCGplayer active listings
      description: Active TCGplayer listings for a product with price, shipping, condition and seller details. One successful call uses one request.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: keyword
        in: query
        required: false
        schema:
          type: string
          maxLength: 300
          example: charizard ex obsidian flames 223
          description: Card or product name (required unless productId is sent)
      - name: productId
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Exact TCGplayer product ID
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 1
          description: Page number
      - name: count
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 25
          description: Listings per page
      - name: condition
        in: query
        required: false
        schema:
          type: string
          example: Near Mint
          description: Condition filter
      - name: variant
        in: query
        required: false
        schema:
          type: string
          example: Holofoil
          description: Variant filter
      - name: language
        in: query
        required: false
        schema:
          type: string
          example: English
          description: Language filter
      responses:
        '200':
          description: Listings
          content:
            application/json:
              schema:
                type: object
                properties:
                  keyword:
                    type: string
                  page:
                    type: integer
                  count:
                    type: integer
                  marketplace:
                    type: string
                  product:
                    type:
                    - object
                    - 'null'
                    properties:
                      productId:
                        type:
                        - integer
                        - 'null'
                      name:
                        type:
                        - string
                        - 'null'
                      productLine:
                        type:
                        - string
                        - 'null'
                      setName:
                        type:
                        - string
                        - 'null'
                      number:
                        type:
                        - string
                        - 'null'
                      rarity:
                        type:
                        - string
                        - 'null'
                      sealed:
                        type:
                        - boolean
                        - 'null'
                      marketPrice:
                        type:
                        - number
                        - 'null'
                      lowestPrice:
                        type:
                        - number
                        - 'null'
                      lowestPriceWithShipping:
                        type:
                        - number
                        - 'null'
                      totalListings:
                        type:
                        - integer
                        - 'null'
                      url:
                        type:
                        - string
                        - 'null'
                  otherMatches:
                    type: array
                    items:
                      type:
                      - object
                      - 'null'
                      properties:
                        productId:
                          type:
                          - integer
                          - 'null'
                        name:
                          type:
                          - string
                          - 'null'
                        productLine:
                          type:
                          - string
                          - 'null'
                        setName:
                          type:
                          - string
                          - 'null'
                        number:
                          type:
                          - string
                          - 'null'
                        rarity:
                          type:
                          - string
                          - 'null'
                        sealed:
                          type:
                          - boolean
                          - 'null'
                        marketPrice:
                          type:
                          - number
                          - 'null'
                        lowestPrice:
                          type:
                          - number
                          - 'null'
                        lowestPriceWithShipping:
                          type:
                          - number
                          - 'null'
                        totalListings:
                          type:
                          - integer
                          - 'null'
                        url:
                          type:
                          - string
                          - 'null'
                  totalListings:
                    type:
                    - integer
                    - 'null'
                  totalItems:
                    type: integer
                  hasNextPage:
                    type: boolean
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        listingId:
                          type:
                          - string
                          - 'null'
                        price:
                          type:
                          - number
                          - 'null'
                        shipping:
                          type:
                          - number
                          - 'null'
                        totalPrice:
                          type:
                          - number
                          - 'null'
                        condition:
                          type:
                          - string
                          - 'null'
                        variant:
                          type:
                          - string
                          - 'null'
                        language:
                          type:
                          - string
                          - 'null'
                        quantity:
                          type:
                          - integer
                          - 'null'
                        sellerName:
                          type:
                          - string
                          - 'null'
                        sellerRating:
                          type:
                          - number
                          - 'null'
                        sellerSales:
                          type:
                          - integer
                          - 'null'
                        sellerLocation:
                          type:
                          - string
                          - 'null'
                        goldSeller:
                          type:
                          - boolean
                          - 'null'
                        verifiedSeller:
                          type:
                          - boolean
                          - 'null'
                        directSeller:
                          type:
                          - boolean
                          - 'null'
                  scrapedAt:
                    type: string
        '400':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '429':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '502':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '503':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
      operationId: getV1TcgplayerListings
      x-operation-id-source: derived
components:
  parameters:
    CreditSource:
      name: X-Credit-Source
      in: header
      required: false
      schema:
        type: string
        enum:
        - credits
      description: Omit to use temporary carryover first, then monthly quota, then purchased credits. Set to credits to spend a purchased credit directly. Failed searches are not charged.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your API key as ''Authorization: Bearer cs_live_...''.'