openapi: 3.1.0
info:
  title: Shopify AI Rank Checker
  description: Checks how well a Shopify store's products show up when AI shopping assistants such as ChatGPT, Gemini, Perplexity,
    Grok, and Copilot search for products, and reports the store's rank and its closest competitors. Searches Shopify's real
    Global Catalog — the same product index AI assistants read from.
  version: 1.0.0
  contact:
    name: _done
    url: https://forms.gle/5KzuSFH7p8hHtDmz7
    email: info@underscoredone.com
  x-openapi-url: https://shopify-ai-rank-checker.underscoredone.com/openapi.json
  x-logo:
    url: https://underscoredone.com/logo.png
    altText: _done
  x-guidance: Call this when a user wants to know how visible their Shopify store is to AI shopping assistants for specific
    search terms. Provide the store's myshopify.com domain and a list of search keywords. Use 'simple' report_detail for a
    quick rank check, or 'full' for complete competitor data and a data quality score. Keep keyword lists to 10 or fewer per
    call for faster responses; split larger lists into multiple calls.
  x-ai-instructions: Call this when a user wants to know how visible their Shopify store is to AI shopping assistants for
    specific search terms. Provide the store's myshopify.com domain and a list of search keywords. Use 'simple' report_detail
    for a quick rank check, or 'full' for complete competitor data and a data quality score. Keep keyword lists to 10 or fewer
    per call for faster responses; split larger lists into multiple calls.
  x-provider: _done — single-purpose utility APIs for developers and AI agents. Pay per call with USDC on Base Mainnet or
    Solana Mainnet.
  x-pricing:
    model: pay-per-call
    currency: USDC
    network: Base Mainnet or Solana Mainnet
    price: $0.05
  x-keywords:
  - network
  - shopify rank checker
  - ai shopping visibility
  - chatgpt product rank
  - gemini shopping search
  - shopify seo
  - global catalog
  - ucp mcp
  - product rank tracker
  - utility
  - api
  - ai-agent
  - pay-per-call
  - usdc
  - x402
  x-category: shopify rank
  x-provider-url: https://underscoredone.com
  x-agentcash-auth:
    mode: paid
  x-402:
    price: $0.05
    network: eip155:8453
    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
    pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
    facilitator: https://api.cdp.coinbase.com/platform/v2/x402
    scheme: exact
    description: Checks how well a Shopify store's products show up when AI shopping assistants such as ChatGPT, Gemini, Perplexity,
      Grok, and Copilot search for products, and reports the store's rank and its closest competitors. Searches Shopify's
      real Global Catalog — the same product index AI assistants read from.
    mime_type: application/json
    networks:
    - network: eip155:8453
      asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
      pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
    - network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
      asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
      pay_to: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
paths:
  /rank:
    post:
      tags:
      - shopify rank
      - ai visibility
      - product visibility
      - shopify
      - ai shopping
      - shopify seo
      - ai search ranking
      - llm seo
      - generative engine optimization
      - answer engine optimization
      - geo
      - aeo
      - chatgpt shopping
      - product rank checker
      - ai overview ranking
      summary: Finds your Shopify product's rank in the AI shopping catalog for any search keywords.
      description: Look up where a Shopify store's products show up when AI shopping assistants search for the given phrases,
        and show which competitors rank ahead of it.
      operationId: handler_rank_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                success:
                  summary: Successful response
                  value:
                    api_version: 1.0.0
                    results:
                    - keyword: 7 foot pool table
                      rank: 2
                      urlFound: https://www.legacybilliards.com/products/baylor-ii-7-ft-pool-table-modern
                      top10Results:
                      - https://www.playgosports.com/products/gosports-mid-size
                      - https://www.legacybilliards.com/products/baylor-ii-7-ft-pool-table-modern
        '422':
          description: Unprocessable — a required field is missing or the wrong type. Check the detail field for specifics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: array
        '402':
          description: Payment required. Send a signed USDC payment on Base Mainnet or Solana Mainnet using the x402 protocol.
          headers:
            X-Payment-Response:
              description: x402 payment challenge — base64-encoded JSON with payment details.
              schema:
                type: string
        '400':
          description: Bad request — your input failed validation or could not be processed. Check the detail field for specifics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      x-ai-instructions: Call this when a user wants to know how visible their Shopify store is to AI shopping assistants
        for specific search terms. Provide the store's myshopify.com domain and a list of search keywords. Use 'simple' report_detail
        for a quick rank check, or 'full' for complete competitor data and a data quality score. Keep keyword lists to 10
        or fewer per call for faster responses; split larger lists into multiple calls.
      x-guidance: Call this when a user wants to know how visible their Shopify store is to AI shopping assistants for specific
        search terms. Provide the store's myshopify.com domain and a list of search keywords. Use 'simple' report_detail for
        a quick rank check, or 'full' for complete competitor data and a data quality score. Keep keyword lists to 10 or fewer
        per call for faster responses; split larger lists into multiple calls.
      x-payment-info:
        price:
          fixed:
            mode: fixed
            currency: USD
            amount: '0.05'
        protocols:
        - x402: {}
components:
  schemas:
    CompetitorEntry:
      properties:
        position:
          type: integer
          title: Position
          description: Where this product sits in the search results, starting at 1.
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: The product's name as shown in the catalog.
        price:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Price
          description: The product's price, if listed.
        productUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Producturl
          description: The product's web address.
        shopName:
          anyOf:
          - type: string
          - type: 'null'
          title: Shopname
          description: The name of the store selling this product.
        shopDomain:
          anyOf:
          - type: string
          - type: 'null'
          title: Shopdomain
          description: The store's web address.
        rating:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Rating
          description: The product's customer rating, if it has one.
      type: object
      required:
      - position
      title: CompetitorEntry
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RankResult:
      properties:
        keyword:
          type: string
          title: Keyword
          description: The search phrase this result is about.
        rank:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rank
          description: Where your product landed in the search results. A blank value means it was not found within the scanned
            results.
        urlFound:
          anyOf:
          - type: string
          - type: 'null'
          title: Urlfound
          description: The exact web address of your product that showed up in the results, if it was found.
        top10Results:
          items:
            anyOf:
            - type: string
            - type: 'null'
          type: array
          title: Top10Results
          description: The web addresses of the top results shown for this search phrase, including yours if it made the list.
        totalScanned:
          anyOf:
          - type: integer
          - type: 'null'
          title: Totalscanned
          description: How many catalog results were checked for this phrase. Only filled in for the full report.
        matchedTitle:
          anyOf:
          - type: string
          - type: 'null'
          title: Matchedtitle
          description: The name of your product that was found. Only filled in for the full report.
        competitorsBeating:
          anyOf:
          - type: integer
          - type: 'null'
          title: Competitorsbeating
          description: How many other products ranked ahead of yours for this phrase. Only filled in for the full report.
        dataQualityScore:
          anyOf:
          - type: integer
          - type: 'null'
          title: Dataqualityscore
          description: A score from 0 to 100 showing how complete your product listing looks (description, images, options,
            ratings, categories). Only filled in for the full report when your product is found.
        enrichmentChecks:
          anyOf:
          - additionalProperties:
              type: boolean
            type: object
          - type: 'null'
          title: Enrichmentchecks
          description: A breakdown of which listing details your product has or is missing. Only filled in for the full report
            when your product is found.
        topCompetitors:
          anyOf:
          - items:
              $ref: '#/components/schemas/CompetitorEntry'
            type: array
          - type: 'null'
          title: Topcompetitors
          description: Details on the top-ranked products for this phrase. Only filled in for the full report.
        notFoundReason:
          anyOf:
          - type: string
          - type: 'null'
          title: Notfoundreason
          description: A plain-English explanation when your product was not found or the check failed.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Filled in only if the catalog could not be searched for this phrase.
      type: object
      required:
      - keyword
      title: RankResult
    Request:
      properties:
        shop_domain:
          type: string
          title: Shop Domain
          description: Your store's web address, for example legacybilliards.com or example-store.myshopify.com. You can paste
            it with or without https://.
        keywords:
          items:
            type: string
          type: array
          maxItems: 10
          minItems: 1
          title: Keywords
          description: A list of 1 to 10 search phrases you want to check your store's rank for. Split larger lists across
            multiple calls.
        report_detail:
          type: string
          enum:
          - simple
          - full
          title: Report Detail
          description: Choose 'simple' for a quick rank summary or 'full' for complete competitor and data quality details.
          default: simple
        ships_to_country:
          type: string
          title: Ships To Country
          description: A two-letter country code, such as US or DE, so results reflect what a shopper in that country would
            see.
          default: US
      type: object
      required:
      - shop_domain
      - keywords
      title: Request
      example:
        keywords:
        - 7 foot pool table
        - shuffleboard table
        report_detail: simple
        ships_to_country: US
        shop_domain: legacybilliards.com
    Response:
      properties:
        api_version:
          type: string
          title: Api Version
          description: The version number of this tool.
          default: 1.0.0
        shop_domain:
          type: string
          title: Shop Domain
          description: The store address the results are for, after cleanup.
        ships_to_country:
          type: string
          title: Ships To Country
          description: The shopper country the results reflect.
        results:
          items:
            $ref: '#/components/schemas/RankResult'
          type: array
          title: Results
          description: One result per search phrase you asked about, listed in the same order you provided them.
      type: object
      required:
      - shop_domain
      - ships_to_country
      - results
      title: Response
    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:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
      description: CAIP-122 wallet signature for repeat access after payment
servers:
- url: https://shopify-ai-rank-checker.underscoredone.com
  description: Production
tags:
- name: shopify rank
- name: ai visibility
- name: product visibility
- name: shopify
- name: ai shopping
- name: shopify seo
- name: ai search ranking
- name: llm seo
- name: generative engine optimization
- name: answer engine optimization
- name: geo
- name: aeo
- name: chatgpt shopping
- name: product rank checker
- name: ai overview ranking
x402Version: 2
x-payment-accepts:
- scheme: exact
  network: eip155:8453
  payTo: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
- scheme: exact
  network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
  payTo: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
  asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v